scpg3 — Secure Shell file copy client - Generation 3
src_profile: | [
dst_profile: | [
scpg3 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
Copies between two remote hosts are permitted. The remote host(s) must be running a Secure Shell version 2 server with the sftp-server (or sft-server-g3) subsystem enabled. SSH Tectia Server has sft-server-g3 enabled by default.
Any filename may contain a host, user, and port specification to indicate that the file is to be copied to or from that 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.
When entering a connection profile in the scpg3 command, note that SSH Tectia client tools for z/OS deduces the meaning of the argument differently depending on its format. If there is an
Also, if there are dots in a profile name (for example
host parameter can optionally be enclosed in square brackets () to allow the use of semicolons. The
file argument can contain simple wildcards: 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.
Transfers files using the ASCII mode, that is, newlines will be converted on the fly. For transfers between SSH Tectia on z/OS and other hosts, this also enables automatic ASCII-EBCDIC conversions. See the
asciicommand 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
dest:for source or destination convention, respectively. The available conventions are
\ras newlines, respectively. An example is shown below:
$ scpg3 -asrc:unix -adest:dos src_host:src_file dest_host:dest_file
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).
Defines the maximum buffer size for one read/write request (default:
Disables compression from the current connection.
Enables zlib compression for this particular connection.
Sets the allowed ciphers to be offered to the server. List the cipher names in a comma-separated list. For example:
helpas the value to view the currently supported cipher names.
Sets the debug level.
LEVELis 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.
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.
Forces target to be a directory.
Prompts whether to overwrite an existing destination file (does not work with
Defines that private keys defined in the identification file are used for public-key authentication.
Defines that the given key file of a private key or certificate is used in user authentication. The path to the key file is given in the command.
If the file is a private key, it will be read and compared to the keys already known by the Connection Broker key store. If the key is not known, it will be decoded and added to the key store temporarily. If the file is a certificate and Connection Broker knows a matching private key, it will be used. Both the certificate and the private key can be given using multiple
-Koptions on command line.
This option can be used only on Unix. Sets the default file and directory permission bits for file upload to Unix servers.
Defines the maximum number of read/write requests sent in parallel (default:
Sets offset. Offset
<offset>specifies the start offset in the source file. Offset
<offset>specifies the start offset in the destination file. Length
<length>specifies the amount of data to be copied. Truncate length
<length>, if given, specifies the length to which the destination file is truncated or expanded after the file data has been copied.
Preserves the file permissions and the timestamps when both the source and the destination are on Unix filesystems (including z/OS USS). Preserves the timestamps but not the file permissions, if either one, the source or the destination is on Windows. If the destination is on z/OS MVS, none will be preserved.
Connects to this Secure Shell port on the remote machine (default:
Does not show progress indicator. The effect of this option is the same as using
Do not use this option together with parameter
Uses quiet mode (only fatal errors are shown). This option overrides the
quiet-modesetting made in the Connection Broker configuration file.
Removes source files after copying (file move).
Uses verbose mode (equal to
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
Tries an empty password.
Defines the only allowed methods that can be used in user authentication. List the methods in a comma-separated list. Enter
helpas the value to view the currently supported authentication methods.
Appends data to the end of the destination file.
Uses binary transfer mode. If the server is SSH Tectia Server for IBM z/OS, the server is requested not to perform ASCII to EBCDIC conversion, and the file is transferred using the Stream format. You can use the
--dst-siteoptions to change the values.
Byte interval between checkpoint updates (default: 10 MB). This option can only be used when
Time interval between checkpoint updates (default:
10seconds). This option can only be used when
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_bytesare not checked. Use
sha1-forcewith small files (default:
yes, i.e. use SHA1 checksums in FIPS mode, MD5 checksums otherwise). Use checkpointing when transferring large files one by one.
Sets the allowed compression methods to be offered to the server. List the methods in a comma-separated list.
helpas the value to view the currently supported compression methods.
Uses the specified site parameters with the destination files. See the site command in the section called “Commands”.
Defines that a new connection will be opened for each connection attempt, otherwise Connection Broker can reuse recently closed connections.
Performs the checksums using the FIPS cryptographic library.
Destination filename will be converted to lowercase characters.
Defines that the ID of the private key is used in user authentication. The ID can be Connection Broker-internal ordinary number of the key, the key hash or the key file name.
Defines the private key used in user authentication with the corresponding public key hash.
Defines that the Connection Broker-internal ordinary number of the key is used in user authentication.
Defines how often keep-alive messages (non-operation packages) are sent to the Secure Shell server. Enter the value as seconds. The default value is 0, meaning that keep-alive messages are disabled.
Sets the allowed MACs to be offered to the server. List the MAC names in a comma-separated list. For example:
helpas the value to view the currently supported MAC names.
Selects whether to overwrite existing destination file(s) (default:
Sets user password that the client will send as a response to password authentication. The
PASSWORDcan be given directly as an argument to this option (not recommended). Better alternatives are entering a path to a file containing the password (
PASSWORDFILE), or entering a path to a program or script that outputs the password (
When using the
extprog://option to refer to a shell script, make sure the script also defines the user's shell, and outputs the actual password. Otherwise the executed program fails, because it does not know what shell to use for the shell script. For example, if the password string is defined in a file named
my_password.txt, and you want to use the bash shell, include these lines in the script:
#!/usr/bash cat /full/pathname/to/my_password.txt
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.
Adds a prefix to a filename during the file transfer. The prefix is removed after the file has been successfully transferred.
On z/OS, when applied to MVS dataset names, the prefix is inserted after the High Level Qualifier (HLQ). In case you want the prefix to be a separate qualifier, include a dot at the end of the prefix:
Uses the specified site parameters with the source files. See the site command in the section called “Commands”.
In release 6.1.5, the behavior of the
--statisticsoption has changed and the
--statistics-formatoption has been removed. Instead of them, use the new
--statisticsoption chooses the style of the statistics to be shown after a file transfer operation. Note that
--summary-displaymust not be used together.
--statisticsoption takes the following values:
no- no statistics will be created.
yes- shows a progress bar during the file transfer. This is the default. An example of the output:
scpg3 --statistics="yes" sourcefile destinationfile sourcefile | 127MB | 42.9MiB/s | TOC: 00:00:03 | 100%
simple- simple one-line statistics will be displayed after the file transfer has ended. For example:
scpg3 --statistics=simple sourcefile destinationfile sourcefile | 127MB | 151.3MiB/s | TOC: 00:00:00
Chooses the style of the file transfer summary data to be displayed after a file transfer operation. With the summary display, the progress bar data is also displayed by default.
--statisticsmust not be used together.
--summary-displayoption takes the following values:
no- no summary data will be created. This is the default.
yes- detailed summary data will be created. You can configure the contents with the
summary-formatoption. By default, the following contents are displayed in the summary:
Default settings: Render for example this: "Source: %c:%g\n" user@host1#22:/path/to/source/file "Source parameters: %e\n" X=TEXT, C=ISO8859-1,D=IBM.1047 "Destination: %C:%G\n" user@host2#22:/path/to/destination/file "Destination parameters: %E\n" NONE "File size: %s bytes\n" 123456 bytes "Transferred: %t bytes\n" 123456 bytes "Rate: %RB/s\n" 345kiB/s "Start: %xy-%xt-%xd %xh:%xm:%xs\n" 2010-01-26 13:10:56 "Stop: %Xy-%Xt-%Xd %Xh:%Xm:%Xs\n" 2010-01-26 13:23:30 "Time: %y\n" 00:12:34
simple- simple one-line summary will be displayed. For example:
scpg3 --summary-display=simple sourcefile destinationfile sourcefile | 127MB | 151.3MiB/s | TOC: 00:00:00
bytes- basic statistics reporting the transferred bytes will be displayed. For example:
scpg3 --summary-display=bytes sourcefile destinationfile Transferred 12915145984 bytes, file: 'sourcefile' -> 'destinationfile'
Chooses the format and the contents of the summary. You can use this option when
--summary-display=yes. Do not use this option with
Select the contents for the summary using the following definitions:
%c - source connection: user@host#port or profile %C - destination connection: user@host#port or profile %D* - current date %e - source parameters (file transfer and dataset parameters) %E - destination parameters (file transfer and dataset parameters) %f - source file name %F - destination file name %g - /path/to/source/file %G - /path/to/destination/file %k - compression done ("zlib" or "none") %p - transfer percentage %q - transfer rate in bit/s %Q - transfer rate as "XXyb/s" (b/s, kib/s, Mib/s, Gib/s) %r - transfer rate in bytes/s %R - transfer rate as "XXyB/s" (B/s, kiB/s, MiB/s, GiB/s) %s - file size in bytes %S - file size as "XXyB" (B, kiB, MiB or GiB) %t - transfer size in bytes %T - transfer size as "XXyB" (B, kiB, MiB or GiB) %x* - start date %X* - end date %y - elapsed time %Y - time remaining %z - ETA or TOC, if transfer has finished %Z - string "ETA" or "TOC", if transfer has finished Where * is one of the following: h - hours (00-23) m - minutes (00-59) s - seconds (00-59) f - milliseconds (0-999) d - day of the month (1-31) t - month (1-12) y - year (1970-) Other special characters in format strings are: \n - line feed \r - carriage return \t - horizontal tab \\ - backslash
Chooses the mode of displaying the progress during a file transfer operation. The default is
bar, which shows a progress bar. Option
lineshows the progress information according to the settings made in the
Do not use this option with
Chooses what information will be shown on the progress line. You can use this option when
Do not use this option with
Select the contents for the progress line using the definitions described for command:
Defines how often the progress information is updated in line mode. The interval is given in seconds, and the default is 60 seconds.
Do not use this option with
Uses streaming in file transfer, if server supports it. Files smaller than
buffer_size_bytesare not transferred using streaming. Use
forcewith small files. Default:
extwith z/OS hosts to enable direct MVS dataset access. Use this option only when the file transfer is mainly used for mainframe dataset transfers, as it can slow down the transfer of small files in other environments.
--streaming=extoption requires also the
--checksum=nooption, because if checksums are calculated, the file transfer uses staging, which excludes streaming.
Defines a timeout period (in seconds) for establishing a TCP connection to the Secure Shell server. Enter the timeout value as a positive number. Value 0 (zero) disables this feature and the default system TCP timeout will be used, instead.
Stores datasets with unique names. In case more than one of the transferred datasets have the same name, this feature adds a sequential number to the end of the repeated dataset name, for example:
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, 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 server to Windows, you need to provide the files with new names that are acceptable on Windows. Enter the commands in the following format:
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
? 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
Note that on Unix, 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”.
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, escape characters 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
~~ 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.
- Examples of filenames in the scpg3 command:
The following filenames are valid in Unix, 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, in certain cases several escape characters are needed, as they escape one another. 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:
user@server:file\ -\ name.txt .
To run scpg3 on z/OS, the following environment variables must be set:
scpg3 uses DLLs that come as part of SSH Tectia installation. LIBPATH is used for setting the search path for DLLs. If this variable is not set correctly scpg3 fails to start.
If this variable is not set correctly scpg3 fails to start.
This variable defines the permissions for newly created files.
This variable defines that ssh-broker-g3 and scpg3 processes are run in separate address spaces.
If this variable is not set correctly scpg3 fails to start.
scpg3 uses the following environment variables:
This environment variable can be used to specify the format of the debug messages.
For more information, see SSH_DEBUG_FMT.
If this variable is set to
yes, the number of transferred bytes is shown after successful file transfer. Also the names of source and destination files are shown. The default is
If this variable is set to
TYPE119, file transfers create SMF records of type 119.
If this variable is set to
yes(default), normal progress bar is shown while transferring the file. If it is set to
no, progress bar is not shown. If it is set to
simplefile transfer statistics are shown after the file has been transferred.
In addition to the files used by ssh-broker-g3, scpg3 uses the following files:
This is the user-specific file that contains a list of file transfer profiles, which furnish file transfer attributes to be used when processing local files. For more information, see File Transfer Profiles.
This is the global (system-wide) file that contains a list of file transfer profiles, which furnish file transfer attributes to be used when processing local files. For more information, see File Transfer Profiles.
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. 8 Undetermined error from sshfilexfer. 11 Some non-fatal errors occured during a directory operation. 101 Wrong command-line arguments specified by the user.
When the command is run from JCL using BPXBATCH, the exit values are multiplied by 256.
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
$ scpg3 profile1:/src/dir/srcfile profile2:/dst/dir/dstfile