scpg3 — Secure Shell file copy client - Generation 3
scpg3
[options
...]
[ src_profile
: |
[user@
]
src_host
[#port
]:
] src_file
...
[ dst_profile
: |
[user@
]
dst_host
[#port
]:
] dst_file_or_dir
scpg3 (scpg3.exe on Windows) is used to
securely copy files over the network. scpg3 launches
ssh-broker-g3 to provide a secure transport using the
Secure Shell version 2 protocol.
ssh-broker-g3 will ask for passwords or passphrases if they
are needed for authentication. scpg3 uses the configuration
specified in the ssh-broker-config.xml
file.
Any filename may contain a host, user, and port specification to
indicate that the file is to be copied to or from that host
( [user@
] host
[#port
]).
If no username is given, the local username is assumed.
If no port is given, the default Secure Shell port 22 is assumed.
Alternatively, a connection profile defined in the ssh-broker-config.xml
file (profile
) can be given. Copies between two
remote hosts are permitted. The remote host(s) must be running a Secure
Shell version 2 server with the sftp-server
subsystem
enabled.
The host
parameter can optionally be
enclosed in square brackets ([]
) to allow the use of
semicolons. The file
argument can contain simple
wild cards: asterisk (*
) for any number of any characters, and
question mark (?
) for any one character.
For information on special characters in file names, see the section called “Filename Support”.
The following command-line parameters can be used to further specify the scpg3 options.
-a
[arg
]Transfers files using the ASCII mode, that is, newlines will be
converted on the fly. See the ascii
command
in the section called “Commands”.
If the server does not advertise the newline convention, you can give
it a hint by giving an argument after -a
. The default is to
set the destination newline convention, but you can specify either one by
prefixing the argument with src:
or dest:
for source or destination convention, respectively. The available
conventions are dos
, unix
, and mac
,
using \r\n
, \n
, and \r
as newlines,
respectively. An example is shown below:
$ scpg3 -asrc:unix -adest:dos src_host:src_file dest_host:dest_file
-b
buffer_size_bytes
Defines the maximum buffer size for one read/write request
(default: 32768
bytes).
-B, --batch-mode
Uses batch mode. Fails authentication if it requires user interaction on the terminal.
Using batch mode requires that you have previously saved the server host key on the client and set up a non-interactive method for user authentication (for example, host-based authentication or public-key authentication without a passphrase).
-d
Forces target to be a directory.
-D, --debug=
LEVEL
Sets the debug level. LEVEL
is a number
from 0 to 99, where 99 specifies that all debug information should be
displayed. This should be the first argument on the command line.
Note | |
---|---|
Option |
Note | |
---|---|
The debug level can be set only when the scpg3 command starts the Connection Broker. This option has no effect in the command if the Connection Broker is already running. |
-I, --interactive
Prompts whether to overwrite an existing destination file (does not
work with -B
).
-m
fileperm
[:dirperm
]On Windows, sets the default file and directory permission bits for file upload to Unix servers. This option can be used only against Unix servers.
-N
max_requests
Defines the maximum number of read/write requests sent in parallel
(default: 10
).
-O, --offset=
r
<offset>
| w
<offset>
| l
<length>
| t
<length>
Sets offset. Offset
r
<offset>
specifies the
start offset in the source file. Offset
w
<offset>
specifies the
start offset in the destination file. Length
l
<length>
specifies the
amount of data to be copied. Truncate length
t
<length>
, if given,
specifies the length to which the destination file is truncated or expanded
after the file data has been copied.
-p
Preserves file attributes (Unix) and timestamps (Unix and Windows).
-P
port
Connects to this Secure Shell port on the remote machine (default: 22
).
-q
Uses quiet mode (only fatal errors are shown).
-Q
Does not show progress indicator.
-r
Recurses subdirectories.
-u, --unlink-source
Removes source files after copying (file move).
-v, --verbose
Uses verbose mode (equal to -D 2
).
--fips
Performs the checksums using the FIPS cryptographic library.
--force-lower-case
Destination filename will be converted to lowercase characters.
--overwrite
[
=yes
| no
]
Selects whether to overwrite existing destination file(s) (default:
yes
).
--password=
PASSWORD
| file://
PASSWORDFILE
| extprog://
PROGRAM
Sets user password that the client will send as a response to password
authentication. The PASSWORD
can be given
directly as an argument to this option (not recommended), or a path to file
containing the password can be given, or a path to a program or a script
that outputs the password can be given.
Caution | |
---|---|
Supplying the password on the command line is not a secure option. For example, in a multi-user environment, the password given directly on the command line is trivial to recover from the process table. You should set up a more secure way to authenticate. For non-interactive batch jobs, it is more secure to use public-key authentication without a passphrase, or host-based authentication. At a minimum, use a file or a program to supply the password. |
--plugin-path=
PATH
Sets plugin path to PATH
. This is only used in the FIPS mode.
--prefix=
PREFIX
Adds prefix to filename during the file transfer. The prefix is removed after the file has been successfully transferred. This option requires the EFT Expansion Pack on both SSH Tectia Client and Server.
--statistics
[
=yes
| no
| simple
]
Chooses the statistics style (default: yes
).
--streaming
[
=yes
| no
| force
| ext
]
Uses streaming in file transfer, if server supports it. Files
smaller than buffer_size_bytes
are not transferred
using streaming. Use force
with small files.
Default: no
The --streaming=ext
option must be enabled with
z/OS hosts to enable direct MVS dataset access. Use this option when the
scpg3
is mainly used for mainframe dataset transfers. Other
streaming settings can cause unpredictable results in MVS dataset transfers.
On the other hand, note that in Unix System Services (USS) environment,
extended streaming can slow down the transfer of small files.
The --streaming=ext
option requires also the
--checksum=no
option, because if checksums are calculated,
the file transfer uses staging, which excludes streaming.
An alternative way to activate extended streaming is to define environment variables:
SSH_SFTP_STREAMING_MODE=ext
SSH_SFTP_CHECKSUM_MODE=no
--checksum
[
=yes
| no
| md5
| sha1
| md5-force
| sha1-force
| checkpoint
]
Uses MD5 or SHA-1 checksums or a separate checkpoint database to
determine the point in the file where file transfer can be resumed. Files
smaller than buffer_size_bytes
are not checked.
Use md5-force
or sha1-force
with small
files (default: yes
, i.e. use SHA1 checksums in FIPS mode,
MD5 checksums otherwise). Use checkpointing when transferring large files
one by one.
-W, --whole-file
Does not try incremental checks. By default (if this option is not
given), incremental checks are tried. This option can only be used together
with the --checksum
option.
--checkpoint=s
<seconds>
Time interval between checkpoint updates (default:
10
seconds). This option can only be used when
--checksum=checkpoint
.
--checkpoint=b
<bytes>
Byte interval between checkpoint updates (default: 10 MB).
This option can only be used when --checksum=checkpoint
.
--src-site=
PARAM
Uses the specified site parameters with the source files.
See the site
command
in the section called “Commands”.
--dst-site=
PARAM
Uses the specified site parameters with the destination files.
See the site
command
in the section called “Commands”.
--append
Appends data to the end of the destination file.
-V, --version
Displays program version and exits.
-h, --help
Displays a short summary of command-line options and exits.
Different operating systems allow different character sets in filenames. On Unix and Linux, some of the special characters are allowed in filenames, but on Windows, the following characters are not allowed:
\/ : * ? " < > |
When you use the scpg3 command to copy files with
special characters (for example unixfilename*?".txt
) from a
Unix or Linux server to Windows, you need to provide the files with new
names that are acceptable on Windows. Enter the commands in the following format:
$ scpg3 user@unixserver:"unixfilename~*~?\".txt" windowsfilename.txt
The general rule is to follow your platform specific syntax when you enter filenames containing special characters as arguments to the scpg3 command.
SSH Tectia fully supports filenames containing only ASCII characters. Filenames containing characters from other character sets are not guaranteed to work.
The scpg3 command supports *
and ?
as wildcards.
The wildcards can be used both on the remote and the local side in the commands.
The following example command will copy all text files (*.txt
)
from all subdirectories of directory dir2
whose names begin with the prefix data-
into the current local directory ( . ):
$ scpg3 -r user@server
:"dir2/data-*/*.txt" .
Note that on Unix and Linux, the characters *
and
?
can appear also in the filenames. So it is necessary to use escape
characters to distinguish the wildcards from the characters belonging to a filename.
See more information
in the section called “Escaping special characters”.
Some special characters that are used in filenames in different operating system, may have a special meaning in the SSH Tectia commands. Note also that the meaning can be different in various parts of the file transfer system.
In the scpg3 command, the following characters have a special meaning, and they need to be escaped in commands that take filenames as arguments:
*
asterisk is a wildcard for any number of any characters
?
question mark is a wildcard for any single character
""
quotation marks placed around strings that are to be taken 'as is'
\
backslash is an escape character on Unix
~
tilde is an escape character on Windows.
The escape character tells the scpg3 command to treat the next character "as is" and not to assume any special meaning for it. The escape character is selected according to the operating system of the local machine.
Note that the \
and ~
characters are
special characters themselves, and if they are present in the filename, an
escape character must be placed in front of them, too. Therefore, if you need to
enter a filename containing \
in Unix or ~
in Windows
to the scpg3 command, add the relevant escape character to it:
\\
on Unix and Linux
~~
on Windows
See the examples below to learn how the escape characters are used in the SSH Tectia scpg3 command, and how to enter filenames with special characters in different operating systems.
The following filenames are valid in Unix and Linux, but they need escape characters in the commands:
file|name.txt file-"name".txt file?name.txt file*name.txt file\name.txt file - name.txt file~name.txt
When using the scpg3 command on Unix or Linux, enter the above mentioned filenames in the following formats:
file\|name.txt or "file|name.txt" file-\"name\".txt file\?name.txt or "file\?name.txt" file\*name.txt or "file\*name.txt" file\\\\name.txt or "file\\\name.txt" file\ -\ name.txt or "file - name.txt" file~name.txt
Example commands on Unix or Linux:
$ scpg3 user@server
:file\*name.txt .
$ scpg3 user@server
:file\ -\ name.txt .
When using the scpg3 command on Windows, enter the above mentioned Unix filenames in the following formats:
"file|name.txt" file-\"name\".txt (Note that Windows requires \ to escape the " character) "file~?name.txt" "file~*name.txt" file~\name.txt "file - name.txt" file~~name.txt
The operating system interprets the quotation marks ("") here so that the scpg3 command receives the string without the quotation marks as a parameter.
Example commands on Windows:
> scpg3 user@server
:"file~*name.txt" filename.txt
> scpg3 user@server
:"file - name.txt" .
scpg3 returns the following values based on the success of the operation:
0 Operation was successful. 1 Internal error. 2 Connection aborted by the user. 3 Destination is not a directory, but a directory was specified by the user. 4 Connecting to the host failed. 5 Connection lost. 6 File does not exist. 7 No permission to access file. 11 Some non-fatal errors occured during a directory operation. 101 Wrong command-line arguments specified by the user.
scpg3 uses the following environment variables:
=no|md5|md5-force|sha1|sha1-force|checkpoint
Defines the default checksum mode for sftpg3
and
scpg3
commands. Checksums are used to determine the point
in the file where file transfer can be resumed if it gets interrupted.
no
- checksums are not used;
the file is always transferred from the beginning until EOF.
This prevents staging in z/OS.
md5
- MD5 checksums are used
md5-force
- MD5 checksums are forced
sha1
- SHA1 checksums are used
sha1-force
- SHA1 checksums are forced
checkpoint
- a separate checkpoint database is used.
=no|yes|ext
Defines the default streaming mode to be used with
sftpg3
and scpg3
commands.
no
- streaming is not used.
yes
- standard streaming is used.
ext
- extended streaming is used.
This environment variable represents a number of variables where the xxx is one of the file transfer parameters listed under the sftpg3 site command. The variables apply to processing of local files and they set the default values that can be overridden with the advisor strings.
Copy files from your local system to a remote Unix system:
$ scpg3 localfile user@remotehost:/dst/dir/
Copy files from your local system to a remote Windows system:
$ scpg3 localfile user@remotehost:/C:/dst/dir/
Copy files from a remote system to your local disk:
$ scpg3 user@remotehost:/src/dir/srcfile /dst/dir/dstfile
Copy files from one remote system to another using connection profiles
defined in the ssh-broker-config.xml
file:
$ scpg3 profile1:/src/dir/srcfile profile2:/dst/dir/dstfile