Your browser does not allow this site to store cookies and other data. Some functionality on this site may not work without them. See Privacy Policy for details on how we would use cookies.

SSH Tectia

sftpg3

sftpg3 — Secure Shell file transfer client - Generation 3

Synopsis

sftpg3 [options...]
[ profile | [user@] host [#port] ]

Description

sftpg3 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. SSH Tectia Server has sftp-server enabled by default.

When defining a connection profile in the sftpg3 command, notice that SSH Tectia client tools for z/OS deduces the meaning of the argument differently depending on its format. If there is an @ sign in the given attribute value, SSH Tectia client tools for z/OS always interprets it to be <username@hostname>, i.e. not a profile.

Also, if there are dots in a profile name (for example host.x.example.com, the dots need to be escaped on command line. Enter host\.x\.example\.com, instead. Otherwise the profile name is taken as a host name and the current local user name is used for logging in.

For information on special characters in file names, see the section called “Filename Support”.

Options

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 the given batch_file. The batch file can contain any allowed SFTP commands. For a description of the commands, see the section called “Commands”.

Note that if the user has a a start-up batch file defined, this option can be used only after the start-up batch file has been run. For information on the start-up batch file, 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]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 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 as a path to a file containing the password or as a path to a program or script that outputs the password. It is also possible, but not recommended, to enter the password directly as an argument to this option.

[Caution]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.

-V, --version

Displays program version and exits.

-h, --help

Displays a short summary of command-line options and exits.

Commands

It is possible to define a start-up batch file for the sftpg3 client to make it run a set of commands immediately when started. If the user has such a file in the default location in $HOME/.ssh2/ssh_sftp_batch_file on Unix (%USERPROFILE%\Application Data\SSH\ssh_sftp_batch_file on Windows), sftpg3 reads that file during the start-up and runs the sftp commands defined in the file before letting the user give any commands on the command line or run another batch file given with the -B <file> option.

The location of the start-up batch file can be changed with environment variable SSH_SFTP_BATCH_FILE.

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 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] [--statistics-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=ext | yes | no | force

Defines streaming for file transfer. On z/OS, ext is the default and enables direct MVS dataset access. All files will use extended streaming, if not otherwise set with "--streaming".

The --streaming=ext option requires also the --checksum=no option, because if checksums are calculated, the file transfer uses staging, which excludes streaming.

Option yes means regular streaming will be used, but files smaller than buffer_size_bytes are not transferred using streaming. Use force with small files.

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 filename will be converted to lowercase characters.

The semantics of options --statistics, --statistics-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 SSH Tectia on z/OS and other hosts, this also enables automatic ASCII-EBCDIC conversion. Default conversion is between codesets ISO8859-1 and IBM-1047. File is transferred using the LINE format. The site and lsite commands can be used to change the values.

Options:

-s

Only shows the current newline convention. Does not set the transfer mode to ASCII.

remote_nl_conv [local_nl_conv]

Sets hints for the remote and local newline conventions. The local_nl_conv option operates on the local side, but notice that usually the correct local newline convention is already compiled in.

Notice that those options are only hints for the underlying transfer layer, which tries to use the actual newline convention given by the server whenever possible. You can set either of these options 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.

This command 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.

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...]

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] [--statistics] [--statistics-format] [--progress-display] [--progress-line-format] [--progress-line-interval] 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 transfer 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 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.

-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=no | yes | md5 | sha1 | md5-force | sha1-force | checkpoint

Defines whether MD5 or SHA-1 checksums or a separate checkpoint database are used to determine the point in the file where file transfer can be resumed. The default is no, meaning that checksums are not used if "--checksum" is not specified.

With option yes, SHA1 checksums are used in FIPS mode, and MD5 checksums are used otherwise. Note however, that files smaller than buffer_size_bytes are not checked. Use md5-force or sha1-force with small files. 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=ext | yes | no | force

Defines streaming for file transfer. On z/OS, ext is the default and enables direct MVS dataset access. All files will use extended streaming, if not otherwise set with "--streaming".

The --streaming=ext option requires also the --checksum=no option, because if checksums are calculated, the file transfer uses staging, which excludes streaming.

Option yes means regular streaming will be used, but files smaller than buffer_size_bytes are not transferred using streaming. Use force with small files.

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 filename will be converted to lower case characters.

--prefix=PREFIX

