SFTP

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
INTERACTIVE COMMANDS
EXIT VALUES
EXAMPLES
COPYRIGHT
SEE ALSO

NAME

sftp - secure file transfer program.

SYNOPSIS

sftp [-4] [-6] [-b buffer_size] [-B batch_file]

[-c cipher] [-D debug_level] [-h] [-m mac_algorithm]

[-N max_requests] [-o option] [-P port] [-v] [-V] [-W]

[[user@]host[#port]]

DESCRIPTION

sftp is an interactive file transfer program that provides a secure alternative to ftp. 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 -o option to configure settings on the sftp command line. Command line options override configuration file settings.

Note: The sshd2_config(5) keyword AllowSftpCommands controls what kinds of operations users can perform using sftp. This keyword supports a comma-separated list of one or more of the following: `all', `none', `browse', `download', `upload', `delete',` rename'.

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.

Caution: All options specified on the command line (including user names, host names, and other sensitive information) will show up in a process status (ps) listing. Exercise care when specifying sensitive options and switches so that other users cannot easily see that information. A more secure alternative is to set these options in a configuration file and to protect the configuration file using recommended file permissions (configuration file = 600, directory containing the file = 700).

-4

Forces connections using IPv4 addresses only. You can also configure IP address requirements using the AddressFamily keyword.

-6

Forces connections using IPv6 addresses only. You can also configure IP address requirements using the AddressFamily keyword.

-b buffer_size

Specifies the buffer size used for data transfer. The default is 32768 bytes. The minimum allowed value is 1024. The maximum allowed value is 4194304 bytes. 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 until a bye, exit or quit command is found, 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 continues executing the remaining commands, and returns the error code of the first failed command. However, commands prefixed with "-" (dash) always return 0, even if the command fails.

-c cipher

Specifies one or more (comma-separated) encryption algorithms supported by the client. The cipher used for a given session is the cipher highest in the client's order of preference that is also supported by the server. Allowed values are `aes128-ctr', `aes128-cbc', `aes192-ctr', `aes192-cbc', `aes256-ctr', `aes256-cbc', `blowfish-cbc', `arcfour', `arcfour128', `arcfour256', `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' (all supported aes ciphers), `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 codes) are supported for this connection. Allowed values are `hmac-sha256', `hmac-sha1', `hmac-sha1-96', `hmac-md5', `hmac-md5-96', `hmac-sha512', and `hmac-ripemd160'. Use `AnyMac' to support all of these. Use `AnyStdMac' to specify `hmac-sha256, hmac-sha1,hmac-sha1-96,hmac-md5,hmac-md5-96, hmac-sha512'. Specifying hmac-sha256 also enables hmac-sha2-256. Specifying hmac-sha512 also enables hmac-sha2-512. Multiple MACs can also be specified as a comma-separated list. Additional options are `none', `any' (equivalent to AnyMac plus `none'), and `AnyStd' (equivalent to `AnyStdMac' plus `none'). 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 256.

-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"
-o key=value1,value2
-o key="value1, value2"

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'. Note: When the source and destination files are identical, no transfer occurs regardless of the value of this setting.

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

-W password_file

Specifies a file containing the password to use for the connection. Set permissions on the password file to 600; the file is not accepted if it has read or write permissions for group or other. Also, for a non-root user, the file is not accepted if there has been a change in identity (userid). This option applies only to password authentication. If AllowedAuthentications is configured to attempt keyboard-interactive before password authentication (the default), users will receive a password prompt even if a valid password file is present. To prevent this, modify the allowed authentications list to support only password authentication or to attempt password authentication before keyboard-interactive.

Note: Passphraseless public keys provide a more secure way to configure authentication without requiring user interaction, because private keys are not transmitted over the encrypted connection like passwords are.

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). If no explicit value for the remote end-of-line convention is given, the remote host is queried to provide the convention. If the remote host does not support this functionality, the DOS end-of-line convention is assumed. The only supported value for local_newline is `Unix' (\n). Use -s to display the current transfer mode.

auto

Sets the transfer mode to `auto'. In auto mode, the transfer method is determined by file extension. Files with specified file extensions use ASCII transfer; all other files use binary transfer. The default list of ASCII file types is "txt, htm*, pl, php*. To modify this list for a given sftp session, use the setext command. To change the default file extension list, use the client keyword FileCopyAsciiExtensions.

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

close

Closes the connection to the remote server without exiting sftp.

debug debug_level |disable | no

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.) Use either `disable' or `no' to disable debugging.

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.

getext

Displays the current list of file extensions that use ASCII file transfer when auto mode is enabled. Use auto to enable auto mode. Use setext to change this list for the current session. Use the client keyword FileCopyAsciiExtensions to change the default list.

help | ? [command]

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

lcd directory

Sets the local directory to directory.

lls [-1 | -a | -f | -l | -n | -r | -S | -t | --] [file]

Displays the local directory listing. The options are:

-1  (one column)
-a  (show hidden files)
-f  (do not sort)
-l  (long list format)
-n  (long list format with numeric user and group ids)
-r  (reverse order)
-S  (sort by size)
-t  (sort by file access time)
--  (treat hyphens that follow as ordinary characters.)

lmkdir directory

Creates the specified local directory.

ln

This is a synonym for symlink.

lpwd

Displays the local working directory.

ls [-1 | -a | -f | -l | -n | -r | -S | -t | --] [file ]

Displays the remote directory listing. The options are the same as for lls, and are described above.

mget

This is a synonym for get.

mkdir directory

Creates the specified remote directory.

mput

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.

setext

Specifies the current list of file extensions that use ASCII file transfer when auto mode is enabled. To specify multiple extensions, use a comma or space-separated list; this command is not cumulative. Wildcard (zsh-glob) characters are supported. Don't precede file extensions with a period. To specify extensions containing spaces, use quotation marks around the extension or use a backslash as an escape character. Use auto to enable auto mode. Use getext to display the current list. Use the client keyword FileCopyAsciiExtensions to change the default list.

symlink linked_path target_path

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

verbose

Sets the debug level to verbose mode, which is equivalent to setting the debug level to 2. To disable verbose mode, use `debug disable'.

version

Displays the supported SFTP protocol version.

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