| 1 | \define{versionidpscp} \versionid $Id$ |
| 2 | |
| 3 | \#FIXME: Need examples |
| 4 | |
| 5 | \C{pscp} Using \i{PSCP} to transfer files securely |
| 6 | |
| 7 | \i{PSCP}, the PuTTY Secure Copy client, is a tool for \i{transferring files} |
| 8 | securely between computers using an SSH connection. |
| 9 | |
| 10 | If you have an SSH-2 server, you might prefer PSFTP (see \k{psftp}) |
| 11 | for interactive use. PSFTP does not in general work with SSH-1 |
| 12 | servers, however. |
| 13 | |
| 14 | \H{pscp-starting} Starting PSCP |
| 15 | |
| 16 | PSCP is a command line application. This means that you cannot just |
| 17 | double-click on its icon to run it and instead you have to bring up a |
| 18 | \i{console window}. With Windows 95, 98, and ME, this is called an |
| 19 | \q{MS-DOS Prompt} and with Windows NT, 2000, and XP, it is called a |
| 20 | \q{Command Prompt}. It should be available from the Programs section |
| 21 | of your \i{Start Menu}. |
| 22 | |
| 23 | To start PSCP it will need either to be on your \i{\c{PATH}} or in your |
| 24 | current directory. To add the directory containing PSCP to your |
| 25 | \c{PATH} environment variable, type into the console window: |
| 26 | |
| 27 | \c set PATH=C:\path\to\putty\directory;%PATH% |
| 28 | |
| 29 | This will only work for the lifetime of that particular console |
| 30 | window. To set your \c{PATH} more permanently on Windows NT, 2000, |
| 31 | and XP, use the Environment tab of the System Control Panel. On |
| 32 | Windows 95, 98, and ME, you will need to edit your \i\c{AUTOEXEC.BAT} |
| 33 | to include a \c{set} command like the one above. |
| 34 | |
| 35 | \H{pscp-usage} PSCP Usage |
| 36 | |
| 37 | Once you've got a console window to type into, you can just type |
| 38 | \c{pscp} on its own to bring up a usage message. This tells you the |
| 39 | version of PSCP you're using, and gives you a brief summary of how to |
| 40 | use PSCP: |
| 41 | |
| 42 | \c Z:\owendadmin>pscp |
| 43 | \c PuTTY Secure Copy client |
| 44 | \c Release 0.61 |
| 45 | \c Usage: pscp [options] [user@]host:source target |
| 46 | \c pscp [options] source [source...] [user@]host:target |
| 47 | \c pscp [options] -ls [user@]host:filespec |
| 48 | \c Options: |
| 49 | \c -V print version information and exit |
| 50 | \c -pgpfp print PGP key fingerprints and exit |
| 51 | \c -p preserve file attributes |
| 52 | \c -q quiet, don't show statistics |
| 53 | \c -r copy directories recursively |
| 54 | \c -v show verbose messages |
| 55 | \c -load sessname Load settings from saved session |
| 56 | \c -P port connect to specified port |
| 57 | \c -l user connect with specified username |
| 58 | \c -pw passw login with specified password |
| 59 | \c -1 -2 force use of particular SSH protocol version |
| 60 | \c -4 -6 force use of IPv4 or IPv6 |
| 61 | \c -C enable compression |
| 62 | \c -i key private key file for authentication |
| 63 | \c -noagent disable use of Pageant |
| 64 | \c -agent enable use of Pageant |
| 65 | \c -batch disable all interactive prompts |
| 66 | \c -unsafe allow server-side wildcards (DANGEROUS) |
| 67 | \c -sftp force use of SFTP protocol |
| 68 | \c -scp force use of SCP protocol |
| 69 | |
| 70 | (PSCP's interface is much like the Unix \c{scp} command, if you're |
| 71 | familiar with that.) |
| 72 | |
| 73 | \S{pscp-usage-basics} The basics |
| 74 | |
| 75 | To \I{receiving files}receive (a) file(s) from a remote server: |
| 76 | |
| 77 | \c pscp [options] [user@]host:source target |
| 78 | |
| 79 | So to copy the file \c{/etc/hosts} from the server \c{example.com} as |
| 80 | user \c{fred} to the file \c{c:\\temp\\example-hosts.txt}, you would type: |
| 81 | |
| 82 | \c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt |
| 83 | |
| 84 | To \I{sending files}send (a) file(s) to a remote server: |
| 85 | |
| 86 | \c pscp [options] source [source...] [user@]host:target |
| 87 | |
| 88 | So to copy the local file \c{c:\\documents\\foo.txt} to the server |
| 89 | \c{example.com} as user \c{fred} to the file \c{/tmp/foo} you would |
| 90 | type: |
| 91 | |
| 92 | \c pscp c:\documents\foo.txt fred@example.com:/tmp/foo |
| 93 | |
| 94 | You can use \i{wildcards} to transfer multiple files in either |
| 95 | direction, like this: |
| 96 | |
| 97 | \c pscp c:\documents\*.doc fred@example.com:docfiles |
| 98 | \c pscp fred@example.com:source/*.c c:\source |
| 99 | |
| 100 | However, in the second case (using a wildcard for multiple remote |
| 101 | files) you may see a warning saying something like \q{warning: |
| 102 | remote host tried to write to a file called \cq{terminal.c} when we |
| 103 | requested a file called \cq{*.c}. If this is a wildcard, consider |
| 104 | upgrading to SSH-2 or using the \cq{-unsafe} option. Renaming of |
| 105 | this file has been disallowed}. |
| 106 | |
| 107 | This is due to a \I{security risk}fundamental insecurity in the old-style |
| 108 | \i{SCP protocol}: the client sends the wildcard string (\c{*.c}) to the |
| 109 | server, and the server sends back a sequence of file names that |
| 110 | match the wildcard pattern. However, there is nothing to stop the |
| 111 | server sending back a \e{different} pattern and writing over one of |
| 112 | your other files: if you request \c{*.c}, the server might send back |
| 113 | the file name \c{AUTOEXEC.BAT} and install a virus for you. Since |
| 114 | the wildcard matching rules are decided by the server, the client |
| 115 | cannot reliably verify that the filenames sent back match the |
| 116 | pattern. |
| 117 | |
| 118 | PSCP will attempt to use the newer \i{SFTP} protocol (part of SSH-2) |
| 119 | where possible, which does not suffer from this security flaw. If |
| 120 | you are talking to an SSH-2 server which supports SFTP, you will |
| 121 | never see this warning. (You can force use of the SFTP protocol, |
| 122 | if available, with \c{-sftp} - see \k{pscp-usage-options-backend}.) |
| 123 | |
| 124 | If you really need to use a server-side wildcard with an SSH-1 |
| 125 | server, you can use the \i\c{-unsafe} command line option with PSCP: |
| 126 | |
| 127 | \c pscp -unsafe fred@example.com:source/*.c c:\source |
| 128 | |
| 129 | This will suppress the warning message and the file transfer will |
| 130 | happen. However, you should be aware that by using this option you |
| 131 | are giving the server the ability to write to \e{any} file in the |
| 132 | target directory, so you should only use this option if you trust |
| 133 | the server administrator not to be malicious (and not to let the |
| 134 | server machine be cracked by malicious people). Alternatively, do |
| 135 | any such download in a newly created empty directory. (Even in |
| 136 | \q{unsafe} mode, PSCP will still protect you against the server |
| 137 | trying to get out of that directory using pathnames including |
| 138 | \cq{..}.) |
| 139 | |
| 140 | \S2{pscp-usage-basics-user} \c{user} |
| 141 | |
| 142 | The \i{login name} on the remote server. If this is omitted, and \c{host} |
| 143 | is a PuTTY saved session, PSCP will use any username specified by that |
| 144 | saved session. Otherwise, PSCP will attempt to use the local Windows |
| 145 | username. |
| 146 | |
| 147 | \S2{pscp-usage-basics-host} \I{hostname}\c{host} |
| 148 | |
| 149 | The name of the remote server, or the name of an existing PuTTY saved |
| 150 | session. In the latter case, the session's settings for hostname, port |
| 151 | number, cipher type and username will be used. |
| 152 | |
| 153 | \S2{pscp-usage-basics-source} \c{source} |
| 154 | |
| 155 | One or more source files. \ii{Wildcards} are allowed. The syntax of |
| 156 | wildcards depends on the system to which they apply, so if you are |
| 157 | copying \e{from} a Windows system \e{to} a UNIX system, you should use |
| 158 | Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \e{from} |
| 159 | a UNIX system \e{to} a Windows system, you would use the wildcard |
| 160 | syntax allowed by your UNIX shell (e.g. \c{*}). |
| 161 | |
| 162 | If the source is a remote server and you do not specify a full |
| 163 | pathname (in UNIX, a pathname beginning with a \c{/} (slash) |
| 164 | character), what you specify as a source will be interpreted relative |
| 165 | to your \i{home directory} on the remote server. |
| 166 | |
| 167 | \S2{pscp-usage-basics-target} \c{target} |
| 168 | |
| 169 | The filename or directory to put the file(s). When copying from a |
| 170 | remote server to a local host, you may wish simply to place the |
| 171 | file(s) in the current directory. To do this, you should specify a |
| 172 | target of \c{.}. For example: |
| 173 | |
| 174 | \c pscp fred@example.com:/home/tom/.emacs . |
| 175 | |
| 176 | ...would copy \c{/home/tom/.emacs} on the remote server to the current |
| 177 | directory. |
| 178 | |
| 179 | As with the \c{source} parameter, if the target is on a remote server |
| 180 | and is not a full path name, it is interpreted relative to your home |
| 181 | directory on the remote server. |
| 182 | |
| 183 | \S{pscp-usage-options} Options |
| 184 | |
| 185 | PSCP accepts all the general command line options supported by the |
| 186 | PuTTY tools, except the ones which make no sense in a file transfer |
| 187 | utility. See \k{using-general-opts} for a description of these |
| 188 | options. (The ones not supported by PSCP are clearly marked.) |
| 189 | |
| 190 | PSCP also supports some of its own options. The following sections |
| 191 | describe PSCP's specific command-line options. |
| 192 | |
| 193 | \S2{pscp-usage-options-ls}\I{-ls-PSCP}\c{-ls} \I{listing files}list remote files |
| 194 | |
| 195 | If the \c{-ls} option is given, no files are transferred; instead, |
| 196 | remote files are listed. Only a hostname specification and |
| 197 | optional remote file specification need be given. For example: |
| 198 | |
| 199 | \c pscp -ls fred@example.com:dir1 |
| 200 | |
| 201 | The SCP protocol does not contain within itself a means of listing |
| 202 | files. If SCP is in use, this option therefore assumes that the |
| 203 | server responds appropriately to the command \c{ls\_-la}; |
| 204 | this may not work with all servers. |
| 205 | |
| 206 | If SFTP is in use, this option should work with all servers. |
| 207 | |
| 208 | \S2{pscp-usage-options-p}\I{-p-PSCP}\c{-p} \i{preserve file attributes} |
| 209 | |
| 210 | By default, files copied with PSCP are \i{timestamp}ed with the date and |
| 211 | time they were copied. The \c{-p} option preserves the original |
| 212 | timestamp on copied files. |
| 213 | |
| 214 | \S2{pscp-usage-options-q}\I{-q-PSCP}\c{-q} quiet, don't show \i{statistics} |
| 215 | |
| 216 | By default, PSCP displays a meter displaying the progress of the |
| 217 | current transfer: |
| 218 | |
| 219 | \c mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13% |
| 220 | |
| 221 | The fields in this display are (from left to right), filename, size |
| 222 | (in kilobytes) of file transferred so far, estimate of how fast the |
| 223 | file is being transferred (in kilobytes per second), estimated time |
| 224 | that the transfer will be complete, and percentage of the file so far |
| 225 | transferred. The \c{-q} option to PSCP suppresses the printing of |
| 226 | these statistics. |
| 227 | |
| 228 | \S2{pscp-usage-options-r}\I{-r-PSCP}\c{-r} copies directories \i{recursive}ly |
| 229 | |
| 230 | By default, PSCP will only copy files. Any directories you specify to |
| 231 | copy will be skipped, as will their contents. The \c{-r} option tells |
| 232 | PSCP to descend into any directories you specify, and to copy them and |
| 233 | their contents. This allows you to use PSCP to transfer whole |
| 234 | directory structures between machines. |
| 235 | |
| 236 | \S2{pscp-usage-options-batch}\I{-batch-PSCP}\c{-batch} avoid interactive prompts |
| 237 | |
| 238 | If you use the \c{-batch} option, PSCP will never give an |
| 239 | interactive prompt while establishing the connection. If the |
| 240 | server's host key is invalid, for example (see \k{gs-hostkey}), then |
| 241 | the connection will simply be abandoned instead of asking you what |
| 242 | to do next. |
| 243 | |
| 244 | This may help PSCP's behaviour when it is used in automated |
| 245 | scripts: using \c{-batch}, if something goes wrong at connection |
| 246 | time, the batch job will fail rather than hang. |
| 247 | |
| 248 | \S2{pscp-usage-options-backend}\i\c{-sftp}, \i\c{-scp} force use of |
| 249 | particular protocol |
| 250 | |
| 251 | As mentioned in \k{pscp-usage-basics}, there are two different file |
| 252 | transfer protocols in use with SSH. Despite its name, PSCP (like many |
| 253 | other ostensible \cw{scp} clients) can use either of these protocols. |
| 254 | |
| 255 | The older \i{SCP protocol} does not have a written specification and |
| 256 | leaves a lot of detail to the server platform. \ii{Wildcards} are expanded |
| 257 | on the server. The simple design means that any wildcard specification |
| 258 | supported by the server platform (such as brace expansion) can be |
| 259 | used, but also leads to interoperability issues such as with filename |
| 260 | quoting (for instance, where filenames contain spaces), and also the |
| 261 | security issue described in \k{pscp-usage-basics}. |
| 262 | |
| 263 | The newer \i{SFTP} protocol, which is usually associated with SSH-2 |
| 264 | servers, is specified in a more platform independent way, and leaves |
| 265 | issues such as wildcard syntax up to the client. (PuTTY's SFTP |
| 266 | wildcard syntax is described in \k{psftp-wildcards}.) This makes it |
| 267 | more consistent across platforms, more suitable for scripting and |
| 268 | automation, and avoids security issues with wildcard matching. |
| 269 | |
| 270 | Normally PSCP will attempt to use the SFTP protocol, and only fall |
| 271 | back to the SCP protocol if SFTP is not available on the server. |
| 272 | |
| 273 | The \c{-scp} option forces PSCP to use the SCP protocol or quit. |
| 274 | |
| 275 | The \c{-sftp} option forces PSCP to use the SFTP protocol or quit. |
| 276 | When this option is specified, PSCP looks harder for an SFTP server, |
| 277 | which may allow use of SFTP with SSH-1 depending on server setup. |
| 278 | |
| 279 | \S{pscp-retval} \ii{Return value} |
| 280 | |
| 281 | PSCP returns an \i\cw{ERRORLEVEL} of zero (success) only if the files |
| 282 | were correctly transferred. You can test for this in a \i{batch file}, |
| 283 | using code such as this: |
| 284 | |
| 285 | \c pscp file*.* user@hostname: |
| 286 | \c if errorlevel 1 echo There was an error |
| 287 | |
| 288 | \S{pscp-pubkey} Using \i{public key authentication} with PSCP |
| 289 | |
| 290 | Like PuTTY, PSCP can authenticate using a public key instead of a |
| 291 | password. There are three ways you can do this. |
| 292 | |
| 293 | Firstly, PSCP can use PuTTY saved sessions in place of hostnames |
| 294 | (see \k{pscp-usage-basics-host}). So you would do this: |
| 295 | |
| 296 | \b Run PuTTY, and create a PuTTY saved session (see |
| 297 | \k{config-saving}) which specifies your private key file (see |
| 298 | \k{config-ssh-privkey}). You will probably also want to specify a |
| 299 | username to log in as (see \k{config-username}). |
| 300 | |
| 301 | \b In PSCP, you can now use the name of the session instead of a |
| 302 | hostname: type \c{pscp sessionname:file localfile}, where |
| 303 | \c{sessionname} is replaced by the name of your saved session. |
| 304 | |
| 305 | Secondly, you can supply the name of a private key file on the command |
| 306 | line, with the \c{-i} option. See \k{using-cmdline-identity} for more |
| 307 | information. |
| 308 | |
| 309 | Thirdly, PSCP will attempt to authenticate using Pageant if Pageant |
| 310 | is running (see \k{pageant}). So you would do this: |
| 311 | |
| 312 | \b Ensure Pageant is running, and has your private key stored in it. |
| 313 | |
| 314 | \b Specify a user and host name to PSCP as normal. PSCP will |
| 315 | automatically detect Pageant and try to use the keys within it. |
| 316 | |
| 317 | For more general information on public-key authentication, see |
| 318 | \k{pubkey}. |