Previous | Contents | Index | Next
PSCP, the PuTTY Secure Copy client, is a tool for transferring files securely between computers using an SSH connection.
If you have an SSH-2 server, you might prefer PSFTP (see chapter 6) for interactive use. PSFTP does not in general work with SSH-1 servers, however.
PSCP is a command line application. This means that you cannot just double-click on its icon to run it and instead you have to bring up a console window. With Windows 95, 98, and ME, this is called an ‘MS-DOS Prompt’ and with Windows NT, 2000, and XP, it is called a ‘Command Prompt’. It should be available from the Programs section of your Start Menu.
To start PSCP it will need either to be on your PATH or in your current directory. To add the directory containing PSCP to your PATH environment variable, type into the console window:
set PATH=C:\path\to\putty\directory;%PATH%
This will only work for the lifetime of that particular console window. To set your PATH more permanently on Windows NT, 2000, and XP, use the Environment tab of the System Control Panel. On Windows 95, 98, and ME, you will need to edit your AUTOEXEC.BAT to include a set command like the one above.
Once you've got a console window to type into, you can just type pscp on its own to bring up a usage message. This tells you the version of PSCP you're using, and gives you a brief summary of how to use PSCP:
Z:\owendadmin>pscp
PuTTY Secure Copy client
Release 0.58
Usage: pscp [options] [user@]host:source target
pscp [options] source [source...] [user@]host:target
pscp [options] -ls [user@]host:filespec
Options:
-V print version information and exit
-pgpfp print PGP key fingerprints and exit
-p preserve file attributes
-q quiet, don't show statistics
-r copy directories recursively
-v show verbose messages
-load sessname Load settings from saved session
-P port connect to specified port
-l user connect with specified username
-pw passw login with specified password
-1 -2 force use of particular SSH protocol version
-4 -6 force use of IPv4 or IPv6
-C enable compression
-i key private key file for authentication
-batch disable all interactive prompts
-unsafe allow server-side wildcards (DANGEROUS)
-sftp force use of SFTP protocol
-scp force use of SCP protocol
(PSCP's interface is much like the Unix scp command, if you're familiar with that.)
To receive (a) file(s) from a remote server:
pscp [options] [user@]host:source target
So to copy the file /etc/hosts from the server example.com as user fred to the file c:\temp\example-hosts.txt, you would type:
pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt
To send (a) file(s) to a remote server:
pscp [options] source [source...] [user@]host:target
So to copy the local file c:\documents\foo.txt to the server example.com as user fred to the file /tmp/foo you would type:
pscp c:\documents\foo.txt fred@example.com:/tmp/foo
You can use wildcards to transfer multiple files in either direction, like this:
pscp c:\documents\*.doc fred@example.com:docfiles
pscp fred@example.com:source/*.c c:\source
However, in the second case (using a wildcard for multiple remote files) you may see a warning saying something like ‘warning: remote host tried to write to a file called ‘terminal.c’ when we requested a file called ‘*.c’. If this is a wildcard, consider upgrading to SSH-2 or using the ‘-unsafe’ option. Renaming of this file has been disallowed’.
This is due to a fundamental insecurity in the old-style SCP protocol: the client sends the wildcard string (*.c) to the server, and the server sends back a sequence of file names that match the wildcard pattern. However, there is nothing to stop the server sending back a different pattern and writing over one of your other files: if you request *.c, the server might send back the file name AUTOEXEC.BAT and install a virus for you. Since the wildcard matching rules are decided by the server, the client cannot reliably verify that the filenames sent back match the pattern.
PSCP will attempt to use the newer SFTP protocol (part of SSH-2) where possible, which does not suffer from this security flaw. If you are talking to an SSH-2 server which supports SFTP, you will never see this warning. (You can force use of the SFTP protocol, if available, with -sftp - see section 5.2.2.6.)
If you really need to use a server-side wildcard with an SSH-1 server, you can use the -unsafe command line option with PSCP:
pscp -unsafe fred@example.com:source/*.c c:\source
This will suppress the warning message and the file transfer will happen. However, you should be aware that by using this option you are giving the server the ability to write to any file in the target directory, so you should only use this option if you trust the server administrator not to be malicious (and not to let the server machine be cracked by malicious people). Alternatively, do any such download in a newly created empty directory. (Even in ‘unsafe’ mode, PSCP will still protect you against the server trying to get out of that directory using pathnames including ‘..’.)
user
The login name on the remote server. If this is omitted, and host is a PuTTY saved session, PSCP will use any username specified by that saved session. Otherwise, PSCP will attempt to use the local Windows username.
hostThe name of the remote server, or the name of an existing PuTTY saved session. In the latter case, the session's settings for hostname, port number, cipher type and username will be used.
source
One or more source files. Wildcards are allowed. The syntax of wildcards depends on the system to which they apply, so if you are copying from a Windows system to a UNIX system, you should use Windows wildcard syntax (e.g. *.*), but if you are copying from a UNIX system to a Windows system, you would use the wildcard syntax allowed by your UNIX shell (e.g. *).
If the source is a remote server and you do not specify a full pathname (in UNIX, a pathname beginning with a / (slash) character), what you specify as a source will be interpreted relative to your home directory on the remote server.
target
The filename or directory to put the file(s). When copying from a remote server to a local host, you may wish simply to place the file(s) in the current directory. To do this, you should specify a target of .. For example:
pscp fred@example.com:/home/tom/.emacs .
...would copy /home/tom/.emacs on the remote server to the current directory.
As with the source parameter, if the target is on a remote server and is not a full path name, it is interpreted relative to your home directory on the remote server.
PSCP accepts all the general command line options supported by the PuTTY tools, except the ones which make no sense in a file transfer utility. See section 3.7.3 for a description of these options. (The ones not supported by PSCP are clearly marked.)
PSCP also supports some of its own options. The following sections describe PSCP's specific command-line options.
These are the command line options that PSCP accepts.
-ls list remote files
If the -ls option is given, no files are transferred; instead, remote files are listed. Only a hostname specification and optional remote file specification need be given. For example:
pscp -ls fred@example.com:dir1
The SCP protocol does not contain within itself a means of listing files. If SCP is in use, this option therefore assumes that the server responds appropriately to the command ls -la; this may not work with all servers.
If SFTP is in use, this option should work with all servers.
-p preserve file attributes
By default, files copied with PSCP are timestamped with the date and time they were copied. The -p option preserves the original timestamp on copied files.
-q quiet, don't show statisticsBy default, PSCP displays a meter displaying the progress of the current transfer:
mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13%
The fields in this display are (from left to right), filename, size (in kilobytes) of file transferred so far, estimate of how fast the file is being transferred (in kilobytes per second), estimated time that the transfer will be complete, and percentage of the file so far transferred. The -q option to PSCP suppresses the printing of these statistics.
-r copies directories section 3.1.3.1) thinks it has successfully sent a signature, it might be worth enabling the workaround for this bug to see if it helps.
If this bug is detected, PuTTY will sign data in the way OpenSSH expects. If this bug is enabled when talking to a correct server, SSH-2 public-key authentication will fail.
This is an SSH-2-specific bug.
Some SSH servers cannot cope with repeat key exchange at all, and will ignore attempts by the client to start one. Since PuTTY pauses the session while performing a repeat key exchange, the effect of this would be to cause the session to hang after an hour (unless you have your rekey timeout set differently; see section 4.19.2 for more about rekeys). Other, very old, SSH servers handle repeat key exchange even more badly, and disconnect upon receiving a repeat key exchange request.
If this bug is detected, PuTTY will never initiate a repeat key exchange. If this bug is enabled when talking to a correct server, the session should still function, but may be less secure than you would expect.
This is an SSH-2-specific bug.
PuTTY does not currently support storing its configuration in a file instead of the Registry. However, you can work around this with a couple of batch files.
You will need a file called (say) PUTTY.BAT which imports the contents of a file into the Registry, then runs PuTTY, exports the contents of the Registry back into the file, and deletes the Registry entries. This can all be done using the Regedit command line options, so it's all automatic. Here is what you need in PUTTY.BAT:
@ECHO OFF
regedit /s putty.reg
regedit /s puttyrnd.reg
start /w putty.exe
regedit /ea new.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
copy new.reg putty.reg
del new.reg
regedit /s puttydel.reg
This batch file needs two auxiliary files: PUTTYRND.REG which sets up an initial safe location for the PUTTY.RND random seed file, and PUTTYDEL.REG which destroys everything in the Registry once it's been successfully saved back to the file.
Here is PUTTYDEL.REG:
REGEDIT4
[-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
Here is an example PUTTYRND.REG file:
REGEDIT4
[HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
"RandSeedFile"="a:\\putty.rnd"
You should replace a:\putty.rnd with the location where you want to store your random number data. If the aim is to carry around PuTTY and its settings on one floppy, you probably want to store it on the floppy.
If you want to provide feedback on this manual or on the PuTTY tools themselves, see the Feedback page.
[PuTTY release 0.58]