Damien Miller | 16a1333 | 2002-02-13 14:03:56 +1100 | [diff] [blame^] | 1 | .\" $OpenBSD: sftp.1,v 1.30 2002/02/12 12:32:27 djm Exp $ |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 2 | .\" |
Ben Lindstrom | 92a2e38 | 2001-03-05 06:59:27 +0000 | [diff] [blame] | 3 | .\" Copyright (c) 2001 Damien Miller. All rights reserved. |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 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 | .\" |
Ben Lindstrom | 8ffeacf | 2001-04-10 02:43:57 +0000 | [diff] [blame] | 25 | .Dd February 4, 2001 |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 26 | .Dt SFTP 1 |
| 27 | .Os |
| 28 | .Sh NAME |
| 29 | .Nm sftp |
Damien Miller | 225736c | 2001-02-19 21:51:08 +1100 | [diff] [blame] | 30 | .Nd Secure file transfer program |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 31 | .Sh SYNOPSIS |
| 32 | .Nm sftp |
Damien Miller | 81b6e78 | 2002-02-08 22:06:03 +1100 | [diff] [blame] | 33 | .Op Fl vC1 |
Ben Lindstrom | 562c26b | 2001-03-07 01:26:48 +0000 | [diff] [blame] | 34 | .Op Fl b Ar batchfile |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 35 | .Op Fl o Ar ssh_option |
Ben Lindstrom | 6a33763 | 2001-09-18 05:47:32 +0000 | [diff] [blame] | 36 | .Op Fl s Ar subsystem | sftp_server |
Damien Miller | 81b6e78 | 2002-02-08 22:06:03 +1100 | [diff] [blame] | 37 | .Op Fl B Ar buffer_size |
| 38 | .Op Fl F Ar ssh_config |
| 39 | .Op Fl P Ar sftp_server path |
Damien Miller | 16a1333 | 2002-02-13 14:03:56 +1100 | [diff] [blame^] | 40 | .Op Fl R Ar num_requests |
Ben Lindstrom | 6a33763 | 2001-09-18 05:47:32 +0000 | [diff] [blame] | 41 | .Op Fl S Ar program |
| 42 | .Ar host |
Ben Lindstrom | 63667f6 | 2001-04-13 00:00:14 +0000 | [diff] [blame] | 43 | .Nm sftp |
| 44 | .Op [\fIuser\fR@]\fIhost\fR[:\fIfile\fR [\fIfile\fR]] |
| 45 | .Nm sftp |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 46 | .Op [\fIuser\fR@]\fIhost\fR[:\fIdir\fR[\fI/\fR]] |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 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 |
Ben Lindstrom | aafff9c | 2001-05-06 03:01:02 +0000 | [diff] [blame] | 58 | .Ar host , |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 59 | then enters an interactive command mode. |
| 60 | .Pp |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 61 | The second usage format will retrieve files automatically if a non-interactive |
Ben Lindstrom | aafff9c | 2001-05-06 03:01:02 +0000 | [diff] [blame] | 62 | authentication method is used; otherwise it will do so after |
| 63 | successful interactive authentication. |
Ben Lindstrom | 63667f6 | 2001-04-13 00:00:14 +0000 | [diff] [blame] | 64 | .Pp |
| 65 | The last usage format allows the sftp client to start in a remote directory. |
| 66 | .Pp |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 67 | The options are as follows: |
| 68 | .Bl -tag -width Ds |
Ben Lindstrom | 562c26b | 2001-03-07 01:26:48 +0000 | [diff] [blame] | 69 | .It Fl b Ar batchfile |
| 70 | Batch mode reads a series of commands from an input |
Ben Lindstrom | 283cb82 | 2001-03-09 00:09:02 +0000 | [diff] [blame] | 71 | .Ar batchfile |
Ben Lindstrom | 562c26b | 2001-03-07 01:26:48 +0000 | [diff] [blame] | 72 | instead of |
Ben Lindstrom | 283cb82 | 2001-03-09 00:09:02 +0000 | [diff] [blame] | 73 | .Em stdin . |
| 74 | Since it lacks user interaction it should be used in conjunction with |
| 75 | non-interactive authentication. |
| 76 | .Nm |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 77 | will abort if any of the following |
| 78 | commands fail: |
Ben Lindstrom | 283cb82 | 2001-03-09 00:09:02 +0000 | [diff] [blame] | 79 | .Ic get , put , rename , ln , rm , mkdir , chdir , lchdir |
Ben Lindstrom | 562c26b | 2001-03-07 01:26:48 +0000 | [diff] [blame] | 80 | and |
Ben Lindstrom | 283cb82 | 2001-03-09 00:09:02 +0000 | [diff] [blame] | 81 | .Ic lmkdir . |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 82 | .It Fl o Ar ssh_option |
Ben Lindstrom | 14c62eb | 2001-08-15 23:25:46 +0000 | [diff] [blame] | 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 |
Ben Lindstrom | 6a33763 | 2001-09-18 05:47:32 +0000 | [diff] [blame] | 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. |
Damien Miller | 81b6e78 | 2002-02-08 22:06:03 +1100 | [diff] [blame] | 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. |
Damien Miller | 16a1333 | 2002-02-13 14:03:56 +1100 | [diff] [blame^] | 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. |
Ben Lindstrom | 6a33763 | 2001-09-18 05:47:32 +0000 | [diff] [blame] | 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. |
Damien Miller | 81b6e78 | 2002-02-08 22:06:03 +1100 | [diff] [blame] | 133 | .It Fl 1 |
| 134 | Specify the use of protocol version 1. |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 135 | .El |
| 136 | .Sh INTERACTIVE COMMANDS |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 137 | Once in interactive mode, |
| 138 | .Nm |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 139 | understands a set of commands similar to those of |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 140 | .Xr ftp 1 . |
Ben Lindstrom | 27cb1d0 | 2001-02-10 21:59:35 +0000 | [diff] [blame] | 141 | Commands are case insensitive and pathnames may be enclosed in quotes if they |
| 142 | contain spaces. |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 143 | .Bl -tag -width Ds |
Ben Lindstrom | 59e1249 | 2001-08-15 23:22:56 +0000 | [diff] [blame] | 144 | .It Ic bye |
| 145 | Quit sftp. |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 146 | .It Ic cd Ar path |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 147 | Change remote directory to |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 148 | .Ar path . |
| 149 | .It Ic lcd Ar path |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 150 | Change local directory to |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 151 | .Ar path . |
| 152 | .It Ic chgrp Ar grp Ar path |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 153 | Change group of file |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 154 | .Ar path |
| 155 | to |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 156 | .Ar grp . |
| 157 | .Ar grp |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 158 | must be a numeric GID. |
| 159 | .It Ic chmod Ar mode Ar path |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 160 | Change permissions of file |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 161 | .Ar path |
| 162 | to |
| 163 | .Ar mode . |
| 164 | .It Ic chown Ar own Ar path |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 165 | Change owner of file |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 166 | .Ar path |
| 167 | to |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 168 | .Ar own . |
| 169 | .Ar own |
| 170 | must be a numeric UID. |
Ben Lindstrom | c9b6eab | 2001-03-07 01:29:17 +0000 | [diff] [blame] | 171 | .It Ic exit |
| 172 | Quit sftp. |
Ben Lindstrom | 9d4f2c8 | 2001-02-15 03:22:45 +0000 | [diff] [blame] | 173 | .It Xo Ic get |
| 174 | .Op Ar flags |
| 175 | .Ar remote-path |
| 176 | .Op Ar local-path |
| 177 | .Xc |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 178 | Retrieve the |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 179 | .Ar remote-path |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 180 | and store it on the local machine. |
| 181 | If the local |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 182 | path name is not specified, it is given the same name it has on the |
| 183 | remote machine. If the |
Ben Lindstrom | 9d4f2c8 | 2001-02-15 03:22:45 +0000 | [diff] [blame] | 184 | .Fl P |
| 185 | flag is specified, then the file's full permission and access time are |
| 186 | copied too. |
Ben Lindstrom | c9b6eab | 2001-03-07 01:29:17 +0000 | [diff] [blame] | 187 | .It Ic help |
| 188 | Display help text. |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 189 | .It Ic lls Op Ar ls-options Op Ar path |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 190 | Display local directory listing of either |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 191 | .Ar path |
| 192 | or current directory if |
| 193 | .Ar path |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 194 | is not specified. |
| 195 | .It Ic lmkdir Ar path |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 196 | Create local directory specified by |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 197 | .Ar path . |
Damien Miller | 058316f | 2001-03-08 10:08:49 +1100 | [diff] [blame] | 198 | .It Ic ln Ar oldpath Ar newpath |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 199 | Create a symbolic link from |
Damien Miller | 058316f | 2001-03-08 10:08:49 +1100 | [diff] [blame] | 200 | .Ar oldpath |
| 201 | to |
| 202 | .Ar newpath . |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 203 | .It Ic lpwd |
| 204 | Print local working directory. |
| 205 | .It Ic ls Op Ar path |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 206 | Display remote directory listing of either |
| 207 | .Ar path |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 208 | or current directory if |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 209 | .Ar path |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 210 | is not specified. |
| 211 | .It Ic lumask Ar umask |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 212 | Set local umask to |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 213 | .Ar umask . |
| 214 | .It Ic mkdir Ar path |
| 215 | Create remote directory specified by |
| 216 | .Ar path . |
Ben Lindstrom | 9d4f2c8 | 2001-02-15 03:22:45 +0000 | [diff] [blame] | 217 | .It Xo Ic put |
| 218 | .Op Ar flags |
| 219 | .Ar local-path |
| 220 | .Op Ar local-path |
| 221 | .Xc |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 222 | Upload |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 223 | .Ar local-path |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 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 |
Ben Lindstrom | 9d4f2c8 | 2001-02-15 03:22:45 +0000 | [diff] [blame] | 226 | .Fl P |
| 227 | flag is specified, then the file's full permission and access time are |
| 228 | copied too. |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 229 | .It Ic pwd |
| 230 | Display remote working directory. |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 231 | .It Ic quit |
| 232 | Quit sftp. |
| 233 | .It Ic rename Ar oldpath Ar newpath |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 234 | Rename remote file from |
| 235 | .Ar oldpath |
| 236 | to |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 237 | .Ar newpath . |
| 238 | .It Ic rmdir Ar path |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 239 | Remove remote directory specified by |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 240 | .Ar path . |
| 241 | .It Ic rm Ar path |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 242 | Delete remote file specified by |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 243 | .Ar path . |
Damien Miller | 058316f | 2001-03-08 10:08:49 +1100 | [diff] [blame] | 244 | .It Ic symlink Ar oldpath Ar newpath |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 245 | Create a symbolic link from |
Damien Miller | 058316f | 2001-03-08 10:08:49 +1100 | [diff] [blame] | 246 | .Ar oldpath |
| 247 | to |
| 248 | .Ar newpath . |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 249 | .It Ic ! Ar command |
Ben Lindstrom | 2464322 | 2001-06-25 05:08:11 +0000 | [diff] [blame] | 250 | Execute |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 251 | .Ar command |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 252 | in local shell. |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 253 | .It Ic ! |
Damien Miller | d7686fd | 2001-02-10 00:40:03 +1100 | [diff] [blame] | 254 | Escape to local shell. |
| 255 | .It Ic ? |
| 256 | Synonym for help. |
| 257 | .El |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 258 | .Sh AUTHORS |
| 259 | Damien Miller <djm@mindrot.org> |
| 260 | .Sh SEE ALSO |
Ben Lindstrom | 160ec62 | 2001-04-22 17:17:46 +0000 | [diff] [blame] | 261 | .Xr scp 1 , |
Damien Miller | 3380426 | 2001-02-04 23:20:18 +1100 | [diff] [blame] | 262 | .Xr ssh 1 , |
| 263 | .Xr ssh-add 1 , |
| 264 | .Xr ssh-keygen 1 , |
Ben Lindstrom | 160ec62 | 2001-04-22 17:17:46 +0000 | [diff] [blame] | 265 | .Xr sftp-server 8 , |
| 266 | .Xr sshd 8 |
| 267 | .Rs |
Ben Lindstrom | 90fd060 | 2001-06-25 04:45:33 +0000 | [diff] [blame] | 268 | .%A T. Ylonen |
| 269 | .%A S. Lehtinen |
Ben Lindstrom | 160ec62 | 2001-04-22 17:17:46 +0000 | [diff] [blame] | 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 |