sftp.1

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