crypto/openssh/sftp.1

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