\versionid $Id: pscp.but,v 1.17 2001/09/24 22:00:46 simon Exp $ \#FIXME: Need examples \C{pscp} Using PSCP to transfer files securely \i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files securely between computers using an SSH connection. \H{pscp-starting} Starting PSCP 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 \i{console window}. With Windows 95, 98, and ME, this is called an \q{MS-DOS Prompt} and with Windows NT and 2000 it is called a \q{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 \i{\c{PATH}} or in your current directory. To add the directory containing PSCP to your \c{PATH} environment variable, type into the console window: \c set PATH=C:\path\to\putty\directory;%PATH% This will only work for the lifetime of that particular console window. To set your \c{PATH} more permanently on Windows NT, use the Environment tab of the System Control Panel. On Windows 95, 98, and ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set} command like the one above. \H{pscp-usage} PSCP Usage Once you've got a console window to type into, you can just type \c{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: \c Z:\owendadmin>pscp \c PuTTY Secure Copy client \c Release 0.50 \c Usage: pscp [options] [user@]host:source target \c pscp [options] source [source...] [user@]host:target \c pscp [options] -ls user@host:filespec \c Options: \c -p preserve file attributes \c -q quiet, don't show statistics \c -r copy directories recursively \c -v show verbose messages \c -P port connect to specified port \c -pw passw login with specified password (PSCP's interface is much like the Unix \c{scp} command, if you're familiar with that.) \S{pscp-usage-basics} The basics To receive (a) file(s) from a remote server: \c pscp [options] [user@]host:source target So to copy the file \c{/etc/hosts} from the server \c{example.com} as user \c{fred} to the file \c{c:\\temp\\example-hosts.txt}, you would type: \c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt To send (a) file(s) to a remote server: \c pscp [options] source [source...] [user@]host:target So to copy the local file \c{c:\\documents\\csh-whynot.txt} to the server \c{example.com} as user \c{fred} to the file \c{/tmp/csh-whynot} you would type: \c pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot You can use wildcards to transfer multiple files in either direction, like this: \c pscp c:\documents\*.doc fred@example.com:docfiles \c 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 like this: \c warning: remote host tried to write to a file called 'terminal.c' \c when we requested a file called '*.c'. \c If this is a wildcard, consider upgrading to SSH 2 or using \c 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{*.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 \e{different} pattern and writing over one of your other files: if you request \c{*.c}, the server might send back the file name \c{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. If you really need to use a server-side wildcard with an SSH 1 server, you can use the \c{-unsafe} command line option with PSCP: \c 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 \e{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). \S2{pscp-usage-basics-user} \c{user} The login name on the remote server. If this is omitted, and \c{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. \S2{pscp-usage-basics-host} \c{host} The 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. \S2{pscp-usage-basics-source} \c{source} One or more source files. \i{Wildcards} are allowed. The syntax of wildcards depends on the system to which they apply, so if you are copying \e{from} a Windows system \e{to} a UNIX system, you should use Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \e{from} a UNIX system \e{to} a Windows system, you would use the wildcard syntax allowed by your UNIX shell (e.g. \c{*}). If the source is a remote server and you do not specify a full pathname (in UNIX, a pathname beginning with a \c{/} (slash) character), what you specify as a source will be interpreted relative to your home directory on the remote server. \S2{pscp-usage-basics-target} \c{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 \c{.}. For example: \c pscp fred@example.com:/home/tom/.emacs . ...would copy \c{/home/tom/.emacs} on the remote server to the current directory. As with the \c{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. \S{pscp-usage-options} Options These are the command line options that PSCP accepts. \S2{pscp-usage-options-p}\c{-p} preserve file attributes By default, files copied with PSCP are \i{timestamp}ed with the date and time they were copied. The \c{-p} option preserves the original timestamp on copied files. \S2{pscp-usage-options-q}\c{-q} quiet, don't show \i{statistics} By default, PSCP displays a meter displaying the progress of the current transfer: \c 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 \c{-q} option to PSCP suppresses the printing of these statistics. \S2{pscp-usage-options-r}\c{-r} copies directories \i{recursive}ly By default, PSCP will only copy files. Any directories you specify to copy will be skipped, as will their contents. The \c{-r} option tells PSCP to descend into any directories you specify, and to copy them and their contents. This allows you to use PSCP to transfer whole directory structures between machines. \S2{pscp-usage-options-v}\c{-v} show \i{verbose} messages The \c{-v} option to PSCP makes it print extra information about the file transfer. For example: \c Logging in as "fred". \c fred@example.com's password: \c Sending command: scp -v -f mibs.tar \c Connected to example.com \c Sending file modes: C0644 1320960 mibs.tar \c mibs.tar | 1290 kB | 67.9 kB/s | ETA: 00:00:00 | 100% \c Remote exit status 0 \c Closing connection This information may be useful for debugging problems with PSCP. \S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port} If the \c{host} you specify is a saved session, PSCP uses any port number specified in that saved session. If not, PSCP uses the default SSH port, 22. The \c{-P} option allows you specify the port number to connect to for PSCP's SSH connection. \S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password} If a password is required to connect to the \c{host}, PSCP will interactively prompt you for it. However, this may not always be appropriate. If you are running PSCP as part of some automated job, it will not be possible to enter a password by hand. The \c{-pw} option to PSCP lets you specify the password to use on the command line. Since specifying passwords in scripts is a bad idea for security reasons, you might want instead to consider using public-key authentication; see \k{pscp-pubkey}. \S{pscp-pubkey} Return value PSCP returns an \cw{ERRORLEVEL} of zero (success) only if the files were correctly transferred. You can test for this in a batch file, using code such as this: \c pscp file*.* user@hostname: \c if errorlevel 1 echo There was an error \S{pscp-pubkey} Using public key authentication with PSCP Like PuTTY, PSCP can authenticate using a public key instead of a password. There are two ways you can do this. Firstly, PSCP can use PuTTY saved sessions in place of hostnames (see \k{pscp-usage-basics-host}). So you would do this: \b Run PuTTY, and create a PuTTY saved session (see \k{config-saving}) which specifies your private key file (see \k{config-ssh-privkey}). You will probably also want to specify a username to log in as (see \k{config-username}). \b In PSCP, you can now use the name of the session instead of a hostname: type \c{pscp sessionname:file localfile}, where \c{sessionname} is replaced by the name of your saved session. Secondly, PSCP will attempt to authenticate using Pageant if Pageant is running (see \k{pageant}). So you would do this: \b Ensure Pageant is running, and has your private key stored in it. \b Specify a user and host name to PSCP as normal. PSCP will automatically detect Pageant and try to use the keys within it. For more general information on public-key authentication, see \k{pubkey}. \H{pscp-ixplorer} \i{Secure iXplorer} Lars Gunnarson has written a graphical interface for PSCP. You can get it from his web site, at \W{http://www.i-tree.org/}{www.i-tree.org}.