openssh/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 256 outstanding requests providing for 8MB
 208 of outstanding data with a 32KB buffer.
 209 .It Fl S Ar program
 210 Name of the
 211 .Ar program
 212 to use for the encrypted connection.
 213 The program must understand
 214 .Xr ssh 1
 215 options.
 216 .It Fl s Ar subsystem | sftp_server
 217 Specifies the SSH2 subsystem or the path for an sftp server
 218 on the remote host.
 219 A path is useful for using
 220 .Nm
 221 over protocol version 1, or when the remote
 222 .Xr sshd 8
 223 does not have an sftp subsystem configured.
 224 .It Fl v
 225 Raise logging level.
 226 This option is also passed to ssh.
 227 .El
 228 .Sh INTERACTIVE COMMANDS
 229 Once in interactive mode,
 230 .Nm
 231 understands a set of commands similar to those of
 232 .Xr ftp 1 .
 233 Commands are case insensitive.
 234 Pathnames that contain spaces must be enclosed in quotes.
 235 Any special characters contained within pathnames that are recognized by
 236 .Xr glob 3
 237 must be escaped with backslashes
 238 .Pq Sq \e .
 239 .Bl -tag -width Ds
 240 .It Ic bye
 241 Quit
 242 .Nm sftp .
 243 .It Ic cd Ar path
 244 Change remote directory to
 245 .Ar path .
 246 .It Ic chgrp Ar grp Ar path
 247 Change group of file
 248 .Ar path
 249 to
 250 .Ar grp .
 251 .Ar path
 252 may contain
 253 .Xr glob 3
 254 characters and may match multiple files.
 255 .Ar grp
 256 must be a numeric GID.
 257 .It Ic chmod Ar mode Ar path
 258 Change permissions of file
 259 .Ar path
 260 to
 261 .Ar mode .
 262 .Ar path
 263 may contain
 264 .Xr glob 3
 265 characters and may match multiple files.
 266 .It Ic chown Ar own Ar path
 267 Change owner of file
 268 .Ar path
 269 to
 270 .Ar own .
 271 .Ar path
 272 may contain
 273 .Xr glob 3
 274 characters and may match multiple files.
 275 .Ar own
 276 must be a numeric UID.
 277 .It Xo Ic df
 278 .Op Fl hi
 279 .Op Ar path
 280 .Xc
 281 Display usage information for the filesystem holding the current directory
 282 (or
 283 .Ar path
 284 if specified).
 285 If the
 286 .Fl h
 287 flag is specified, the capacity information will be displayed using
 288 "human-readable" suffixes.
 289 The
 290 .Fl i
 291 flag requests display of inode information in addition to capacity information.
 292 This command is only supported on servers that implement the
 293 .Dq statvfs@openssh.com
 294 extension.
 295 .It Ic exit
 296 Quit
 297 .Nm sftp .
 298 .It Xo Ic get
 299 .Op Fl P
 300 .Ar remote-path
 301 .Op Ar local-path
 302 .Xc
 303 Retrieve the
 304 .Ar remote-path
 305 and store it on the local machine.
 306 If the local
 307 path name is not specified, it is given the same name it has on the
 308 remote machine.
 309 .Ar remote-path
 310 may contain
 311 .Xr glob 3
 312 characters and may match multiple files.
 313 If it does and
 314 .Ar local-path
 315 is specified, then
 316 .Ar local-path
 317 must specify a directory.
 318 If the
 319 .Fl P
 320 flag is specified, then full file permissions and access times are
 321 copied too.
 322 .It Ic help
 323 Display help text.
 324 .It Ic lcd Ar path
 325 Change local directory to
 326 .Ar path .
 327 .It Ic lls Op Ar ls-options Op Ar path
 328 Display local directory listing of either
 329 .Ar path
 330 or current directory if
 331 .Ar path
 332 is not specified.
 333 .Ar ls-options
 334 may contain any flags supported by the local system's
 335 .Xr ls 1
 336 command.
 337 .Ar path
 338 may contain
 339 .Xr glob 3
 340 characters and may match multiple files.
 341 .It Ic lmkdir Ar path
 342 Create local directory specified by
 343 .Ar path .
 344 .It Ic ln Ar oldpath Ar newpath
 345 Create a symbolic link from
 346 .Ar oldpath
 347 to
 348 .Ar newpath .
 349 .It Ic lpwd
 350 Print local working directory.
 351 .It Xo Ic ls
 352 .Op Fl 1aflnrSt
 353 .Op Ar path
 354 .Xc
 355 Display a remote directory listing of either
 356 .Ar path
 357 or the current directory if
 358 .Ar path
 359 is not specified.
 360 .Ar path
 361 may contain
 362 .Xr glob 3
 363 characters and may match multiple files.
 364 .Pp
 365 The following flags are recognized and alter the behaviour of
 366 .Ic ls
 367 accordingly:
 368 .Bl -tag -width Ds
 369 .It Fl 1
 370 Produce single columnar output.
 371 .It Fl a
 372 List files beginning with a dot
 373 .Pq Sq \&. .
 374 .It Fl f
 375 Do not sort the listing.
 376 The default sort order is lexicographical.
 377 .It Fl l
 378 Display additional details including permissions
 379 and ownership information.
 380 .It Fl n
 381 Produce a long listing with user and group information presented
 382 numerically.
 383 .It Fl r
 384 Reverse the sort order of the listing.
 385 .It Fl S
 386 Sort the listing by file size.
 387 .It Fl t
 388 Sort the listing by last modification time.
 389 .El
 390 .It Ic lumask Ar umask
 391 Set local umask to
 392 .Ar umask .
 393 .It Ic mkdir Ar path
 394 Create remote directory specified by
 395 .Ar path .
 396 .It Ic progress
 397 Toggle display of progress meter.
 398 .It Xo Ic put
 399 .Op Fl P
 400 .Ar local-path
 401 .Op Ar remote-path
 402 .Xc
 403 Upload
 404 .Ar local-path
 405 and store it on the remote machine.
 406 If the remote path name is not specified, it is given the same name it has
 407 on the local machine.
 408 .Ar local-path
 409 may contain
 410 .Xr glob 3
 411 characters and may match multiple files.
 412 If it does and
 413 .Ar remote-path
 414 is specified, then
 415 .Ar remote-path
 416 must specify a directory.
 417 If the
 418 .Fl P
 419 flag is specified, then the file's full permission and access time are
 420 copied too.
 421 .It Ic pwd
 422 Display remote working directory.
 423 .It Ic quit
 424 Quit
 425 .Nm sftp .
 426 .It Ic rename Ar oldpath Ar newpath
 427 Rename remote file from
 428 .Ar oldpath
 429 to
 430 .Ar newpath .
 431 .It Ic rm Ar path
 432 Delete remote file specified by
 433 .Ar path .
 434 .It Ic rmdir Ar path
 435 Remove remote directory specified by
 436 .Ar path .
 437 .It Ic symlink Ar oldpath Ar newpath
 438 Create a symbolic link from
 439 .Ar oldpath
 440 to
 441 .Ar newpath .
 442 .It Ic version
 443 Display the
 444 .Nm
 445 protocol version.
 446 .It Ic \&! Ar command
 447 Execute
 448 .Ar command
 449 in local shell.
 450 .It Ic \&!
 451 Escape to local shell.
 452 .It Ic \&?
 453 Synonym for help.
 454 .El
 455 .Sh SEE ALSO
 456 .Xr ftp 1 ,
 457 .Xr ls 1 ,
 458 .Xr scp 1 ,
 459 .Xr ssh 1 ,
 460 .Xr ssh-add 1 ,
 461 .Xr ssh-keygen 1 ,
 462 .Xr glob 3 ,
 463 .Xr ssh_config 5 ,
 464 .Xr sftp-server 8 ,
 465 .Xr sshd 8
 466 .Rs
 467 .%A T. Ylonen
 468 .%A S. Lehtinen
 469 .%T "SSH File Transfer Protocol"
 470 .%N draft-ietf-secsh-filexfer-00.txt
 471 .%D January 2001
 472 .%O work in progress material
 473 .Re