1 \versionid $Id: pscp.but,v 1.5 2001/01/28 14:38:23 owen Exp $
3 \#FIXME: Need examples, index entries, links
5 \C{pscp} Using PSCP to transfer files securely
7 \# Explain PSCP: the command line, the modes of use (local->remote
8 \# and remote->local, recursive, wildcards).
10 \H{pscp-intro} Introduction to PSCP
12 PSCP, the PuTTY Secure Copy client, is a tool for transferring files
13 securely between computers using an SSH connection.
15 \H{pscp-starting} Starting PSCP
17 PSCP is a command line application. This means that you cannot just
18 double-click on its icon to run it and instead you have to bring up a
19 console window. With Windows 95, 98, and ME, this is called an
20 \q{MS-DOS Prompt} and with Windows NT and 2000 it is called a
21 \q{Command Prompt}. It should be available from the Programs section
24 To start PSCP it will need either to be on your \c{PATH} or in your
25 current directory. To add the directory containing PSCP to your
26 \c{PATH} environment variable, type into the console window:
28 \c set PATH C:\path\to\putty\directory;%PATH%
30 This will only work for the lifetime of that particular console
31 window. To set your \c{PATH} more permanently on Windows NT, use the
32 Environment tab of the System Control Panel. On Windows 95, 98, and
33 ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set}
34 command like the one above.
36 \H{pscp-usage} PSCP Usage
38 Once you've got a console window to type into, you can just type
39 \c{pscp} on its own to bring up a usage message. This tells you the
40 version of PSCP you're using, and gives you a brief summary of how to
44 \c PuTTY Secure Copy client
46 \c Usage: pscp [options] [user@]host:source target
47 \c pscp [options] source [source...] [user@]host:target
48 \c pscp [options] -ls user@host:filespec
50 \c -p preserve file attributes
51 \c -q quiet, don't show statistics
52 \c -r copy directories recursively
53 \c -v show verbose messages
54 \c -P port connect to specified port
55 \c -pw passw login with specified password
57 (PSCP's interface is much like the Unix \c{scp} command, if you're
60 \S{pscp-usage-basics} The basics
62 To receive (a) file(s) from a remote server:
64 \c{pscp [options] [user@]host:source target}
66 To send (a) file(s) to a remote server:
68 \c{pscp [options] source [source...] [user@]host:target}
70 \b \c{user} The login name on the remote server. If this is omitted, scp
71 will try to use the default login from the PuTTY saved session.
73 \b \c{host} The name of the remote server, or the name of an existing PuTTY
74 saved session. In the latter case, the session's settings for
75 hostname, port number, cipher type and username will be used.
77 \b \c{source} One or more source files. Wildcards are allowed.
79 \# FIXME: describe wildcard syntax
81 \b \c{target} The filename or directory to put the file(s).
83 \S{pscp-usage-options} Options
85 \# Document each command line option.
87 \S2{pscp-usage-options-p}\c{-p} preserve file attributes
89 By default, files copied with PSCP are timestamped with the date and
90 time they were copied. The \c{-p} option preserves the original
91 timestamp on copied files.
93 \S2{pscp-usage-options-q}\c{-q} quiet, don't show statistics
95 By default, PSCP displays a meter displaying the progress of the
98 \c mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13%
100 The fields in this display are (from left to right), filename, size
101 (in kilobytes) of file transferred so far, estimate of how fast the
102 file is being transferred (in kilobytes per second), estimated time
103 that the transfer will be complete, and percentage of the file so far
104 transferred. The \c{-q} option to PSCP suppresses the printing of
107 \S2{pscp-usage-options-r}\c{-r} copies directories recursively
109 By default, PSCP will only copy files. Any directories you specify to
110 copy will be skipped, as will their contents. The \c{-r} option tells
111 PSCP to descend into any directories you specify, and to copy them and
112 their contents. This allows you to use PSCP to transfer whole
113 directory structures between machines.
115 \S2{pscp-usage-options-v}\c{-v} show verbose messages
117 The \c{-v} option to PSCP makes it print extra information about the
118 file transfer. For example:
120 \c Logging in as "fred".
121 \c fred@example.com's password:
122 \c Sending command: scp -v -f mibs.tar
123 \c Connected to example.com
124 \c Sending file modes: C0644 1320960 mibs.tar
125 \c mibs.tar | 1290 kB | 67.9 kB/s | ETA: 00:00:00 | 100%
126 \c Remote exit status 0
127 \c Closing connection
129 This information may be useful for debugging problems with PSCP.
131 \S2{pscp-usage-options-P}\c{-P port} connect to specified port
133 If the \c{host} you specify is a saved session, PSCP uses any port
134 number specified in that saved session. If not, PSCP uses the default
135 SSH port, 22. The \c{-P} option allows you specify the port number to
136 connect to for PSCP's SSH connection.
138 \S2{pscp-usage-options-pw}\c{-pw passw} login with specified password
140 If a password is required to connect to the \c{host}, PSCP will
141 interactively prompt you for it. However, this may not always be
142 appropriate. If you are running PSCP as part of some automated job,
143 it will not be possible to enter a password by hand. The \c{-pw}
144 option to PSCP lets you specify the password to use on the command
147 Since specifying passwords in scripts is a bad idea for security
148 reasons, you might want instead to consider using public-key
149 authentication (see \k{pubkey}). PSCP will attempt to authenticate
150 with any public key specified in a saved session's configuration
151 before asking for a password.
153 \H{pscp-ixplorer} Secure iXplorer
155 Lars Gunnarson has written a graphical interface for PSCP. You can
156 get it from his web site, at
157 \W{http://www.i-tree.org/}{www.i-tree.org}.