1 \versionid $Id: psftp.but,v 1.4 2001/12/31 16:15:19 simon 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 The following sections describe PSFTP's command-line options.
54 \S{psftp-option-l} \c{-l}: specify a user name
56 The \c{-l} option is an alternative way to specify the user name to
57 log in as, on the command line. Instead of typing \c{psftp
58 user@host}, you can also type \c{psftp host -l user}.
60 This option does not work in the \c{open} command once PSFTP has
63 \S{psftp-option-P} \c{-P}: specify a port number
65 If the \c{host} you specify is a saved session, PSFTP uses any port
66 number specified in that saved session. If not, PSFTP uses the
67 default SSH port, 22. The \c{-P} option allows you specify the port
68 number to connect to for PSFTP's SSH connection.
70 \S{psftp-option-v}\c{-v}: show verbose messages
72 The \c{-v} option to PSFTP makes it print verbose information about
73 the establishing of the SSH connection. The information displayed is
74 equivalent to what is shown in the PuTTY Event Log
77 This information may be useful for debugging problems with PSFTP.
79 \S{psftp-option-pw} \c{-pw}: specify a password
81 If a password is required to connect to the \c{host}, PSFTP will
82 interactively prompt you for it. However, this may not always be
83 appropriate. If you are running PSFTP as part of some automated
84 job, it will not be possible to enter a password by hand. The
85 \c{-pw} option to PSFTP lets you specify the password to use on the
88 Since specifying passwords in scripts is a bad idea for security
89 reasons, you might want instead to consider using public-key
90 authentication; see \k{psftp-pubkey}.
92 \S{psftp-option-b} \c{-b}: specify a file containing batch commands
94 In normal operation, PSFTP is an interactive program which displays
95 a command line and accepts commands from the keyboard.
97 If you need to do automated tasks with PSFTP, you would probably
98 prefer to specify a set of commands in advance and have them
99 executed automatically. The \c{-b} option allows you to do this. You
100 use it with a file name containing batch commands. For example, you
101 might create a file called \c{myscript.scr} containing lines like
104 \c cd /home/ftp/users/jeff
105 \c del jam-old.tar.gz
106 \c ren jam.tar.gz jam-old.tar.gz
108 \c chmod a+r jam.tar.gz
111 and then you could run the script by typing
113 \c psftp user@hostname -b myscript.scr
115 When you run a batch script in this way, PSFTP will abort the script
116 if any command fails to complete successfully. To change this
117 behaviour, you can use the \c{-be} option (\k{psftp-option-be}).
119 \S{psftp-option-bc} \c{-bc}: display batch commands as they are run
121 The \c{-bc} option alters what PSFTP displays while processing a
122 batch script. With the \c{-bc} option, PSFTP will display prompts
123 and commands just as if the commands had been typed at the keyboard.
124 So instead of seeing this:
126 \c Sent username "fred"
127 \c Remote working directory is /home/fred
128 \c Listing directory /home/fred/lib
129 \c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
130 \c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
131 \c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
132 \c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
133 \c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
137 \c Sent username "fred"
138 \c Remote working directory is /home/fred
140 \c Listing directory /home/fred/lib
141 \c drwxrwsr-x 4 fred fred 1024 Sep 6 10:42 .
142 \c drwxr-sr-x 25 fred fred 2048 Dec 14 09:36 ..
143 \c drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed
144 \c lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber
145 \c drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn
148 \S{psftp-option-be} \c{-be}: continue batch processing on errors
150 When running a batch file, this option causes PSFTP to continue
151 processing even if a command fails to complete successfully.
153 You might want this to happen if you wanted to delete a file and
154 didn't care if it was already not present, for example.
156 \S{psftp-usage-options-batch}\c{-batch}: avoid interactive prompts
158 If you use the \c{-batch} option, PSFTP will never give an
159 interactive prompt while establishing the connection. If the
160 server's host key is invalid, for example (see \k{gs-hostkey}), then
161 the connection will simply be abandoned instead of asking you what
164 This may help PSFTP's behaviour when it is used in automated
165 scripts: using \c{-batch}, if something goes wrong at connection
166 time, the batch job will fail rather than hang.
168 \H{psftp-commands} Running PSFTP
170 Once you have started your PSFTP session, you will see a \c{psftp>}
171 prompt. You can now type commands to perform file-transfer
172 functions. This section lists all the available commands.
174 \S{psftp-quoting} General quoting rules for PSFTP commands
176 Most PSFTP commands are considered by the PSFTP command interpreter
177 as a sequence of words, separated by spaces. For example, the
178 command \c{ren oldfilename newfilename} splits up into three words:
179 \c{ren} (the command name), \c{oldfilename} (the name of the file to
180 be renamed), and \c{newfilename} (the new name to give the file).
182 Sometimes you will need to specify file names that \e{contain}
183 spaces. In order to do this, you can surround the file name with
184 double quotes. This works equally well for local file names and
187 \c psftp> get "spacey file name.txt" "save it under this name.txt"
189 The double quotes themselves will not appear as part of the file
190 names; they are removed by PSFTP and their only effect is to stop
191 the spaces inside them from acting as word separators.
193 If you need to \e{use} a double quote (on some types of remote
194 system, such as Unix, you are allowed to use double quotes in file
195 names), you can do this by doubling it. This works both inside and
196 outside double quotes. For example, this command
198 \c psftp> ren ""this"" "a file with ""quotes"" in it"
200 will take a file whose current name is \c{"this"} (with a double
201 quote character at the beginning and the end) and rename it to a
202 file whose name is \c{a file with "quotes" in it}.
204 (The one exception to the PSFTP quoting rules is the \c{!} command,
205 which passes its command line straight to Windows without splitting
206 it up into words at all. See \k{psftp-cmd-pling}.)
208 \S{psftp-cmd-open} The \c{open} command: start a session
210 If you started PSFTP by double-clicking in the GUI, or just by
211 typing \c{psftp} at the command line, you will need to open a
212 connection to an SFTP server before you can issue any other
213 commands (except \c{help} and \c{quit}).
215 To create a connection, type \c{open host.name}, or if you need to
216 specify a user name as well you can type \c{open user@host.name}.
218 Once you have issued this command, you will not be able to issue it
219 again, \e{even} if the command fails (for example, if you mistype
220 the host name or the connection times out). So if the connection is
221 not opened successfully, PSFTP will terminate immediately.
223 \S{psftp-cmd-quit} The \c{quit} command: end your session
225 When you have finished your session, type the command \c{quit} to
226 terminate PSFTP and return to the command line (or just close the
227 PSFTP console window if you started it from the GUI).
229 You can also use the \c{bye} and \c{exit} commands, which have
230 exactly the same effect.
232 \S{psftp-cmd-help} The \c{help} command: get quick online help
234 If you type \c{help}, PSFTP will give a short list of the available
237 If you type \c{help} with a command name - for example, \c{help get}
238 - then PSFTP will give a short piece of help on that particular
241 \S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the
242 remote working directory
244 PSFTP maintains a notion of your \q{working directory} on the
245 server. This is the default directory that other commands will
246 operate on. For example, if you type \c{get filename.dat} then PSFTP
247 will look for \c{filename.dat} in your remote working directory on
250 To change your remote working directory, use the \c{cd} command. To
251 display your current remote working directory, type \c{pwd}.
253 \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
254 local working directory
256 As well as having a working directory on the remote server, PSFTP
257 also has a working directory on your local machine (just like any
258 other Windows process). This is the default local directory that
259 other commands will operate on. For example, if you type \c{get
260 filename.dat} then PSFTP will save the resulting file as
261 \c{filename.dat} in your local working directory.
263 To change your local working directory, use the \c{lcd} command. To
264 display your current local working directory, type \c{lpwd}.
266 \S{psftp-cmd-get} The \c{get} command: fetch a file from the server
268 To download a file from the server and store it on your local PC,
269 you use the \c{get} command.
271 In its simplest form, you just use this with a file name:
275 If you want to store the file locally under a different name,
276 specify the local file name after the remote one:
278 \c get myfile.dat newname.dat
280 This will fetch the file on the server called \c{myfile.dat}, but
281 will save it to your local machine under the name \c{newname.dat}.
283 \S{psftp-cmd-put} The \c{put} command: send a file to the server
285 To upload a file to the server from your local PC, you use the
288 In its simplest form, you just use this with a file name:
292 If you want to store the file remotely under a different name,
293 specify the remote file name after the local one:
295 \c put myfile.dat newname.dat
297 This will send the local file called \c{myfile.dat}, but will store
298 it on the server under the name \c{newname.dat}.
300 \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
301 resuming file transfers
303 If a file transfer fails half way through, and you end up with half
304 the file stored on your disk, you can resume the file transfer using
305 the \c{reget} and \c{reput} commands. These work exactly like the
306 \c{get} and \c{put} commands, but they check for the presence of the
307 half-written destination file and start transferring from where the
308 last attempt left off.
310 The syntax of \c{reget} and \c{reput} is exactly the same as the
311 syntax of \c{get} and \c{put}:
314 \c reget myfile.dat newname.dat
316 \S{psftp-cmd-dir} The \c{dir} command: list remote files
318 To list the files in your remote working directory, just type
321 You can also list the contents of a different directory by typing
322 \c{dir} followed by the directory name:
327 The \c{ls} command works exactly the same way as \c{dir}.
329 \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
332 PSFTP allows you to modify the file permissions on files on the
333 server. You do this using the \c{chmod} command, which works very
334 much like the Unix \c{chmod} command.
336 The basic syntax is \c{chmod modes file}, where \c{modes} represents
337 a modification to the file permissions, and \c{file} is the filename
338 to modify. For example:
340 \c chmod go-rwx,u+w privatefile
341 \c chmod a+r publicfile
342 \c chmod 640 groupfile
344 The \c{modes} parameter can be a set of octal digits in the Unix
345 style. (If you don't know what this means, you probably don't want
346 to be using it!) Alternatively, it can be a list of permission
347 modifications, separated by commas. Each modification consists of:
349 \b The people affected by the modification. This can be \c{u} (the
350 owning user), \c{g} (members of the owning group), or \c{o}
351 (everybody else - \q{others}), or some combination of those. It can
352 also be \c{a} (\q{all}) to affect everybody at once.
354 \b A \c{+} or \c{-} sign, indicating whether permissions are to be
357 \b The actual permissions being added or removed. These can be \c{r}
358 (permission to read the file), \c{w} (permission to write to the
359 file), and \c{x} (permission to execute the file, or in the case of
360 a directory, permission to access files within the directory).
362 So the above examples would do:
364 \b The first example: \c{go-rwx} removes read, write and execute
365 permissions for members of the owning group and everybody else (so
366 the only permissions left are the ones for the file owner). \c{u+w}
367 adds write permission for the file owner.
369 \b The second example: \c{a+r} adds read permission for everybody.
371 In addition to all this, there are a few extra special cases for
372 Unix systems. On non-Unix systems these are unlikely to be useful:
374 \b You can specify \c{u+s} and \c{u-s} to add or remove the Unix
375 set-user-ID bit. This is typically only useful for special purposes;
376 refer to your Unix documentation if you're not sure about it.
378 \b You can specify \c{g+s} and \c{g-s} to add or remove the Unix
379 set-group-ID bit. On a file, this works similarly to the set-user-ID
380 bit (see your Unix documentation again); on a directory it ensures
381 that files created in the directory are accessible by members of the
382 group that owns the directory.
384 \b You can specify \c{+t} and \c{-t} to add or remove the Unix
385 \q{sticky bit}. When applied to a directory, this means that the
386 owner of a file in that directory can delete the file (whereas
387 normally only the owner of the \e{directory} would be allowed to).
389 \S{psftp-cmd-del} The \c{del} command: delete remote files
391 To delete a file on the server, type \c{del} and then the filename:
395 The \c{rm} command works exactly the same way as \c{del}.
397 \S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories
399 To create a directory on the server, type \c{mkdir} and then the
404 \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
406 To remove a directory on the server, type \c{rmdir} and then the
411 Most SFTP servers will probably refuse to remove a directory if the
412 directory has anything in it, so you will need to delete the
415 \S{psftp-cmd-ren} The \c{ren} command: rename remote files
417 To rename a file on the server, type \c{ren}, then the current file
418 name, and then the new file name:
420 \c ren oldfile newname
422 The \c{rename} and \c{mv} commands work exactly the same way as
425 \S{psftp-cmd-pling} The \c{!} command: run a local Windows command
427 You can run local Windows commands using the \c{!} command. This is
428 the only PSFTP command that is not subject to the command quoting
429 rules given in \k{psftp-quoting}. If any command line begins with
430 the \c{!} character, then the rest of the line will be passed
431 straight to Windows without further translation.
433 For example, if you want to move an existing copy of a file out of
434 the way before downloading an updated version, you might type:
436 \c psftp> !ren myfile.dat myfile.bak
437 \c psftp> get myfile.dat
439 using the Windows \c{ren} command to rename files on your local PC.
441 \H{psftp-pubkey} Using public key authentication with PSFTP
443 Like PuTTY, PSFTP can authenticate using a public key instead of a
444 password. There are two ways you can do this.
446 Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
447 So you might do this:
449 \b Run PuTTY, and create a PuTTY saved session (see
450 \k{config-saving}) which specifies your private key file (see
451 \k{config-ssh-privkey}). You will probably also want to specify a
452 username to log in as (see \k{config-username}).
454 \b In PSFTP, you can now use the name of the session instead of a
455 hostname: type \c{psftp sessionname}, where \c{sessionname} is
456 replaced by the name of your saved session.
458 Secondly, PSFTP will attempt to authenticate using Pageant if Pageant
459 is running (see \k{pageant}). So you would do this:
461 \b Ensure Pageant is running, and has your private key stored in it.
463 \b Specify a user and host name to PSFTP as normal. PSFTP will
464 automatically detect Pageant and try to use the keys within it.
466 For more general information on public-key authentication, see