sftp.1

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