sftp.1

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