| 1 | \versionid $Id: plink.but,v 1.12 2001/12/06 20:05:39 simon Exp $ |
| 2 | |
| 3 | \C{plink} Using the command-line connection tool Plink |
| 4 | |
| 5 | \i{Plink} (PuTTY Link) is a command-line connection tool similar to |
| 6 | UNIX \c{ssh}. It is mostly used for automated operations, such as |
| 7 | making CVS access a repository on a remote server. |
| 8 | |
| 9 | Plink is probably not what you want if you want to run an |
| 10 | interactive session in a console window. |
| 11 | |
| 12 | \H{plink-starting} Starting Plink |
| 13 | |
| 14 | Plink is a command line application. This means that you cannot just |
| 15 | double-click on its icon to run it and instead you have to bring up |
| 16 | a \i{console window}. In Windows 95, 98, and ME, this is called an |
| 17 | \q{MS-DOS Prompt}, and in Windows NT and 2000 it is called a |
| 18 | \q{Command Prompt}. It should be available from the Programs section |
| 19 | of your Start Menu. |
| 20 | |
| 21 | In order to use Plink, the file \c{plink.exe} will need either to be |
| 22 | on your \i{\c{PATH}} or in your current directory. To add the |
| 23 | directory containing Plink to your \c{PATH} environment variable, |
| 24 | 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{plink-usage} Using Plink |
| 35 | |
| 36 | This section describes the basics of how to use Plink for |
| 37 | interactive logins and for automated processes. |
| 38 | |
| 39 | Once you've got a console window to type into, you can just type |
| 40 | \c{plink} on its own to bring up a usage message. This tells you the |
| 41 | version of Plink you're using, and gives you a brief summary of how to |
| 42 | use Plink: |
| 43 | |
| 44 | \c Z:\sysosd>plink |
| 45 | \c PuTTY Link: command-line connection utility |
| 46 | \c Release 0.50 |
| 47 | \c Usage: plink [options] [user@]host [command] |
| 48 | \c Options: |
| 49 | \c -v show verbose messages |
| 50 | \c -ssh force use of ssh protocol |
| 51 | \c -P port connect to specified port |
| 52 | \c -pw passw login with specified password |
| 53 | |
| 54 | Once this works, you are ready to use Plink. |
| 55 | |
| 56 | \S{plink-usage-interactive} Using Plink for interactive logins |
| 57 | |
| 58 | To make a simple interactive connection to a remote server, just |
| 59 | type \c{plink} and then the host name: |
| 60 | |
| 61 | \c Z:\sysosd>plink login.example.com |
| 62 | \c |
| 63 | \c Debian GNU/Linux 2.2 flunky.example.com |
| 64 | \c flunky login: |
| 65 | |
| 66 | You should then be able to log in as normal and run a session. The |
| 67 | output sent by the server will be written straight to your command |
| 68 | prompt window, which will most likely not interpret terminal control |
| 69 | codes in the way the server expects it to. So if you run any |
| 70 | full-screen applications, for example, you can expect to see strange |
| 71 | characters appearing in your window. Interactive connections like |
| 72 | this are not the main point of Plink. |
| 73 | |
| 74 | In order to connect with a different protocol, you can give the |
| 75 | command line options \c{-ssh}, \c{-telnet}, \c{-rlogin} or \c{-raw}. |
| 76 | To make an SSH connection, for example: |
| 77 | |
| 78 | \c Z:\sysosd>plink -ssh login.example.com |
| 79 | \c login as: |
| 80 | |
| 81 | If you have already set up a PuTTY saved session, then instead of |
| 82 | supplying a host name, you can give the saved session name. This |
| 83 | allows you to use public-key authentication, specify a user name, |
| 84 | and use most of the other features of PuTTY: |
| 85 | |
| 86 | \c Z:\sysosd>plink my-ssh-session |
| 87 | \c Sent username "fred" |
| 88 | \c Authenticating with public key "fred@winbox" |
| 89 | \c Last login: Thu Dec 6 19:25:33 2001 from :0.0 |
| 90 | \c fred@flunky:~$ |
| 91 | |
| 92 | \S{plink-usage-batch} Using Plink for automated connections |
| 93 | |
| 94 | More typically Plink is used with the SSH protocol, to enable you to |
| 95 | talk directly to a program running on the server. To do this you |
| 96 | have to ensure Plink is \e{using} the SSH protocol. You can do this |
| 97 | in several ways: |
| 98 | |
| 99 | \b Use the \c{-ssh} option as described in |
| 100 | \k{plink-usage-interactive}. |
| 101 | |
| 102 | \b Set up a PuTTY saved session that describes the server you are |
| 103 | connecting to, and that also specifies the protocol as SSH. |
| 104 | |
| 105 | \b Set the Windows environment variable \c{PLINK_PROTOCOL} to the |
| 106 | word \c{ssh}. |
| 107 | |
| 108 | Usually Plink is not invoked directly by a user, but run |
| 109 | automatically by another process. Therefore you typically do not |
| 110 | want Plink to prompt you for a user name or a password. |
| 111 | |
| 112 | To avoid being prompted for a user name, you can: |
| 113 | |
| 114 | \b Use the \c{-l} option to specify a user name on the command line. |
| 115 | For example, \c{plink login.example.com -l fred}. |
| 116 | |
| 117 | \b Set up a PuTTY saved session that describes the server you are |
| 118 | connecting to, and that also specifies the username to log in as |
| 119 | (see \k{config-username}). |
| 120 | |
| 121 | To avoid being prompted for a password, you should almost certainly |
| 122 | set up public-key authentication. (See \k{pubkey} for a general |
| 123 | introduction to public-key authentication.) Again, you can do this |
| 124 | in two ways: |
| 125 | |
| 126 | \b Set up a PuTTY saved session that describes the server you are |
| 127 | connecting to, and that also specifies a private key file (see |
| 128 | \k{config-ssh-privkey}). For this to work without prompting, your |
| 129 | private key will need to have no passphrase. |
| 130 | |
| 131 | \b Store the private key in Pageant. See \k{pageant} for further |
| 132 | information. |
| 133 | |
| 134 | Once you have done all this, you should be able to run a remote |
| 135 | command on the SSH server machine and have it execute automatically |
| 136 | with no prompting: |
| 137 | |
| 138 | \c Z:\sysosd>plink login.example.com -l fred echo hello, world |
| 139 | \c hello, world |
| 140 | \c |
| 141 | \c Z:\sysosd> |
| 142 | |
| 143 | Or, if you have set up a saved session with all the connection |
| 144 | details: |
| 145 | |
| 146 | \c Z:\sysosd>plink mysession echo hello, world |
| 147 | \c hello, world |
| 148 | \c |
| 149 | \c Z:\sysosd> |
| 150 | |
| 151 | Then you can set up other programs to run this Plink command and |
| 152 | talk to it as if it were a process on the server machine. |
| 153 | |
| 154 | \S{plink-usage-options} Options |
| 155 | |
| 156 | This section describes the command line options that Plink accepts. |
| 157 | |
| 158 | \S2{plink-usage-options-v}\c{-v} show verbose messages |
| 159 | |
| 160 | By default, Plink only displays any password prompts and the output of |
| 161 | the remote command. The \c{-v} option makes it print extra |
| 162 | information about the connection being made, for example: |
| 163 | |
| 164 | \c Server version: SSH-1.5-OpenSSH-1.2.3 |
| 165 | \c We claim version: SSH-1.5-PuTTY |
| 166 | \c Using SSH protocol version 1 |
| 167 | \c Received public keys |
| 168 | \c Host key fingerprint is: |
| 169 | \c 1023 e3:65:44:44:bd:b1:04:59:bc:e2:3d:a1:4d:09:ce:99 |
| 170 | \c Encrypted session key |
| 171 | \c Using 3DES encryption |
| 172 | \c Trying to enable encryption... |
| 173 | \c Successfully started encryption |
| 174 | \c Sent username "fred". |
| 175 | \c Sent username "fred" |
| 176 | \c fred@example.com's password: |
| 177 | |
| 178 | This information can be useful for diagnosing problems. |
| 179 | |
| 180 | \S2{plink-usage-options-ssh} Protocol selection options |
| 181 | |
| 182 | Plink is most useful when using the SSH protocol. However, it allows |
| 183 | you to interface to all the protocols supported by PuTTY. You can |
| 184 | specify the option \c{-ssh} on the command line to select the SSH |
| 185 | protocol; you can also specify \c{-telnet}, \c{-rlogin} or \c{-raw} |
| 186 | to select other protocols. |
| 187 | |
| 188 | \S2{plink-usage-options-P}\c{-P port} connect to specified port |
| 189 | |
| 190 | If your server machine is running its SSH service on a port other |
| 191 | than the standard one, you can specify an alternative port number to |
| 192 | connect to using the \c{-P} option, like this: |
| 193 | |
| 194 | \c plink -ssh login.example.com -P 5022 |
| 195 | |
| 196 | \S2{plink-usage-options-pw}\c{-pw passw} login with specified password |
| 197 | |
| 198 | A simple way to automate a remote login is to supply your password |
| 199 | on the Plink command line. This is \e{not recommended} for reasons |
| 200 | of security. If you possibly can, we recommend you set up public-key |
| 201 | authentication instead. See \k{pubkey} for details. |
| 202 | |
| 203 | \S2{plink-usage-options-user}\c{-l username} login with specified |
| 204 | username |
| 205 | |
| 206 | As described in \k{plink-usage-batch}, you can specify the user name |
| 207 | to log in as on the remote server using the \c{-l} option. For |
| 208 | example, \c{plink login.example.com -l fred}. |
| 209 | |
| 210 | \S2{plink-usage-options-cmdfile} \c{-m filename} read command from a |
| 211 | file |
| 212 | |
| 213 | If the command you want to run on the remote server is particularly |
| 214 | large, you can read it from a file using the \c{-m} option, instead |
| 215 | of putting it directly on Plink's command line. On most Unix |
| 216 | systems, you can even put multiple lines in this file and execute |
| 217 | more than one command in sequence, or a whole shell script. |
| 218 | |
| 219 | \S2{plink-usage-options-portfwd} \c{-L} and \c{-R} set up port |
| 220 | forwarding |
| 221 | |
| 222 | Plink allows you to use port forwarding just as PuTTY does; if you |
| 223 | have set up a PuTTY saved session that specifies port forwardings, |
| 224 | and you connect to that session using Plink, then the same port |
| 225 | forwardings will be set up. |
| 226 | |
| 227 | For convenience, Plink also offers the option to set up port |
| 228 | forwarding on the command line. The command-line options work just |
| 229 | like the ones in Unix \c{ssh} programs. |
| 230 | |
| 231 | To forward a local port (say 5110) to a remote destination (say |
| 232 | \cw{popserver.example.com} port 110), you can write: |
| 233 | |
| 234 | \c plink mysession -L 5110:popserver.example.com:110 |
| 235 | |
| 236 | And to forward a remote port to a local destination, just use the |
| 237 | \c{-R} option instead of \c{-L}: |
| 238 | |
| 239 | \c plink mysession -R 5023:mytelnetserver.myhouse.org:23 |
| 240 | |
| 241 | For general information on port forwarding, see |
| 242 | \k{using-port-forwarding}. |
| 243 | |
| 244 | \H{plink-batch} Using Plink in \i{batch files} and \i{scripts} |
| 245 | |
| 246 | Once you have set up Plink to be able to log in to a remote server |
| 247 | without any interactive prompting (see \k{plink-usage-batch}), you |
| 248 | can use it for lots of scripting and batch purposes. For example, to |
| 249 | start a backup on a remote machine, you might use a command like: |
| 250 | |
| 251 | \c plink root@myserver /etc/backups/do-backup.sh |
| 252 | |
| 253 | Or perhaps you want to fetch all system log lines relating to a |
| 254 | particular web area: |
| 255 | |
| 256 | \c plink mysession grep /~fjbloggs/ /var/log/httpd/access.log > fredlogs |
| 257 | |
| 258 | Any non-interactive command you could usefully run on the server |
| 259 | command line, you can run in a batch file using Plink in this way. |
| 260 | |
| 261 | \H{plink-cvs} Using Plink with \i{CVS} |
| 262 | |
| 263 | To use Plink with CVS, you need to set the environment variable |
| 264 | \c{CVS_RSH} to point to Plink: |
| 265 | |
| 266 | \c set CVS_RSH=\path\to\plink.exe |
| 267 | |
| 268 | You also need to arrange to be able to connect to a remote host |
| 269 | without any interactive prompts, as described in |
| 270 | \k{plink-usage-batch}. |
| 271 | |
| 272 | You should then be able to run CVS as follows: |
| 273 | |
| 274 | \c cvs -d :ext:user@sessionname:/path/to/repository co module |
| 275 | |
| 276 | If you specified a username in your saved session, you don't even |
| 277 | need to specify the \q{user} part of this, and you can just say: |
| 278 | |
| 279 | \c cvs -d :ext:sessionname:/path/to/repository co module |
| 280 | |
| 281 | \H{plink-wincvs} Using Plink with \i{WinCVS} |
| 282 | |
| 283 | Plink can also be used with WinCVS. Firstly, arrange for Plink to be |
| 284 | able to connect to a remote host non-interactively, as described in |
| 285 | \k{plink-usage-batch}. |
| 286 | |
| 287 | Then, in WinCVS, bring up the \q{Preferences} dialogue box from the |
| 288 | \e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there |
| 289 | labelled \q{Check for an alternate \cw{rsh} name} and in the text |
| 290 | entry field to the right enter the full path to \c{plink.exe}. |
| 291 | Select \q{OK} on the \q{Preferences} dialogue box. |
| 292 | |
| 293 | Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type |
| 294 | a CVS command as in \k{plink-cvs}, for example: |
| 295 | |
| 296 | \c cvs -d :ext:user@hostname:/path/to/repository co module |
| 297 | |
| 298 | Select the folder you want to check out to with the \q{Change Folder} |
| 299 | button, and click \q{OK} to check out your module. Once you've got |
| 300 | modules checked out, WinCVS will happily invoke plink from the GUI for |
| 301 | CVS operations. |
| 302 | |
| 303 | \# \H{plink-whatelse} Using Plink with... ? |