sftp.1

   1 .\" $OpenBSD: sftp.1,v 1.30 2002/02/12 12:32:27 djm 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 , rm , mkdir , chdir , lchdir
  80 and
  81 .Ic lmkdir .
  82 .It Fl o Ar ssh_option
  83 Can be used to pass options to
  84 .Nm ssh
  85 in the format used in the
  86 .Xr ssh 1
  87 configuration file. This is useful for specifying options
  88 for which there is no separate
  89 .Nm sftp
  90 command-line flag.  For example, to specify an alternate
  91 port use:
  92 .Ic sftp -oPort=24 .
  93 .It Fl s Ar subsystem | sftp_server
  94 Specifies the SSH2 subsystem or the path for an sftp server
  95 on the remote host.  A path is useful for using sftp over
  96 protocol version 1, or when the remote
  97 .Nm sshd
  98 does not have an sftp subsystem configured.
  99 .It Fl v
 100 Raise logging level. This option is also passed to ssh.
 101 .It Fl B Ar buffer_size
 102 Specify  the size of the buffer that
 103 .Nm
 104 uses when transferring files. Larger buffers require fewer round trips at
 105 the cost of higher memory consumption. The default is 32768 bytes.
 106 .It Fl C
 107 Enables compression (via ssh's
 108 .Fl C
 109 flag).
 110 .It Fl F Ar ssh_config
 111 Specifies an alternative
 112 per-user configuration file for
 113 .Nm ssh .
 114 This option is directly passed to
 115 .Xr ssh 1 .
 116 .It Fl P Ar sftp_server path
 117 Connect directly to a local
 118 .Nm sftp-server
 119 (rather than via
 120 .Nm ssh )
 121 This option may be useful in debugging the client and server.
 122 .It Fl R Ar num_requests
 123 Specify how many requests may be outstanding at any one time. Increasing
 124 this may slightly improve file transfer speed but will increase memory
 125 usage. The default is 16 outstanding requests.
 126 .It Fl S Ar program
 127 Name of the
 128 .Ar program
 129 to use for the encrypted connection.
 130 The program must understand
 131 .Xr ssh 1
 132 options.
 133 .It Fl 1
 134 Specify the use of protocol version 1.
 135 .El
 136 .Sh INTERACTIVE COMMANDS
 137 Once in interactive mode,
 138 .Nm
 139 understands a set of commands similar to those of
 140 .Xr ftp 1 .
 141 Commands are case insensitive and pathnames may be enclosed in quotes if they
 142 contain spaces.
 143 .Bl -tag -width Ds
 144 .It Ic bye
 145 Quit sftp.
 146 .It Ic cd Ar path
 147 Change remote directory to
 148 .Ar path .
 149 .It Ic lcd Ar path
 150 Change local directory to
 151 .Ar path .
 152 .It Ic chgrp Ar grp Ar path
 153 Change group of file
 154 .Ar path
 155 to
 156 .Ar grp .
 157 .Ar grp
 158 must be a numeric GID.
 159 .It Ic chmod Ar mode Ar path
 160 Change permissions of file
 161 .Ar path
 162 to
 163 .Ar mode .
 164 .It Ic chown Ar own Ar path
 165 Change owner of file
 166 .Ar path
 167 to
 168 .Ar own .
 169 .Ar own
 170 must be a numeric UID.
 171 .It Ic exit
 172 Quit sftp.
 173 .It Xo Ic get
 174 .Op Ar flags
 175 .Ar remote-path
 176 .Op Ar local-path
 177 .Xc
 178 Retrieve the
 179 .Ar remote-path
 180 and store it on the local machine.
 181 If the local
 182 path name is not specified, it is given the same name it has on the
 183 remote machine. If the
 184 .Fl P
 185 flag is specified, then the file's full permission and access time are
 186 copied too.
 187 .It Ic help
 188 Display help text.
 189 .It Ic lls Op Ar ls-options Op Ar path
 190 Display local directory listing of either
 191 .Ar path
 192 or current directory if
 193 .Ar path
 194 is not specified.
 195 .It Ic lmkdir Ar path
 196 Create local directory specified by
 197 .Ar path .
 198 .It Ic ln Ar oldpath Ar newpath
 199 Create a symbolic link from
 200 .Ar oldpath
 201 to
 202 .Ar newpath .
 203 .It Ic lpwd
 204 Print local working directory.
 205 .It Ic ls Op Ar path
 206 Display remote directory listing of either
 207 .Ar path
 208 or current directory if
 209 .Ar path
 210 is not specified.
 211 .It Ic lumask Ar umask
 212 Set local umask to
 213 .Ar umask .
 214 .It Ic mkdir Ar path
 215 Create remote directory specified by
 216 .Ar path .
 217 .It Xo Ic put
 218 .Op Ar flags
 219 .Ar local-path
 220 .Op Ar local-path
 221 .Xc
 222 Upload
 223 .Ar local-path
 224 and store it on the remote machine. If the remote path name is not
 225 specified, it is given the same name it has on the local machine. If the
 226 .Fl P
 227 flag is specified, then the file's full permission and access time are
 228 copied too.
 229 .It Ic pwd
 230 Display remote working directory.
 231 .It Ic quit
 232 Quit sftp.
 233 .It Ic rename Ar oldpath Ar newpath
 234 Rename remote file from
 235 .Ar oldpath
 236 to
 237 .Ar newpath .
 238 .It Ic rmdir Ar path
 239 Remove remote directory specified by
 240 .Ar path .
 241 .It Ic rm Ar path
 242 Delete remote file specified by
 243 .Ar path .
 244 .It Ic symlink Ar oldpath Ar newpath
 245 Create a symbolic link from
 246 .Ar oldpath
 247 to
 248 .Ar newpath .
 249 .It Ic ! Ar command
 250 Execute
 251 .Ar command
 252 in local shell.
 253 .It Ic !
 254 Escape to local shell.
 255 .It Ic ?
 256 Synonym for help.
 257 .El
 258 .Sh AUTHORS
 259 Damien Miller <djm@mindrot.org>
 260 .Sh SEE ALSO
 261 .Xr scp 1 ,
 262 .Xr ssh 1 ,
 263 .Xr ssh-add 1 ,
 264 .Xr ssh-keygen 1 ,
 265 .Xr sftp-server 8 ,
 266 .Xr sshd 8
 267 .Rs
 268 .%A T. Ylonen
 269 .%A S. Lehtinen
 270 .%T "SSH File Transfer Protocol"
 271 .%N draft-ietf-secsh-filexfer-00.txt
 272 .%D January 2001
 273 .%O work in progress material
 274 .Re