sftp.1

   1 .\" $OpenBSD: sftp.1,v 1.48 2003/12/09 21:53:37 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 SmartcardDevice
 174 .It StrictHostKeyChecking
 175 .It TCPKeepAlive
 176 .It UsePrivilegedPort
 177 .It User
 178 .It UserKnownHostsFile
 179 .It VerifyHostKeyDNS
 180 .El
 181 .It Fl P Ar sftp_server_path
 182 Connect directly to a local sftp server
 183 (rather than via
 184 .Xr ssh 1 )
 185 This option may be useful in debugging the client and server.
 186 .It Fl R Ar num_requests
 187 Specify how many requests may be outstanding at any one time.
 188 Increasing this may slightly improve file transfer speed
 189 but will increase memory usage.
 190 The default is 16 outstanding requests.
 191 .It Fl S Ar program
 192 Name of the
 193 .Ar program
 194 to use for the encrypted connection.
 195 The program must understand
 196 .Xr ssh 1
 197 options.
 198 .It Fl s Ar subsystem | sftp_server
 199 Specifies the SSH2 subsystem or the path for an sftp server
 200 on the remote host.
 201 A path is useful for using
 202 .Nm
 203 over protocol version 1, or when the remote
 204 .Xr sshd 8
 205 does not have an sftp subsystem configured.
 206 .It Fl v
 207 Raise logging level.
 208 This option is also passed to ssh.
 209 .El
 210 .Sh INTERACTIVE COMMANDS
 211 Once in interactive mode,
 212 .Nm
 213 understands a set of commands similar to those of
 214 .Xr ftp 1 .
 215 Commands are case insensitive and pathnames may be enclosed in quotes if they
 216 contain spaces.
 217 .Bl -tag -width "lmdir path"
 218 .It Ic bye
 219 Quit
 220 .Nm sftp .
 221 .It Ic cd Ar path
 222 Change remote directory to
 223 .Ar path .
 224 .It Ic chgrp Ar grp Ar path
 225 Change group of file
 226 .Ar path
 227 to
 228 .Ar grp .
 229 .Ar grp
 230 must be a numeric GID.
 231 .It Ic chmod Ar mode Ar path
 232 Change permissions of file
 233 .Ar path
 234 to
 235 .Ar mode .
 236 .It Ic chown Ar own Ar path
 237 Change owner of file
 238 .Ar path
 239 to
 240 .Ar own .
 241 .Ar own
 242 must be a numeric UID.
 243 .It Ic exit
 244 Quit
 245 .Nm sftp .
 246 .It Xo Ic get
 247 .Op Ar flags
 248 .Ar remote-path
 249 .Op Ar local-path
 250 .Xc
 251 Retrieve the
 252 .Ar remote-path
 253 and store it on the local machine.
 254 If the local
 255 path name is not specified, it is given the same name it has on the
 256 remote machine.
 257 If the
 258 .Fl P
 259 flag is specified, then the file's full permission and access time are
 260 copied too.
 261 .It Ic help
 262 Display help text.
 263 .It Ic lcd Ar path
 264 Change local directory to
 265 .Ar path .
 266 .It Ic lls Op Ar ls-options Op Ar path
 267 Display local directory listing of either
 268 .Ar path
 269 or current directory if
 270 .Ar path
 271 is not specified.
 272 .It Ic lmkdir Ar path
 273 Create local directory specified by
 274 .Ar path .
 275 .It Ic ln Ar oldpath Ar newpath
 276 Create a symbolic link from
 277 .Ar oldpath
 278 to
 279 .Ar newpath .
 280 .It Ic lpwd
 281 Print local working directory.
 282 .It Xo Ic ls
 283 .Op Ar flags
 284 .Op Ar path
 285 .Xc
 286 Display remote directory listing of either
 287 .Ar path
 288 or current directory if
 289 .Ar path
 290 is not specified.
 291 If the
 292 .Fl l
 293 flag is specified, then display additional details including permissions
 294 and ownership information.
 295 .It Ic lumask Ar umask
 296 Set local umask to
 297 .Ar umask .
 298 .It Ic mkdir Ar path
 299 Create remote directory specified by
 300 .Ar path .
 301 .It Ic progress
 302 Toggle display of progress meter.
 303 .It Xo Ic put
 304 .Op Ar flags
 305 .Ar local-path
 306 .Op Ar remote-path
 307 .Xc
 308 Upload
 309 .Ar local-path
 310 and store it on the remote machine.
 311 If the remote path name is not specified, it is given the same name it has
 312 on the local machine.
 313 If the
 314 .Fl P
 315 flag is specified, then the file's full permission and access time are
 316 copied too.
 317 .It Ic pwd
 318 Display remote working directory.
 319 .It Ic quit
 320 Quit
 321 .Nm sftp .
 322 .It Ic rename Ar oldpath Ar newpath
 323 Rename remote file from
 324 .Ar oldpath
 325 to
 326 .Ar newpath .
 327 .It Ic rm Ar path
 328 Delete remote file specified by
 329 .Ar path .
 330 .It Ic rmdir Ar path
 331 Remove remote directory specified by
 332 .Ar path .
 333 .It Ic symlink Ar oldpath Ar newpath
 334 Create a symbolic link from
 335 .Ar oldpath
 336 to
 337 .Ar newpath .
 338 .It Ic version
 339 Display the
 340 .Nm
 341 protocol version.
 342 .It Ic \&! Ar command
 343 Execute
 344 .Ar command
 345 in local shell.
 346 .It Ic \&!
 347 Escape to local shell.
 348 .It Ic \&?
 349 Synonym for help.
 350 .El
 351 .Sh SEE ALSO
 352 .Xr ftp 1 ,
 353 .Xr scp 1 ,
 354 .Xr ssh 1 ,
 355 .Xr ssh-add 1 ,
 356 .Xr ssh-keygen 1 ,
 357 .Xr ssh_config 5 ,
 358 .Xr sftp-server 8 ,
 359 .Xr sshd 8
 360 .Rs
 361 .%A T. Ylonen
 362 .%A S. Lehtinen
 363 .%T "SSH File Transfer Protocol"
 364 .%N draft-ietf-secsh-filexfer-00.txt
 365 .%D January 2001
 366 .%O work in progress material
 367 .Re