sftp.1

   1 .\" $OpenBSD: sftp.1,v 1.49 2003/12/16 15:49:51 markus 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 the sftp client to start in a remote directory.
  75 .Pp
  76 The final usage format allows for automated sessions using the
  77 .Fl b
  78 option.
  79 In such cases, it is usually necessary to configure public key authentication
  80 to obviate the need to enter a password at connection time (see
  81 .Xr sshd 8
  82 and
  83 .Xr ssh-keygen 1
  84 for details).
  85 The options are as follows:
  86 .Bl -tag -width Ds
  87 .It Fl 1
  88 Specify the use of protocol version 1.
  89 .It Fl B Ar buffer_size
  90 Specify the size of the buffer that
  91 .Nm
  92 uses when transferring files.
  93 Larger buffers require fewer round trips at the cost of higher
  94 memory consumption.
  95 The default is 32768 bytes.
  96 .It Fl b Ar batchfile
  97 Batch mode reads a series of commands from an input
  98 .Ar batchfile
  99 instead of
 100 .Em stdin .
 101 Since it lacks user interaction it should be used in conjunction with
 102 non-interactive authentication.
 103 .Nm
 104 will abort if any of the following
 105 commands fail:
 106 .Ic get , put , rename , ln ,
 107 .Ic rm , mkdir , chdir , ls ,
 108 .Ic lchdir , chmod , chown , chgrp , lpwd
 109 and
 110 .Ic lmkdir .
 111 Termination on error can be suppressed on a command by command basis by
 112 prefixing the command with a
 113 .Sq Ic \-
 114 character (for example,
 115 .Ic -rm /tmp/blah* ) .
 116 .It Fl C
 117 Enables compression (via ssh's
 118 .Fl C
 119 flag).
 120 .It Fl F Ar ssh_config
 121 Specifies an alternative
 122 per-user configuration file for
 123 .Xr ssh 1 .
 124 This option is directly passed to
 125 .Xr ssh 1 .
 126 .It Fl o Ar ssh_option
 127 Can be used to pass options to
 128 .Nm ssh
 129 in the format used in
 130 .Xr ssh_config 5 .
 131 This is useful for specifying options
 132 for which there is no separate
 133 .Nm sftp
 134 command-line flag.
 135 For example, to specify an alternate port use:
 136 .Ic sftp -oPort=24 .
 137 For full details of the options listed below, and their possible values, see
 138 .Xr ssh_config 5 .
 139 .Pp
 140 .Bl -tag -width Ds -offset indent -compact
 141 .It AddressFamily
 142 .It BatchMode
 143 .It BindAddress
 144 .It ChallengeResponseAuthentication
 145 .It CheckHostIP
 146 .It Cipher
 147 .It Ciphers
 148 .It Compression
 149 .It CompressionLevel
 150 .It ConnectionAttempts
 151 .It ConnectionTimeout
 152 .It GlobalKnownHostsFile
 153 .It GSSAPIAuthentication
 154 .It GSSAPIDelegateCredentials
 155 .It Host
 156 .It HostbasedAuthentication
 157 .It HostKeyAlgorithms
 158 .It HostKeyAlias
 159 .It HostName
 160 .It IdentityFile
 161 .It LogLevel
 162 .It MACs
 163 .It NoHostAuthenticationForLocalhost
 164 .It NumberOfPasswordPrompts
 165 .It PasswordAuthentication
 166 .It Port
 167 .It PreferredAuthentications
 168 .It Protocol
 169 .It ProxyCommand
 170 .It PubkeyAuthentication
 171 .It RhostsRSAAuthentication
 172 .It RSAAuthentication
 173 .It ServerAliveInterval
 174 .It ServerAliveCountMax
 175 .It SmartcardDevice
 176 .It StrictHostKeyChecking
 177 .It TCPKeepAlive
 178 .It UsePrivilegedPort
 179 .It User
 180 .It UserKnownHostsFile
 181 .It VerifyHostKeyDNS
 182 .El
 183 .It Fl P Ar sftp_server_path
 184 Connect directly to a local sftp server
 185 (rather than via
 186 .Xr ssh 1 )
 187 This option may be useful in debugging the client and server.
 188 .It Fl R Ar num_requests
 189 Specify how many requests may be outstanding at any one time.
 190 Increasing this may slightly improve file transfer speed
 191 but will increase memory usage.
 192 The default is 16 outstanding requests.
 193 .It Fl S Ar program
 194 Name of the
 195 .Ar program
 196 to use for the encrypted connection.
 197 The program must understand
 198 .Xr ssh 1
 199 options.
 200 .It Fl s Ar subsystem | sftp_server
 201 Specifies the SSH2 subsystem or the path for an sftp server
 202 on the remote host.
 203 A path is useful for using
 204 .Nm
 205 over protocol version 1, or when the remote
 206 .Xr sshd 8
 207 does not have an sftp subsystem configured.
 208 .It Fl v
 209 Raise logging level.
 210 This option is also passed to ssh.
 211 .El
 212 .Sh INTERACTIVE COMMANDS
 213 Once in interactive mode,
 214 .Nm
 215 understands a set of commands similar to those of
 216 .Xr ftp 1 .
 217 Commands are case insensitive and pathnames may be enclosed in quotes if they
 218 contain spaces.
 219 .Bl -tag -width "lmdir path"
 220 .It Ic bye
 221 Quit
 222 .Nm sftp .
 223 .It Ic cd Ar path
 224 Change remote directory to
 225 .Ar path .
 226 .It Ic chgrp Ar grp Ar path
 227 Change group of file
 228 .Ar path
 229 to
 230 .Ar grp .
 231 .Ar grp
 232 must be a numeric GID.
 233 .It Ic chmod Ar mode Ar path
 234 Change permissions of file
 235 .Ar path
 236 to
 237 .Ar mode .
 238 .It Ic chown Ar own Ar path
 239 Change owner of file
 240 .Ar path
 241 to
 242 .Ar own .
 243 .Ar own
 244 must be a numeric UID.
 245 .It Ic exit
 246 Quit
 247 .Nm sftp .
 248 .It Xo Ic get
 249 .Op Ar flags
 250 .Ar remote-path
 251 .Op Ar local-path
 252 .Xc
 253 Retrieve the
 254 .Ar remote-path
 255 and store it on the local machine.
 256 If the local
 257 path name is not specified, it is given the same name it has on the
 258 remote machine.
 259 If the
 260 .Fl P
 261 flag is specified, then the file's full permission and access time are
 262 copied too.
 263 .It Ic help
 264 Display help text.
 265 .It Ic lcd Ar path
 266 Change local directory to
 267 .Ar path .
 268 .It Ic lls Op Ar ls-options Op Ar path
 269 Display local directory listing of either
 270 .Ar path
 271 or current directory if
 272 .Ar path
 273 is not specified.
 274 .It Ic lmkdir Ar path
 275 Create local directory specified by
 276 .Ar path .
 277 .It Ic ln Ar oldpath Ar newpath
 278 Create a symbolic link from
 279 .Ar oldpath
 280 to
 281 .Ar newpath .
 282 .It Ic lpwd
 283 Print local working directory.
 284 .It Xo Ic ls
 285 .Op Ar flags
 286 .Op Ar path
 287 .Xc
 288 Display remote directory listing of either
 289 .Ar path
 290 or current directory if
 291 .Ar path
 292 is not specified.
 293 If the
 294 .Fl l
 295 flag is specified, then display additional details including permissions
 296 and ownership information.
 297 .It Ic lumask Ar umask
 298 Set local umask to
 299 .Ar umask .
 300 .It Ic mkdir Ar path
 301 Create remote directory specified by
 302 .Ar path .
 303 .It Ic progress
 304 Toggle display of progress meter.
 305 .It Xo Ic put
 306 .Op Ar flags
 307 .Ar local-path
 308 .Op Ar remote-path
 309 .Xc
 310 Upload
 311 .Ar local-path
 312 and store it on the remote machine.
 313 If the remote path name is not specified, it is given the same name it has
 314 on the local machine.
 315 If the
 316 .Fl P
 317 flag is specified, then the file's full permission and access time are
 318 copied too.
 319 .It Ic pwd
 320 Display remote working directory.
 321 .It Ic quit
 322 Quit
 323 .Nm sftp .
 324 .It Ic rename Ar oldpath Ar newpath
 325 Rename remote file from
 326 .Ar oldpath
 327 to
 328 .Ar newpath .
 329 .It Ic rm Ar path
 330 Delete remote file specified by
 331 .Ar path .
 332 .It Ic rmdir Ar path
 333 Remove remote directory specified by
 334 .Ar path .
 335 .It Ic symlink Ar oldpath Ar newpath
 336 Create a symbolic link from
 337 .Ar oldpath
 338 to
 339 .Ar newpath .
 340 .It Ic version
 341 Display the
 342 .Nm
 343 protocol version.
 344 .It Ic \&! Ar command
 345 Execute
 346 .Ar command
 347 in local shell.
 348 .It Ic \&!
 349 Escape to local shell.
 350 .It Ic \&?
 351 Synonym for help.
 352 .El
 353 .Sh SEE ALSO
 354 .Xr ftp 1 ,
 355 .Xr scp 1 ,
 356 .Xr ssh 1 ,
 357 .Xr ssh-add 1 ,
 358 .Xr ssh-keygen 1 ,
 359 .Xr ssh_config 5 ,
 360 .Xr sftp-server 8 ,
 361 .Xr sshd 8
 362 .Rs
 363 .%A T. Ylonen
 364 .%A S. Lehtinen
 365 .%T "SSH File Transfer Protocol"
 366 .%N draft-ietf-secsh-filexfer-00.txt
 367 .%D January 2001
 368 .%O work in progress material
 369 .Re