1 \define{versionidplink} \versionid $Id$
3 \C{plink} Using the command-line connection tool \i{Plink}
5 \i{Plink} (PuTTY Link) is a command-line connection tool similar to
6 UNIX \c{ssh}. It is mostly used for \i{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 \i{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, 2000, and XP, 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, 2000,
30 and XP, use the Environment tab of the System Control Panel. On
31 Windows 95, 98, and ME, you will need to edit your \i\c{AUTOEXEC.BAT}
32 to include a \c{set} 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]
48 \c ("host" can also be a PuTTY saved session name)
50 \c -V print version information and exit
51 \c -pgpfp print PGP key fingerprints and exit
52 \c -v show verbose messages
53 \c -load sessname Load settings from saved session
54 \c -ssh -telnet -rlogin -raw -serial
55 \c force use of a particular protocol
56 \c -P port connect to specified port
57 \c -l user connect with specified username
58 \c -batch disable all interactive prompts
59 \c The following options only apply to SSH connections:
60 \c -pw passw login with specified password
61 \c -D [listen-IP:]listen-port
62 \c Dynamic SOCKS-based port forwarding
63 \c -L [listen-IP:]listen-port:host:port
64 \c Forward local port to remote address
65 \c -R [listen-IP:]listen-port:host:port
66 \c Forward remote port to local address
67 \c -X -x enable / disable X11 forwarding
68 \c -A -a enable / disable agent forwarding
69 \c -t -T enable / disable pty allocation
70 \c -1 -2 force use of particular protocol version
71 \c -4 -6 force use of IPv4 or IPv6
72 \c -C enable compression
73 \c -i key private key file for authentication
74 \c -noagent disable use of Pageant
75 \c -agent enable use of Pageant
76 \c -m file read remote command(s) from file
77 \c -s remote command is an SSH subsystem (SSH-2 only)
78 \c -N don't start a shell/command (SSH-2 only)
80 \c open tunnel in place of session (SSH-2 only)
81 \c -sercfg configuration-string (e.g. 19200,8,n,1,X)
82 \c Specify the serial configuration (serial only)
84 Once this works, you are ready to use Plink.
86 \S{plink-usage-interactive} Using Plink for interactive logins
88 To make a simple interactive connection to a remote server, just
89 type \c{plink} and then the host name:
91 \c Z:\sysosd>plink login.example.com
93 \c Debian GNU/Linux 2.2 flunky.example.com
96 You should then be able to log in as normal and run a session. The
97 output sent by the server will be written straight to your command
98 prompt window, which will most likely not interpret terminal \i{control
99 codes} in the way the server expects it to. So if you run any
100 full-screen applications, for example, you can expect to see strange
101 characters appearing in your window. Interactive connections like
102 this are not the main point of Plink.
104 In order to connect with a different protocol, you can give the
105 command line options \c{-ssh}, \c{-telnet}, \c{-rlogin} or \c{-raw}.
106 To make an SSH connection, for example:
108 \c Z:\sysosd>plink -ssh login.example.com
111 If you have already set up a PuTTY saved session, then instead of
112 supplying a host name, you can give the saved session name. This
113 allows you to use public-key authentication, specify a user name,
114 and use most of the other features of PuTTY:
116 \c Z:\sysosd>plink my-ssh-session
117 \c Sent username "fred"
118 \c Authenticating with public key "fred@winbox"
119 \c Last login: Thu Dec 6 19:25:33 2001 from :0.0
122 (You can also use the \c{-load} command-line option to load a saved
123 session; see \k{using-cmdline-load}. If you use \c{-load}, the saved
124 session exists, and it specifies a hostname, you cannot also specify a
125 \c{host} or \c{user@host} argument - it will be treated as part of the
128 \S{plink-usage-batch} Using Plink for automated connections
130 More typically Plink is used with the SSH protocol, to enable you to
131 talk directly to a program running on the server. To do this you
132 have to ensure Plink is \e{using} the SSH protocol. You can do this
135 \b Use the \c{-ssh} option as described in
136 \k{plink-usage-interactive}.
138 \b Set up a PuTTY saved session that describes the server you are
139 connecting to, and that also specifies the protocol as SSH.
141 \b Set the Windows environment variable \i\c{PLINK_PROTOCOL} to the
144 Usually Plink is not invoked directly by a user, but run
145 automatically by another process. Therefore you typically do not
146 want Plink to prompt you for a user name or a password.
148 Next, you are likely to need to avoid the various interactive
149 prompts Plink can produce. You might be prompted to verify the host
150 key of the server you're connecting to, to enter a user name, or to
153 To avoid being prompted for the server host key when using Plink for
154 an automated connection, you should first make a \e{manual}
155 connection (using either of PuTTY or Plink) to the same server,
156 verify the host key (see \k{gs-hostkey} for more information), and
157 select Yes to add the host key to the Registry. After that, Plink
158 commands connecting to that server should not give a host key prompt
159 unless the host key changes.
161 To avoid being prompted for a user name, you can:
163 \b Use the \c{-l} option to specify a user name on the command line.
164 For example, \c{plink login.example.com -l fred}.
166 \b Set up a PuTTY saved session that describes the server you are
167 connecting to, and that also specifies the username to log in as
168 (see \k{config-username}).
170 To avoid being prompted for a password, you should almost certainly
171 set up \i{public-key authentication}. (See \k{pubkey} for a general
172 introduction to public-key authentication.) Again, you can do this
175 \b Set up a PuTTY saved session that describes the server you are
176 connecting to, and that also specifies a private key file (see
177 \k{config-ssh-privkey}). For this to work without prompting, your
178 private key will need to have no passphrase.
180 \b Store the private key in Pageant. See \k{pageant} for further
183 Once you have done all this, you should be able to run a remote
184 command on the SSH server machine and have it execute automatically
187 \c Z:\sysosd>plink login.example.com -l fred echo hello, world
192 Or, if you have set up a saved session with all the connection
195 \c Z:\sysosd>plink mysession echo hello, world
200 Then you can set up other programs to run this Plink command and
201 talk to it as if it were a process on the server machine.
203 \S{plink-options} Plink command line options
205 Plink accepts all the general command line options supported by the
206 PuTTY tools. See \k{using-general-opts} for a description of these
209 Plink also supports some of its own options. The following sections
210 describe Plink's specific command-line options.
212 \S2{plink-option-batch} \I{-batch-plink}\c{-batch}: disable all
215 If you use the \c{-batch} option, Plink will never give an
216 interactive prompt while establishing the connection. If the
217 server's host key is invalid, for example (see \k{gs-hostkey}), then
218 the connection will simply be abandoned instead of asking you what
221 This may help Plink's behaviour when it is used in automated
222 scripts: using \c{-batch}, if something goes wrong at connection
223 time, the batch job will fail rather than hang.
225 \S2{plink-option-s} \I{-s-plink}\c{-s}: remote command is SSH subsystem
227 If you specify the \c{-s} option, Plink passes the specified command
228 as the name of an SSH \q{\i{subsystem}} rather than an ordinary command
231 (This option is only meaningful with the SSH-2 protocol.)
233 \H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
235 Once you have set up Plink to be able to log in to a remote server
236 without any interactive prompting (see \k{plink-usage-batch}), you
237 can use it for lots of scripting and batch purposes. For example, to
238 start a backup on a remote machine, you might use a command like:
240 \c plink root@myserver /etc/backups/do-backup.sh
242 Or perhaps you want to fetch all system log lines relating to a
245 \c plink mysession grep /~fred/ /var/log/httpd/access.log > fredlog
247 Any non-interactive command you could usefully run on the server
248 command line, you can run in a batch file using Plink in this way.
250 \H{plink-cvs} Using Plink with \i{CVS}
252 To use Plink with CVS, you need to set the environment variable
253 \i\c{CVS_RSH} to point to Plink:
255 \c set CVS_RSH=\path\to\plink.exe
257 You also need to arrange to be able to connect to a remote host
258 without any interactive prompts, as described in
259 \k{plink-usage-batch}.
261 You should then be able to run CVS as follows:
263 \c cvs -d :ext:user@sessionname:/path/to/repository co module
265 If you specified a username in your saved session, you don't even
266 need to specify the \q{user} part of this, and you can just say:
268 \c cvs -d :ext:sessionname:/path/to/repository co module
270 \H{plink-wincvs} Using Plink with \i{WinCVS}
272 Plink can also be used with WinCVS. Firstly, arrange for Plink to be
273 able to connect to a remote host non-interactively, as described in
274 \k{plink-usage-batch}.
276 Then, in WinCVS, bring up the \q{Preferences} dialogue box from the
277 \e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there
278 labelled \q{Check for an alternate \cw{rsh} name} and in the text
279 entry field to the right enter the full path to \c{plink.exe}.
280 Select \q{OK} on the \q{Preferences} dialogue box.
282 Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type
283 a CVS command as in \k{plink-cvs}, for example:
285 \c cvs -d :ext:user@hostname:/path/to/repository co module
287 or (if you're using a saved session):
289 \c cvs -d :ext:user@sessionname:/path/to/repository co module
291 Select the folder you want to check out to with the \q{Change Folder}
292 button, and click \q{OK} to check out your module. Once you've got
293 modules checked out, WinCVS will happily invoke plink from the GUI for
296 \# \H{plink-whatelse} Using Plink with... ?