eb4f8180 |
1 | \versionid $Id: psftp.but,v 1.2 2001/12/14 12:22:09 simon Exp $ |
9a313f60 |
2 | |
3 | \C{psftp} Using PSFTP to transfer files securely |
4 | |
5 | \i{PSFTP}, the PuTTY SFTP client, is a tool for transferring files |
6 | securely between computers using an SSH connection. |
7 | |
8 | PSFTP differs from PSCP in the following ways: |
9 | |
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.) |
14 | |
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 |
20 | terminate. |
21 | |
22 | \H{psftp-starting} Starting PSFTP |
23 | |
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: |
28 | |
29 | \c set PATH=C:\path\to\putty\directory;%PATH% |
30 | |
31 | Unlike PSCP, however, PSFTP has no complex command-line syntax; you |
32 | just specify a host name and perhaps a user name: |
33 | |
34 | \c psftp server.example.com |
35 | |
36 | or perhaps |
37 | |
38 | \c psftp fred@server.example.com |
39 | |
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 |
43 | any server: |
44 | |
45 | \c C:\>psftp |
46 | \c psftp: no hostname specified; use "open host.name" to connect |
47 | \c psftp> |
48 | |
49 | At this point you can type \c{open server.example.com} or \c{open |
50 | fred@server.example.com} to start a session. |
51 | |
52 | The following sections describe PSFTP's command-line options. |
53 | |
54 | \S{psftp-option-l} \c{-l}: specify a user name |
55 | |
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}. |
59 | |
60 | This option does not work in the \c{open} command once PSFTP has |
61 | started. |
62 | |
63 | \S{psftp-option-P} \c{-P}: specify a port number |
64 | |
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. |
69 | |
70 | \S{psftp-option-v}\c{-v}: show verbose messages |
71 | |
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 |
75 | (\k{using-eventlog}). |
76 | |
77 | This information may be useful for debugging problems with PSFTP. |
78 | |
79 | \S{psftp-option-pw} \c{-pw}: specify a password |
80 | |
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 |
86 | command line. |
87 | |
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}. |
91 | |
92 | \S{psftp-option-b} \c{-b}: specify a file containing batch commands |
93 | |
94 | In normal operation, PSFTP is an interactive program which displays |
95 | a command line and accepts commands from the keyboard. |
96 | |
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 |
102 | this: |
103 | |
104 | \c cd /home/ftp/users/jeff |
105 | \c del jam-old.tar.gz |
106 | \c ren jam.tar.gz jam-old.tar.gz |
107 | \c put jam.tar.gz |
108 | \c chmod a+r jam.tar.gz |
109 | \c quit |
110 | |
111 | and then you could run the script by typing |
112 | |
113 | \c psftp user@hostname -b myscript.scr |
114 | |
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}). |
118 | |
119 | \S{psftp-option-bc} \c{-bc}: display batch commands as they are run |
120 | |
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: |
125 | |
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 |
134 | |
135 | you might see this: |
136 | |
137 | \c Sent username "fred" |
138 | \c Remote working directory is /home/fred |
139 | \c psftp> dir lib |
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 |
146 | \c psftp> quit |
147 | |
148 | \S{psftp-option-be} \c{-be}: continue batch processing on errors |
149 | |
150 | When running a batch file, this option causes PSFTP to continue |
151 | processing even if a command fails to complete successfully. |
152 | |
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. |
155 | |
156 | \H{psftp-commands} Running PSFTP |
157 | |
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. |
161 | |
162 | \S{psftp-cmd-open} The \c{open} command: start a session |
163 | |
164 | If you started PSFTP by double-clicking in the GUI, or just by |
165 | typing \c{psftp} at the command line, you will need to open a |
166 | connection to an SFTP server before you can issue any other |
167 | commands (except \c{help} and \c{quit}). |
168 | |
169 | To create a connection, type \c{open host.name}, or if you need to |
170 | specify a user name as well you can type \c{open user@host.name}. |
171 | |
172 | Once you have issued this command, you will not be able to issue it |
173 | again, \e{even} if the command fails (for example, if you mistype |
174 | the host name or the connection times out). So if the connection is |
175 | not opened successfully, PSFTP will terminate immediately. |
176 | |
177 | \S{psftp-cmd-quit} The \c{quit} command: end your session |
178 | |
179 | When you have finished your session, type the command \c{quit} to |
180 | terminate PSFTP and return to the command line (or just close the |
181 | PSFTP console window if you started it from the GUI). |
182 | |
183 | You can also use the \c{bye} and \c{exit} commands, which have |
184 | exactly the same effect. |
185 | |
186 | \S{psftp-cmd-help} The \c{help} command: get quick online help |
187 | |
188 | If you type \c{help}, PSFTP will give a short list of the available |
189 | commands. |
190 | |
191 | If you type \c{help} with a command name - for example, \c{help get} |
192 | - then PSFTP will give a short piece of help on that particular |
193 | command. |
194 | |
195 | \S{psftp-cmd-cd} The \c{cd} and \c{pwd} commands: changing the |
196 | remote working directory |
197 | |
198 | PSFTP maintains a notion of your \q{working directory} on the |
199 | server. This is the default directory that other commands will |
200 | operate on. For example, if you type \c{get filename.dat} then PSFTP |
201 | will look for \c{filename.dat} in your working directory on the |
202 | server. |
203 | |
204 | To change your working directory, use the \c{cd} command. To display |
205 | your current working directory, type \c{pwd}. |
206 | |
207 | \S{psftp-cmd-get} The \c{get} command: fetch a file from the server |
208 | |
209 | To download a file from the server and store it on your local PC, |
210 | you use the \c{get} command. |
211 | |
212 | In its simplest form, you just use this with a file name: |
213 | |
214 | \c get myfile.dat |
215 | |
216 | If you want to store the file locally under a different name, |
217 | specify the local file name after the remote one: |
218 | |
219 | \c get myfile.dat newname.dat |
220 | |
221 | This will fetch the file on the server called \c{myfile.dat}, but |
222 | will save it to your local machine under the name \c{newname.dat}. |
223 | |
224 | \S{psftp-cmd-put} The \c{put} command: send a file to the server |
225 | |
226 | To upload a file to the server from your local PC, you use the |
227 | \c{put} command. |
228 | |
229 | In its simplest form, you just use this with a file name: |
230 | |
231 | \c put myfile.dat |
232 | |
233 | If you want to store the file remotely under a different name, |
234 | specify the remote file name after the local one: |
235 | |
236 | \c put myfile.dat newname.dat |
237 | |
238 | This will send the local file called \c{myfile.dat}, but will store |
239 | it on the server under the name \c{newname.dat}. |
240 | |
241 | \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands: |
242 | resuming file transfers |
243 | |
244 | If a file transfer fails half way through, and you end up with half |
245 | the file stored on your disk, you can resume the file transfer using |
246 | the \c{reget} and \c{reput} commands. These work exactly like the |
247 | \c{get} and \c{put} commands, but they check for the presence of the |
248 | half-written destination file and start transferring from where the |
249 | last attempt left off. |
250 | |
251 | The syntax of \c{reget} and \c{reput} is exactly the same as the |
252 | syntax of \c{get} and \c{put}: |
253 | |
254 | \c reget myfile.dat |
255 | \c reget myfile.dat newname.dat |
256 | |
257 | \S{psftp-cmd-dir} The \c{dir} command: list remote files |
258 | |
259 | To list the files in your remote working directory, just type |
260 | \c{dir}. |
261 | |
262 | You can also list the contents of a different directory by typing |
263 | \c{dir} followed by the directory name: |
264 | |
265 | \c dir /home/fred |
266 | \c dir sources |
267 | |
268 | The \c{ls} command works exactly the same way as \c{dir}. |
269 | |
270 | \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on |
271 | remote files |
272 | |
273 | PSFTP allows you to modify the file permissions on files on the |
274 | server. You do this using the \c{chmod} command, which works very |
275 | much like the Unix \c{chmod} command. |
276 | |
277 | The basic syntax is \c{chmod modes file}, where \c{modes} represents |
278 | a modification to the file permissions, and \c{file} is the filename |
279 | to modify. For example: |
280 | |
281 | \c chmod go-rwx,u+w privatefile |
282 | \c chmod a+r publicfile |
283 | \c chmod 640 groupfile |
284 | |
285 | The \c{modes} parameter can be a set of octal digits in the Unix |
286 | style. (If you don't know what this means, you probably don't want |
287 | to be using it!) Alternatively, it can be a list of permission |
288 | modifications, separated by commas. Each modification consists of: |
289 | |
290 | \b The people affected by the modification. This can be \c{u} (the |
291 | owning user), \c{g} (members of the owning group), or \c{o} |
292 | (everybody else - \q{others}), or some combination of those. It can |
293 | also be \c{a} (\q{all}) to affect everybody at once. |
294 | |
295 | \b A \c{+} or \c{-} sign, indicating whether permissions are to be |
296 | added or removed. |
297 | |
298 | \b The actual permissions being added or removed. These can be \c{r} |
299 | (permission to read the file), \c{w} (permission to write to the |
300 | file), and \c{x} (permission to execute the file, or in the case of |
301 | a directory, permission to access files within the directory). |
302 | |
303 | So the above examples would do: |
304 | |
305 | \b The first example: \c{go-rwx} removes read, write and execute |
306 | permissions for members of the owning group and everybody else (so |
307 | the only permissions left are the ones for the file owner). \c{u+w} |
308 | adds write permission for the file owner. |
309 | |
310 | \b The second example: \c{a+r} adds read permission for everybody. |
311 | |
312 | In addition to all this, there are a few extra special cases for |
313 | Unix systems. On non-Unix systems these are unlikely to be useful: |
314 | |
315 | \b You can specify \c{u+s} and \c{u-s} to add or remove the Unix |
316 | set-user-ID bit. This is typically only useful for special purposes; |
317 | refer to your Unix documentation if you're not sure about it. |
318 | |
319 | \b You can specify \c{g+s} and \c{g-s} to add or remove the Unix |
320 | set-group-ID bit. On a file, this works similarly to the set-user-ID |
321 | bit (see your Unix documentation again); on a directory it ensures |
322 | that files created in the directory are accessible by members of the |
323 | group that owns the directory. |
324 | |
325 | \b You can specify \c{+t} and \c{-t} to add or remove the Unix |
326 | \q{sticky bit}. When applied to a directory, this means that the |
327 | owner of a file in that directory can delete the file (whereas |
328 | normally only the owner of the \e{directory} would be allowed to). |
329 | |
330 | \S{psftp-cmd-del} The \c{del} command: delete remote files |
331 | |
332 | To delete a file on the server, type \c{del} and then the filename: |
333 | |
334 | \c del oldfile.dat |
335 | |
336 | The \c{rm} command works exactly the same way as \c{del}. |
337 | |
338 | \S{psftp-cmd-mkdir} The \c{mkdir} command: create remote directories |
339 | |
340 | To create a directory on the server, type \c{mkdir} and then the |
341 | directory name: |
342 | |
343 | \c mkdir newstuff |
344 | |
345 | \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories |
346 | |
347 | To remove a directory on the server, type \c{rmdir} and then the |
348 | directory name: |
349 | |
350 | \c rmdir oldstuff |
351 | |
352 | Most SFTP servers will probably refuse to remove a directory if the |
353 | directory has anything in it, so you will need to delete the |
354 | contents first. |
355 | |
356 | \S{psftp-cmd-ren} The \c{ren} command: rename remote files |
357 | |
358 | To rename a file on the server, type \c{ren}, then the current file |
359 | name, and then the new file name: |
360 | |
361 | \c ren oldfile newname |
362 | |
363 | The \c{rename} and \c{mv} commands work exactly the same way as |
364 | \c{ren}. |
eb4f8180 |
365 | |
366 | \H{psftp-pubkey} Using public key authentication with PSFTP |
367 | |
368 | Like PuTTY, PSFTP can authenticate using a public key instead of a |
369 | password. There are two ways you can do this. |
370 | |
371 | Firstly, PSFTP can use PuTTY saved sessions in place of hostnames. |
372 | So you might do this: |
373 | |
374 | \b Run PuTTY, and create a PuTTY saved session (see |
375 | \k{config-saving}) which specifies your private key file (see |
376 | \k{config-ssh-privkey}). You will probably also want to specify a |
377 | username to log in as (see \k{config-username}). |
378 | |
379 | \b In PSFTP, you can now use the name of the session instead of a |
380 | hostname: type \c{psftp sessionname}, where \c{sessionname} is |
381 | replaced by the name of your saved session. |
382 | |
383 | Secondly, PSFTP will attempt to authenticate using Pageant if Pageant |
384 | is running (see \k{pageant}). So you would do this: |
385 | |
386 | \b Ensure Pageant is running, and has your private key stored in it. |
387 | |
388 | \b Specify a user and host name to PSFTP as normal. PSFTP will |
389 | automatically detect Pageant and try to use the keys within it. |
390 | |
391 | For more general information on public-key authentication, see |
392 | \k{pubkey}. |