Adds prefix PREFIX to filename during the file transfer. The prefix is removed after the file has been successfully transferred.

--statistics= no | yes | simple | bytes

Chooses the style of the statistics to be shown after a file transfer operation. The options mean:

no - no statistics will be shown. This is the default.

yes - detailed statistics will be shown. You can configure the contents with the statistics-format option. The default statistics contents are:

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"   2008-12-19 13:10:56
"Stop: %Xy-%Xt-%Xd %Xh:%Xm:%Xs\n"    2008-12-19 13:23:30
"Time: %y\n"                         00:12:34

simple - simple one-line statistics will be shown. You can configure the contents with the statistics-format option. The default statistics contents are:

Default settings:                   Render for example this:  
"%f | %TB | %RB/s | TOC: %z\n"      file | 2.8kiB |  72kiB/s | TOC: 00:00:38

bytes - basic statistics reporting the transferred bytes will be shown. You can configure the contents with the statistics-format option. The default statistics contents are:

Default settings:                             
"Transferred %t bytes, file: '%f' -> '%F'\n"  

Render for example this:  
Transferred 12345 bytes, file: 'file1' -> 'file2'
--statistics-format= FORMAT_STRING

Chooses the format and the contents of the statistics. Use this option when --statistics=yes|simple|bytes. Select the contents for the statistics using the following definitions:

%c      - source connection: user@host#port or profile
%g      - /path/to/source/file
%f      - source file name
%e      - source parameters (file transfer and dataset parameters)
%C      - destination connection: user@host#port or profile
%G      - /path/to/destination/file
%F      - destination file name
%E      - destination parameters (file transfer and dataset parameters)
%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)
%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)
%D      - current date in format: Wed Jan 28 2009 17:11:52 +0200
%D(FMT) - current date
%x      - start date in format: Wed Jan 28 2009 17:11:52 +0200
%x(FMT) - start date
%X      - end date in format: Wed Jan 28 2009 17:11:52 +0200
%X(FMT) - end date
%y      - elapsed time
%Y      - time remaining
%z      - ETA or, if transfer has finished, TOC
%Z      - string "ETA" or, if transfer has finished, "TOC"
%Z(eta)(toc) - string "eta" or, if transfer has finished, "toc"

Above, (FMT) indicates the conversion specifications used in the strftime(3) POSIX function. Note that the supported conversion specifications vary slightly between operating systems. See your operating system documentation for details. For POSIX related specifications, see also IEEE Std 1003.1, 2004 Edition.

For example on Linux, the following conversion specifications can be used:

%a The abbreviated weekday name according to the current locale.
%A The full weekday name according to the current locale.
%b The abbreviated month name according to the current locale.
%B The full month name according to the current locale.
%c The preferred date and time representation for the current locale.
%C The century number (year/100) as a 2-digit integer.
%d The day of the month as a decimal number (range 01 to 31).
%D Equivalent to %m/%d/%y. 
%e Like %d, the day of the month as a decimal number, but a leading zero is 
   replaced by a space.
%F Equivalent to %Y-%m-%d (the ISO 8601 date format).
%G The ISO 8601 year with century as a decimal number. The 4-digit year 
   corresponding to the ISO week number (see %V). This has the same format 
   and value as %y, except that if the ISO week number belongs to the 
   previous or next year, that year is used instead.
%g Like %G, but without century, that is, with a 2-digit year (00-99).
%h Equivalent to %b.
%H The hour as a decimal number using a 24-hour clock (range 00-23).
%I The hour as a decimal number using a 12-hour clock (range 01-12).
%j The day of the year as a decimal number (range 001-366).
%k The hour (24-hour clock) as a decimal number (range 0-23);
   single digits are preceded by a blank. (See also %H.)
%l The hour (12-hour clock) as a decimal number (range 1-12);
   single digits are preceded by a blank. (See also %I.)
%m The month as a decimal number (range 01-12).
%M The minute as a decimal number (range 00-59).
%p Either `AM' or `PM' according to the given time value, or the 
   corresponding strings for the current locale. Noon is treated as `pm' 
   and midnight as `am'.
%r The time in a.m. or p.m. notation. In the POSIX locale this is equivalent 
   to %I:%M:%S%p.
%R The time in 24-hour notation (%H:%M). 
   For a version including the seconds, see %T below.
