sftpg3 — Secure Shell file transfer client - Generation 3
sftpg3 (sftpg3.exe on Windows) is an
FTP-like client that can be used for 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.
However, it should be noted that sftpg3 is not designed to be a drop-in replacement for an FTP client. It is an application that implements secure file transfer functionality and has most features that common FTP applications have.
To connect to a remote host using sftpg3,
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 username and the port of the Secure Shell server
( [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.
The remote host must be running a Secure Shell version 2 server with the
sftp-server
subsystem enabled.
For information on special characters in file names, see the section called “Filename Support”.
The following options are available:
-b
buffer_size_bytes
Defines the maximum buffer size for one read/write request
(default: 32768
bytes).
-B
batch_file
Uses batch mode and executes SFTP commands from
batch_file
. 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).
-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. |
-N
max_requests
Defines the maximum number of read/write requests sent in parallel
(default: 10
).
-P
port
Connects to this Secure Shell port on the remote machine (default: 22
).
-v, --verbose
Uses verbose mode (equal to -D 2
).
--fips
Performs the checksums using the FIPS cryptographic library.
--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.
-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:
append
[-u, --unlink-source
] [--streaming
] [--force-lower-case
] 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: no
The --streaming=ext
option must be enabled with
z/OS hosts to enable direct MVS dataset access. Use this option when the
sftpg3
command 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
--force-lower-case
Destination filename will be converted to lowercase characters.
ascii
[-s
] [remote_nl_conv
] [local_nl_conv
]
Sets the transfer mode to ASCII. remote_nl_conv
sets a remote newline convention. local_nl_conv
operates on the local side, but is not as useful (the correct local
newline convention is usually compiled in, so this is mainly for testing).
Please note that these are only hints for the underlying transfer layer,
which tries to use the newline convention given by the server wherever
possible. You can set either of these to ask
, which will
cause sftpg3 to prompt you for the newline convention when
needed. The available conventions are dos
, unix
, and
mac
, using \r\n
, \n
, and
\r
as newlines, respectively.
Options:
-s
Only shows current newline convention. Does not set the transfer mode to ASCII.
auto
File transfer mode will be selected automatically from the file extension.
binary
Files will be transfered in binary mode.
break
Interrupts batch file execution. Batch file execution can be continued with the continue command.
cd
directory
Changes the current remote working directory.
chmod
[-R
] [-f
] [-v
] OCTAL-MODE
[file
...]
chmod
[-R
] [-f
] [-v
] [ugoa
] [+-=
] [rwxs
] [file
...]
Sets file permissions of the specified file or files to the bit
pattern OCTAL-MODE
or changes permissions
according to the symbolic mode [ugoa][+-=][rwxs]
. Only one
symbolic mode combination is supported.
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
.
digest
[-H, --hash
] [-o, --offset
] [-l, --length
] file
Calculates MD5 or SHA-1 digest over file data.
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.
get
[-p, --preserve-attributes
] [-u, --unlink-source
] [-I, --interactive
] [--overwrite
] [--checksum
] [-W, --whole-file
] [--checkpoint
] [--streaming
] [--force-lower-case
] [--prefix=
PREFIX
] file
...
Transfers the specified files from the remote end to the local end. Directories are recursively copied with their contents.
Options:
-p, --preserve-attributes
Tries to retain permissions and timestamps.
-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 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
.
--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: no
The --streaming=ext
option must be enabled with
z/OS hosts to enable direct MVS dataset access. Use this option when the
sftpg3
command 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
--force-lower-case
Destination filename will be converted to lowercase characters.
--prefix=
PREFIX
Adds prefix 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.
getext
Displays the extensions that will be ASCII in the auto transfer mode.
lappend
[options
...] srcfile
[dstfile
]
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
...]
Same as chmod, but operates on local files.
lclose
Closes the local connection.
ldigest
[-H, --hash
] [-o, --offset
] [-l, --length
] file
Same as digest, but operates on local files.
lls
[-R
] [-l
] [-S
] [-r
] [-p
] [-z|+z
] [file
...]
Same as ls, but operates on local files.
llsroots
Same as lsroots, but operates on local files (when the local side has been opened to a VShell server).
lmkdir
directory
Same as mkdir, but operates on local files.
lopen
hostname
| -l
Tries to connect the local side to the host
hostname
. If this is successful,
lls and friends will operate on the filesystem on that
host.
Options:
-l
Connects the local side to the local filesystem (which does not require a server).
lpwd
Prints the name of the current local working directory.
lreadlink
path
Same as readlink, but operates on local files.
lrename
oldfile
newfile
Same as rename, but operates on local files.
lrm
[options
...] file
...
Same as rm, but operates on local files.
lrmdir
directory
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 (alias for option -l
).
+z
The long output supplied by the server is used, if available.
lsite
[
none
| name1=value1 name2=value2
...
]
Same as site, but operates on local files and datasets.
lsroots
Dumps the virtual roots of the server. (This is a VShell extension. Without this you cannot know the filesystem structure of a VShell server.)
lsymlink
targetpath
linkpath
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
...
Synonymous to put.
open
hostname
| -l
Tries to connect the remote side to the host hostname
.
Options:
-l
Connects the remote side to the local filesystem (which does not require a server).
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. Directories are recursively copied with their contents. Options 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.
When renaming is used on MVS datasets on z/OS hosts, you need to define the following environment variables:
SSH_SFTP_STREAMING_MODE=ext
to activate extended streaming
SSH_SFTP_CHECKSUM_MODE=no
to deactivate the checksum mode
The checksums cannot be used with streaming, because checksum calculation requires staging, but staging and streaming are mutually exclusive.
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.
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 dataset 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:
P|profile=
PROFILE
T|type=
TYPE
O|RECfm=
RECFM
R|LRecl=
LENGTH
B|BLKsize|BLOCKSIze=
SIZE
L|size=
SIZE
M|DIrectory|directory_size=
SIZE
CYlinders
TRacks
BLocks
space_unit=
UNIT
PRImary|primary_space=
SPACE
SECondary|secondary_space=
SPACE
DATAClass|dataclas=
CLASS
MGmtclass|mgmtclas=
CLASS
STOrclass|storclas=
CLASS
keyoff=
OFFSET
keylen=
LENGTH
volumes=
VOLUMES
unit=
UNIT
like=
LIKE
X|transfer_mode=
MODE
F|transfer_format=
FORMAT
U|record_truncate=
yes|no
C|transfer_codeset=
CODESET
D|transfer_file_codeset=
CODESET
E|transfer_translate_table=
TABLE
A|transfer_translate_dsn_templates=
TEMPLATES
I|transfer_line_delimiter=
CONVENTION
J|transfer_file_line_delimiter=
CONVENTION
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.
symlink
targetpath
linkpath
Creates symbolic link linkpath
, which will point to
targetpath
.
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.
Quotation marks can be used for specifying filenames with spaces.
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 wild cards (also known as glob patterns) given to commands chmod, lchmod, ls, lls, rm, lrm, get, and put.
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:
\/ : * ? " < > |
The sftpg3 command-line tool (both as an
interactive and in a batch file) follows the syntax and semantics of Linux
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 or Linux 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 wildcards 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 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 and Linux
~~
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 SSH Tectia sftpg3 commands, 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 sftpg3 command-line tool on Unix or Linux, 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 or Linux:
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 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.
In batch mode, sftpg3 returns the value 0 only if no errors occured 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.
sftpg3 uses the following environment variables:
=<file>
Defines the path to the batch file to be run when sftpg3
is started. This can be used for example to perform a certain action before
an interactive session is started.
=sftp|ftp|openssh
Defines whether the get
and put
commands
work as the sget
and sput
commands.
sftp
- get
and put
work as usually, while sget
and sput
allow
you to define the destination file name.
ftp
- get
= sget
,
and put
= sput
openssh
- get
=
sget
, and put
=
sput
.
=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.
Open a sftpg3 session with the remote side connected
to the server defined in the connection profile profile1
in the ssh-broker-config.xml
file (the local side is intially
connected to the local filesystem):
$ 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 side of the connection to a
Unix server and the remote side 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.