1 \versionid $Id: plink.but,v 1.15 2002/03/05 20:39:27 simon Exp $
3 \C{plink} Using the command-line connection tool Plink
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.
9 Plink is probably not what you want if you want to run an
10 interactive session in a console window.
12 \H{plink-starting} Starting Plink
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
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:
26 \c set PATH=C:\path\to\putty\directory;%PATH%
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.
34 \H{plink-usage} Using Plink
36 This section describes the basics of how to use Plink for
37 interactive logins and for automated processes.
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
45 \c PuTTY Link: command-line connection utility
47 \c Usage: plink [options] [user@]host [command]
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
54 Once this works, you are ready to use Plink.
56 \S{plink-usage-interactive} Using Plink for interactive logins
58 To make a simple interactive connection to a remote server, just
59 type \c{plink} and then the host name:
61 \c Z:\sysosd>plink login.example.com
63 \c Debian GNU/Linux 2.2 flunky.example.com
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.
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:
78 \c Z:\sysosd>plink -ssh login.example.com
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:
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
92 \S{plink-usage-batch} Using Plink for automated connections
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
99 \b Use the \c{-ssh} option as described in
100 \k{plink-usage-interactive}.
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.
105 \b Set the Windows environment variable \c{PLINK_PROTOCOL} to the
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.
112 To avoid being prompted for a user name, you can:
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}.
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}).
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
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.
131 \b Store the private key in Pageant. See \k{pageant} for further
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
138 \c Z:\sysosd>plink login.example.com -l fred echo hello, world
143 Or, if you have set up a saved session with all the connection
146 \c Z:\sysosd>plink mysession echo hello, world
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.
154 You may also find it useful to use the \c{-batch} command-line
155 option; see \k{plink-usage-options-batch}.
157 \S{plink-usage-options} Options
159 This section describes the command line options that Plink accepts.
161 \S2{plink-usage-options-v}\c{-v} show verbose messages
163 By default, Plink only displays any password prompts and the output of
164 the remote command. The \c{-v} option makes it print extra
165 information about the connection being made, for example:
167 \c Server version: SSH-1.5-OpenSSH-1.2.3
168 \c We claim version: SSH-1.5-PuTTY
169 \c Using SSH protocol version 1
170 \c Received public keys
171 \c Host key fingerprint is:
172 \c 1023 e3:65:44:44:bd:b1:04:59:bc:e2:3d:a1:4d:09:ce:99
173 \c Encrypted session key
174 \c Using 3DES encryption
175 \c Trying to enable encryption...
176 \c Successfully started encryption
177 \c Sent username "fred".
178 \c Sent username "fred"
179 \c fred@example.com's password:
181 This information can be useful for diagnosing problems.
183 \S2{plink-usage-options-ssh} Protocol selection options
185 Plink is most useful when using the SSH protocol. However, it allows
186 you to interface to all the protocols supported by PuTTY. You can
187 specify the option \c{-ssh} on the command line to select the SSH
188 protocol; you can also specify \c{-telnet}, \c{-rlogin} or \c{-raw}
189 to select other protocols.
191 \S2{plink-usage-options-P}\c{-P port} connect to specified port
193 If your server machine is running its SSH service on a port other
194 than the standard one, you can specify an alternative port number to
195 connect to using the \c{-P} option, like this:
197 \c plink -ssh login.example.com -P 5022
199 \S2{plink-usage-options-pw}\c{-pw passw} login with specified password
201 A simple way to automate a remote login is to supply your password
202 on the Plink command line. This is \e{not recommended} for reasons
203 of security. If you possibly can, we recommend you set up public-key
204 authentication instead. See \k{pubkey} for details.
206 Note that the \c{-pw} option only works when you are using the SSH
207 protocol. Due to fundamental limitations of Telnet and Rlogin, these
208 protocols do not support automated password authentication.
210 \S2{plink-usage-options-user}\c{-l username} login with specified
213 As described in \k{plink-usage-batch}, you can specify the user name
214 to log in as on the remote server using the \c{-l} option. For
215 example, \c{plink login.example.com -l fred}.
217 \S2{plink-usage-options-batch}\c{-batch} avoid interactive prompts
219 If you use the \c{-batch} option, Plink will never give an
220 interactive prompt while establishing the connection. If the
221 server's host key is invalid, for example (see \k{gs-hostkey}), then
222 the connection will simply be abandoned instead of asking you what
225 This may help Plink's behaviour when it is used in automated
226 scripts: using \c{-batch}, if something goes wrong at connection
227 time, the batch job will fail rather than hang.
229 \S2{plink-usage-options-cmdfile} \c{-m filename} read command from a
232 If the command you want to run on the remote server is particularly
233 large, you can read it from a file using the \c{-m} option, instead
234 of putting it directly on Plink's command line. On most Unix
235 systems, you can even put multiple lines in this file and execute
236 more than one command in sequence, or a whole shell script.
238 \S2{plink-usage-options-portfwd} \c{-L} and \c{-R} set up port
241 Plink allows you to use port forwarding just as PuTTY does; if you
242 have set up a PuTTY saved session that specifies port forwardings,
243 and you connect to that session using Plink, then the same port
244 forwardings will be set up.
246 For convenience, Plink also offers the option to set up port
247 forwarding on the command line. The command-line options work just
248 like the ones in Unix \c{ssh} programs.
250 To forward a local port (say 5110) to a remote destination (say
251 \cw{popserver.example.com} port 110), you can write:
253 \c plink mysession -L 5110:popserver.example.com:110
255 And to forward a remote port to a local destination, just use the
256 \c{-R} option instead of \c{-L}:
258 \c plink mysession -R 5023:mytelnetserver.myhouse.org:23
260 For general information on port forwarding, see
261 \k{using-port-forwarding}.
263 \H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
265 Once you have set up Plink to be able to log in to a remote server
266 without any interactive prompting (see \k{plink-usage-batch}), you
267 can use it for lots of scripting and batch purposes. For example, to
268 start a backup on a remote machine, you might use a command like:
270 \c plink root@myserver /etc/backups/do-backup.sh
272 Or perhaps you want to fetch all system log lines relating to a
275 \c plink mysession grep /~fjbloggs/ /var/log/httpd/access.log > fredlogs
277 Any non-interactive command you could usefully run on the server
278 command line, you can run in a batch file using Plink in this way.
280 \H{plink-cvs} Using Plink with \i{CVS}
282 To use Plink with CVS, you need to set the environment variable
283 \c{CVS_RSH} to point to Plink:
285 \c set CVS_RSH=\path\to\plink.exe
287 You also need to arrange to be able to connect to a remote host
288 without any interactive prompts, as described in
289 \k{plink-usage-batch}.
291 You should then be able to run CVS as follows:
293 \c cvs -d :ext:user@sessionname:/path/to/repository co module
295 If you specified a username in your saved session, you don't even
296 need to specify the \q{user} part of this, and you can just say:
298 \c cvs -d :ext:sessionname:/path/to/repository co module
300 \H{plink-wincvs} Using Plink with \i{WinCVS}
302 Plink can also be used with WinCVS. Firstly, arrange for Plink to be
303 able to connect to a remote host non-interactively, as described in
304 \k{plink-usage-batch}.
306 Then, in WinCVS, bring up the \q{Preferences} dialogue box from the
307 \e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there
308 labelled \q{Check for an alternate \cw{rsh} name} and in the text
309 entry field to the right enter the full path to \c{plink.exe}.
310 Select \q{OK} on the \q{Preferences} dialogue box.
312 Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type
313 a CVS command as in \k{plink-cvs}, for example:
315 \c cvs -d :ext:user@hostname:/path/to/repository co module
317 or (if you're using a saved session):
319 \c cvs -d :ext:user@sessionname:/path/to/repository co module
321 Select the folder you want to check out to with the \q{Change Folder}
322 button, and click \q{OK} to check out your module. Once you've got
323 modules checked out, WinCVS will happily invoke plink from the GUI for
326 \# \H{plink-whatelse} Using Plink with... ?