%S The second as a decimal number (range 00-60). (The range is up to 60 to 
   allow for occasional leap seconds.)
%T The time in 24-hour notation (%H:%M:%S).
%u The day of the week as a decimal, range 1 to 7, Monday being 1. See
   also %w.
%U The week number of the current year as a decimal number, range 00-53, 
   starting with the first Sunday as the first day of week 01. 
   See also %V and %W.
%V The ISO 8601:1988 week number of the current year as a decimal number, 
   range 01-53, where week 1 is the first week that has at least 4 days in 
   the current year, and with Monday as the first day of the week. 
   See also %U and %W.
%w The day of the week as a decimal, range 0-6, Sunday being 0. See also %u.
%W The week number of the current year as a decimal number, range 00-53, 
   starting with the first Monday as the first day of week 01.
%x The preferred date representation for the current locale without the time.
%X The preferred time representation for the current locale without the date.
%y The year as a decimal number without a century (range 00-99).
%Y The year as a decimal number including the century.
%z The time-zone as hour offset from GMT. Required to emit RFC 822
   conformant dates (using "%a, %d %b %Y %H:%M:%S %z").
%Z The time zone or name or abbreviation.

Other special characters in the format strings are:

\n - line feed
\t - horizontal tab
\\ - backslash
%% - a literal % sign

--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.

--progress-line-format=FORMAT_STRING

Chooses what information will be shown on the progress line. Use this option when --progress-display=line. Select the contents for the progress line using the same conversion specification options as with --statistics-format above.

--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.

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.

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 | 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=no

When at least one of the communicating parties is a z/OS host, sftpg3 checksums cannot be used, and so the default is always no.

If you need to change the sftpg3 checksum behaviour, use the command option "--checksum", instead.

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.

overwrite=yes | no

Decides whether to overwrite existing destination file(s) (default: yes).

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 with the progress-line-format option.

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.

statistics-display= no | yes | simple | bytes

Chooses the style of the statistics to be shown after a file transfer operation (default: no). See the options described for command: get --statistics.

statistics-format=FORMAT_STRING

Chooses the format and contents of the statistics. Use this command when statistics-display=yes|simple|bytes. See the definitions of contents options in command: get --statistics-format

streaming=ext | force

When at least one of the communicating parties is a z/OS host, sftpg3 streaming always defaults to ext, and extended streaming is used enabling direct MVS dataset access.

If you need to change the sftpg3 streaming behaviour, use the command option "--streaming".

By default, files smaller than buffer_size_bytes are not transferred using streaming. Use force with small files.

On z/OS, the default streaming=ext option also forces the checksum=no setting, because any checksum calculations would require staging, which in turn would exclude 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.

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:

  • A|transfer_translate_dsn_templates=TEMPLATES
  • B|BLKsize|BLOCKSIze=SIZE
  • BLocks
  • C|transfer_codeset=CODESET
  • CONDdisp=catlg|delete
  • CYlinders
  • D|transfer_file_codeset=CODESET
  • DATAClass|dataclas=CLASS
  • E|transfer_translate_table=TABLE
  • F|transfer_format=FORMAT
  • fixrecfm=LENGTH
  • fixrecfm LENGTH
  • I|transfer_line_delimiter=CONVENTION
  • J|transfer_file_line_delimiter=CONVENTION
  • keylen=LENGTH
  • keyoff=OFFSET
  • L|size=SIZE
  • like=LIKE
  • M|DIrectory|directory_size=SIZE
  • MGmtclass|mgmtclas=CLASS
  • NOTRAILingblanks
  • NOTRUNcate
  • O|RECfm=RECFM
  • P|profile=PROFILE
  • PRImary|primary_space=SPACE
  • R|LRecl=LENGTH
  • SECondary|secondary_space=SPACE
  • space_unit=UNIT
  • space_unit_length=LENGTH
  • STOrclass|storclas=CLASS
  • T|type=TYPE
  • TRacks
  • trailing_blanks=yes|no
  • TRAILingblanks
  • TRUNcate
  • U|record_truncate=yes|no
  • unit=UNIT
  • volumes=VOLUMES
  • X|transfer_mode=MODE

For a detailed description of the parameters, see Site Command.

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 datasets have the same name, this feature adds a sequencial number to the end of the repeated dataset name, for example: DS.version, DS.version1, and DS.version2.

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.

