sftp Man Page

NAME

sftp - secure file transfer program.

SYNOPSIS

sftp [-b buffer_size] [-B batch_file] [-c cipher]

[-D debug_level] [-h] [-m mac_algorithm] [-N max_requests]

[-o option] [-P port] [-v] [-V] [[user@]host[#port]]

DESCRIPTION

sftp is an interactive file transfer program that provides a secure alternative toftp. It uses authentication and encryption provided by ssh, and a Secure Shell server must be running on the remote computer. The sftp client uses the `sftp' subsystem of the server to establish and manage the secure connection.

sftp connects and logs into the specified host, then enters an interactive command mode. After a successful connection is established, you see an "sftp>" prompt and you can use any of the interactive commands documented below. To script a series of commands you can use the batch file option (-B).

Settings for sftp connections are controlled by the ssh client configuration file. For details about these settings, see the ssh2_config man page. You can also use the -ooption to configure settings on the sftp command line. Command line options override configuration file settings.

OPTIONS

Options are available in both a single-character form (such as -o) and a descriptive equivalent (--option). Single characters are shown here. To view the descriptive equivalents, use the -h command line option.

-b buffer_size

Specifies the buffer size used for data transfer. The default is 32768 bytes. The minimum allowed value is 1024. The maximum value is limited by the amount of physical memory on your computer. In most cases the default value provides close to optimal transfer speeds. On some systems, moderate increases to the buffer size can improve performance. Caution: Using very large buffer sizes rarely improves performance and can create problems including: slower transfers, transfer failures with servers that don't support very large buffers, and fatal errors when client or server memory limits are exceeded.

-B batch_file

Specifies a file to use for batch processing sftp commands. After a successful login, sftp executes each command in the specified file and then terminates the connection. Authentication methods that require user interaction are not supported in this mode. The batch file can use any of the interactive commands documented below. If a command in the batch file fails, sftp terminates and subsequent commands are not processed. You can suppress termination on error by prefixing the command with a `-' character (for example "-get /home/joe/nosuchfile").

-c cipher

Specifies one or more (comma-separated) encryption algorithm supported by the client. The client and server agree on a cipher during the key exchange portion of the connection process. The client presents a list of supported ciphers in order of preference. The cipher used for a given session is the first item in this list that is also supported by the server. Allowed values are `aes128-cbc', `blowfish-cbc', `arcfour', `arcfour128', `arcfour256', `aes192-cbc', `aes256-cbc', `cast128-cbc', and `3des-cbc'.

You can also set this value to `none'. When `none' is the agreed on cipher, data is not encrypted. Note that this method provides no confidentiality protection, and is not recommended.

The following values are provided for convenience: `aes' (which combines `aes128-cbc', `aes192-cbc', and `aes256-cbc'), `blowfish' (equivalent to `blowfish-cbc'), `cast' (equivalent to `cast128-cbc'), `3des' (equivalent to `3des-cbc'), `Any' or `AnyStd' (all available ciphers plus `none'), and `AnyCipher' or `AnyStdCipher' (all available ciphers). If no cipher is specified, the cipher is determined by the Ciphers keyword in the Secure Shell configuration file ssh2_config(5); the default is `AnyStdCipher'.

-D debug_level

Sets the debug level. Increasing the value increases the amount of information displayed. Use 1, 2, 3, or 99. (Values 4-98 are accepted, but are equivalent to 3.)

-h

Displays a brief summary of command options.

-m mac_algorithm

Specifies which MACs (message authentication algorithms) are supported for this connection. Allowed values are `hmac-sha1', `hmac-sha1-96', `hmac-md5', `hmac-md5-96'; and `hmac-ripemd160'. Use `AnyMac' to support all of these. Use `AnyStdMac' to support `hmac-sha1', `hmac-sha1-96', `hmac-md5', and `hmac-md5-96'. Additional options are `none', `any' (equivalent to AnyMac plus `none'), and `AnyStd' (equivalent to `AnyStdMac' plus `none'). Multiple MACs can also be specified as a comma-separated list. When `none' is the agreed on MAC, no message authentication code is used. Because this provides no data integrity protection, options that include `none' are not recommended.

-N max_requests

Specifies the maximum number of concurrent requests. Increasing this may slightly improve file transfer speed, but also increases memory use. The default is 16.

-o option

Sets any option that can be configured using a configuration file keyword. For a list of keywords and their meanings, see ssh2_config(5). Syntax alternatives are shown below. Use quotation marks to contain expressions that include spaces.

-o key1=value

-o key1="sample value"

-o "key1 value"

To configure multiple options, use multiple -o switches.

-o key1=value -o key2=value

--overwrite [yes|no|ask]

Specifies whether or not to overwrite existing destination files. The allowed values are `yes', `no', and `ask'. The default is `yes'.

-P port

Specifies the port to connect to on the server. The default is 22, which is the standard port for Secure Shell connections. You can also configure the port in the configuration file using the Port keyword.

-v

Sets the debug level to verbose mode, which is equivalent to setting the debug level to 2. You can also configure this in the configuration file using the VerboseMode keyword.

-V

Displays product name and version information and exits. If other options are specified on the command line, they are ignored.

INTERACTIVE COMMANDS

When you use sftp in interactive mode (no batch file specified), you see an "sftp>" prompt after a successful connection is established. You can use any of the following commands at the prompt.

ascii [-s] [remote_newline] [local_newline]

Sets the current file transfer mode to ASCII. ASCII mode is useful for translating end-of-line characters. Use remote_newline and local_newline if you need to override the default handling of new lines. Supported values for remote_newline are `DOS' (\r\n) and `Unix' (\n). The only supported value for local_newline is `Unix' (\n). Use -s to display the current transfer mode.

binary

Sets the transfer mode to binary. In this mode, files transfer without any modification. Binary is the default transfer mode. This command is useful for turning off ASCII mode within a batch script.

bye

This is a synonym for quit.

cd directory

Changes the remote directory to directory.

chgrp group file

Sets group ownership of files or directories specified by file to group. The group must be specified as a numeric group id (GID).

chmod[-R]mode file

Sets file permissions for the files or directories specified by file. The mode must be specified in numeric format (for example, 664). Use -R to change files and directories recursively.

chown owner file

Sets the owner of the files or directories specified by file to owner. The owner must be specified as a numeric user id (UID).

Closes the connection to the remote server without exiting sftp.

dir

This is a synonym for ls.

exit

This is a synonym for quit.

get [--preserve] | [-p] remote-file [remote-file ...]

Copies the specified file or files to the current local working directory. (To copy to a different location, use lcd to change the local working directory.) If a file with the same name already exists, the existing file is overwritten. Wildcards are supported, but name substitution occurs on file names only, not directories. Use either --preserve or -p to preserve file attributes and time stamps.

help [command]

Displays sftp help. Use command to display help on the specified command.

lcd directory

Sets the local directory to directory.

lls [-R | -l | -S | -r] [file]

Displays the local directory listing. Options are -R (recursive), -l (long list format), -S (sort by size; not supported on HP-UX), and -r (reverse order).

lmkdir directory

Creates the specified local directory.

This is a synonym for symlink.

lpwd

Displays the local working directory.

ls [-l | -S | -r] [file ]

Displays the remote directory listing. Options are -l (long list format), -S (sort by size; not supported on HP-UX), and -r (reverse order).

mget

This is a synonym for get.

mkdir directory

Creates the specified remote directory.

mput [--preserve] [-p] local_file [remote_file ]

This is a synonym for put.

open [-l | [user@]host]

Opens a connection to the specified host. Use -l to connect to the local host; in which case both local and remote commands act on files on the local file system.

put [--preserve] | [-p] local_file [local_file ...]

Copies the specified file or files to the current remote working directory. (To copy to a different location, use cd to change the remote working directory.) If a file with the same name already exists, the existing file is overwritten. Wildcards are supported, but name substitution occurs on file names only, not directories. Use either --preserve or -p to preserve file attributes and time stamps.

pwd

Displays the remote working directory.

quit

Exits sftp and closes the connection.

rename source destination

Renames a file from source to destination. No rename occurs if the destination file already exists.

rm file

Deletes the specified remote file or files. Wildcards are supported.

rmdir directory

Deletes the specified remote directory.

symlink linked_path target_path

Creates a symbolic link (soft) from linked_path to target_path on the remote host.

EXIT VALUES

Exit values are provided to assist in troubleshooting. In scripts we recommend that you use only zero or non-zero for error handling. Looking for specific non-zero values is not reliable because of variability caused by operating systems and servers.

0 Success.

1 An undetermined error occurred in the file copy.

2 The destination must be a directory and isn't.

4 A connection to the host could not be established.

5 The connection to the host was lost.

6 The specified file does not exist.

7 You don't have permission to access a specified file.

8 An undetermined error occurred.

9 There is a file transfer protocol mismatch.

255 An error occurred in ssh.

EXAMPLES

To create an interactive session, logging in as joe on myhost.com:

sftp joe@myhost.com

To connect to myhost, log in with the default user name, authenticate using a key specified in keyfile, and execute the sftp commands in transferbatch:

sftp -o IdentificationFile=keyfile -B transferbatch myhost