sftpg3
(sftpg3.exe on Windows) is an FTP-like client
that can be used for secure file transfer over the network. sftpg3 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. sftpg3 uses the configuration specified
in the ssh-broker-config.xml
file.
When started interactively, sftpg3 displays a prompt where the SFTP commands can be entered. It is also possible to start sftpg3 non-interactively with a batch file that contains the commands to be run. For information on the available commands, see the section called “Commands”.
As an alternative to using the command line to set default values for various parameters,
it is possible to define the commands in a startup batch file that is run each time
sftpg3 is started.
By default, sftpg3 looks for a file named
ssh_sftp_batch_file
in the user-specific directory
$HOME/.ssh2/
on Unix or %APPDATA%\SSH\
on
Windows.
sftpg3 has two connection end points, local and remote, and both of them can be connected to other hosts than the SFTP client host. If started without arguments, the local end point is connected to the file system of the SFTP client host and the remote end point is unconnected. The connected host(s), with the exception of the SFTP client host, must be running a Secure Shell version 2 server with the sftp-server (or sft-server-g3) subsystem enabled. Tectia Server has sft-server-g3 enabled by default.
The remote connection end point can be given directly as an argument to the sftpg3 command or it can be given with the open SFTP command after sftpg3 has started. The local connection end point can be given with the lopen SFTP command.
When connecting, you can give either the name of a connection profile defined in the
ssh-broker-config.xml
file (profile
) or the
IP address or DNS name of the remote host, optionally with the remote user name and the port
of the Secure Shell server
( [user@
] host
[#port
]).
If no user name is given, the local user name is assumed. If no port is given, the default
Secure Shell port 22 is assumed.
Note | |
---|---|
When entering a connection profile in sftpg3, note that Tectia ConnectSecure
deduces the meaning of the argument differently depending on its format. If there is an
@ sign in the given attribute value, Tectia ConnectSecure always interprets it to be
Also, if there are dots in a profile name (for example
|
For information on special characters in filenames, see the section called “Filename Support”.
The following options are available:
-4
Defines that all connection-related DNS resolutions will be resolved as an IPv4 address.
-6
Defines that all connection-related DNS resolutions will be resolved as an IPv6 address.
-b
buffer_size_bytes
Defines the maximum buffer size for one SFTP protocol read or write request
(default: 32768
bytes).
The maximum number of SFTP protocol read or write requests sent in parallel within
the transfer of a single file can be specified with the
-N
option.
Note that when streaming (see
--streaming
)
is used (as it is by default when transferring files larger than
buffer_size_bytes
to/from Tectia Server), this option is not used
for defining buffer sizes.
-B
[ -
| batch_file
]
The -B -
option enables reading from the standard input. This
option is useful when you want to launch processes with sftpg3 and
redirect the stdin pipes.
By defining the name of a batch_file
as an attribute, you
can execute SFTP commands from the given file in batch mode. The file can contain any
allowed SFTP commands. For a description of the commands, see
the section called “Commands”.
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).
-C
Disables compression from the current connection.
+C
Enables zlib compression for this particular connection.
-c, --ciphers=
LIST
Sets the allowed ciphers to be offered to the server. List the cipher names in a comma-separated list. For example:
--ciphers seed-cbc@ssh.com,aes256-cbc
Enter help
as the value to view the currently supported cipher
names.
-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 sftpg3 command starts the Connection Broker. This option has no effect in the command if the Connection Broker is already running. |
-i
FILE
Defines that private keys defined in the identification file are used for public-key authentication.
-K, --identity-key-file=
FILE
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
-K
options on command line.
-N
max_requests
Defines the maximum number of SFTP protocol read or write requests sent in parallel (default: 10).
The size of the buffer used in each read or write request can be specified with the
-b
option.
Note that this value applies within the transfer of a single file; it cannot be used to define the number of files sent in parallel.
When streaming (see
--streaming
)
is used (as it is by default when transferring files larger than
buffer_size_bytes
specified with the -b
option to/from Tectia Server), this option is not used.
-P
port
Connects to this Secure Shell port on the remote machine (default:
22
).
-q, --quiet
Suppresses the printing of error, warning, and informational messages. This option
overrides the quiet-mode
setting made in the Connection Broker configuration
file.
-v, --verbose
Uses verbose mode (equal to -D 2
).
--aa, --allowed-authentications=
METHODS
Defines the only allowed methods that can be used in user authentication. List the methods in a comma-separated list. For example:
--allowed-authentications keyboard-interactive,password
Enter help
as the value to view the currently supported
authentication methods.
--compressions=
METHODS
Sets the allowed compression methods to be offered to the server. List the methods in a comma-separated list.
Enter help
as the value to view the currently supported compression
methods.
--exclusive
Defines that a new connection will be opened for each connection attempt, otherwise Connection Broker can reuse recently closed connections.
--fips
Performs the checksums using the FIPS cryptographic library.
--hostkey-algorithms=
algorithms
Sets the allowed host key algorithms to be offered to the server. List the host key algorithms in a comma-separated list. For example:
--hostkey-algorithms ssh-dss-sha224@ssh.com,ssh-dss-sha256@ssh.com
Enter help
as the value to view the currently supported host key
algorithms.
--identity=
ID
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.
--identity-key-hash=
ID
Defines the private key used in user authentication with the corresponding public key hash.
--identity-key-id=
ID
Defines that the Connection Broker-internal ordinary number of the key is used in user authentication.
--keep-alive=
VALUE
Defines how often keep-alive messages are sent to the Secure Shell server. Enter the value as seconds. The default value is 0, meaning that keep-alive messages are disabled.
--kexs=
kexs
Sets the allowed key exchange (KEX) methods to be offered to the server. List the KEX names in a comma-separated list. For example:
--kexs diffie-hellman-group14-sha224@ssh.com,diffie-hellman-group14-sha256@ssh.com
Enter help
as the value to view the currently supported KEX
methods.
All the supported KEXs can operate in the FIPS mode on Linux, Windows,
Solaris and HP-UX Itanium. However,
diffie-hellman-group15-sha256@ssh.com
,
diffie-hellman-group15-sha384@ssh.com
,
ecdh-sha2-nistp256
, ecdh-sha2-nistp384
and
ecdh-sha2-nistp521
that are supported KEXs, cannot operate in the
FIPS mode on HP-UX PA-RISC and IBM AIX due to issues in the OpenSSL cryptographic
library version 0.9.8.
--kip
Defines keyboard-interactive and password as the allowed methods for user authentication; the same as
--allowed-authentications keyboard-interactive,password
--macs=
LIST
Sets the allowed MACs to be offered to the server. List the MAC names in a comma-separated list. For example:
--macs hmac-sha1-96,hmac-md5,hmac-md5-96
Enter help
as the value to view the currently supported MAC
names.
--password=
PASSWORD
| file://
PASSWORDFILE
| extprog://
PROGRAM
Sets the user password or passphrase that the client will send as a response to an authentication method requesting a password or passphrase (hereafter: password). This can be used also with password-protected certificates and public-keys.
The PASSWORD
can be given directly as an argument to this
option (not recommended). Better alternatives are entering a path to a file containing
the password
(--password=file://
PASSWORDFILE
), or
entering a path to a program or script that outputs the password
(--password=extprog://
PROGRAM
).
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
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.
--tcp-connect-timeout=
VALUE
Defines a timeout period (in seconds) for establishing a TCP connection to the Secure Shell server. Enter a timeout value as a positive number. Value 0 (zero) disables this feature and the default system TCP timeout will be used, instead.
--user=
USERNAME
USERNAME
will be used in the logon if the user name is
not specified in the address string.
-V, --version
Displays program version and exits.
-h, --help, -?
Displays a short summary of command-line options and exits.
When sftpg3 is ready to accept commands, it will display the prompt
sftp>
. The user can then enter any of the following commands:
!
[command
] [arguments
]
Invokes an interactive shell on the local machine. if a
command
is given, it is used as the command to be executed.
Optional arguments
can be given depending on the
command.
append
[-u, --unlink-source
] [--streaming
] [--force-lower-case
] [--statistics
] [--summary-display
] [--summary-format
] [--progress-display
] [--progress-line-format
] [--progress-line-interval
] srcfile
[dstfile
]
Appends the specified local file to the remote file. No globbing can be used.
Options:
-u, --unlink-source
Removes the source file after file transfer.
--streaming
[
=yes
| no
| force
| ext
]
Uses streaming in file transfer if the server supports it. Files smaller than
buffer_size_bytes
are not transferred using
streaming. Use force
with small files. Default:
yes
Use ext
with z/OS hosts to enable direct MVS data set access.
Use this option only when the file transfer is mainly used for mainframe data set
transfers, as it can slow down the transfer of small files in other environments.
The --streaming=ext
option requires also the
--checksum=no
option, because if checksums are calculated, the
file transfer uses staging, which excludes streaming.
--force-lower-case
Destination filename will be converted to lowercase characters.
The semantics of options --statistics
,
--summary-display
, --summary-format
,
--progress-display
, --progress-line-format
, and
--progress-line-interval
are the same as with
get.
ascii
[-s
] [remote_nl_conv
] [local_nl_conv
]
Command ascii sets the transfer mode to ASCII.
For transfers between Tectia on z/OS and other hosts, this also enables automatic
ASCII-EBCDIC conversion. Default conversion is between code sets ISO8859-1 and IBM-1047.
Files are transferred using the LINE
format. The
site and lsite commands can be used to change
the values.
If you enter the ascii command with any options, it does not set
the transfer mode to ASCII, but affects the newline conventions used in the transferred
files. You can also set the server's newline convention by using a host profile that
specifies the host type. For more information, see the
host-type
attribute in
the section called “The profiles
Element”.
Options:
-s
Shows the current newline convention. The line delimiters used in different systems are:
dos: CRLF (\r\n, 0x0d 0x0a) mac: CR (\r, 0x0d) mvs: NEL (\n, 0x15) unix: LF (\n, 0x0a)
remote_nl_conv
local_nl_conv
This syntax can be used to define the remote and local newline conventions.
The local_nl_conv
option operates on the local end, but
notice that usually the correct local newline convention is already compiled in.
You can either set hints of the newline conventions for the underlying transfer layer, which by default tries to use the actual newline convention given by the server, or alternatively you can force the newline mode.
To set hints of the newline conventions, use these values in the
remote_nl_conv
and
local_nl_conv
options: dos
,
unix
, and mac
. These settings will be used if
the remote SSH server does not automatically provide any newline information to
the SFTP client. For example:
sftp> ascii File transfer mode is now ascii. sftp> ascii unix dos Newline conventions updated.
To force the newline conventions, use these values:
force-dos
, force-unix
, and
force-mac
. These settings force the newline mode irrespective
of what the remote SSH server suggests to the SFTP client.
sftp> ascii File transfer mode is now ascii. sftp> ascii force-unix force-dos Newline conventions updated.
You can also set either one of the options to ask
, which will
cause sftpg3 to prompt you for the newline convention when
needed.
auto
File transfer mode will be selected automatically from the file extension.
binary
Files will be transferred in binary mode.
break
Interrupts batch file execution. Batch file execution can be continued with the continue command.
bye
Quits the application.
cd
directory
Changes the current remote working directory.
chmod
[-R
] [-f
] [-v
] OCTAL-MODE
[file
...]
chmod
[-R
] [-f
] [-v
] [ugoa
] [+-=
] [rwxs
] [file
...]
With Unix files, sets file permissions of the specified file or files to the bit
pattern OCTAL-MODE
or changes the file permissions according
to the symbolic mode [ugoa][+-=][rwxs]
.
Options:
-R
Recursively changes files and directories.
-f
Uses silent mode (error messages are suppressed).
-v
Uses verbose mode (lists every file processed).
close
Closes the remote connection.
continue
Continues interrupted batch file execution.
debug
[
disable
| no
| debuglevel
]
Disables or enables debug. With disable
or no
,
debugging is disabled. Otherwise, sets debuglevel
as debug
level string, as per command-line option -D
.
delete
[-H, --hash
] [-o, --offset
] [-l, --length
] file
Tries to delete a file or directory specified in file
.
The options are the same as for
rm.
digest
[-H, --hash
] [-o, --offset
] [-l, --length
] file
Calculates MD5 or SHA-1 digest over file data. The digest is calculated over the data on the disk. If any code or line delimiter conversion attributes are in effect, they are ignored when calculating the digest.
Options:
-H, --hash=
[
md5
| sha1
]
Use md5
or sha1
hash algorithm (default:
md5
).
-o, --offset=
OFFSET
Start reading from file offset OFFSET
.
-l, --length=
LENGTH
Read LENGTH
bytes of file data.
echo
Text to be echoed.
Echo the text. This command can be used for example in batch mode to print text into batch logs.
exit
Quits the application.
get
[-p, --preserve-attributes
] [-u, --unlink-source
] [-I, --interactive
] [--overwrite
] [--checksum
] [-W, --whole-file
] [--checkpoint
] [--streaming
] [--force-lower-case
] [--prefix
] [--statistics
] [--summary-display
] [--summary-format
] [--progress-display
] [--progress-line-format
] [--progress-line-interval
] [--max-depth=
] file
...
Transfers the specified files from the remote end to the local end. By default,
directories are recursively copied with their contents, but this is configurable in the
Connection Broker configuration with the SFTP compatibility mode setting
(sftpg3-mode
in ssh-broker-config.xml
). To view
the currently set SFTP compatibility mode, run command:
sftp> help get
The currently set compatibility mode is shown in the beginning of the help for command get.
The SFTP compatibility mode options are:
tectia
The sftpg3 client transfers files recursively from the current directory and all its subdirectories.
ftp
The get command is executed as sget meaning that it transfers a single file, and no subdirectories are copied.
openssh
Only regular files and symbolic links from the specified directory are copied, and no subdirectories are copied. Otherwise the semantics of the get command are unchanged.
Options:
-p, --preserve-attributes
Preserves the file permissions and the timestamps when both the source and the destination are on Unix file systems (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.
-u, --unlink-source
Removes the source file after file transfer. Also directories are removed, if they become empty (move mode).
-I, --interactive
Prompts whether to overwrite an existing destination file (does not work with batch mode).
--overwrite
[
=yes
| no
]
Decides whether to overwrite existing destination file(s) (default:
yes
).
--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 MD5 checksums). 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
.
--streaming
[
=yes
| no
| force
| ext
]
Uses streaming in file transfer if the server supports it. Files smaller than
buffer_size_bytes
are not transferred using
streaming. Use force
with small files. Default:
yes
Use ext
with z/OS hosts to enable direct MVS data set access.
Use this option only when the file transfer is mainly used for mainframe data set
transfers, as it can slow down the transfer of small files in other
environments.
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
SSH_SFTP_STREAMING_MODE=ext
and
SSH_SFTP_CHECKSUM_MODE=no
as environment variables.
--force-lower-case
Destination file name will be converted to lower case characters.
--max-depth=
VALUE
Defines whether directories are copied recursively. The value can be:
0
- unlimited recursion, directories are recursively copied
with their contents
1
- copies files from the specified directory only, not from
subdirectories
2-n
- copies files recursively from the specified number of
directory levels. Here n
means the system-specific
maximum.
This command line option overrides the recursion depth set in the Connection Broker
configuration with element sftpg3-mode
and/or the setting made
using environment variable SSH_SFTP_CMD_GETPUT_MODE
.
--prefix=
PREFIX
Adds prefix PREFIX
to filename during the file transfer. The
prefix is removed after the file has been successfully transferred.
On z/OS, when applied to MVS data set names, the prefix will be inserted after the High Level Qualifier (HLQ) by default. In case you want the prefix to be a separate qualifier, include a dot at the end of the prefix:
--prefix=PREFIX.
--statistics
[
=no
| yes
| simple
]
Note | |
---|---|
In release 6.1.5, the behavior of the |
The --statistics
option chooses the style of the statistics
to be shown after a file transfer operation. Note that
--statistics
and --summary-display
must not be
used together.
The --statistics
option 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:
sftp> get --statistics="yes" sourcefile 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:
sftp> get --statistics=simple testfile sourcefile | 127MB | 151.3MiB/s | TOC: 00:00:00 | 100%
--summary-display
[
=no
| yes
| simple
| bytes
]
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.
Note that --summary-display
and --statistics
must not be used together.
The --summary-display
option 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-format
option. 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:
sftp> get --summary-display=simple sourcefile sourcefile | 127MB | 151.3MiB/s | TOC: 00:00:00 | 100%
bytes
- basic statistics reporting the transferred bytes will
be displayed. For example:
sftp> get --summary-display=bytes sourcefile Transferred 12915145984 bytes, file: 'sourcefile' -> 'destinationfile'
--summary-format=
FORMAT_STRING
Chooses the format and the contents of the summary. You can use this option
when --summary-display=yes
. Do not use this option with
--statistics
.
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 data set parameters) %E - destination parameters (file transfer and data set 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
--progress-display
[
=no
| bar
| line
]
Chooses the mode of displaying the progress during a file transfer operation.
The default is bar
, which shows a progress bar. Option
line
shows the progress information according to the settings
made in the --progress-line-format
option.
Do not use this option with --statistics
.
--progress-line-format=
FORMAT_STRING
Chooses what information will be shown on the progress line. You can use this
option when --progress-display=line
.
Do not use this option with --statistics
.
Select the contents for the progress line using the definitions described for
option --summary-format
of the get command
above.
--progress-line-interval=
seconds
Defines how often the progress information is updated in the line mode. The interval is given in seconds, and the default is 60 seconds.
Do not use this option with --statistics
.
getext
Displays the extensions that will be ASCII in the auto transfer mode.
lappend
[options
...] srcfile
[dstfile
]
The same as append, but appends the specified remote file to the local file.
lcd
directory
Changes the current local working directory.
lchmod
[-R
] [-f
] [-v
] OCTAL-MODE
[file
...]
lchmod
[-R
] [-f
] [-v
] [ugoa
] [+-=
] [rwxs
] [file
...]
The same as chmod, but operates on local files.
lclose
Closes the local connection.
ldelete
[options
...] file
...
The same as delete, but operates on local files.
ldigest
[-H, --hash
] [-o, --offset
] [-l, --length
] file
The same as digest, but operates on local files.
lls
[-R
] [-l
] [-S
] [-r
] [-p
] [-z|+z
] [file
...]
The same as ls, but operates on local files.
llsroots
The same as lsroots, but operates on local files (when the local end has been opened to a VShell server).
lmkdir
directory
The same as mkdir, but operates on local files.
localopen
[user@
]hostname
[#port
] [-l
] [--user=
USERNAME
]
The same as lopen.
lopen
[user@
]hostname
[#port
] [-l
] [--user=
USERNAME
]
Tries to connect the local end to the host hostname
. If
this is successful, lls and friends will operate on the file system
on that host.
Options:
-l
Connects the local end to the file system of the SFTP client host (which does not require a server). This is also the default state when no lopen commands have been given.
--user
Defines the user in the connection to be
USERNAME
.
locsite
[
none
| name1=value1 name2=value2
...
]
The same as site, but operates on local files and data sets.
lpwd
Prints the name of the current local working directory.
lreadlink
path
The same as readlink, but operates on local files.
lrename
oldfile
newfile
The same as rename, but operates on local files.
lrm
[options
...] file
...
The same as rm, but operates on local files.
lrmdir
directory
The same as rmdir, but operates on local files.
ls
[-R
] [-l
] [-S
] [-r
] [-p
] [-z|+z
] [file
...]
Lists the names of files on the remote server. For directories, contents are listed. If no arguments are given, the contents of the current working directory are listed.
Options:
-R
Directory trees are listed recursively. By default, subdirectories of the arguments are not visited.
-l
Permissions, owners, sizes and modification times are also shown (long format).
-S
Sorting is done based on file sizes (default: alphabetical sorting).
-r
The sort order is reversed.
-p
Only one page of listing is shown at a time.
-z
The client generates the long output.
+z
The long output supplied by the server is used, if available (alias for option
-l
).
lsite
[
none
| name1=value1 name2=value2
...
]
The same as site, but operates on local files and data sets.
lsroots
Dumps the virtual roots of the server. (This is a VShell extension. Without this you cannot know the file system structure of a VShell server.)
lsymlink
targetpath
linkpath
The same as symlink, but operates on local files.
mget
[options
...] file
...
Synonymous to get.
mkdir
directory
Tries to create the directory specified in directory
.
mput
[options
...] file
...
Transfers the specified files from the local end to the remote end. Options and semantics are the same as for get. Synonymous to put.
open
[user@
]hostname
[#port
] [-l
] [--user=
USERNAME
]
Tries to connect the remote end to the host hostname
.
Options:
-l
Connects the remote end to the file system of the SFTP client host (which does not require a server).
--user
Defines the user in the connection to be USERNAME
.
pause
[seconds
]
Pauses batch file execution for seconds
seconds, or if
seconds
is not given until ENTER is
pressed.
put
[options
...] file
...
Transfers the specified files from the local end to the remote end. Options and semantics are the same as for get.
pwd
Prints the name of the current remote working directory.
quit
Quits the application.
readlink
path
Provided that path
is a symbolic link, shows where the
link is pointing to.
rename
oldfile
newfile
Tries to rename the oldfile
to
newfile
. If newfile
already
exists, the files are left intact.
rm
[-I, --interactive
] [-r, --recursive
] file
...
Tries to delete a file or directory specified in file
.
Options:
-I, --interactive
Prompts whether to remove a file or directory (does not work with batch mode).
-r, --recursive
Directories are removed recursively.
rmdir
directory
Tries to delete the directory specified in directory
.
This command removes the directory only if it is empty and has no subdirectories.
set
[
defaults
| [
--commands=
name1,name2,
... exit-value=
VALUE
] | option1=value1 option2=value2
...
]
Sets the default values for various parameters. The set
command
takes the following options:
defaults
Sets the parameters to be system defaults.
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. The
default is md5
(in z/OS the default is no
). Use
checkpointing when transferring large files one by one.
compatibility-mode
[
=tectia
| ftp
| openssh
]
Defines what mode of recursiveness is used in the file transfer:
tectia
The sftpg3 client transfers files recursively from the current directory and all its subdirectories. This is the default mode.
ftp
A single file is transferred, and no subdirectories are copied.
openssh
Only regular files and symbolic links from the specified directory are copied, and no subdirectories are copied.
compressions
[
=none
| zlib
]
Defines whether compression is used in file transfer:
none
Compression is not used. This is the default.
zlib
Enables zlib compression in file transfer.
exit-value=
VALUE
Defines the exit value of sftpg3 in batch mode in case of
an error. The value must be between 0 and 255. If exit-value
is
set to something else than 0 and the --commands
parameter is not
used, batch execution terminates when the first error occurs.
Example 1: If the rename command in this batch job fails, sftpg3 will stop and return exit value "6":
openuser
@host
set exit-value=6 renamefile
file2
<next command in batch job>
quit
Example 2: If you want to ignore a possible failure of a
specific command and return exit value "0" independent of the actual result of
the operation, use set exit-value=0
after the command. This
example batch job ignores possible failure in renaming a file:
openuser
@host
renamefile
file2
set exit-value=0<next command in batch job>
quit
--commands=
name1,name2,...
exit-value=
VALUE
This option makes an sftpg3 batch job abort when any
of the specified commands fail. When a command that is
not specified with this option fails, the batch job
execution continues, and the exit value of the batch job is set to the one
defined with exit-value
. Note that if
exit-value=0
, the exit value of the failed command will
be returned.
Example 3: When sftpg3 is running in batch mode, it will abort execution if a put, get, or ls command fails. If any other command (with the exceptions mentioned below) fails, execution will continue until the end of the batch file. In both cases value "3" will be returned:
set --commands=put,get,ls exit-value=3
Example 4: When sftpg3 is running in batch mode, it will abort execution when a put or get command fails. If any other command (with the exceptions mentioned below) fails, execution will continue. In any case the original exit value of the last failed command will be returned:
set --commands=put,get exit-value=0
Exceptions: When exit-value
is set
for specific commands with the --commands
option, also the
following situations will cause the batch job execution to abort:
A cd command resulting in an error
Any invalid command
Authentication failed
error
Unable to connect to server
error
Connection aborted
error
By default (set defaults
), in case of errors, sftpg3 does not stop
but instead will continue executing and return the last error message.
Invalid commands added in --commands
will be ignored.
overwrite
[
=yes
| no
]
Decides whether to overwrite existing destination file(s) (default:
yes
).
progress-display
[
=bar
| line
| no
]
Chooses the mode of displaying the progress during a file transfer operation.
The default is bar
, which shows a progress bar. Option
line
shows the progress information according to the settings
made with the progress-line-format
option. Option
no
disables progress display.
progress-line-format=
FORMAT_STRING
Chooses what information will be shown on the progress line. Use this option
when --progress-display=line
. See the definitions of contents
options in command: get --progress-line-format
.
progress-line-interval=
seconds
Defines how often the progress information is updated in line mode. The interval is given in seconds, and the default is 60 seconds.
summary-display
[
=no
| yes
| simple
| bytes
]
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. Do not use this option with
--statistics
.
See the options described for command: get
--summary-display
summary-format=
FORMAT_STRING
Chooses the format and the contents of the summary. You can use this option
when --summary-display=yes
. Do not use this option with
--statistics
.
See the definitions of contents options in command:
get --summary-format
streaming
[
=yes
| no
| force
| ext
]
Uses streaming in file transfer if the server supports it. Files smaller than
buffer_size_bytes
are not transferred using
streaming. Use force
with small files. Default:
yes
Use ext
with z/OS hosts to enable direct MVS data set access.
Use this option only when the file transfer is mainly used for mainframe data set
transfers, as it can slow down the transfer of small files in other environments.
The streaming=ext
option requires also the
checksum=no
option, because if checksums are calculated, the
file transfer uses staging, which excludes streaming.
setext
[extension
...]
Sets the file extensions that will be ASCII in the auto transfer mode. Normal zsh-fileglob regexps can be used in the file extensions.
setperm
fileperm
[:dirperm
]
Sets the default file or directory permission bits for upload. (Prefix
fileperm
with p
to preserve permissions of
existing files or directories.)
sget
[options
...] srcfile
[dstfile
]
Transfers a single specified file from the remote end to the local end under the
filename defined with dstfile
. Directories are not copied. No
wildcards can be used. Options are the same as for
get.
site
[
none
| name1=value1 name2=value2
...
]
Sets the file and data set parameters for the remote host. Parameters can be entered
either one by one, or several parameters can be delimited by spaces or commas. Both long
parameters and abbreviations can be used. When run without arguments, the
site command outputs the list of entered parameters. Setting
none
resets all parameters.
The available parameters are:
AUTOMOUNT=YES|NO|IMMED
[NO]AUTOMOUNT|[NO]AUTOM
AUTORECALL=YES|NO
[NO]AUTORECALL|[NO]AUTOR
BLKSIZE|B|BLOCKSI=
size
BLOCKS|BL
CONDDISP|CO=CATLG|UNCATLG|KEEP|DELETE
CYLINDERS|CY
DATACLAS|DA=
class
DATASET_SEQUENCE_NUMBER|SEQNUM=
number
DEFER|DE=YES|NO
[NO]DEFER|DE
DIRECTORY_SIZE|M|DI|DIRSZ=
size
EXPIRY_DATE|EXPDT=
yyddd|yyyyddd
FILE_STATUS|STATUS=NEW|MOD|SHR|OLD
FILETYPE|FILET=SEQ|JES
FIXRECFM|FI=
length
JOB_ID|JESID=
ID
JOB_OWNER|JESO=
name
JOBNAME|JESJOB=
name
KEYLEN|KEYL=
length
KEYOFF|KEYO=
offset
LABEL_TYPE|LABEL=NL|SL|NSL|SUL|BLP|LTM|AL|AUL
LIKE=
like
LRECL|R|LR=
length
MGMTCLAS|MG=
class
NORMDISP|NOR=CATLG|UNCATLG|KEEP|DELETE
PRIMARY_SPACE|PRI=
space
PROFILE|P|PROF=
profile
RECFM|O|REC=
recfm
RECORD_TRUNCATE|U|TRUN=YES|NO
[NO]TRUNCATE|[NO]TRU|[NO]TRUN
RETENTION_PERIOD|RET=
days
SECONDARY_SPACE|SE|SEC=
space
SIZE|L=
size
SPACE_RELEASE|RLSE=YES|NO
SPACE_UNIT|SU=BLKS|TRKS|CYLS|AVGRECLEN
SPACE_UNIT_LENGTH|SUL=
length
STAGING|S|STAGE=YES|NO
STORCLAS|ST=
class
SVC99_TEXT_UNITS|SVC99=
string
TRACKS|TR
TRAILING_BLANKS|TRAIL=YES|NO
[NO]TRAILINGBLANKS|[NO]TRAI|[NO]TRAIL
TRANSFER_CODESET|C|CODESET=
codeset
TRANSFER_FILE_CODESET|D|FCODESET=
codeset
TRANSFER_FILE_LINE_DELIMITER|J|FLDELIM=UNIX|MVS|MVS-FTP|DOS|MAC|NEL
TRANSFER_FORMAT|F|FORMAT=LINE|STREAM|RECORD
TRANSFER_LINE_DELIMITER|I|LDELIM=UNIX|MVS|MVS-FTP|DOS|MAC|NEL
TRANSFER_MODE|X|MODE=BIN|TEXT
TRANSFER_TRANSLATE_DSN_TEMPLATES|A|XDSNT=
templates
TRANSFER_TRANSLATE_TABLE|E|XTBL=
table
TYPE|T=PS|PO|PDS|POE|PDSE|GDG|HFS|VSAM|ESDS|KSDS|RRN
UNIT|UN=
unit
UNIT_COUNT|UC|UNC=
number
UNIT_PARALLEL|UNP=YES|NO
VOLUME_COUNT|VC|VOLCNT=
number
VOLUMES|VO|VOL=
vol1+vol2+...
sput
[options
...] srcfile
[dstfile
]
Transfers a single specified file from the local end to the remote end under the
filename defined with dstfile
. Directories are not copied. No
wildcards can be used. Options are the same as for
get.
sunique
[on
] [off
]
Stores files with unique names. If no option is specified, the command toggles the state of 'sunique'.
In case more than one of the transferred files have the same name,
this feature adds a sequential number to the end of the repeated filename, for example:
file.name
, file.name1
, and
file.name2
.
symlink
targetpath
linkpath
Creates symbolic link linkpath
, which will point to
targetpath
.
type
[
ascii
| auto
| binary
| default
]
Sets file transfer type. If type is not specified, the current file transfer type is displayed.
ascii
Transfer file in ascii mode. See ascii for more information.
auto
Transfer file in auto mode. See auto for more information.
binary
Transfer file in binary mode. See binary for more information.
default
Transfer file in binary mode. This mode is identical to
binary
except that when the server is Tectia Server for IBM z/OS, no extra
parameters are specified for the server. See
binary
for more information.
verbose
Enables verbose mode (identical to the debug 2 command). You may later disable verbose mode by debug disable.
help
[topic
]
If topic
is not given, lists the available topics. If
topic
is given, outputs available online help about the
topic.
helpall
Outputs available online help about all topics.
sftpg3 understands both backslashes (\) and quotation marks ("") on the command line. A backslash can be used for ignoring the special meaning of any character in the command-line interpretation. It will be removed even if the character it precedes has no special meaning.
When specifying filenames that contain spaces, enclose them in quotation marks.
Note | |
---|---|
Commands get . and put . will get or put every file in the current directory and possibly they overwrite files in your current directory. |
sftpg3 supports wildcard characters (also known as glob patterns) given to commands chmod, lchmod, ls, lls, rm, lrm, get, and put.
On Unix, the following key sequences can be used for command-line editing:
Set mark.
Go to the beginning of the line.
Move the cursor one character to the left.
Erase the character to the right of the cursor, or exit the program if the command line is empty.
Go to the end of the line.
Move the cursor one character to the right.
Backspace.
Tab.
Enter.
Delete the rest of the line.
Redraw the line.
Enter.
Move to the next line.
Move to the previous line.
Toggle two characters.
Delete the line.
Delete a region (the region's other end is marked with Ctrl-Space).
Begin an extended command.
Yank deleted line.
Undo.
Lower case region.
Upper case region.
Exchange cursor and mark.
Mark the whole buffer.
Undo.
Backwards word delete.
Backwards word delete.
Delete extra spaces (leaves only one space).
Go to the beginning of the line.
Go to the end of the line.
Mark current word.
Go back one sentence.
Go back one word.
Capitalize current word.
Delete current word.
Go forward one sentence.
Go forward one word.
Delete current sentence.
Change current word to lower case.
Transpose words.
Change current word to upper case.
Backspace.
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:
\/ : * ? " < > |
The sftpg3 command-line tool (both as an interactive and in a batch file) follows the syntax and semantics of Unix shell command-line also on the Windows platform, except that the escape character is ~ (tilde).
When you transfer files that have special characters in the filename (for example
unixfilename*?".txt
) from a Unix server to Windows, you need to provide
the files with new names that are acceptable on Windows.
The get command can be used to transfer several files at the same time, but it is not possible to define target filenames. Note that if there are special characters in the filenames, you need to rename the files already on Unix so that the names are acceptable also on Windows.
The sget command is used to transfer one file at a time, and it allows you to define a new name for the destination file. Use it to make the name acceptable on Windows. The command sequence is as follows:
$ sftpg3
sftp> open user@server
sftp> sget "file*name.txt" windowsfilename.txt
In the sftpg3 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 character for any number of any characters
? question mark is a wildcard for any single character
"" quotation marks are 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 sftpg3 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 any of the sftpg3 commands, add the relevant escape character to it:
\\ on Unix
~~ on Windows
When a filename or part of a filename is placed within the quotation marks "", the sftpg3 command interprets the quoted part 'as is', and none of the characters within the quote are interpreted as wildcards or as any other special characters.
However, on Unix a quotation mark " can also be part of a filename. If you need to enter the " character in a filename, you must add the escape character in front of it both on Unix and on Windows.
For example, to enter a file named file-"name".txt
into a command
on Windows, enter the following command:
sftp> sget "file-~"name~".txt" filename.txt
See the examples below to learn how the escape characters are used in the Tectia sftpg3 commands, and how to enter filenames with special characters in different operating systems.
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 sftpg3 command-line tool on Unix, enter the above mentioned filenames in the following formats:
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 or "file\\name.txt" file\ -\ name.txt or "file - name.txt" file~name.txt or "file~name.txt"
Example commands on Unix:
sftp> get "file*name.txt"
sftp> sget "file*name.txt" newfilename.txt
When using the sftpg3 command on Windows, enter the above mentioned Unix filenames in the following formats:
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 or "file\name.txt" file~ -~ name.txt or "file - name.txt" file~~name.txt or "file~~name.txt"
Example command sequence on Windows:
> sftpg3 open user@server
sftp> get "file name.txt"
sftp> sget "file*name.txt" filename.txt
sftpg3 uses the following environment variables:
startup_batch_file
Defines the path to the sftpg3 startup batch file. The file is run and the sftpg3 commands defined in the file are executed each time sftpg3 is started.
If this variable is not defined, sftpg3 looks for a startup batch
file named ssh_sftp_batch_file
in the user-specific directory
$HOME/.ssh2/
on Unix or %APPDATA%\SSH\
on
Windows.
Note that if this variable is defined but the file is missing or cannot be accessed, sftpg3 fails to start.
=yes|no|md5|sha1|md5-force|sha1-force|checkpoint
Defines the setting for comparing checksums. For more information on the available values, see checksum.
=yes|no
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 no
.
=yes|no|simple
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 simple
, file transfer statistics are shown
after the file has been transferred.
sftpg3 returns the following values based on the result 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.
In batch mode, sftpg3 returns the value 0 only if no errors occurred during the execution. A failure to change the current working directory, a failure to establish a connection, or a connection loss during batch operation cause sftpg3 to abort. Other errors are reported to stderr and the last error value is returned as the exit value of the sftpg3 process.
Open a sftpg3 session with the remote end connected to the server
defined in the connection profile profile1
in the
ssh-broker-config.xml
file (the local end is initially connected to the
file system of the SFTP client host):
$ sftpg3 profile1
Run sftpg3 in batch mode:
$ sftpg3 -B batch.txt
Example contents of the batch file batch.txt
are shown below.
Non-interactive authentication methods are used and the server host keys have been stored
beforehand:
lopen user@unixserver.example.com open user@winserver.example.com binary lcd backup cd c:/temp get --force-lower-case Testfile-X.bin lchmod 700 testfile-x.bin quit
The example batch file opens the local end of the connection to a Unix server and the
remote end to a Windows server, and sets the transfer mode to binary. It changes to local
directory backup
and remote directory
C:\Temp
, and copies a file from the remote directory to the local
directory. The filename is changed to lower-case characters
(testfile-x.bin
). After transfer, the file permissions are
changed to allow the user full rights and others no rights.