sftp.1

   1 .\" $OpenBSD: sftp.1,v 1.43 2003/05/14 08:25:39 jmc 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 vC1
  35 .Op Fl b Ar batchfile
  36 .Op Fl o Ar ssh_option
  37 .Op Fl s Ar subsystem | sftp_server
  38 .Op Fl B Ar buffer_size
  39 .Op Fl F Ar ssh_config
  40 .Op Fl P Ar sftp_server path
  41 .Op Fl R Ar num_requests
  42 .Op Fl S Ar program
  43 .Ar host
  44 .Ek
  45 .Nm sftp
  46 .Oo Oo Ar user Ns No @ 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 No @ 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 No @ Oc Ns Ar host Ns
  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 form allows for automated sessions using the
  77 .Fl b
  78 option. In such cases, it is usually necessary to configure public key
  79 authentication to obviate the need to enter a password at connection
  80 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 b Ar batchfile
  88 Batch mode reads a series of commands from an input
  89 .Ar batchfile
  90 instead of
  91 .Em stdin .
  92 Since it lacks user interaction it should be used in conjunction with
  93 non-interactive authentication.
  94 .Nm
  95 will abort if any of the following
  96 commands fail:
  97 .Ic get , put , rename , ln ,
  98 .Ic rm , mkdir , chdir , ls ,
  99 .Ic lchdir , chmod , chown , chgrp , lpwd
 100 and
 101 .Ic lmkdir .
 102 Termination on error can be suppressed on a command by command basis by
 103 prefixing the command with a
 104 .Ic '-'
 105 character (For example,
 106 .Ic -rm /tmp/blah*
 107 ).
 108 .It Fl o Ar ssh_option
 109 Can be used to pass options to
 110 .Nm ssh
 111 in the format used in
 112 .Xr ssh_config 5 .
 113 This is useful for specifying options
 114 for which there is no separate
 115 .Nm sftp
 116 command-line flag. For example, to specify an alternate
 117 port use:
 118 .Ic sftp -oPort=24 .
 119 .It Fl s Ar subsystem | sftp_server
 120 Specifies the SSH2 subsystem or the path for an sftp server
 121 on the remote host. A path is useful for using sftp over
 122 protocol version 1, or when the remote
 123 .Nm sshd
 124 does not have an sftp subsystem configured.
 125 .It Fl v
 126 Raise logging level. This option is also passed to ssh.
 127 .It Fl B Ar buffer_size
 128 Specify the size of the buffer that
 129 .Nm
 130 uses when transferring files. Larger buffers require fewer round trips at
 131 the cost of higher memory consumption. The default is 32768 bytes.
 132 .It Fl C
 133 Enables compression (via ssh's
 134 .Fl C
 135 flag).
 136 .It Fl F Ar ssh_config
 137 Specifies an alternative
 138 per-user configuration file for
 139 .Nm ssh .
 140 This option is directly passed to
 141 .Xr ssh 1 .
 142 .It Fl P Ar sftp_server path
 143 Connect directly to a local
 144 .Nm sftp-server
 145 (rather than via
 146 .Nm ssh )
 147 This option may be useful in debugging the client and server.
 148 .It Fl R Ar num_requests
 149 Specify how many requests may be outstanding at any one time. Increasing
 150 this may slightly improve file transfer speed but will increase memory
 151 usage. The default is 16 outstanding requests.
 152 .It Fl S Ar program
 153 Name of the
 154 .Ar program
 155 to use for the encrypted connection.
 156 The program must understand
 157 .Xr ssh 1
 158 options.
 159 .It Fl 1
 160 Specify the use of protocol version 1.
 161 .El
 162 .Sh INTERACTIVE COMMANDS
 163 Once in interactive mode,
 164 .Nm
 165 understands a set of commands similar to those of
 166 .Xr ftp 1 .
 167 Commands are case insensitive and pathnames may be enclosed in quotes if they
 168 contain spaces.
 169 .Bl -tag -width Ds
 170 .It Ic bye
 171 Quit sftp.
 172 .It Ic cd Ar path
 173 Change remote directory to
 174 .Ar path .
 175 .It Ic lcd Ar path
 176 Change local directory to
 177 .Ar path .
 178 .It Ic chgrp Ar grp Ar path
 179 Change group of file
 180 .Ar path
 181 to
 182 .Ar grp .
 183 .Ar grp
 184 must be a numeric GID.
 185 .It Ic chmod Ar mode Ar path
 186 Change permissions of file
 187 .Ar path
 188 to
 189 .Ar mode .
 190 .It Ic chown Ar own Ar path
 191 Change owner of file
 192 .Ar path
 193 to
 194 .Ar own .
 195 .Ar own
 196 must be a numeric UID.
 197 .It Ic exit
 198 Quit sftp.
 199 .It Xo Ic get
 200 .Op Ar flags
 201 .Ar remote-path
 202 .Op Ar local-path
 203 .Xc
 204 Retrieve the
 205 .Ar remote-path
 206 and store it on the local machine.
 207 If the local
 208 path name is not specified, it is given the same name it has on the
 209 remote machine. If the
 210 .Fl P
 211 flag is specified, then the file's full permission and access time are
 212 copied too.
 213 .It Ic help
 214 Display help text.
 215 .It Ic lls Op Ar ls-options Op Ar path
 216 Display local directory listing of either
 217 .Ar path
 218 or current directory if
 219 .Ar path
 220 is not specified.
 221 .It Ic lmkdir Ar path
 222 Create local directory specified by
 223 .Ar path .
 224 .It Ic ln Ar oldpath Ar newpath
 225 Create a symbolic link from
 226 .Ar oldpath
 227 to
 228 .Ar newpath .
 229 .It Ic lpwd
 230 Print local working directory.
 231 .It Xo Ic ls
 232 .Op Ar flags
 233 .Op Ar path
 234 .Xc
 235 Display remote directory listing of either
 236 .Ar path
 237 or current directory if
 238 .Ar path
 239 is not specified. If the
 240 .Fl l
 241 flag is specified, then display additional details including permissions
 242 and ownership information.
 243 .It Ic lumask Ar umask
 244 Set local umask to
 245 .Ar umask .
 246 .It Ic mkdir Ar path
 247 Create remote directory specified by
 248 .Ar path .
 249 .It Ic progress
 250 Toggle display of progress meter.
 251 .It Xo Ic put
 252 .Op Ar flags
 253 .Ar local-path
 254 .Op Ar remote-path
 255 .Xc
 256 Upload
 257 .Ar local-path
 258 and store it on the remote machine. If the remote path name is not
 259 specified, it is given the same name it has on the local machine. 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 pwd
 264 Display remote working directory.
 265 .It Ic quit
 266 Quit sftp.
 267 .It Ic rename Ar oldpath Ar newpath
 268 Rename remote file from
 269 .Ar oldpath
 270 to
 271 .Ar newpath .
 272 .It Ic rmdir Ar path
 273 Remove remote directory specified by
 274 .Ar path .
 275 .It Ic rm Ar path
 276 Delete remote file specified by
 277 .Ar path .
 278 .It Ic symlink Ar oldpath Ar newpath
 279 Create a symbolic link from
 280 .Ar oldpath
 281 to
 282 .Ar newpath .
 283 .It Ic version
 284 Display the
 285 .Nm
 286 protocol version.
 287 .It Ic ! Ar command
 288 Execute
 289 .Ar command
 290 in local shell.
 291 .It Ic !
 292 Escape to local shell.
 293 .It Ic ?
 294 Synonym for help.
 295 .El
 296 .Sh SEE ALSO
 297 .Xr scp 1 ,
 298 .Xr ssh 1 ,
 299 .Xr ssh-add 1 ,
 300 .Xr ssh-keygen 1 ,
 301 .Xr ssh_config 5 ,
 302 .Xr sftp-server 8 ,
 303 .Xr sshd 8
 304 .Rs
 305 .%A T. Ylonen
 306 .%A S. Lehtinen
 307 .%T "SSH File Transfer Protocol"
 308 .%N draft-ietf-secsh-filexfer-00.txt
 309 .%D January 2001
 310 .%O work in progress material
 311 .Re