crypto/openssh/sftp.1

   1 .\" $OpenBSD: sftp.1,v 1.88 2010/12/04 00:18:01 djm Exp $
   2 .\" $FreeBSD$
   3 .\"
   4 .\" Copyright (c) 2001 Damien Miller.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .Dd December 4, 2010
  27 .Dt SFTP 1
  28 .Os
  29 .Sh NAME
  30 .Nm sftp
  31 .Nd secure file transfer program
  32 .Sh SYNOPSIS
  33 .Nm sftp
  34 .Bk -words
  35 .Op Fl 1246Cpqrv
  36 .Op Fl B Ar buffer_size
  37 .Op Fl b Ar batchfile
  38 .Op Fl c Ar cipher
  39 .Op Fl D Ar sftp_server_path
  40 .Op Fl F Ar ssh_config
  41 .Op Fl i Ar identity_file
  42 .Op Fl l Ar limit
  43 .Op Fl o Ar ssh_option
  44 .Op Fl P Ar port
  45 .Op Fl R Ar num_requests
  46 .Op Fl S Ar program
  47 .Op Fl s Ar subsystem | sftp_server
  48 .Ar host
  49 .Ek
  50 .Nm sftp
  51 .Oo Ar user Ns @ Oc Ns
  52 .Ar host Ns Op : Ns Ar
  53 .Nm sftp
  54 .Oo
  55 .Ar user Ns @ Oc Ns
  56 .Ar host Ns Oo : Ns Ar dir Ns
  57 .Op Ar /
  58 .Oc
  59 .Nm sftp
  60 .Fl b Ar batchfile
  61 .Oo Ar user Ns @ Oc Ns Ar host
  62 .Sh DESCRIPTION
  63 .Nm
  64 is an interactive file transfer program, similar to
  65 .Xr ftp 1 ,
  66 which performs all operations over an encrypted
  67 .Xr ssh 1
  68 transport.
  69 It may also use many features of ssh, such as public key authentication and
  70 compression.
  71 .Nm
  72 connects and logs into the specified
  73 .Ar host ,
  74 then enters an interactive command mode.
  75 .Pp
  76 The second usage format will retrieve files automatically if a non-interactive
  77 authentication method is used; otherwise it will do so after
  78 successful interactive authentication.
  79 .Pp
  80 The third usage format allows
  81 .Nm
  82 to start in a remote directory.
  83 .Pp
  84 The final usage format allows for automated sessions using the
  85 .Fl b
  86 option.
  87 In such cases, it is necessary to configure non-interactive authentication
  88 to obviate the need to enter a password at connection time (see
  89 .Xr sshd 8
  90 and
  91 .Xr ssh-keygen 1
  92 for details).
  93 The options are as follows:
  94 .Bl -tag -width Ds
  95 .It Fl 1
  96 Specify the use of protocol version 1.
  97 .It Fl 2
  98 Specify the use of protocol version 2.
  99 .It Fl 4
 100 Forces
 101 .Nm
 102 to use IPv4 addresses only.
 103 .It Fl 6
 104 Forces
 105 .Nm
 106 to use IPv6 addresses only.
 107 .It Fl B Ar buffer_size
 108 Specify the size of the buffer that
 109 .Nm
 110 uses when transferring files.
 111 Larger buffers require fewer round trips at the cost of higher
 112 memory consumption.
 113 The default is 32768 bytes.
 114 .It Fl b Ar batchfile
 115 Batch mode reads a series of commands from an input
 116 .Ar batchfile
 117 instead of
 118 .Em stdin .
 119 Since it lacks user interaction it should be used in conjunction with
 120 non-interactive authentication.
 121 A
 122 .Ar batchfile
 123 of
 124 .Sq \-
 125 may be used to indicate standard input.
 126 .Nm
 127 will abort if any of the following
 128 commands fail:
 129 .Ic get , put , rename , ln ,
 130 .Ic rm , mkdir , chdir , ls ,
 131 .Ic lchdir , chmod , chown ,
 132 .Ic chgrp , lpwd , df , symlink ,
 133 and
 134 .Ic lmkdir .
 135 Termination on error can be suppressed on a command by command basis by
 136 prefixing the command with a
 137 .Sq \-
 138 character (for example,
 139 .Ic -rm /tmp/blah* ) .
 140 .It Fl C
 141 Enables compression (via ssh's
 142 .Fl C
 143 flag).
 144 .It Fl c Ar cipher
 145 Selects the cipher to use for encrypting the data transfers.
 146 This option is directly passed to
 147 .Xr ssh 1 .
 148 .It Fl D Ar sftp_server_path
 149 Connect directly to a local sftp server
 150 (rather than via
 151 .Xr ssh 1 ) .
 152 This option may be useful in debugging the client and server.
 153 .It Fl F Ar ssh_config
 154 Specifies an alternative
 155 per-user configuration file for
 156 .Xr ssh 1 .
 157 This option is directly passed to
 158 .Xr ssh 1 .
 159 .It Fl i Ar identity_file
 160 Selects the file from which the identity (private key) for public key
 161 authentication is read.
 162 This option is directly passed to
 163 .Xr ssh 1 .
 164 .It Fl l Ar limit
 165 Limits the used bandwidth, specified in Kbit/s.
 166 .It Fl o Ar ssh_option
 167 Can be used to pass options to
 168 .Nm ssh
 169 in the format used in
 170 .Xr ssh_config 5 .
 171 This is useful for specifying options
 172 for which there is no separate
 173 .Nm sftp
 174 command-line flag.
 175 For example, to specify an alternate port use:
 176 .Ic sftp -oPort=24 .
 177 For full details of the options listed below, and their possible values, see
 178 .Xr ssh_config 5 .
 179 .Pp
 180 .Bl -tag -width Ds -offset indent -compact
 181 .It AddressFamily
 182 .It BatchMode
 183 .It BindAddress
 184 .It ChallengeResponseAuthentication
 185 .It CheckHostIP
 186 .It Cipher
 187 .It Ciphers
 188 .It Compression
 189 .It CompressionLevel
 190 .It ConnectionAttempts
 191 .It ConnectTimeout
 192 .It ControlMaster
 193 .It ControlPath
 194 .It GlobalKnownHostsFile
 195 .It GSSAPIAuthentication
 196 .It GSSAPIDelegateCredentials
 197 .It HashKnownHosts
 198 .It Host
 199 .It HostbasedAuthentication
 200 .It HostKeyAlgorithms
 201 .It HostKeyAlias
 202 .It HostName
 203 .It IdentityFile
 204 .It IdentitiesOnly
 205 .It IPQoS
 206 .It KbdInteractiveDevices
 207 .It KexAlgorithms
 208 .It LogLevel
 209 .It MACs
 210 .It NoHostAuthenticationForLocalhost
 211 .It NumberOfPasswordPrompts
 212 .It PasswordAuthentication
 213 .It PKCS11Provider
 214 .It Port
 215 .It PreferredAuthentications
 216 .It Protocol
 217 .It ProxyCommand
 218 .It PubkeyAuthentication
 219 .It RekeyLimit
 220 .It RhostsRSAAuthentication
 221 .It RSAAuthentication
 222 .It SendEnv
 223 .It ServerAliveInterval
 224 .It ServerAliveCountMax
 225 .It StrictHostKeyChecking
 226 .It TCPKeepAlive
 227 .It UsePrivilegedPort
 228 .It User
 229 .It UserKnownHostsFile
 230 .It VerifyHostKeyDNS
 231 .El
 232 .It Fl P Ar port
 233 Specifies the port to connect to on the remote host.
 234 .It Fl p
 235 Preserves modification times, access times, and modes from the
 236 original files transferred.
 237 .It Fl q
 238 Quiet mode: disables the progress meter as well as warning and
 239 diagnostic messages from
 240 .Xr ssh 1 .
 241 .It Fl R Ar num_requests
 242 Specify how many requests may be outstanding at any one time.
 243 Increasing this may slightly improve file transfer speed
 244 but will increase memory usage.
 245 The default is 256 outstanding requests providing for 8MB
 246 of outstanding data with a 32KB buffer.
 247 .It Fl r
 248 Recursively copy entire directories when uploading and downloading.
 249 Note that
 250 .Nm
 251 does not follow symbolic links encountered in the tree traversal.
 252 .It Fl S Ar program
 253 Name of the
 254 .Ar program
 255 to use for the encrypted connection.
 256 The program must understand
 257 .Xr ssh 1
 258 options.
 259 .It Fl s Ar subsystem | sftp_server
 260 Specifies the SSH2 subsystem or the path for an sftp server
 261 on the remote host.
 262 A path is useful for using
 263 .Nm
 264 over protocol version 1, or when the remote
 265 .Xr sshd 8
 266 does not have an sftp subsystem configured.
 267 .It Fl v
 268 Raise logging level.
 269 This option is also passed to ssh.
 270 .El
 271 .Sh INTERACTIVE COMMANDS
 272 Once in interactive mode,
 273 .Nm
 274 understands a set of commands similar to those of
 275 .Xr ftp 1 .
 276 Commands are case insensitive.
 277 Pathnames that contain spaces must be enclosed in quotes.
 278 Any special characters contained within pathnames that are recognized by
 279 .Xr glob 3
 280 must be escaped with backslashes
 281 .Pq Sq \e .
 282 .Bl -tag -width Ds
 283 .It Ic bye
 284 Quit
 285 .Nm sftp .
 286 .It Ic cd Ar path
 287 Change remote directory to
 288 .Ar path .
 289 .It Ic chgrp Ar grp Ar path
 290 Change group of file
 291 .Ar path
 292 to
 293 .Ar grp .
 294 .Ar path
 295 may contain
 296 .Xr glob 3
 297 characters and may match multiple files.
 298 .Ar grp
 299 must be a numeric GID.
 300 .It Ic chmod Ar mode Ar path
 301 Change permissions of file
 302 .Ar path
 303 to
 304 .Ar mode .
 305 .Ar path
 306 may contain
 307 .Xr glob 3
 308 characters and may match multiple files.
 309 .It Ic chown Ar own Ar path
 310 Change owner of file
 311 .Ar path
 312 to
 313 .Ar own .
 314 .Ar path
 315 may contain
 316 .Xr glob 3
 317 characters and may match multiple files.
 318 .Ar own
 319 must be a numeric UID.
 320 .It Xo Ic df
 321 .Op Fl hi
 322 .Op Ar path
 323 .Xc
 324 Display usage information for the filesystem holding the current directory
 325 (or
 326 .Ar path
 327 if specified).
 328 If the
 329 .Fl h
 330 flag is specified, the capacity information will be displayed using
 331 "human-readable" suffixes.
 332 The
 333 .Fl i
 334 flag requests display of inode information in addition to capacity information.
 335 This command is only supported on servers that implement the
 336 .Dq statvfs@openssh.com
 337 extension.
 338 .It Ic exit
 339 Quit
 340 .Nm sftp .
 341 .It Xo Ic get
 342 .Op Fl Ppr
 343 .Ar remote-path
 344 .Op Ar local-path
 345 .Xc
 346 Retrieve the
 347 .Ar remote-path
 348 and store it on the local machine.
 349 If the local
 350 path name is not specified, it is given the same name it has on the
 351 remote machine.
 352 .Ar remote-path
 353 may contain
 354 .Xr glob 3
 355 characters and may match multiple files.
 356 If it does and
 357 .Ar local-path
 358 is specified, then
 359 .Ar local-path
 360 must specify a directory.
 361 .Pp
 362 If either the
 363 .Fl P
 364 or
 365 .Fl p
 366 flag is specified, then full file permissions and access times are
 367 copied too.
 368 .Pp
 369 If the
 370 .Fl r
 371 flag is specified then directories will be copied recursively.
 372 Note that
 373 .Nm
 374 does not follow symbolic links when performing recursive transfers.
 375 .It Ic help
 376 Display help text.
 377 .It Ic lcd Ar path
 378 Change local directory to
 379 .Ar path .
 380 .It Ic lls Op Ar ls-options Op Ar path
 381 Display local directory listing of either
 382 .Ar path
 383 or current directory if
 384 .Ar path
 385 is not specified.
 386 .Ar ls-options
 387 may contain any flags supported by the local system's
 388 .Xr ls 1
 389 command.
 390 .Ar path
 391 may contain
 392 .Xr glob 3
 393 characters and may match multiple files.
 394 .It Ic lmkdir Ar path
 395 Create local directory specified by
 396 .Ar path .
 397 .It Xo Ic ln
 398 .Op Fl s
 399 .Ar oldpath
 400 .Ar newpath
 401 .Xc
 402 Create a link from
 403 .Ar oldpath
 404 to
 405 .Ar newpath .
 406 If the
 407 .Fl s
 408 flag is specified the created link is a symbolic link, otherwise it is
 409 a hard link.
 410 .It Ic lpwd
 411 Print local working directory.
 412 .It Xo Ic ls
 413 .Op Fl 1afhlnrSt
 414 .Op Ar path
 415 .Xc
 416 Display a remote directory listing of either
 417 .Ar path
 418 or the current directory if
 419 .Ar path
 420 is not specified.
 421 .Ar path
 422 may contain
 423 .Xr glob 3
 424 characters and may match multiple files.
 425 .Pp
 426 The following flags are recognized and alter the behaviour of
 427 .Ic ls
 428 accordingly:
 429 .Bl -tag -width Ds
 430 .It Fl 1
 431 Produce single columnar output.
 432 .It Fl a
 433 List files beginning with a dot
 434 .Pq Sq \&. .
 435 .It Fl f
 436 Do not sort the listing.
 437 The default sort order is lexicographical.
 438 .It Fl h
 439 When used with a long format option, use unit suffixes: Byte, Kilobyte,
 440 Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce
 441 the number of digits to four or fewer using powers of 2 for sizes (K=1024,
 442 M=1048576, etc.).
 443 .It Fl l
 444 Display additional details including permissions
 445 and ownership information.
 446 .It Fl n
 447 Produce a long listing with user and group information presented
 448 numerically.
 449 .It Fl r
 450 Reverse the sort order of the listing.
 451 .It Fl S
 452 Sort the listing by file size.
 453 .It Fl t
 454 Sort the listing by last modification time.
 455 .El
 456 .It Ic lumask Ar umask
 457 Set local umask to
 458 .Ar umask .
 459 .It Ic mkdir Ar path
 460 Create remote directory specified by
 461 .Ar path .
 462 .It Ic progress
 463 Toggle display of progress meter.
 464 .It Xo Ic put
 465 .Op Fl Ppr
 466 .Ar local-path
 467 .Op Ar remote-path
 468 .Xc
 469 Upload
 470 .Ar local-path
 471 and store it on the remote machine.
 472 If the remote path name is not specified, it is given the same name it has
 473 on the local machine.
 474 .Ar local-path
 475 may contain
 476 .Xr glob 3
 477 characters and may match multiple files.
 478 If it does and
 479 .Ar remote-path
 480 is specified, then
 481 .Ar remote-path
 482 must specify a directory.
 483 .Pp
 484 If ether the
 485 .Fl P
 486 or
 487 .Fl p
 488 flag is specified, then full file permissions and access times are
 489 copied too.
 490 .Pp
 491 If the
 492 .Fl r
 493 flag is specified then directories will be copied recursively.
 494 Note that
 495 .Nm
 496 does not follow symbolic links when performing recursive transfers.
 497 .It Ic pwd
 498 Display remote working directory.
 499 .It Ic quit
 500 Quit
 501 .Nm sftp .
 502 .It Ic rename Ar oldpath Ar newpath
 503 Rename remote file from
 504 .Ar oldpath
 505 to
 506 .Ar newpath .
 507 .It Ic rm Ar path
 508 Delete remote file specified by
 509 .Ar path .
 510 .It Ic rmdir Ar path
 511 Remove remote directory specified by
 512 .Ar path .
 513 .It Ic symlink Ar oldpath Ar newpath
 514 Create a symbolic link from
 515 .Ar oldpath
 516 to
 517 .Ar newpath .
 518 .It Ic version
 519 Display the
 520 .Nm
 521 protocol version.
 522 .It Ic \&! Ns Ar command
 523 Execute
 524 .Ar command
 525 in local shell.
 526 .It Ic \&!
 527 Escape to local shell.
 528 .It Ic \&?
 529 Synonym for help.
 530 .El
 531 .Sh SEE ALSO
 532 .Xr ftp 1 ,
 533 .Xr ls 1 ,
 534 .Xr scp 1 ,
 535 .Xr ssh 1 ,
 536 .Xr ssh-add 1 ,
 537 .Xr ssh-keygen 1 ,
 538 .Xr glob 3 ,
 539 .Xr ssh_config 5 ,
 540 .Xr sftp-server 8 ,
 541 .Xr sshd 8
 542 .Rs
 543 .%A T. Ylonen
 544 .%A S. Lehtinen
 545 .%T "SSH File Transfer Protocol"
 546 .%N draft-ietf-secsh-filexfer-00.txt
 547 .%D January 2001
 548 .%O work in progress material
 549 .Re