| 1 | \versionid $Id: pscp.but,v 1.8 2001/02/04 15:35:36 owen Exp $ |
| 2 | |
| 3 | \#FIXME: Need examples |
| 4 | |
| 5 | \C{pscp} Using PSCP to transfer files securely |
| 6 | |
| 7 | \# Explain PSCP: the command line, the modes of use (local->remote |
| 8 | \# and remote->local, recursive, wildcards). |
| 9 | |
| 10 | \i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files |
| 11 | securely between computers using an SSH connection. |
| 12 | |
| 13 | \H{pscp-starting} Starting PSCP |
| 14 | |
| 15 | PSCP is a command line application. This means that you cannot just |
| 16 | double-click on its icon to run it and instead you have to bring up a |
| 17 | \i{console window}. With Windows 95, 98, and ME, this is called an |
| 18 | \q{MS-DOS Prompt} and with Windows NT and 2000 it is called a |
| 19 | \q{Command Prompt}. It should be available from the Programs section |
| 20 | of your Start Menu. |
| 21 | |
| 22 | To start PSCP it will need either to be on your \i{\c{PATH}} or in your |
| 23 | current directory. To add the directory containing PSCP to your |
| 24 | \c{PATH} environment variable, type into the console window: |
| 25 | |
| 26 | \c set PATH C:\path\to\putty\directory;%PATH% |
| 27 | |
| 28 | This will only work for the lifetime of that particular console |
| 29 | window. To set your \c{PATH} more permanently on Windows NT, use the |
| 30 | Environment tab of the System Control Panel. On Windows 95, 98, and |
| 31 | ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set} |
| 32 | command like the one above. |
| 33 | |
| 34 | \H{pscp-usage} PSCP Usage |
| 35 | |
| 36 | Once you've got a console window to type into, you can just type |
| 37 | \c{pscp} on its own to bring up a usage message. This tells you the |
| 38 | version of PSCP you're using, and gives you a brief summary of how to |
| 39 | use PSCP: |
| 40 | |
| 41 | \c Z:\owendadmin>pscp |
| 42 | \c PuTTY Secure Copy client |
| 43 | \c Release 0.50 |
| 44 | \c Usage: pscp [options] [user@]host:source target |
| 45 | \c pscp [options] source [source...] [user@]host:target |
| 46 | \c pscp [options] -ls user@host:filespec |
| 47 | \c Options: |
| 48 | \c -p preserve file attributes |
| 49 | \c -q quiet, don't show statistics |
| 50 | \c -r copy directories recursively |
| 51 | \c -v show verbose messages |
| 52 | \c -P port connect to specified port |
| 53 | \c -pw passw login with specified password |
| 54 | |
| 55 | (PSCP's interface is much like the Unix \c{scp} command, if you're |
| 56 | familiar with that.) |
| 57 | |
| 58 | \S{pscp-usage-basics} The basics |
| 59 | |
| 60 | To receive (a) file(s) from a remote server: |
| 61 | |
| 62 | \c pscp [options] [user@]host:source target |
| 63 | |
| 64 | So to copy the file /c{/etc/hosts} from the server /c{example.com} as |
| 65 | user /c{fred} to the file \c{c:\temp\example-hosts.txt}, you would type: |
| 66 | |
| 67 | \c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt |
| 68 | |
| 69 | To send (a) file(s) to a remote server: |
| 70 | |
| 71 | \c pscp [options] source [source...] [user@]host:target |
| 72 | |
| 73 | So to copy the local file /c{c:\documents\csh-whynot.txt} to the |
| 74 | server /c{example.com} as user /c{fred} to the file |
| 75 | \c{/tmp/csh-whynot} you would type: |
| 76 | |
| 77 | \c pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot |
| 78 | |
| 79 | \S2{pscp-usage-basics-user} \c{user} |
| 80 | |
| 81 | The login name on the remote server. If this is omitted, and \c{host} |
| 82 | is a PuTTY saved session, PSCP will use any username specified by that |
| 83 | saved session. Otherwise, PSCP will attempt to use the local Windows |
| 84 | username. |
| 85 | |
| 86 | \S2{pscp-usage-basics-host} \c{host} |
| 87 | |
| 88 | The name of the remote server, or the name of an existing PuTTY saved |
| 89 | session. In the latter case, the session's settings for hostname, port |
| 90 | number, cipher type and username will be used. |
| 91 | |
| 92 | \S2{pscp-usage-basics-source} \c{source} |
| 93 | |
| 94 | One or more source files. \i{Wildcards} are allowed. The syntax of |
| 95 | wildcards depends on the system to which they apply, so if you are |
| 96 | copying \e{from} a Windows system \e{to} a UNIX system, you should use |
| 97 | Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \e{from} |
| 98 | a UNIX system \e{to} a Windows system, you would use the wildcard |
| 99 | syntax allowed by your UNIX shell (e.g. \c{*}). |
| 100 | |
| 101 | If the source is a remote server and you do not specify a full |
| 102 | pathname (in UNIX, a pathname beginning with a \c{/} (slash) |
| 103 | character), what you specify as a source will be interpreted relative |
| 104 | to your home directory on the remote server. |
| 105 | |
| 106 | \S2{pscp-usage-basics-target} \c{target} |
| 107 | |
| 108 | The filename or directory to put the file(s). When copying from a |
| 109 | remote server to a local host, you may wish simply to place the |
| 110 | file(s) in the current directory. To do this, you should specify a |
| 111 | target of \c{.}. For example: |
| 112 | |
| 113 | \c pscp fred@example.com:/home/tom/.emacs . |
| 114 | |
| 115 | ...would copy \c{/home/tom/.emacs} on the remote server to the current |
| 116 | directory. |
| 117 | |
| 118 | As with the \c{source} parameter, if the target is on a remote server |
| 119 | and is not a full path name, it is interpreted relative to your home |
| 120 | directory on the remote server. |
| 121 | |
| 122 | \S{pscp-usage-options} Options |
| 123 | |
| 124 | These are the command line options that PSCP accepts. |
| 125 | |
| 126 | \S2{pscp-usage-options-p}\c{-p} preserve file attributes |
| 127 | |
| 128 | By default, files copied with PSCP are \i{timestamp}ed with the date and |
| 129 | time they were copied. The \c{-p} option preserves the original |
| 130 | timestamp on copied files. |
| 131 | |
| 132 | \S2{pscp-usage-options-q}\c{-q} quiet, don't show \i{statistics} |
| 133 | |
| 134 | By default, PSCP displays a meter displaying the progress of the |
| 135 | current transfer: |
| 136 | |
| 137 | \c mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13% |
| 138 | |
| 139 | The fields in this display are (from left to right), filename, size |
| 140 | (in kilobytes) of file transferred so far, estimate of how fast the |
| 141 | file is being transferred (in kilobytes per second), estimated time |
| 142 | that the transfer will be complete, and percentage of the file so far |
| 143 | transferred. The \c{-q} option to PSCP suppresses the printing of |
| 144 | these statistics. |
| 145 | |
| 146 | \S2{pscp-usage-options-r}\c{-r} copies directories \i{recursive}ly |
| 147 | |
| 148 | By default, PSCP will only copy files. Any directories you specify to |
| 149 | copy will be skipped, as will their contents. The \c{-r} option tells |
| 150 | PSCP to descend into any directories you specify, and to copy them and |
| 151 | their contents. This allows you to use PSCP to transfer whole |
| 152 | directory structures between machines. |
| 153 | |
| 154 | \S2{pscp-usage-options-v}\c{-v} show \i{verbose} messages |
| 155 | |
| 156 | The \c{-v} option to PSCP makes it print extra information about the |
| 157 | file transfer. For example: |
| 158 | |
| 159 | \c Logging in as "fred". |
| 160 | \c fred@example.com's password: |
| 161 | \c Sending command: scp -v -f mibs.tar |
| 162 | \c Connected to example.com |
| 163 | \c Sending file modes: C0644 1320960 mibs.tar |
| 164 | \c mibs.tar | 1290 kB | 67.9 kB/s | ETA: 00:00:00 | 100% |
| 165 | \c Remote exit status 0 |
| 166 | \c Closing connection |
| 167 | |
| 168 | This information may be useful for debugging problems with PSCP. |
| 169 | |
| 170 | \S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port} |
| 171 | |
| 172 | If the \c{host} you specify is a saved session, PSCP uses any port |
| 173 | number specified in that saved session. If not, PSCP uses the default |
| 174 | SSH port, 22. The \c{-P} option allows you specify the port number to |
| 175 | connect to for PSCP's SSH connection. |
| 176 | |
| 177 | \S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password} |
| 178 | |
| 179 | If a password is required to connect to the \c{host}, PSCP will |
| 180 | interactively prompt you for it. However, this may not always be |
| 181 | appropriate. If you are running PSCP as part of some automated job, |
| 182 | it will not be possible to enter a password by hand. The \c{-pw} |
| 183 | option to PSCP lets you specify the password to use on the command |
| 184 | line. |
| 185 | |
| 186 | Since specifying passwords in scripts is a bad idea for security |
| 187 | reasons, you might want instead to consider using public-key |
| 188 | authentication (see \k{pubkey}). PSCP will attempt to authenticate |
| 189 | with any key specified in a saved session's configuration or with a |
| 190 | key stored in Pageant (see \k{pageant}) before asking for a password. |
| 191 | |
| 192 | \H{pscp-ixplorer} \i{Secure iXplorer} |
| 193 | |
| 194 | Lars Gunnarson has written a graphical interface for PSCP. You can |
| 195 | get it from his web site, at |
| 196 | \W{http://www.i-tree.org/}{www.i-tree.org}. |