SFTP2(1) SSH2 SFTP2(1)
NAME
sftp2 - secure FTP client on z/OS
SYNOPSIS
sftp2 [-v] [-D debug_level_spec] [-B batchfile] [-S path]
[-h] [-P port] [-b buffer_size] [-N max_requests] [-V] [-4
] [-6 ] [-c cipher] [-m MAC] [-o ssh-option]
[user@]host[#port]
DESCRIPTION
sftp2 is an FTP-like client that can be used for secure
file transfer over the network. sftp2 uses ssh2 to secure
traffic. Even though sftp works like ftp, it does not use
the FTP daemon (ftpd or wu-ftpd) for connections.
In order to connect using sftp2, you need to make sure
that sshd2 is running on the remote machine you are con-
necting to. sftp2 uses a "subsystem" of sshd2 to transfer
files securely. See sshd2(8).
OPTIONS
-v Verbose mode. Equivalent to the -D 2 option.
-D debug_level_spec
Debug mode. Makes sftp2 send verbose debug output
to stderr. The debugging level is a number (0-99).
-B batchfile
Batch mode. Reads commands from a file instead of
standard input. Since this mode is intended for
scripts/cronjobs, sftp2 will not try to interact
with the user, which means that only passwordless
authentication methods will work. In batch mode, a
failure to change the current working directory
will cause sftp2 to abort. Other errors are
ignored.
-S path
Specifies the path to the ssh2 binary.
-h Prints usage information and exits.
-P port
Port to connect to on the remote host. This option
can also be specified in the configuration file.
-b buffer_size
Defines the maximum buffer size for one request
(default 32768 bytes).
SSH2 14 August 2007 1
SFTP2(1) SSH2 SFTP2(1)
-N max_requests
Defines the maximum number of concurrent requests
(default 10).
-V Prints the version and exits.
-4 Instructs ssh2 to use IPv4.
-6 Instructs ssh2 to use IPv6.
-c cipher
Selects the encryption algorithm. See ssh2(1) for
more information.
-m MAC Selects the MAC (Message Authentication Code) algo-
rithm. See ssh2(1) for more information.
-o ssh-options
Can be used to give options in the format used in
the ssh2_config file. This is useful for specify-
ing options for which there is no separate command-
line flag. The option has the same format as a
line in the configuration file. Comment lines are
not accepted. Where applicable, egrep regex format
is used.
user Specifies the username to use when connecting.
(Optional)
host Specifies the host to connect to.
port Specifies the port on the host to connect to.
(Optional)
COMMANDS
When sftp2 is ready to accept commands, it will display
the prompt sftp> . The user can then enter any of the
following commands.
open -l or open hostname
Tries to connect to a host specified with hostname.
With the -l parameter, the "remote" end is opened
to the localhost (without connecting to an sshd2
daemon), after which for example ls can be used to
show the contents of the local file system.
lopen -l or lopen hostname
Tries to connect to a host specified with hostname.
With the -l parameter, the "local" end is opened to
the localhost (without connecting to an sshd2 dae-
mon), after which for example lls can be used to
show the contents of the local file system. The
command localopen is a synonym for this command.
SSH2 14 August 2007 2
SFTP2(1) SSH2 SFTP2(1)
close Closes the remote connection.
lclose Closes the local connection.
quit Quits the application.
cd directory
Changes the current remote working directory.
lcd directory
Changes the current local working directory.
pwd Prints the name of the current remote working
directory.
lpwd Prints the name of the current local working direc-
tory.
ls [-R] [-l [-z]] [-S] [-r] [file ...]
Lists the names of the files on the remote server.
For directories, the contents of the directory are
listed. When the -R option is specified, all direc-
tories are listed recursively. (By default, the
subdirectories of the argument directories are not
visited.) With -l, permissions, owners, sizes and
modification times are displayed. With -z, the long
format listing is generated by the client, other-
wise sftp2 shows the server generated string, if
available (with the server generated string, times-
tamps are in the server's locale; however, the
client generated string doesn't have usernames or
groups (this is a limitation in the SFTPv3 proto-
col)). This behaviour can be made default by set-
ting environment variable SSH_SFTP_LS_LONG_FORMAT
to "client" (without the quotes). If -S is given,
sorting is done based on file sizes (default:
alphabetically). If -r is given, the sort order is
reversed. When no file arguments are given, the
contents of the current working directory are
listed.
lls [options] [ file ... ]
Same as ls, but operates on local files.
get [--preserve-attributes] [-p] [--overwrite] [-I]
[--interac- tive] [--whole-file] [-W] [--checksum]
[-c] [--force-lower-case] [file ...]
Transfers the specified files from the remote end
to the local end. Directories are recursively
copied with their contents. If -p,--preserve-
attributes is given, sftp tries to retain permis-
sions and timestamps. --overwrite specifies whether
to overwrite existing destination file(s). Default
is to overwrite. -I,--interactive prompts whether
SSH2 14 August 2007 3
SFTP2(1) SSH2 SFTP2(1)
to overwrite an existing destination file (does not
work with batch mode). --force-lower-case will
cause the destination filename to be in lower case.
Only ASCII characters will be affected. If
-W,--whole-file is given, incremental checksums are
not made. If -c,--checksum is given, and source and
destination files have the same size, an MD5 check-
sum is done to determine whether the file needs to
be transferred (default: do checksum). All switches
can be toggled with no as an attribute [example:
--checksum=no].
mget [options] [file ...]
Synonymous to get.
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.
mput [options] [file ...]
Synonymous to put.
sget [--preserve-attributes] [-p] [--overwrite] [-I]
[--interac- tive] [--whole-file] [-W] [--checksum]
[-c] [--force-lower-case] source_file destina-
tion_file
Transfers single file from the remote end to the
local end. Directories are not copied. Globbing is
not performed. If -p,--preserve-attributes is
given, sftp tries to retain permissions and times-
tamps. --overwrite specifies whether to overwrite
existing destination file(s). Default is to over-
write. -I,--interactive prompts whether to over-
write an existing destination file (does not work
with batch mode). --force-lower-case will cause the
destination filename to be in lower case. Only
ASCII characters will be affected. If -W,--whole-
file is given, incremental checksums are not made.
If -c,--checksum is given, and source and destina-
tion files have the same size, an MD5 checksum is
done to determine whether the file needs to be
transferred (default: do checksum). All switches
can be toggled with no as an attribute [example:
--checksum=no].
sput [options] source_file destination_file
Transfers single file from the local end to the
remote end. Directories are not copied. Globbing
is not performed. Options are the same as for sget.
rename source target
Renames the file source to target. If target
SSH2 14 August 2007 4
SFTP2(1) SSH2 SFTP2(1)
already exists, the files are left intact.
lrename source target
Same as rename, but operates on local files.
rm file
Tries to delete the specified file.
lrm file
Same as rm, but operates on local files.
mkdir directory
Tries to create the specified directory.
lmkdir directory
Same as mkdir, but operates on local files.
rmdir directory
Tries to delete the specified directory.
lrmdir directory
Same as rmdir, but operates on local files.
help [topic]
Lists online help on topic. If topic is not given,
lists the available topics.
lsroots
Dumps the virtual roots of the server. This is an
extension required by older versions of VShell
(from VanDyke Software), and only usable against
it. SSH Tectia Server (Windows version) displays
the file system roots in the Unix style, and does
not require this extension.
ascii [-s] [-f] [<remote_nl_conv>] [<local_nl_conv>]
With the -s option, shows the current newline con-
vention. <remote_nl_conv> sets the remote newline
convention. <local_nl_conv> operates on the local
side, but is not as useful (the correct local new-
line 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 sftp to prompt you
for the newline convention when needed. With the
exception of the -s option, this command sets the
transfer mode to ASCII, i.e. newlines will be con-
verted according to the conventions. Available con-
ventions are dos, unix, and mac, using "\r\n",
"\n", and "\r" as newlines, respectively.
binary Files will be transferred unmodified.
SSH2 14 August 2007 5
SFTP2(1) SSH2 SFTP2(1)
auto Files whose extension matches the one set with
setext will be transferred using ASCII mode. Other
files will be transferred unmodified.
setext <extension> [<extension> ...]
Set the file types which will be transferred in
ASCII mode, if the transfer mode is auto. Standard
zsh-fileglob regexs can be used for matching (only
the file extension is matched, i.e. extension "*ml"
matches with files foo.html and bar.ml.
getext Displays the extensions of files which will be
transferred using ASCII (newline) conversion in the
auto transfer mode.
chmod [options] OCTAL-MODE [<file> ...]
chmod [options] [ugoa][+-=][rwxs] [<file> ...]
Sets file permissions of the specified file or
files to the bit pattern OCTAL-MODE or changes per-
missions according to the symbolic mode
[ugoa][+-=][rwxs].
Only one symbolic mode combination is supported.
Options are:
-R recursive (recursively changes files and
directories
-f silent (error messages suppressed)
-v verbose (lists every file processed)
lchmod Same as chmod, but operates on local files
! [<command> [<args>]]
Invokes an interactive shell on the local machine.
If <command> is given, it is used as the command to
be executed. Optional <args> are used as arguments
to the command.
COMMAND INTERPRETATION
sftp2 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 file names with
spaces.
The command-line processing and globbing use the same
escape character (a backslash), so if you want to use a
backslash to escape the meta-characters in the globbing,
you have to precede the backslash with another backslash
to escape its special meaning from the command-line
SSH2 14 August 2007 6
SFTP2(1) SSH2 SFTP2(1)
processor.
Warning: If you do get . or put . you will get or put
every file in the current directory and possibly override
files in your current directory.
GLOB PATTERNS
sftp2 supports glob patterns (wildcards) given to commands
ls, lls, get, and put. The format is described in the man
page sshregex(1).
COMMAND-LINE EDITING
The following key sequences can be used for command-line
editing:
Ctrl-Space
Set mark.
Ctrl-A Go to the beginning of the line.
Ctrl-B Move the cursor one character to the left.
Ctrl-D Erase the character to the right of the cursor, or
exit the program if the command line is empty.
Ctrl-E Go to the end of the line.
Ctrl-F Move the cursor one character to the right.
Ctrl-H Backspace.
Ctrl-I Tab.
Ctrl-J Enter.
Ctrl-K Delete the rest of the line.
Ctrl-L Redraw the line.
Ctrl-M Enter.
Ctrl-N Move to the next line.
Ctrl-P Move to the previous line.
Ctrl-T Toggle two characters.
Ctrl-U Delete the line.
Ctrl-W Delete a region (the region's other end is marked
with Ctrl-Space).
SSH2 14 August 2007 7
SFTP2(1) SSH2 SFTP2(1)
Ctrl-X Begin an extended command.
Ctrl-Y Yank deleted line.
Ctrl-_ Undo.
Ctrl-X Ctrl-L
Lower case region.
Ctrl-X Ctrl-U
Upper case region.
Ctrl-X Ctrl-X
Exchange cursor and mark.
Ctrl-X H
Mark the whole buffer.
Ctrl-X U
Undo.
Esc Ctrl-H
Backwards word delete.
Esc Delete
Backwards word delete.
Esc Space
Delete extra spaces (leaves only one space).
Esc < Go to the beginning of the line.
Esc > Go to the end of the line.
Esc @ Mark current word.
Esc A Go back one sentence.
Esc B Go back one word.
Esc C Capitalize current word.
Esc D Delete current word.
Esc E Go forward one sentence.
Esc F Go forward one word.
Esc K Delete current sentence.
Esc L Change current word to lower case.
Esc T Transpose words.
SSH2 14 August 2007 8
SFTP2(1) SSH2 SFTP2(1)
Esc U Change current word to upper case.
Delete Backspace.
EXIT VALUES
sftp2 returns the following values based on the success of
the operation:
0 Operation was successful.
1 Operation resulted in an undetermined error within
sshfilecopy.
2 Destination is not a directory, but a directory was
specified by the user.
3 Maximum symlink level exceeded.
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.
9 File transfer protocol mismatch.
In batch mode, sftp2 returns the value 0 only if no errors
occured during the execution. A failure to change the cur-
rent working directory, a failure to establish a connec-
tion, or a connection loss during batch operation cause
sftp2 to abort. Other errors are reported to stderr and
the greatest of the error values is returned as the exit
value of the sftp2 process.
Note that when the command is run from JCL using BPXBATCH,
the exit values are multiplied by 256.
ENVIRONMENT
sftp2 uses the following environment variables:
SSH_SFTP_CMD_GETPUT_MODE
Specify the ftp compatibility mode for get and put
commands. If the variable is set to ftp, the com-
mands behave as in ftp client. See commands sget
and sput.
SSH_SFTP_OVERWRITE
If this variable is set to yes, the default behav-
ior is to overwrite existing files. If set to no,
the default behavior is not to overwrite existing
files.
SSH_SFTP_SHOW_BYTE_COUNT
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
SSH2 14 August 2007 9
SFTP2(1) SSH2 SFTP2(1)
files are shown.
SSH_SFTP_SMF_TYPE
If this variable is set to TYPE119, file transfers
create SMF records of type 119.
SSH_SFTP_ADVISOR_xxx
This is a number of variables where the xxx is one
of the file transfer attributes (see the SSH Tectia
Server for IBM z/OS Administrator Manual, chapter
"Advice String"). The variables apply to processing
local files and they set default values that can be
overridden on Advice Strings.
FILES
In addition to the files used by ssh2, sftp2 uses the fol-
lowing file:
$HOME/.ssh2/ssh_ftadv_config
Contains file transfer profiles which furnish file
transfer attributes to be used when processing
local files. See the SSH Tectia Server for IBM z/OS
Administrator Manual, chapter "File Transfer Pro-
files".
AUTHORS
SSH Communications Security Corp.
For more information, see http://www.ssh.com.
SEE ALSO
sshregex(1), ssh2(1), sshd2(8), ssh-keygen2(1), ssh-
agent2(1), ssh-add2(1), scp2(1)
SSH2 14 August 2007 10