1 \versionid $Id: psftp.but,v 1.5 2002/08/07 19:20:06 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 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. To
219 display your current remote working directory, type \c{pwd}.
221 \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
222 local working directory
224 As well as having a working directory on the remote server, PSFTP
225 also has a working directory on your local machine (just like any
226 other Windows process). This is the default local directory that
227 other commands will operate on. For example, if you type \c{get
228 filename.dat} then PSFTP will save the resulting file as
229 \c{filename.dat} in your local working directory.
231 To change your local working directory, use the \c{lcd} command. To
232 display your current local working directory, type \c{lpwd}.
234 \S{psftp-cmd-get} The \c{get} command: fetch a file from the server
236 To download a file from the server and store it on your local PC,
237 you use the \c{get} command.
239 In its simplest form, you just use this with a file name:
243 If you want to store the file locally under a different name,
244 specify the local file name after the remote one:
246 \c get myfile.dat newname.dat
248 This will fetch the file on the server called \c{myfile.dat}, but
249 will save it to your local machine under the name \c{newname.dat}.
251 \S{psftp-cmd-put} The \c{put} command: send a file to the server
253 To upload a file to the server from your local PC, you use the
256 In its simplest form, you just use this with a file name:
260 If you want to store the file remotely under a different name,
261 specify the remote file name after the local one:
263 \c put myfile.dat newname.dat
265 This will send the local file called \c{myfile.dat}, but will store
266 it on the server under the name \c{newname.dat}.
268 \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
269 resuming file transfers
271 If a file transfer fails half way through, and you end up with half
272 the file stored on your disk, you can resume the file transfer using
273 the \c{reget} and \c{reput} commands. These work exactly like the
274 \c{get} and \c{put} commands, but they check for the presence of the
275 half-written destination file and start transferring from where the
276 last attempt left off.
278 The syntax of \c{reget} and \c{reput} is exactly the same as the
279 syntax of \c{get} and \c{put}:
282 \c reget myfile.dat newname.dat
284 \S{psftp-cmd-dir} The \c{dir} command: list remote files
286 To list the files in your remote working directory, just type
289 You can also list the contents of a different directory by typing
290 \c{dir} followed by the directory name:
295 The \c{ls} command works exactly the same way as \c{dir}.
297 \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
300 PSFTP allows you to modify the file permissions on files on the
301 server. You do this using the \c{chmod} command, which works very
302 much like the Unix \c{chmod} command.
304 The basic syntax is \c{chmod modes file}, where \c{modes} represents
305 a modification to the file permissions, and \c{file} is the filename
306 to modify. For example:
308 \c chmod go-rwx,u+w privatefile
309 \c chmod a+r publicfile
310 \c chmod 640 groupfile
312 The \c{modes} parameter can be a set of octal digits in the Unix
313 style. (If you don't know what this means, you probably don't want
314 to be using it!) Alternatively, it can be a list of permission
315 modifications, separated by commas. Each modification consists of:
317 \b The people affected by the modification. This can be \c{u} (the
318 owning user), \c{g} (members of the owning group), or \c{o}
319 (everybody else - \q{others}), or some combination of those. It can
320 also be \c{a} (\q{all}) to affect everybody at once.
322 \b A \c{+} or \c{-} sign, indicating whether permissions are to be
325 \b The actual permissions being added or removed. These can be \c{r}
326 (permission to read the file), \c{w} (permission to write to the
327 file), and \c{x} (permission to execute the file, or in the case of
328 a directory, permission to access files within the directory).
330 So the above examples would do:
332 \b The first example: \c{go-rwx} removes read, write and execute
333 permissions for members of the owning group and everybody else (so
334 the only permissions left are the ones for the file owner). \c{u+w}
335 adds write permission for the file owner.
337 \b The second example: \c{a+r} adds read permission for everybody.
339 In addition to all this, there are a few extra special cases for
340 Unix systems. On non-Unix systems these are unlikely to be useful:
342 \b You can specify \c{u+s} and \c{u-s} to add or remove the Unix
343 set-user-ID bit. This is typically only useful for special purposes;
344 refer to your Unix documentation if you're not sure about it.
346 \b You can specify \c{g+s} and \c{g-s} to add or remove the Unix
347 set-group-ID bit. On a file, this works similarly to the set-user-ID
348 bit (see your Unix documentation again); on a directory it ensures
349 that files created in the directory are accessible by members of the
350 group that owns the directory.
352 \b You can specify \c{+t} and \c{-t} to add or remove the Unix
353 \q{sticky bit}. When applied to a directory, this means that the
354 owner of a file in that directory can delete the file (whereas
355 normally only the owner of the \e{directory} would be allowed to).
357 \S{psftp-cmd-del} The \c{del} command: delete remote files
359 To delete a file on the server, type \c{del} and then the filename:
363 The \c{rm} command works exactly the same way as \c{del}.
365 \S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories
367 To create a directory on the server, type \c{mkdir} and then the
372 \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
374 To remove a directory on the server, type \c{rmdir} and then the
379 Most SFTP servers will probably refuse to remove a directory if the
380 directory has anything in it, so you will need to delete the
383 \S{psftp-cmd-ren} The \c{ren} command: rename remote files
385 To rename a file on the server, type \c{ren}, then the current file
386 name, and then the new file name:
388 \c ren oldfile newname
390 The \c{rename} and \c{mv} commands work exactly the same way as
393 \S{psftp-cmd-pling} The \c{!} command: run a local Windows command
395 You can run local Windows commands using the \c{!} command. This is
396 the only PSFTP command that is not subject to the command quoting
397 rules given in \k{psftp-quoting}. If any command line begins with
398 the \c{!} character, then the rest of the line will be passed
399 straight to Windows without further translation.
401 For example, if you want to move an existing copy of a file out of
402 the way before downloading an updated version, you might type:
404 \c psftp> !ren myfile.dat myfile.bak
405 \c psftp> get myfile.dat
407 using the Windows \c{ren} command to rename files on your local PC.
409 \H{psftp-pubkey} Using public key authentication with PSFTP
411 Like PuTTY, PSFTP can authenticate using a public key instead of a
412 password. There are two ways you can do this.
414 Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
415 So you might do this:
417 \b Run PuTTY, and create a PuTTY saved session (see
418 \k{config-saving}) which specifies your private key file (see
419 \k{config-ssh-privkey}). You will probably also want to specify a
420 username to log in as (see \k{config-username}).
422 \b In PSFTP, you can now use the name of the session instead of a
423 hostname: type \c{psftp sessionname}, where \c{sessionname} is
424 replaced by the name of your saved session.
426 Secondly, PSFTP will attempt to authenticate using Pageant if Pageant
427 is running (see \k{pageant}). So you would do this:
429 \b Ensure Pageant is running, and has your private key stored in it.
431 \b Specify a user and host name to PSFTP as normal. PSFTP will
432 automatically detect Pageant and try to use the keys within it.
434 For more general information on public-key authentication, see