sftp.1

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