1 \define{versionidpsftp} \versionid $Id$
3 \C{psftp} Using \i{PSFTP} to transfer files securely
5 \i{PSFTP}, the PuTTY SFTP client, is a tool for \i{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 \i{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 \i\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} \I{-b-PSFTP}\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 \I{batch scripts in PSFTP}specify a set of commands in
67 advance and have them executed automatically. The \c{-b} option
68 allows you to do this. You use it with a file name containing batch
69 commands. For example, you might create a file called \c{myscript.scr}
70 containing lines like this:
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
78 and then you could run the script by typing
80 \c psftp user@hostname -b myscript.scr
82 When you run a batch script in this way, PSFTP will abort the script
83 if any command fails to complete successfully. To change this
84 behaviour, you can add the \c{-be} option (\k{psftp-option-be}).
86 PSFTP will terminate after it finishes executing the batch script.
88 \S{psftp-option-bc} \I{-bc-PSFTP}\c{-bc}: display batch commands as they are run
90 The \c{-bc} option alters what PSFTP displays while processing a
91 batch script specified with \c{-b}. With the \c{-bc} option, PSFTP
92 will display prompts and commands just as if the commands had been
93 typed at the keyboard. So instead of seeing this:
95 \c C:\>psftp fred@hostname -b batchfile
96 \c Sent username "fred"
97 \c Remote working directory is /home/fred
98 \c Listing directory /home/fred/lib
99 \c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
100 \c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
101 \c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
102 \c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
103 \c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
107 \c C:\>psftp fred@hostname -bc -b batchfile
108 \c Sent username "fred"
109 \c Remote working directory is /home/fred
111 \c Listing directory /home/fred/lib
112 \c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
113 \c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
114 \c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
115 \c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
116 \c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
119 \S{psftp-option-be} \I{-be-PSFTP}\c{-be}: continue batch processing on errors
121 When running a batch file, this additional option causes PSFTP to
122 continue processing even if a command fails to complete successfully.
124 You might want this to happen if you wanted to delete a file and
125 didn't care if it was already not present, for example.
127 \S{psftp-usage-options-batch} \I{-batch-PSFTP}\c{-batch}: avoid
130 If you use the \c{-batch} option, PSFTP will never give an
131 interactive prompt while establishing the connection. If the
132 server's host key is invalid, for example (see \k{gs-hostkey}), then
133 the connection will simply be abandoned instead of asking you what
136 This may help PSFTP's behaviour when it is used in automated
137 scripts: using \c{-batch}, if something goes wrong at connection
138 time, the batch job will fail rather than hang.
140 \H{psftp-commands} Running PSFTP
142 Once you have started your PSFTP session, you will see a \c{psftp>}
143 prompt. You can now type commands to perform file-transfer
144 functions. This section lists all the available commands.
146 Any line starting with a \cw{#} will be treated as a \i{comment}
149 \S{psftp-quoting} \I{quoting, in PSFTP}General quoting rules for PSFTP commands
151 Most PSFTP commands are considered by the PSFTP command interpreter
152 as a sequence of words, separated by spaces. For example, the
153 command \c{ren oldfilename newfilename} splits up into three words:
154 \c{ren} (the command name), \c{oldfilename} (the name of the file to
155 be renamed), and \c{newfilename} (the new name to give the file).
157 Sometimes you will need to specify \I{spaces in filenames}file names
158 that \e{contain} spaces. In order to do this, you can surround
159 the file name with double quotes. This works equally well for
160 local file names and remote file names:
162 \c psftp> get "spacey file name.txt" "save it under this name.txt"
164 The double quotes themselves will not appear as part of the file
165 names; they are removed by PSFTP and their only effect is to stop
166 the spaces inside them from acting as word separators.
168 If you need to \e{use} a double quote (on some types of remote
169 system, such as Unix, you are allowed to use double quotes in file
170 names), you can do this by doubling it. This works both inside and
171 outside double quotes. For example, this command
173 \c psftp> ren ""this"" "a file with ""quotes"" in it"
175 will take a file whose current name is \c{"this"} (with a double
176 quote character at the beginning and the end) and rename it to a
177 file whose name is \c{a file with "quotes" in it}.
179 (The one exception to the PSFTP quoting rules is the \c{!} command,
180 which passes its command line straight to Windows without splitting
181 it up into words at all. See \k{psftp-cmd-pling}.)
183 \S{psftp-wildcards} Wildcards in PSFTP
185 Several commands in PSFTP support \q{\i{wildcards}} to select multiple
188 For \e{local} file specifications (such as the first argument to
189 \c{put}), wildcard rules for the local operating system are used. For
190 instance, PSFTP running on Windows might require the use of \c{*.*}
191 where PSFTP on Unix would need \c{*}.
193 For \e{remote} file specifications (such as the first argument to
194 \c{get}), PSFTP uses a standard wildcard syntax (similar to \i{POSIX}
197 \b \c{*} matches any sequence of characters (including a zero-length
200 \b \c{?} matches exactly one character.
202 \b \c{[abc]} matches exactly one character which can be \cw{a},
207 \c{[a-z]} matches any character in the range \cw{a} to \cw{z}.
209 \c{[^abc]} matches a single character that is \e{not} \cw{a}, \cw{b},
212 Special cases: \c{[-a]} matches a literal hyphen (\cw{-}) or \cw{a};
213 \c{[^-a]} matches all other characters. \c{[a^]} matches a literal
214 caret (\cw{^}) or \cw{a}.
218 \b \c{\\} (backslash) before any of the above characters (or itself)
219 removes that character's special meaning.
221 A leading period (\cw{.}) on a filename is not treated specially,
222 unlike in some Unix contexts; \c{get *} will fetch all files, whether
223 or not they start with a leading period.
225 \S{psftp-cmd-open} The \c{open} command: start a session
227 If you started PSFTP by double-clicking in the GUI, or just by
228 typing \c{psftp} at the command line, you will need to open a
229 connection to an SFTP server before you can issue any other
230 commands (except \c{help} and \c{quit}).
232 To create a connection, type \c{open host.name}, or if you need to
233 specify a user name as well you can type \c{open user@host.name}.
234 You can optionally specify a port as well:
235 \c{open user@host.name 22}.
237 Once you have issued this command, you will not be able to issue it
238 again, \e{even} if the command fails (for example, if you mistype
239 the host name or the connection times out). So if the connection is
240 not opened successfully, PSFTP will terminate immediately.
242 \S{psftp-cmd-quit} The \c{quit} command: end your session
244 When you have finished your session, type the command \c{quit} to
245 close the connection, terminate PSFTP and return to the command line
246 (or just close the PSFTP console window if you started it from the
249 You can also use the \c{bye} and \c{exit} commands, which have
250 exactly the same effect.
252 \S{psftp-cmd-close} The \c{close} command: close your connection
254 If you just want to close the network connection but keep PSFTP
255 running, you can use the \c{close} command. You can then use the
256 \c{open} command to open a new connection.
258 \S{psftp-cmd-help} The \c{help} command: get quick online help
260 If you type \c{help}, PSFTP will give a short list of the available
263 If you type \c{help} with a command name - for example, \c{help get}
264 - then PSFTP will give a short piece of help on that particular
267 \S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the
268 remote \i{working directory}
270 PSFTP maintains a notion of your \q{working directory} on the
271 server. This is the default directory that other commands will
272 operate on. For example, if you type \c{get filename.dat} then PSFTP
273 will look for \c{filename.dat} in your remote working directory on
276 To change your remote working directory, use the \c{cd} command. If
277 you don't provide an argument, \c{cd} will return you to your home
278 directory on the server (more precisely, the remote directory you were
279 in at the start of the connection).
281 To display your current remote working directory, type \c{pwd}.
283 \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
284 local \i{working directory}
286 As well as having a working directory on the remote server, PSFTP
287 also has a working directory on your local machine (just like any
288 other Windows process). This is the default local directory that
289 other commands will operate on. For example, if you type \c{get
290 filename.dat} then PSFTP will save the resulting file as
291 \c{filename.dat} in your local working directory.
293 To change your local working directory, use the \c{lcd} command. To
294 display your current local working directory, type \c{lpwd}.
296 \S{psftp-cmd-get} The \c{get} command: fetch a file from the server
298 To \i{download a file} from the server and store it on your local PC,
299 you use the \c{get} command.
301 In its simplest form, you just use this with a file name:
305 If you want to store the file locally under a different name,
306 specify the local file name after the remote one:
308 \c get myfile.dat newname.dat
310 This will fetch the file on the server called \c{myfile.dat}, but
311 will save it to your local machine under the name \c{newname.dat}.
313 To fetch an entire directory \i{recursive}ly, you can use the \c{-r}
317 \c get -r mydir newname
319 (If you want to fetch a file whose name starts with a hyphen, you
320 may have to use the \c{--} special argument, which stops \c{get}
321 from interpreting anything as a switch after it. For example,
322 \cq{get -- -silly-name-}.)
324 \S{psftp-cmd-put} The \c{put} command: send a file to the server
326 To \i{upload a file} to the server from your local PC, you use the
329 In its simplest form, you just use this with a file name:
333 If you want to store the file remotely under a different name,
334 specify the remote file name after the local one:
336 \c put myfile.dat newname.dat
338 This will send the local file called \c{myfile.dat}, but will store
339 it on the server under the name \c{newname.dat}.
341 To send an entire directory \i{recursive}ly, you can use the \c{-r}
345 \c put -r mydir newname
347 (If you want to send a file whose name starts with a hyphen, you may
348 have to use the \c{--} special argument, which stops \c{put} from
349 interpreting anything as a switch after it. For example, \cq{put --
352 \S{psftp-cmd-mgetput} The \c{mget} and \c{mput} commands: fetch or
355 \c{mget} works almost exactly like \c{get}, except that it allows
356 you to specify more than one file to fetch at once. You can do this
359 \b by giving two or more explicit file names (\cq{mget file1.txt
362 \b by using a wildcard (\cq{mget *.txt}).
364 Every argument to \c{mget} is treated as the name of a file to fetch
365 (unlike \c{get}, which will interpret at most one argument like
366 that, and a second argument will be treated as an alternative name
367 under which to store the retrieved file), or a \i{wildcard} expression
368 matching more than one file.
370 The \c{-r} and \c{--} options from \c{get} are also available with
373 \c{mput} is similar to \c{put}, with the same differences.
375 \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
376 \i{resuming file transfers}
378 If a file transfer fails half way through, and you end up with half
379 the file stored on your disk, you can resume the file transfer using
380 the \c{reget} and \c{reput} commands. These work exactly like the
381 \c{get} and \c{put} commands, but they check for the presence of the
382 half-written destination file and start transferring from where the
383 last attempt left off.
385 The syntax of \c{reget} and \c{reput} is exactly the same as the
386 syntax of \c{get} and \c{put}:
389 \c reget myfile.dat newname.dat
392 These commands are intended mainly for resuming interrupted transfers.
393 They assume that the remote file or directory structure has not
394 changed in any way; if there have been changes, you may end up with
395 corrupted files. In particular, the \c{-r} option will not pick up
396 changes to files or directories already transferred in full.
398 \S{psftp-cmd-dir} The \c{dir} command: \I{listing files}list remote files
400 To list the files in your remote working directory, just type
403 You can also list the contents of a different directory by typing
404 \c{dir} followed by the directory name:
409 And you can list a subset of the contents of a directory by
410 providing a wildcard:
412 \c dir /home/fred/*.txt
415 The \c{ls} command works exactly the same way as \c{dir}.
417 \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
420 \I{changing permissions on files}PSFTP
421 allows you to modify the file permissions on files and
422 directories on the server. You do this using the \c{chmod} command,
423 which works very much like the Unix \c{chmod} command.
425 The basic syntax is \c{chmod modes file}, where \c{modes} represents
426 a modification to the file permissions, and \c{file} is the filename
427 to modify. You can specify multiple files or wildcards. For example:
429 \c chmod go-rwx,u+w privatefile
431 \c chmod 640 groupfile1 groupfile2
433 The \c{modes} parameter can be a set of octal digits in the Unix
434 style. (If you don't know what this means, you probably don't want
435 to be using it!) Alternatively, it can be a list of permission
436 modifications, separated by commas. Each modification consists of:
438 \b The people affected by the modification. This can be \c{u} (the
439 owning user), \c{g} (members of the owning group), or \c{o}
440 (everybody else - \q{others}), or some combination of those. It can
441 also be \c{a} (\q{all}) to affect everybody at once.
443 \b A \c{+} or \c{-} sign, indicating whether permissions are to be
446 \b The actual permissions being added or removed. These can be
447 \I{read permission}\c{r} (permission to read the file),
448 \I{write permission}\c{w} (permission to write to the file), and
449 \I{execute permission}\c{x} (permission to execute the file, or in
450 the case of a directory, permission to access files within the
453 So the above examples would do:
455 \b The first example: \c{go-rwx} removes read, write and execute
456 permissions for members of the owning group and everybody else (so
457 the only permissions left are the ones for the file owner). \c{u+w}
458 adds write permission for the file owner.
460 \b The second example: \c{a+r} adds read permission for everybody to
461 all files and directories starting with \q{public}.
463 In addition to all this, there are a few extra special cases for
464 \i{Unix} systems. On non-Unix systems these are unlikely to be useful:
466 \b You can specify \c{u+s} and \c{u-s} to add or remove the Unix
467 \i{set-user-ID bit}. This is typically only useful for special purposes;
468 refer to your Unix documentation if you're not sure about it.
470 \b You can specify \c{g+s} and \c{g-s} to add or remove the Unix
471 \i{set-group-ID bit}. On a file, this works similarly to the set-user-ID
472 bit (see your Unix documentation again); on a directory it ensures
473 that files created in the directory are accessible by members of the
474 group that owns the directory.
476 \b You can specify \c{+t} and \c{-t} to add or remove the Unix
477 \q{\i{sticky bit}}. When applied to a directory, this means that the
478 owner of a file in that directory can delete the file (whereas
479 normally only the owner of the \e{directory} would be allowed to).
481 \S{psftp-cmd-del} The \c{del} command: delete remote files
483 To \I{deleting files}delete a file on the server, type \c{del} and
484 then the filename or filenames:
487 \c del file1.txt file2.txt
490 Files will be deleted without further prompting, even if multiple files
493 \c{del} will only delete files. You cannot use it to delete
494 directories; use \c{rmdir} for that.
496 The \c{rm} command works exactly the same way as \c{del}.
498 \S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories
500 To \i{create a directory} on the server, type \c{mkdir} and then the
505 You can specify multiple directories to create at once:
507 \c mkdir dir1 dir2 dir3
509 \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
511 To \i{remove a directory} on the server, type \c{rmdir} and then the
512 directory name or names:
515 \c rmdir *.old ancient
517 Directories will be deleted without further prompting, even if
518 multiple directories are specified.
520 Most SFTP servers will probably refuse to remove a directory if the
521 directory has anything in it, so you will need to delete the
524 \S{psftp-cmd-mv} The \c{mv} command: move and \i{rename remote files}
526 To rename a single file on the server, type \c{mv}, then the current
527 file name, and then the new file name:
529 \c mv oldfile newname
531 You can also move the file into a different directory and change the
534 \c mv oldfile dir/newname
536 To move one or more files into an existing subdirectory, specify the
537 files (using wildcards if desired), and then the destination
541 \c mv file1 dir1/file2 dir2
544 The \c{rename} and \c{ren} commands work exactly the same way as
547 \S{psftp-cmd-pling} The \c{!} command: run a \i{local Windows command}
549 You can run local Windows commands using the \c{!} command. This is
550 the only PSFTP command that is not subject to the command quoting
551 rules given in \k{psftp-quoting}. If any command line begins with
552 the \c{!} character, then the rest of the line will be passed
553 straight to Windows without further translation.
555 For example, if you want to move an existing copy of a file out of
556 the way before downloading an updated version, you might type:
558 \c psftp> !ren myfile.dat myfile.bak
559 \c psftp> get myfile.dat
561 using the Windows \c{ren} command to rename files on your local PC.
563 \H{psftp-pubkey} Using \i{public key authentication} with PSFTP
565 Like PuTTY, PSFTP can authenticate using a public key instead of a
566 password. There are three ways you can do this.
568 Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
569 So you might do this:
571 \b Run PuTTY, and create a PuTTY saved session (see
572 \k{config-saving}) which specifies your private key file (see
573 \k{config-ssh-privkey}). You will probably also want to specify a
574 username to log in as (see \k{config-username}).
576 \b In PSFTP, you can now use the name of the session instead of a
577 hostname: type \c{psftp sessionname}, where \c{sessionname} is
578 replaced by the name of your saved session.
580 Secondly, you can supply the name of a private key file on the command
581 line, with the \c{-i} option. See \k{using-cmdline-identity} for more
584 Thirdly, PSFTP will attempt to authenticate using Pageant if Pageant
585 is running (see \k{pageant}). So you would do this:
587 \b Ensure Pageant is running, and has your private key stored in it.
589 \b Specify a user and host name to PSFTP as normal. PSFTP will
590 automatically detect Pageant and try to use the keys within it.
592 For more general information on public-key authentication, see