1 \versionid $Id: psftp.but,v 1.6 2004/08/15 17:21:46 jacob Exp $
3 \C{psftp} Using PSFTP to transfer files securely
5 \i{PSFTP}, the PuTTY SFTP client, is a tool for transferring files
6 securely between computers using an SSH connection.
8 PSFTP differs from PSCP in the following ways:
10 \b PSCP should work on virtually every SSH server. PSFTP uses the
11 new SFTP protocol, which is a feature of SSH 2 only. (PSCP will also
12 use this protocol if it can, but there is an SSH 1 equivalent it can
13 fall back to if it cannot.)
15 \b PSFTP allows you to run an interactive file transfer session,
16 much like the Windows \c{ftp} program. You can list the contents of
17 directories, browse around the file system, issue multiple \c{get}
18 and \c{put} commands, and eventually log out. By contrast, PSCP is
19 designed to do a single file transfer operation and immediately
22 \H{psftp-starting} Starting PSFTP
24 The usual way to start PSFTP is from a command prompt, much like
25 PSCP. To do this, it will need either to be on your \i{\c{PATH}} or
26 in your current directory. To add the directory containing PSFTP to
27 your \c{PATH} environment variable, type into the console window:
29 \c set PATH=C:\path\to\putty\directory;%PATH%
31 Unlike PSCP, however, PSFTP has no complex command-line syntax; you
32 just specify a host name and perhaps a user name:
34 \c psftp server.example.com
38 \c psftp fred@server.example.com
40 Alternatively, if you just type \c{psftp} on its own (or
41 double-click the PSFTP icon in the Windows GUI), you will see the
42 PSFTP prompt, and a message telling you PSFTP has not connected to
46 \c psftp: no hostname specified; use "open host.name" to connect
49 At this point you can type \c{open server.example.com} or \c{open
50 fred@server.example.com} to start a session.
52 PSFTP accepts all the general command line options supported by the
53 PuTTY tools, except the ones which make no sense in a file transfer
54 utility. See \k{using-general-opts} for a description of these
55 options. (The ones not supported by PSFTP are clearly marked.)
57 PSFTP also supports some of its own options. The following sections
58 describe PSFTP's specific command-line options.
60 \S{psftp-option-b} \c{-b}: specify a file containing batch commands
62 In normal operation, PSFTP is an interactive program which displays
63 a command line and accepts commands from the keyboard.
65 If you need to do automated tasks with PSFTP, you would probably
66 prefer to specify a set of commands in advance and have them
67 executed automatically. The \c{-b} option allows you to do this. You
68 use it with a file name containing batch commands. For example, you
69 might create a file called \c{myscript.scr} containing lines like
72 \c cd /home/ftp/users/jeff
74 \c ren jam.tar.gz jam-old.tar.gz
76 \c chmod a+r jam.tar.gz
79 and then you could run the script by typing
81 \c psftp user@hostname -b myscript.scr
83 When you run a batch script in this way, PSFTP will abort the script
84 if any command fails to complete successfully. To change this
85 behaviour, you can use the \c{-be} option (\k{psftp-option-be}).
87 \S{psftp-option-bc} \c{-bc}: display batch commands as they are run
89 The \c{-bc} option alters what PSFTP displays while processing a
90 batch script. With the \c{-bc} option, PSFTP will display prompts
91 and commands just as if the commands had been typed at the keyboard.
92 So instead of seeing this:
94 \c Sent username "fred"
95 \c Remote working directory is /home/fred
96 \c Listing directory /home/fred/lib
97 \c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
98 \c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
99 \c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
100 \c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
101 \c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
105 \c Sent username "fred"
106 \c Remote working directory is /home/fred
108 \c Listing directory /home/fred/lib
109 \c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
110 \c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
111 \c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
112 \c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
113 \c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
116 \S{psftp-option-be} \c{-be}: continue batch processing on errors
118 When running a batch file, this option causes PSFTP to continue
119 processing even if a command fails to complete successfully.
121 You might want this to happen if you wanted to delete a file and
122 didn't care if it was already not present, for example.
124 \S{psftp-usage-options-batch}\c{-batch}: avoid interactive prompts
126 If you use the \c{-batch} option, PSFTP will never give an
127 interactive prompt while establishing the connection. If the
128 server's host key is invalid, for example (see \k{gs-hostkey}), then
129 the connection will simply be abandoned instead of asking you what
132 This may help PSFTP's behaviour when it is used in automated
133 scripts: using \c{-batch}, if something goes wrong at connection
134 time, the batch job will fail rather than hang.
136 \H{psftp-commands} Running PSFTP
138 Once you have started your PSFTP session, you will see a \c{psftp>}
139 prompt. You can now type commands to perform file-transfer
140 functions. This section lists all the available commands.
142 \S{psftp-quoting} General quoting rules for PSFTP commands
144 Most PSFTP commands are considered by the PSFTP command interpreter
145 as a sequence of words, separated by spaces. For example, the
146 command \c{ren oldfilename newfilename} splits up into three words:
147 \c{ren} (the command name), \c{oldfilename} (the name of the file to
148 be renamed), and \c{newfilename} (the new name to give the file).
150 Sometimes you will need to specify file names that \e{contain}
151 spaces. In order to do this, you can surround the file name with
152 double quotes. This works equally well for local file names and
155 \c psftp> get "spacey file name.txt" "save it under this name.txt"
157 The double quotes themselves will not appear as part of the file
158 names; they are removed by PSFTP and their only effect is to stop
159 the spaces inside them from acting as word separators.
161 If you need to \e{use} a double quote (on some types of remote
162 system, such as Unix, you are allowed to use double quotes in file
163 names), you can do this by doubling it. This works both inside and
164 outside double quotes. For example, this command
166 \c psftp> ren ""this"" "a file with ""quotes"" in it"
168 will take a file whose current name is \c{"this"} (with a double
169 quote character at the beginning and the end) and rename it to a
170 file whose name is \c{a file with "quotes" in it}.
172 (The one exception to the PSFTP quoting rules is the \c{!} command,
173 which passes its command line straight to Windows without splitting
174 it up into words at all. See \k{psftp-cmd-pling}.)
176 \S{psftp-cmd-open} The \c{open} command: start a session
178 If you started PSFTP by double-clicking in the GUI, or just by
179 typing \c{psftp} at the command line, you will need to open a
180 connection to an SFTP server before you can issue any other
181 commands (except \c{help} and \c{quit}).
183 To create a connection, type \c{open host.name}, or if you need to
184 specify a user name as well you can type \c{open user@host.name}.
186 Once you have issued this command, you will not be able to issue it
187 again, \e{even} if the command fails (for example, if you mistype
188 the host name or the connection times out). So if the connection is
189 not opened successfully, PSFTP will terminate immediately.
191 \S{psftp-cmd-quit} The \c{quit} command: end your session
193 When you have finished your session, type the command \c{quit} to
194 terminate PSFTP and return to the command line (or just close the
195 PSFTP console window if you started it from the GUI).
197 You can also use the \c{bye} and \c{exit} commands, which have
198 exactly the same effect.
200 \S{psftp-cmd-help} The \c{help} command: get quick online help
202 If you type \c{help}, PSFTP will give a short list of the available
205 If you type \c{help} with a command name - for example, \c{help get}
206 - then PSFTP will give a short piece of help on that particular
209 \S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the
210 remote working directory
212 PSFTP maintains a notion of your \q{working directory} on the
213 server. This is the default directory that other commands will
214 operate on. For example, if you type \c{get filename.dat} then PSFTP
215 will look for \c{filename.dat} in your remote working directory on
218 To change your remote working directory, use the \c{cd} command. If
219 you don't provide an argument, \c{cd} will return you to your home
220 directory on the server (more precisely, the remote directory you were
221 in at the start of the connection).
223 To display your current remote working directory, type \c{pwd}.
225 \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
226 local working directory
228 As well as having a working directory on the remote server, PSFTP
229 also has a working directory on your local machine (just like any
230 other Windows process). This is the default local directory that
231 other commands will operate on. For example, if you type \c{get
232 filename.dat} then PSFTP will save the resulting file as
233 \c{filename.dat} in your local working directory.
235 To change your local working directory, use the \c{lcd} command. To
236 display your current local working directory, type \c{lpwd}.
238 \S{psftp-cmd-get} The \c{get} command: fetch a file from the server
240 To download a file from the server and store it on your local PC,
241 you use the \c{get} command.
243 In its simplest form, you just use this with a file name:
247 If you want to store the file locally under a different name,
248 specify the local file name after the remote one:
250 \c get myfile.dat newname.dat
252 This will fetch the file on the server called \c{myfile.dat}, but
253 will save it to your local machine under the name \c{newname.dat}.
255 \S{psftp-cmd-put} The \c{put} command: send a file to the server
257 To upload a file to the server from your local PC, you use the
260 In its simplest form, you just use this with a file name:
264 If you want to store the file remotely under a different name,
265 specify the remote file name after the local one:
267 \c put myfile.dat newname.dat
269 This will send the local file called \c{myfile.dat}, but will store
270 it on the server under the name \c{newname.dat}.
272 \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
273 resuming file transfers
275 If a file transfer fails half way through, and you end up with half
276 the file stored on your disk, you can resume the file transfer using
277 the \c{reget} and \c{reput} commands. These work exactly like the
278 \c{get} and \c{put} commands, but they check for the presence of the
279 half-written destination file and start transferring from where the
280 last attempt left off.
282 The syntax of \c{reget} and \c{reput} is exactly the same as the
283 syntax of \c{get} and \c{put}:
286 \c reget myfile.dat newname.dat
288 \S{psftp-cmd-dir} The \c{dir} command: list remote files
290 To list the files in your remote working directory, just type
293 You can also list the contents of a different directory by typing
294 \c{dir} followed by the directory name:
299 The \c{ls} command works exactly the same way as \c{dir}.
301 \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
304 PSFTP allows you to modify the file permissions on files on the
305 server. You do this using the \c{chmod} command, which works very
306 much like the Unix \c{chmod} command.
308 The basic syntax is \c{chmod modes file}, where \c{modes} represents
309 a modification to the file permissions, and \c{file} is the filename
310 to modify. For example:
312 \c chmod go-rwx,u+w privatefile
313 \c chmod a+r publicfile
314 \c chmod 640 groupfile
316 The \c{modes} parameter can be a set of octal digits in the Unix
317 style. (If you don't know what this means, you probably don't want
318 to be using it!) Alternatively, it can be a list of permission
319 modifications, separated by commas. Each modification consists of:
321 \b The people affected by the modification. This can be \c{u} (the
322 owning user), \c{g} (members of the owning group), or \c{o}
323 (everybody else - \q{others}), or some combination of those. It can
324 also be \c{a} (\q{all}) to affect everybody at once.
326 \b A \c{+} or \c{-} sign, indicating whether permissions are to be
329 \b The actual permissions being added or removed. These can be \c{r}
330 (permission to read the file), \c{w} (permission to write to the
331 file), and \c{x} (permission to execute the file, or in the case of
332 a directory, permission to access files within the directory).
334 So the above examples would do:
336 \b The first example: \c{go-rwx} removes read, write and execute
337 permissions for members of the owning group and everybody else (so
338 the only permissions left are the ones for the file owner). \c{u+w}
339 adds write permission for the file owner.
341 \b The second example: \c{a+r} adds read permission for everybody.
343 In addition to all this, there are a few extra special cases for
344 Unix systems. On non-Unix systems these are unlikely to be useful:
346 \b You can specify \c{u+s} and \c{u-s} to add or remove the Unix
347 set-user-ID bit. This is typically only useful for special purposes;
348 refer to your Unix documentation if you're not sure about it.
350 \b You can specify \c{g+s} and \c{g-s} to add or remove the Unix
351 set-group-ID bit. On a file, this works similarly to the set-user-ID
352 bit (see your Unix documentation again); on a directory it ensures
353 that files created in the directory are accessible by members of the
354 group that owns the directory.
356 \b You can specify \c{+t} and \c{-t} to add or remove the Unix
357 \q{sticky bit}. When applied to a directory, this means that the
358 owner of a file in that directory can delete the file (whereas
359 normally only the owner of the \e{directory} would be allowed to).
361 \S{psftp-cmd-del} The \c{del} command: delete remote files
363 To delete a file on the server, type \c{del} and then the filename:
367 The \c{rm} command works exactly the same way as \c{del}.
369 \S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories
371 To create a directory on the server, type \c{mkdir} and then the
376 \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
378 To remove a directory on the server, type \c{rmdir} and then the
383 Most SFTP servers will probably refuse to remove a directory if the
384 directory has anything in it, so you will need to delete the
387 \S{psftp-cmd-ren} The \c{ren} command: rename remote files
389 To rename a file on the server, type \c{ren}, then the current file
390 name, and then the new file name:
392 \c ren oldfile newname
394 The \c{rename} and \c{mv} commands work exactly the same way as
397 \S{psftp-cmd-pling} The \c{!} command: run a local Windows command
399 You can run local Windows commands using the \c{!} command. This is
400 the only PSFTP command that is not subject to the command quoting
401 rules given in \k{psftp-quoting}. If any command line begins with
402 the \c{!} character, then the rest of the line will be passed
403 straight to Windows without further translation.
405 For example, if you want to move an existing copy of a file out of
406 the way before downloading an updated version, you might type:
408 \c psftp> !ren myfile.dat myfile.bak
409 \c psftp> get myfile.dat
411 using the Windows \c{ren} command to rename files on your local PC.
413 \H{psftp-pubkey} Using public key authentication with PSFTP
415 Like PuTTY, PSFTP can authenticate using a public key instead of a
416 password. There are two ways you can do this.
418 Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
419 So you might do this:
421 \b Run PuTTY, and create a PuTTY saved session (see
422 \k{config-saving}) which specifies your private key file (see
423 \k{config-ssh-privkey}). You will probably also want to specify a
424 username to log in as (see \k{config-username}).
426 \b In PSFTP, you can now use the name of the session instead of a
427 hostname: type \c{psftp sessionname}, where \c{sessionname} is
428 replaced by the name of your saved session.
430 Secondly, PSFTP will attempt to authenticate using Pageant if Pageant
431 is running (see \k{pageant}). So you would do this:
433 \b Ensure Pageant is running, and has your private key stored in it.
435 \b Specify a user and host name to PSFTP as normal. PSFTP will
436 automatically detect Pageant and try to use the keys within it.
438 For more general information on public-key authentication, see