crypto/openssh/sftp.1

   1 .\" $OpenBSD: sftp.1,v 1.69 2008/12/09 15:35:00 sobrado 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: December 9 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 Ar user Ns @ Oc Ns
  47 .Ar host Ns Op : Ns Ar
  48 .Nm sftp
  49 .Oo Ar user Ns @ Oc Ns
  50 .Ar host Ns Oo : Ns Ar dir Ns
  51 .Op Ar / Oc
  52 .Nm sftp
  53 .Fl b Ar batchfile
  54 .Oo Ar user Ns @ Oc Ns Ar host
  55 .Sh DESCRIPTION
  56 .Nm
  57 is an interactive file transfer program, similar to
  58 .Xr ftp 1 ,
  59 which performs all operations over an encrypted
  60 .Xr ssh 1
  61 transport.
  62 It may also use many features of ssh, such as public key authentication and
  63 compression.
  64 .Nm
  65 connects and logs into the specified
  66 .Ar host ,
  67 then enters an interactive command mode.
  68 .Pp
  69 The second usage format will retrieve files automatically if a non-interactive
  70 authentication method is used; otherwise it will do so after
  71 successful interactive authentication.
  72 .Pp
  73 The third usage format allows
  74 .Nm
  75 to start in a remote directory.
  76 .Pp
  77 The final usage format allows for automated sessions using the
  78 .Fl b
  79 option.
  80 In such cases, it is necessary to configure non-interactive authentication
  81 to obviate the need to enter a password at connection time (see
  82 .Xr sshd 8
  83 and
  84 .Xr ssh-keygen 1
  85 for details).
  86 The options are as follows:
  87 .Bl -tag -width Ds
  88 .It Fl 1
  89 Specify the use of protocol version 1.
  90 .It Fl B Ar buffer_size
  91 Specify the size of the buffer that
  92 .Nm
  93 uses when transferring files.
  94 Larger buffers require fewer round trips at the cost of higher
  95 memory consumption.
  96 The default is 32768 bytes.
  97 .It Fl b Ar batchfile
  98 Batch mode reads a series of commands from an input
  99 .Ar batchfile
 100 instead of
 101 .Em stdin .
 102 Since it lacks user interaction it should be used in conjunction with
 103 non-interactive authentication.
 104 A
 105 .Ar batchfile
 106 of
 107 .Sq \-
 108 may be used to indicate standard input.
 109 .Nm
 110 will abort if any of the following
 111 commands fail:
 112 .Ic get , put , rename , ln ,
 113 .Ic rm , mkdir , chdir , ls ,
 114 .Ic lchdir , chmod , chown ,
 115 .Ic chgrp , lpwd , df ,
 116 and
 117 .Ic lmkdir .
 118 Termination on error can be suppressed on a command by command basis by
 119 prefixing the command with a
 120 .Sq \-
 121 character (for example,
 122 .Ic -rm /tmp/blah* ) .
 123 .It Fl C
 124 Enables compression (via ssh's
 125 .Fl C
 126 flag).
 127 .It Fl F Ar ssh_config
 128 Specifies an alternative
 129 per-user configuration file for
 130 .Xr ssh 1 .
 131 This option is directly passed to
 132 .Xr ssh 1 .
 133 .It Fl o Ar ssh_option
 134 Can be used to pass options to
 135 .Nm ssh
 136 in the format used in
 137 .Xr ssh_config 5 .
 138 This is useful for specifying options
 139 for which there is no separate
 140 .Nm sftp
 141 command-line flag.
 142 For example, to specify an alternate port use:
 143 .Ic sftp -oPort=24 .
 144 For full details of the options listed below, and their possible values, see
 145 .Xr ssh_config 5 .
 146 .Pp
 147 .Bl -tag -width Ds -offset indent -compact
 148 .It AddressFamily
 149 .It BatchMode
 150 .It BindAddress
 151 .It ChallengeResponseAuthentication
 152 .It CheckHostIP
 153 .It Cipher
 154 .It Ciphers
 155 .It Compression
 156 .It CompressionLevel
 157 .It ConnectionAttempts
 158 .It ConnectTimeout
 159 .It ControlMaster
 160 .It ControlPath
 161 .It GlobalKnownHostsFile
 162 .It GSSAPIAuthentication
 163 .It GSSAPIDelegateCredentials
 164 .It HashKnownHosts
 165 .It Host
 166 .It HostbasedAuthentication
 167 .It HostKeyAlgorithms
 168 .It HostKeyAlias
 169 .It HostName
 170 .It IdentityFile
 171 .It IdentitiesOnly
 172 .It KbdInteractiveDevices
 173 .It LogLevel
 174 .It MACs
 175 .It NoHostAuthenticationForLocalhost
 176 .It NumberOfPasswordPrompts
 177 .It PasswordAuthentication
 178 .It Port
 179 .It PreferredAuthentications
 180 .It Protocol
 181 .It ProxyCommand
 182 .It PubkeyAuthentication
 183 .It RekeyLimit
 184 .It RhostsRSAAuthentication
 185 .It RSAAuthentication
 186 .It SendEnv
 187 .It ServerAliveInterval
 188 .It ServerAliveCountMax
 189 .It SmartcardDevice
 190 .It StrictHostKeyChecking
 191 .It TCPKeepAlive
 192 .It UsePrivilegedPort
 193 .It User
 194 .It UserKnownHostsFile
 195 .It VerifyHostKeyDNS
 196 .El
 197 .It Fl P Ar sftp_server_path
 198 Connect directly to a local sftp server
 199 (rather than via
 200 .Xr ssh 1 ) .
 201 This option may be useful in debugging the client and server.
 202 .It Fl R Ar num_requests
 203 Specify how many requests may be outstanding at any one time.
 204 Increasing this may slightly improve file transfer speed
 205 but will increase memory usage.
 206 The default is 256 outstanding requests providing for 8MB
 207 of outstanding data with a 32KB buffer.
 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 \&! Ns 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