Mike Lockwood | 1305e95 | 2011-12-07 08:17:59 -0800 | [diff] [blame] | 1 | SFTP(1) OpenBSD Reference Manual SFTP(1) |
| 2 | |
| 3 | NAME |
| 4 | sftp - secure file transfer program |
| 5 | |
| 6 | SYNOPSIS |
| 7 | sftp [-1246Cpqrv] [-B buffer_size] [-b batchfile] [-c cipher] |
| 8 | [-D sftp_server_path] [-F ssh_config] [-i identity_file] [-l limit] |
| 9 | [-o ssh_option] [-P port] [-R num_requests] [-S program] |
| 10 | [-s subsystem | sftp_server] host |
| 11 | sftp [user@]host[:file ...] |
| 12 | sftp [user@]host[:dir[/]] |
| 13 | sftp -b batchfile [user@]host |
| 14 | |
| 15 | DESCRIPTION |
| 16 | sftp is an interactive file transfer program, similar to ftp(1), which |
| 17 | performs all operations over an encrypted ssh(1) transport. It may also |
| 18 | use many features of ssh, such as public key authentication and |
| 19 | compression. sftp connects and logs into the specified host, then enters |
| 20 | an interactive command mode. |
| 21 | |
| 22 | The second usage format will retrieve files automatically if a non- |
| 23 | interactive authentication method is used; otherwise it will do so after |
| 24 | successful interactive authentication. |
| 25 | |
| 26 | The third usage format allows sftp to start in a remote directory. |
| 27 | |
| 28 | The final usage format allows for automated sessions using the -b option. |
| 29 | In such cases, it is necessary to configure non-interactive |
| 30 | authentication to obviate the need to enter a password at connection time |
| 31 | (see sshd(8) and ssh-keygen(1) for details). |
| 32 | |
| 33 | Since some usage formats use colon characters to delimit host names from |
| 34 | path names, IPv6 addresses must be enclosed in square brackets to avoid |
| 35 | ambiguity. |
| 36 | |
| 37 | The options are as follows: |
| 38 | |
| 39 | -1 Specify the use of protocol version 1. |
| 40 | |
| 41 | -2 Specify the use of protocol version 2. |
| 42 | |
| 43 | -4 Forces sftp to use IPv4 addresses only. |
| 44 | |
| 45 | -6 Forces sftp to use IPv6 addresses only. |
| 46 | |
| 47 | -B buffer_size |
| 48 | Specify the size of the buffer that sftp uses when transferring |
| 49 | files. Larger buffers require fewer round trips at the cost of |
| 50 | higher memory consumption. The default is 32768 bytes. |
| 51 | |
| 52 | -b batchfile |
| 53 | Batch mode reads a series of commands from an input batchfile |
| 54 | instead of stdin. Since it lacks user interaction it should be |
| 55 | used in conjunction with non-interactive authentication. A |
| 56 | batchfile of `-' may be used to indicate standard input. sftp |
| 57 | will abort if any of the following commands fail: get, put, |
| 58 | rename, ln, rm, mkdir, chdir, ls, lchdir, chmod, chown, chgrp, |
| 59 | lpwd, df, symlink, and lmkdir. Termination on error can be |
| 60 | suppressed on a command by command basis by prefixing the command |
| 61 | with a `-' character (for example, -rm /tmp/blah*). |
| 62 | |
| 63 | -C Enables compression (via ssh's -C flag). |
| 64 | |
| 65 | -c cipher |
| 66 | Selects the cipher to use for encrypting the data transfers. |
| 67 | This option is directly passed to ssh(1). |
| 68 | |
| 69 | -D sftp_server_path |
| 70 | Connect directly to a local sftp server (rather than via ssh(1)). |
| 71 | This option may be useful in debugging the client and server. |
| 72 | |
| 73 | -F ssh_config |
| 74 | Specifies an alternative per-user configuration file for ssh(1). |
| 75 | This option is directly passed to ssh(1). |
| 76 | |
| 77 | -i identity_file |
| 78 | Selects the file from which the identity (private key) for public |
| 79 | key authentication is read. This option is directly passed to |
| 80 | ssh(1). |
| 81 | |
| 82 | -l limit |
| 83 | Limits the used bandwidth, specified in Kbit/s. |
| 84 | |
| 85 | -o ssh_option |
| 86 | Can be used to pass options to ssh in the format used in |
| 87 | ssh_config(5). This is useful for specifying options for which |
| 88 | there is no separate sftp command-line flag. For example, to |
| 89 | specify an alternate port use: sftp -oPort=24. For full details |
| 90 | of the options listed below, and their possible values, see |
| 91 | ssh_config(5). |
| 92 | |
| 93 | AddressFamily |
| 94 | BatchMode |
| 95 | BindAddress |
| 96 | ChallengeResponseAuthentication |
| 97 | CheckHostIP |
| 98 | Cipher |
| 99 | Ciphers |
| 100 | Compression |
| 101 | CompressionLevel |
| 102 | ConnectionAttempts |
| 103 | ConnectTimeout |
| 104 | ControlMaster |
| 105 | ControlPath |
| 106 | GlobalKnownHostsFile |
| 107 | GSSAPIAuthentication |
| 108 | GSSAPIDelegateCredentials |
| 109 | HashKnownHosts |
| 110 | Host |
| 111 | HostbasedAuthentication |
| 112 | HostKeyAlgorithms |
| 113 | HostKeyAlias |
| 114 | HostName |
| 115 | IdentityFile |
| 116 | IdentitiesOnly |
| 117 | IPQoS |
| 118 | KbdInteractiveDevices |
| 119 | KexAlgorithms |
| 120 | LogLevel |
| 121 | MACs |
| 122 | NoHostAuthenticationForLocalhost |
| 123 | NumberOfPasswordPrompts |
| 124 | PasswordAuthentication |
| 125 | PKCS11Provider |
| 126 | Port |
| 127 | PreferredAuthentications |
| 128 | Protocol |
| 129 | ProxyCommand |
| 130 | PubkeyAuthentication |
| 131 | RekeyLimit |
| 132 | RhostsRSAAuthentication |
| 133 | RSAAuthentication |
| 134 | SendEnv |
| 135 | ServerAliveInterval |
| 136 | ServerAliveCountMax |
| 137 | StrictHostKeyChecking |
| 138 | TCPKeepAlive |
| 139 | UsePrivilegedPort |
| 140 | User |
| 141 | UserKnownHostsFile |
| 142 | VerifyHostKeyDNS |
| 143 | |
| 144 | -P port |
| 145 | Specifies the port to connect to on the remote host. |
| 146 | |
| 147 | -p Preserves modification times, access times, and modes from the |
| 148 | original files transferred. |
| 149 | |
| 150 | -q Quiet mode: disables the progress meter as well as warning and |
| 151 | diagnostic messages from ssh(1). |
| 152 | |
| 153 | -R num_requests |
| 154 | Specify how many requests may be outstanding at any one time. |
| 155 | Increasing this may slightly improve file transfer speed but will |
| 156 | increase memory usage. The default is 64 outstanding requests. |
| 157 | |
| 158 | -r Recursively copy entire directories when uploading and |
| 159 | downloading. Note that sftp does not follow symbolic links |
| 160 | encountered in the tree traversal. |
| 161 | |
| 162 | -S program |
| 163 | Name of the program to use for the encrypted connection. The |
| 164 | program must understand ssh(1) options. |
| 165 | |
| 166 | -s subsystem | sftp_server |
| 167 | Specifies the SSH2 subsystem or the path for an sftp server on |
| 168 | the remote host. A path is useful for using sftp over protocol |
| 169 | version 1, or when the remote sshd(8) does not have an sftp |
| 170 | subsystem configured. |
| 171 | |
| 172 | -v Raise logging level. This option is also passed to ssh. |
| 173 | |
| 174 | INTERACTIVE COMMANDS |
| 175 | Once in interactive mode, sftp understands a set of commands similar to |
| 176 | those of ftp(1). Commands are case insensitive. Pathnames that contain |
| 177 | spaces must be enclosed in quotes. Any special characters contained |
| 178 | within pathnames that are recognized by glob(3) must be escaped with |
| 179 | backslashes (`\'). |
| 180 | |
| 181 | bye Quit sftp. |
| 182 | |
| 183 | cd path |
| 184 | Change remote directory to path. |
| 185 | |
| 186 | chgrp grp path |
| 187 | Change group of file path to grp. path may contain glob(3) |
| 188 | characters and may match multiple files. grp must be a numeric |
| 189 | GID. |
| 190 | |
| 191 | chmod mode path |
| 192 | Change permissions of file path to mode. path may contain |
| 193 | glob(3) characters and may match multiple files. |
| 194 | |
| 195 | chown own path |
| 196 | Change owner of file path to own. path may contain glob(3) |
| 197 | characters and may match multiple files. own must be a numeric |
| 198 | UID. |
| 199 | |
| 200 | df [-hi] [path] |
| 201 | Display usage information for the filesystem holding the current |
| 202 | directory (or path if specified). If the -h flag is specified, |
| 203 | the capacity information will be displayed using "human-readable" |
| 204 | suffixes. The -i flag requests display of inode information in |
| 205 | addition to capacity information. This command is only supported |
| 206 | on servers that implement the ``statvfs@openssh.com'' extension. |
| 207 | |
| 208 | exit Quit sftp. |
| 209 | |
| 210 | get [-Ppr] remote-path [local-path] |
| 211 | Retrieve the remote-path and store it on the local machine. If |
| 212 | the local path name is not specified, it is given the same name |
| 213 | it has on the remote machine. remote-path may contain glob(3) |
| 214 | characters and may match multiple files. If it does and |
| 215 | local-path is specified, then local-path must specify a |
| 216 | directory. |
| 217 | |
| 218 | If either the -P or -p flag is specified, then full file |
| 219 | permissions and access times are copied too. |
| 220 | |
| 221 | If the -r flag is specified then directories will be copied |
| 222 | recursively. Note that sftp does not follow symbolic links when |
| 223 | performing recursive transfers. |
| 224 | |
| 225 | help Display help text. |
| 226 | |
| 227 | lcd path |
| 228 | Change local directory to path. |
| 229 | |
| 230 | lls [ls-options [path]] |
| 231 | Display local directory listing of either path or current |
| 232 | directory if path is not specified. ls-options may contain any |
| 233 | flags supported by the local system's ls(1) command. path may |
| 234 | contain glob(3) characters and may match multiple files. |
| 235 | |
| 236 | lmkdir path |
| 237 | Create local directory specified by path. |
| 238 | |
| 239 | ln [-s] oldpath newpath |
| 240 | Create a link from oldpath to newpath. If the -s flag is |
| 241 | specified the created link is a symbolic link, otherwise it is a |
| 242 | hard link. |
| 243 | |
| 244 | lpwd Print local working directory. |
| 245 | |
| 246 | ls [-1afhlnrSt] [path] |
| 247 | Display a remote directory listing of either path or the current |
| 248 | directory if path is not specified. path may contain glob(3) |
| 249 | characters and may match multiple files. |
| 250 | |
| 251 | The following flags are recognized and alter the behaviour of ls |
| 252 | accordingly: |
| 253 | |
| 254 | -1 Produce single columnar output. |
| 255 | |
| 256 | -a List files beginning with a dot (`.'). |
| 257 | |
| 258 | -f Do not sort the listing. The default sort order is |
| 259 | lexicographical. |
| 260 | |
| 261 | -h When used with a long format option, use unit suffixes: |
| 262 | Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte, |
| 263 | and Exabyte in order to reduce the number of digits to |
| 264 | four or fewer using powers of 2 for sizes (K=1024, |
| 265 | M=1048576, etc.). |
| 266 | |
| 267 | -l Display additional details including permissions and |
| 268 | ownership information. |
| 269 | |
| 270 | -n Produce a long listing with user and group information |
| 271 | presented numerically. |
| 272 | |
| 273 | -r Reverse the sort order of the listing. |
| 274 | |
| 275 | -S Sort the listing by file size. |
| 276 | |
| 277 | -t Sort the listing by last modification time. |
| 278 | |
| 279 | lumask umask |
| 280 | Set local umask to umask. |
| 281 | |
| 282 | mkdir path |
| 283 | Create remote directory specified by path. |
| 284 | |
| 285 | progress |
| 286 | Toggle display of progress meter. |
| 287 | |
| 288 | put [-Ppr] local-path [remote-path] |
| 289 | Upload local-path and store it on the remote machine. If the |
| 290 | remote path name is not specified, it is given the same name it |
| 291 | has on the local machine. local-path may contain glob(3) |
| 292 | characters and may match multiple files. If it does and |
| 293 | remote-path is specified, then remote-path must specify a |
| 294 | directory. |
| 295 | |
| 296 | If either the -P or -p flag is specified, then full file |
| 297 | permissions and access times are copied too. |
| 298 | |
| 299 | If the -r flag is specified then directories will be copied |
| 300 | recursively. Note that sftp does not follow symbolic links when |
| 301 | performing recursive transfers. |
| 302 | |
| 303 | pwd Display remote working directory. |
| 304 | |
| 305 | quit Quit sftp. |
| 306 | |
| 307 | rename oldpath newpath |
| 308 | Rename remote file from oldpath to newpath. |
| 309 | |
| 310 | rm path |
| 311 | Delete remote file specified by path. |
| 312 | |
| 313 | rmdir path |
| 314 | Remove remote directory specified by path. |
| 315 | |
| 316 | symlink oldpath newpath |
| 317 | Create a symbolic link from oldpath to newpath. |
| 318 | |
| 319 | version |
| 320 | Display the sftp protocol version. |
| 321 | |
| 322 | !command |
| 323 | Execute command in local shell. |
| 324 | |
| 325 | ! Escape to local shell. |
| 326 | |
| 327 | ? Synonym for help. |
| 328 | |
| 329 | SEE ALSO |
| 330 | ftp(1), ls(1), scp(1), ssh(1), ssh-add(1), ssh-keygen(1), glob(3), |
| 331 | ssh_config(5), sftp-server(8), sshd(8) |
| 332 | |
| 333 | T. Ylonen and S. Lehtinen, SSH File Transfer Protocol, |
| 334 | draft-ietf-secsh-filexfer-00.txt, January 2001, work in progress |
| 335 | material. |
| 336 | |
| 337 | OpenBSD 5.0 August 7, 2011 OpenBSD 5.0 |