Command Interpretation

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]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.

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).

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.

Esc U

Change current word to upper case.

Delete

Backspace.

Filename Support

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 sftpg3 command-line client includes two versions of the get command:

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

Escaping special characters

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

~~ 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.

Examples of filenames in the sftpg3 commands:

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

Environment Variables

sftpg3 uses the following environment variables:

SSH_SFTP_BATCH_FILE=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.

SSH_SFTP_CHECKSUM_MODE=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.

SSH_SFTP_CMD_GETPUT_MODE=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.

SSH_DEBUG_FMT

This environment variable can be used to specify the format of the debug messages.

The default variable used is:

SSH_DEBUG_FMT="%Dd/%Dt/%Dy %Dh:%Dm:%Ds:%Df %m/%s:%n:%f %M"

It will produce an output similar to the following example:

debug: 21/08/2007 16:17:25:883 BrokerRun/broker_run.c:158: broker_start returning.

The format of the debug message is composed of flags that are percent signs (%) followed by one or more characters. If no % is used, the character will be literally printed to the debug message. The value of the flags will be shown only if the information is available.

The different flags that can be used are:

%u

Prints the uid.

%e

Prints the euid.

%p

Prints the pid.

%t

Prints the thread id.

%h

Prints the hostname.

%l

Prints the debug level.

%m

Prints the module.

%n

Prints the line.

%f

Prints the function name.

%s

Prints the file name.

%M

Prints the message.

%o

Prints the ordinal or the number of messages printed so far.

%N

Prints the new line.

%E(var)

Expands to the value of the environment variable var.

%Dx

Formats a piece of the current date, where x is one of the following

f -- milliseconds
s -- seconds
m -- minutes
h -- hours
d -- day
t -- month
y -- year
%Rx

Reports resource usage, where x is one of the following

u -- user time used by current process
U -- user time used by children that have terminated and have been waited for
s -- system time used by current process
S -- system time used by children that have terminated and have been waited for
%W(m)(i)

Enables word-wrapping of debug messages. No line of output will be longer than m characters, and every line after the first one in a message will be indented by i spaces. This does not actually output anything.

%c(n)

Just writes the character n in verbatim to the output, and it is assumed to take zero width.

%s(n)

Causes the debug module to sleep n milliseconds after the debug message has been printed. The value of n must lie between 0 and 60,000 (one minute).

%<(n)x

Gives field maximum width n to the option x.

%>(n)x

Gives field minimum width n to the option x.

%$x

Specifies alignment to right.

SSH_SFTP_HOME_MVS=yes|no

If this variable is set to yes, the sftpg3 local directory is set to USER prefix in the MVS side. If it is set to no (default), local directory is the current directory.

SSH_SFTP_OVERWRITE=yes|no

If this variable is set to yes (default), the default behavior is to overwrite existing files. If set to no, the default behavior is not to overwrite existing files.

SSH_SFTP_SHOW_BYTE_COUNT=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.

SSH_SFTP_SMF_TYPE=yes|no

If this variable is set to TYPE119, file transfers create SMF records of type 119.

SSH_SFTP_STATISTICS=yes|no|simple|bytes

If this variable is set to yes (default is no), detailed statistics are shown after a file transfer operation. Option simple outputs a one-line set of information. Option bytes outputs basic statistics reporting the transferred bytes. See the description of command --statistics above for instructions on defining the contents of the statistics to be displayed.

SSH_SFTP_STREAMING_MODE=yes|no|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.

Files

In addition to the files used by ssh-broker-g3, sftpg3 uses the following files:

$HOME/.ssh2/ssh_sftp_batch_file

On Unix, this is the default location for a user-specific start-up batch file that contains a set of sftp-related commands. sftpg3 reads this file during the start-up and runs the commands given in the file before letting the user give any commands on the command-line client.

%USERPROFILE%\Application Data\SSH\ssh_sftp_batch_file

On Windows, this is the default location for a user-specific start-up batch file that contains a set of sftp-related commands. sftpg3 reads this file during the start-up and runs the commands given in the file before letting the user give any commands on the command-line client.

$HOME/.ssh2/ssh_ftadv_config

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.

/opt/tectia/etc/ssh_ftadv_config

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.

Exit Values

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.

Examples

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.

===AUTO_SCHEMA_MARKUP===