1 \versionid $Id: psftp.but,v 1.3 2001/12/16 13:33:04 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 \H{psftp-commands} Running PSFTP
158 Once you have started your PSFTP session, you will see a \c{psftp>}
159 prompt. You can now type commands to perform file-transfer
160 functions. This section lists all the available commands.
162 \S{psftp-quoting} General quoting rules for PSFTP commands
164 Most PSFTP commands are considered by the PSFTP command interpreter
165 as a sequence of words, separated by spaces. For example, the
166 command \c{ren oldfilename newfilename} splits up into three words:
167 \c{ren} (the command name), \c{oldfilename} (the name of the file to
168 be renamed), and \c{newfilename} (the new name to give the file).
170 Sometimes you will need to specify file names that \e{contain}
171 spaces. In order to do this, you can surround the file name with
172 double quotes. This works equally well for local file names and
175 \c psftp> get "spacey file name.txt" "save it under this name.txt"
177 The double quotes themselves will not appear as part of the file
178 names; they are removed by PSFTP and their only effect is to stop
179 the spaces inside them from acting as word separators.
181 If you need to \e{use} a double quote (on some types of remote
182 system, such as Unix, you are allowed to use double quotes in file
183 names), you can do this by doubling it. This works both inside and
184 outside double quotes. For example, this command
186 \c psftp> ren ""this"" "a file with ""quotes"" in it"
188 will take a file whose current name is \c{"this"} (with a double
189 quote character at the beginning and the end) and rename it to a
190 file whose name is \c{a file with "quotes" in it}.
192 (The one exception to the PSFTP quoting rules is the \c{!} command,
193 which passes its command line straight to Windows without splitting
194 it up into words at all. See \k{psftp-cmd-pling}.)
196 \S{psftp-cmd-open} The \c{open} command: start a session
198 If you started PSFTP by double-clicking in the GUI, or just by
199 typing \c{psftp} at the command line, you will need to open a
200 connection to an SFTP server before you can issue any other
201 commands (except \c{help} and \c{quit}).
203 To create a connection, type \c{open host.name}, or if you need to
204 specify a user name as well you can type \c{open user@host.name}.
206 Once you have issued this command, you will not be able to issue it
207 again, \e{even} if the command fails (for example, if you mistype
208 the host name or the connection times out). So if the connection is
209 not opened successfully, PSFTP will terminate immediately.
211 \S{psftp-cmd-quit} The \c{quit} command: end your session
213 When you have finished your session, type the command \c{quit} to
214 terminate PSFTP and return to the command line (or just close the
215 PSFTP console window if you started it from the GUI).
217 You can also use the \c{bye} and \c{exit} commands, which have
218 exactly the same effect.
220 \S{psftp-cmd-help} The \c{help} command: get quick online help
222 If you type \c{help}, PSFTP will give a short list of the available
225 If you type \c{help} with a command name - for example, \c{help get}
226 - then PSFTP will give a short piece of help on that particular
229 \S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the
230 remote working directory
232 PSFTP maintains a notion of your \q{working directory} on the
233 server. This is the default directory that other commands will
234 operate on. For example, if you type \c{get filename.dat} then PSFTP
235 will look for \c{filename.dat} in your remote working directory on
238 To change your remote working directory, use the \c{cd} command. To
239 display your current remote working directory, type \c{pwd}.
241 \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
242 local working directory
244 As well as having a working directory on the remote server, PSFTP
245 also has a working directory on your local machine (just like any
246 other Windows process). This is the default local directory that
247 other commands will operate on. For example, if you type \c{get
248 filename.dat} then PSFTP will save the resulting file as
249 \c{filename.dat} in your local working directory.
251 To change your local working directory, use the \c{lcd} command. To
252 display your current local working directory, type \c{lpwd}.
254 \S{psftp-cmd-get} The \c{get} command: fetch a file from the server
256 To download a file from the server and store it on your local PC,
257 you use the \c{get} command.
259 In its simplest form, you just use this with a file name:
263 If you want to store the file locally under a different name,
264 specify the local file name after the remote one:
266 \c get myfile.dat newname.dat
268 This will fetch the file on the server called \c{myfile.dat}, but
269 will save it to your local machine under the name \c{newname.dat}.
271 \S{psftp-cmd-put} The \c{put} command: send a file to the server
273 To upload a file to the server from your local PC, you use the
276 In its simplest form, you just use this with a file name:
280 If you want to store the file remotely under a different name,
281 specify the remote file name after the local one:
283 \c put myfile.dat newname.dat
285 This will send the local file called \c{myfile.dat}, but will store
286 it on the server under the name \c{newname.dat}.
288 \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
289 resuming file transfers
291 If a file transfer fails half way through, and you end up with half
292 the file stored on your disk, you can resume the file transfer using
293 the \c{reget} and \c{reput} commands. These work exactly like the
294 \c{get} and \c{put} commands, but they check for the presence of the
295 half-written destination file and start transferring from where the
296 last attempt left off.
298 The syntax of \c{reget} and \c{reput} is exactly the same as the
299 syntax of \c{get} and \c{put}:
302 \c reget myfile.dat newname.dat
304 \S{psftp-cmd-dir} The \c{dir} command: list remote files
306 To list the files in your remote working directory, just type
309 You can also list the contents of a different directory by typing
310 \c{dir} followed by the directory name:
315 The \c{ls} command works exactly the same way as \c{dir}.
317 \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
320 PSFTP allows you to modify the file permissions on files on the
321 server. You do this using the \c{chmod} command, which works very
322 much like the Unix \c{chmod} command.
324 The basic syntax is \c{chmod modes file}, where \c{modes} represents
325 a modification to the file permissions, and \c{file} is the filename
326 to modify. For example:
328 \c chmod go-rwx,u+w privatefile
329 \c chmod a+r publicfile
330 \c chmod 640 groupfile
332 The \c{modes} parameter can be a set of octal digits in the Unix
333 style. (If you don't know what this means, you probably don't want
334 to be using it!) Alternatively, it can be a list of permission
335 modifications, separated by commas. Each modification consists of:
337 \b The people affected by the modification. This can be \c{u} (the
338 owning user), \c{g} (members of the owning group), or \c{o}
339 (everybody else - \q{others}), or some combination of those. It can
340 also be \c{a} (\q{all}) to affect everybody at once.
342 \b A \c{+} or \c{-} sign, indicating whether permissions are to be
345 \b The actual permissions being added or removed. These can be \c{r}
346 (permission to read the file), \c{w} (permission to write to the
347 file), and \c{x} (permission to execute the file, or in the case of
348 a directory, permission to access files within the directory).
350 So the above examples would do:
352 \b The first example: \c{go-rwx} removes read, write and execute
353 permissions for members of the owning group and everybody else (so
354 the only permissions left are the ones for the file owner). \c{u+w}
355 adds write permission for the file owner.
357 \b The second example: \c{a+r} adds read permission for everybody.
359 In addition to all this, there are a few extra special cases for
360 Unix systems. On non-Unix systems these are unlikely to be useful:
362 \b You can specify \c{u+s} and \c{u-s} to add or remove the Unix
363 set-user-ID bit. This is typically only useful for special purposes;
364 refer to your Unix documentation if you're not sure about it.
366 \b You can specify \c{g+s} and \c{g-s} to add or remove the Unix
367 set-group-ID bit. On a file, this works similarly to the set-user-ID
368 bit (see your Unix documentation again); on a directory it ensures
369 that files created in the directory are accessible by members of the
370 group that owns the directory.
372 \b You can specify \c{+t} and \c{-t} to add or remove the Unix
373 \q{sticky bit}. When applied to a directory, this means that the
374 owner of a file in that directory can delete the file (whereas
375 normally only the owner of the \e{directory} would be allowed to).
377 \S{psftp-cmd-del} The \c{del} command: delete remote files
379 To delete a file on the server, type \c{del} and then the filename:
383 The \c{rm} command works exactly the same way as \c{del}.
385 \S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories
387 To create a directory on the server, type \c{mkdir} and then the
392 \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
394 To remove a directory on the server, type \c{rmdir} and then the
399 Most SFTP servers will probably refuse to remove a directory if the
400 directory has anything in it, so you will need to delete the
403 \S{psftp-cmd-ren} The \c{ren} command: rename remote files
405 To rename a file on the server, type \c{ren}, then the current file
406 name, and then the new file name:
408 \c ren oldfile newname
410 The \c{rename} and \c{mv} commands work exactly the same way as
413 \S{psftp-cmd-pling} The \c{!} command: run a local Windows command
415 You can run local Windows commands using the \c{!} command. This is
416 the only PSFTP command that is not subject to the command quoting
417 rules given in \k{psftp-quoting}. If any command line begins with
418 the \c{!} character, then the rest of the line will be passed
419 straight to Windows without further translation.
421 For example, if you want to move an existing copy of a file out of
422 the way before downloading an updated version, you might type:
424 \c psftp> !ren myfile.dat myfile.bak
425 \c psftp> get myfile.dat
427 using the Windows \c{ren} command to rename files on your local PC.
429 \H{psftp-pubkey} Using public key authentication with PSFTP
431 Like PuTTY, PSFTP can authenticate using a public key instead of a
432 password. There are two ways you can do this.
434 Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
435 So you might do this:
437 \b Run PuTTY, and create a PuTTY saved session (see
438 \k{config-saving}) which specifies your private key file (see
439 \k{config-ssh-privkey}). You will probably also want to specify a
440 username to log in as (see \k{config-username}).
442 \b In PSFTP, you can now use the name of the session instead of a
443 hostname: type \c{psftp sessionname}, where \c{sessionname} is
444 replaced by the name of your saved session.
446 Secondly, PSFTP will attempt to authenticate using Pageant if Pageant
447 is running (see \k{pageant}). So you would do this:
449 \b Ensure Pageant is running, and has your private key stored in it.
451 \b Specify a user and host name to PSFTP as normal. PSFTP will
452 automatically detect Pageant and try to use the keys within it.
454 For more general information on public-key authentication, see