sftp.1

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