sftp.1

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