1 \define{versionidpsftp} \versionid $Id$
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-wildcards} Wildcards in PSFTP
178 Several commands in PSFTP support \q{wildcards} to select multiple
181 For \e{local} file specifications (such as the first argument to
182 \c{put}), wildcard rules for the local operating system are used. For
183 instance, PSFTP running on Windows might require the use of \c{*.*}
184 where PSFTP on Unix would need \c{*}.
186 For \e{remote} file specifications (such as the first argument to
187 \c{get}), PSFTP uses a standard wildcard syntax (similar to POSIX
190 \b \c{*} matches any sequence of characters (including a zero-length
193 \b \c{?} matches exactly one character.
195 \b \c{[abc]} matches exactly one character which can be \cw{a},
200 \c{[a-z]} matches any character in the range \cw{a} to \cw{z}.
202 \c{[^abc]} matches a single character that is \e{not} \cw{a}, \cw{b},
205 Special cases: \c{[-a]} matches a literal hyphen (\cw{-}) or \cw{a};
206 \c{[^-a]} matches all other characters. \c{[a^]} matches a literal
207 caret (\cw{^}) or \cw{a}.
211 \b \c{\\} (backslash) before any of the above characters (or itself)
212 removes that character's special meaning.
214 A leading period (\cw{.}) on a filename is not treated specially,
215 unlike in some Unix contexts; \c{get *} will fetch all files, whether
216 or not they start with a leading period.
218 \S{psftp-cmd-open} The \c{open} command: start a session
220 If you started PSFTP by double-clicking in the GUI, or just by
221 typing \c{psftp} at the command line, you will need to open a
222 connection to an SFTP server before you can issue any other
223 commands (except \c{help} and \c{quit}).
225 To create a connection, type \c{open host.name}, or if you need to
226 specify a user name as well you can type \c{open user@host.name}.
228 Once you have issued this command, you will not be able to issue it
229 again, \e{even} if the command fails (for example, if you mistype
230 the host name or the connection times out). So if the connection is
231 not opened successfully, PSFTP will terminate immediately.
233 \S{psftp-cmd-quit} The \c{quit} command: end your session
235 When you have finished your session, type the command \c{quit} to
236 close the connection, terminate PSFTP and return to the command line
237 (or just close the PSFTP console window if you started it from the
240 You can also use the \c{bye} and \c{exit} commands, which have
241 exactly the same effect.
243 \S{psftp-cmd-close} The \c{close} command: close your connection
245 If you just want to close the network connection but keep PSFTP
246 running, you can use the \c{close} command. You can then use the
247 \c{open} command to open a new connection.
249 \S{psftp-cmd-help} The \c{help} command: get quick online help
251 If you type \c{help}, PSFTP will give a short list of the available
254 If you type \c{help} with a command name - for example, \c{help get}
255 - then PSFTP will give a short piece of help on that particular
258 \S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the
259 remote working directory
261 PSFTP maintains a notion of your \q{working directory} on the
262 server. This is the default directory that other commands will
263 operate on. For example, if you type \c{get filename.dat} then PSFTP
264 will look for \c{filename.dat} in your remote working directory on
267 To change your remote working directory, use the \c{cd} command. If
268 you don't provide an argument, \c{cd} will return you to your home
269 directory on the server (more precisely, the remote directory you were
270 in at the start of the connection).
272 To display your current remote working directory, type \c{pwd}.
274 \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
275 local working directory
277 As well as having a working directory on the remote server, PSFTP
278 also has a working directory on your local machine (just like any
279 other Windows process). This is the default local directory that
280 other commands will operate on. For example, if you type \c{get
281 filename.dat} then PSFTP will save the resulting file as
282 \c{filename.dat} in your local working directory.
284 To change your local working directory, use the \c{lcd} command. To
285 display your current local working directory, type \c{lpwd}.
287 \S{psftp-cmd-get} The \c{get} command: fetch a file from the server
289 To download a file from the server and store it on your local PC,
290 you use the \c{get} command.
292 In its simplest form, you just use this with a file name:
296 If you want to store the file locally under a different name,
297 specify the local file name after the remote one:
299 \c get myfile.dat newname.dat
301 This will fetch the file on the server called \c{myfile.dat}, but
302 will save it to your local machine under the name \c{newname.dat}.
304 To fetch an entire directory recursively, you can use the \c{-r}
308 \c get -r mydir newname
310 (If you want to fetch a file whose name starts with a hyphen, you
311 may have to use the \c{--} special argument, which stops \c{get}
312 from interpreting anything as a switch after it. For example,
313 \cq{get -- -silly-name-}.)
315 \S{psftp-cmd-put} The \c{put} command: send a file to the server
317 To upload a file to the server from your local PC, you use the
320 In its simplest form, you just use this with a file name:
324 If you want to store the file remotely under a different name,
325 specify the remote file name after the local one:
327 \c put myfile.dat newname.dat
329 This will send the local file called \c{myfile.dat}, but will store
330 it on the server under the name \c{newname.dat}.
332 To send an entire directory recursively, you can use the \c{-r}
336 \c put -r mydir newname
338 (If you want to send a file whose name starts with a hyphen, you may
339 have to use the \c{--} special argument, which stops \c{put} from
340 interpreting anything as a switch after it. For example, \cq{put --
343 \S{psftp-cmd-mgetput} The \c{mget} and \c{mput} commands: fetch or
346 \c{mget} works almost exactly like \c{get}, except that it allows
347 you to specify more than one file to fetch at once. You can do this
350 \b by giving two or more explicit file names (\cq{mget file1.txt
353 \b by using a wildcard (\cq{mget *.txt}).
355 Every argument to \c{mget} is treated as the name of a file to fetch
356 (unlike \c{get}, which will interpret at most one argument like
357 that, and a second argument will be treated as an alternative name
358 under which to store the retrieved file), or a wildcard expression
359 matching more than one file.
361 The \c{-r} and \c{--} options from \c{get} are also available with
364 \c{mput} is similar to \c{put}, with the same differences.
366 \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
367 resuming file transfers
369 If a file transfer fails half way through, and you end up with half
370 the file stored on your disk, you can resume the file transfer using
371 the \c{reget} and \c{reput} commands. These work exactly like the
372 \c{get} and \c{put} commands, but they check for the presence of the
373 half-written destination file and start transferring from where the
374 last attempt left off.
376 The syntax of \c{reget} and \c{reput} is exactly the same as the
377 syntax of \c{get} and \c{put}:
380 \c reget myfile.dat newname.dat
383 These commands are intended mainly for resuming interrupted transfers.
384 They assume that the remote file or directory structure has not
385 changed in any way; if there have been changes, you may end up with
386 corrupted files. In particular, the \c{-r} option will not pick up
387 changes to files or directories already transferred in full.
389 \S{psftp-cmd-dir} The \c{dir} command: list remote files
391 To list the files in your remote working directory, just type
394 You can also list the contents of a different directory by typing
395 \c{dir} followed by the directory name:
400 And you can list a subset of the contents of a directory by
401 providing a wildcard:
403 \c dir /home/fred/*.txt
406 The \c{ls} command works exactly the same way as \c{dir}.
408 \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
411 PSFTP allows you to modify the file permissions on files on the
412 server. You do this using the \c{chmod} command, which works very
413 much like the Unix \c{chmod} command.
415 The basic syntax is \c{chmod modes file}, where \c{modes} represents
416 a modification to the file permissions, and \c{file} is the filename
417 to modify. For example:
419 \c chmod go-rwx,u+w privatefile
420 \c chmod a+r publicfile
421 \c chmod 640 groupfile
423 The \c{modes} parameter can be a set of octal digits in the Unix
424 style. (If you don't know what this means, you probably don't want
425 to be using it!) Alternatively, it can be a list of permission
426 modifications, separated by commas. Each modification consists of:
428 \b The people affected by the modification. This can be \c{u} (the
429 owning user), \c{g} (members of the owning group), or \c{o}
430 (everybody else - \q{others}), or some combination of those. It can
431 also be \c{a} (\q{all}) to affect everybody at once.
433 \b A \c{+} or \c{-} sign, indicating whether permissions are to be
436 \b The actual permissions being added or removed. These can be \c{r}
437 (permission to read the file), \c{w} (permission to write to the
438 file), and \c{x} (permission to execute the file, or in the case of
439 a directory, permission to access files within the directory).
441 So the above examples would do:
443 \b The first example: \c{go-rwx} removes read, write and execute
444 permissions for members of the owning group and everybody else (so
445 the only permissions left are the ones for the file owner). \c{u+w}
446 adds write permission for the file owner.
448 \b The second example: \c{a+r} adds read permission for everybody.
450 In addition to all this, there are a few extra special cases for
451 Unix systems. On non-Unix systems these are unlikely to be useful:
453 \b You can specify \c{u+s} and \c{u-s} to add or remove the Unix
454 set-user-ID bit. This is typically only useful for special purposes;
455 refer to your Unix documentation if you're not sure about it.
457 \b You can specify \c{g+s} and \c{g-s} to add or remove the Unix
458 set-group-ID bit. On a file, this works similarly to the set-user-ID
459 bit (see your Unix documentation again); on a directory it ensures
460 that files created in the directory are accessible by members of the
461 group that owns the directory.
463 \b You can specify \c{+t} and \c{-t} to add or remove the Unix
464 \q{sticky bit}. When applied to a directory, this means that the
465 owner of a file in that directory can delete the file (whereas
466 normally only the owner of the \e{directory} would be allowed to).
468 \S{psftp-cmd-del} The \c{del} command: delete remote files
470 To delete a file on the server, type \c{del} and then the filename:
474 The \c{rm} command works exactly the same way as \c{del}.
476 \S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories
478 To create a directory on the server, type \c{mkdir} and then the
483 \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
485 To remove a directory on the server, type \c{rmdir} and then the
490 Most SFTP servers will probably refuse to remove a directory if the
491 directory has anything in it, so you will need to delete the
494 \S{psftp-cmd-ren} The \c{ren} command: rename remote files
496 To rename a file on the server, type \c{ren}, then the current file
497 name, and then the new file name:
499 \c ren oldfile newname
501 The \c{rename} and \c{mv} commands work exactly the same way as
504 \S{psftp-cmd-pling} The \c{!} command: run a local Windows command
506 You can run local Windows commands using the \c{!} command. This is
507 the only PSFTP command that is not subject to the command quoting
508 rules given in \k{psftp-quoting}. If any command line begins with
509 the \c{!} character, then the rest of the line will be passed
510 straight to Windows without further translation.
512 For example, if you want to move an existing copy of a file out of
513 the way before downloading an updated version, you might type:
515 \c psftp> !ren myfile.dat myfile.bak
516 \c psftp> get myfile.dat
518 using the Windows \c{ren} command to rename files on your local PC.
520 \H{psftp-pubkey} Using public key authentication with PSFTP
522 Like PuTTY, PSFTP can authenticate using a public key instead of a
523 password. There are three ways you can do this.
525 Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
526 So you might do this:
528 \b Run PuTTY, and create a PuTTY saved session (see
529 \k{config-saving}) which specifies your private key file (see
530 \k{config-ssh-privkey}). You will probably also want to specify a
531 username to log in as (see \k{config-username}).
533 \b In PSFTP, you can now use the name of the session instead of a
534 hostname: type \c{psftp sessionname}, where \c{sessionname} is
535 replaced by the name of your saved session.
537 Secondly, you can supply the name of a private key file on the command
538 line, with the \c{-i} option. See \k{using-cmdline-identity} for more
541 Thirdly, PSFTP will attempt to authenticate using Pageant if Pageant
542 is running (see \k{pageant}). So you would do this:
544 \b Ensure Pageant is running, and has your private key stored in it.
546 \b Specify a user and host name to PSFTP as normal. PSFTP will
547 automatically detect Pageant and try to use the keys within it.
549 For more general information on public-key authentication, see