1 \versionid $Id: plink.but,v 1.17 2002/09/11 17:30:36 jacob 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]
48 \c ("host" can also be a PuTTY saved session name)
50 \c -v show verbose messages
51 \c -load sessname Load settings from saved session
52 \c -ssh -telnet -rlogin -raw
53 \c force use of a particular protocol (default SSH)
54 \c -P port connect to specified port
55 \c -l user connect with specified username
56 \c -m file read remote command(s) from file
57 \c -batch disable all interactive prompts
58 \c The following options only apply to SSH connections:
59 \c -pw passw login with specified password
60 \c -L listen-port:host:port Forward local port to remote address
61 \c -R listen-port:host:port Forward remote port to local address
62 \c -X -x enable / disable X11 forwarding
63 \c -A -a enable / disable agent forwarding
64 \c -t -T enable / disable pty allocation
65 \c -1 -2 force use of particular protocol version
66 \c -C enable compression
67 \c -i key private key file for authentication
69 Once this works, you are ready to use Plink.
71 \S{plink-usage-interactive} Using Plink for interactive logins
73 To make a simple interactive connection to a remote server, just
74 type \c{plink} and then the host name:
76 \c Z:\sysosd>plink login.example.com
78 \c Debian GNU/Linux 2.2 flunky.example.com
81 You should then be able to log in as normal and run a session. The
82 output sent by the server will be written straight to your command
83 prompt window, which will most likely not interpret terminal control
84 codes in the way the server expects it to. So if you run any
85 full-screen applications, for example, you can expect to see strange
86 characters appearing in your window. Interactive connections like
87 this are not the main point of Plink.
89 In order to connect with a different protocol, you can give the
90 command line options \c{-ssh}, \c{-telnet}, \c{-rlogin} or \c{-raw}.
91 To make an SSH connection, for example:
93 \c Z:\sysosd>plink -ssh login.example.com
96 If you have already set up a PuTTY saved session, then instead of
97 supplying a host name, you can give the saved session name. This
98 allows you to use public-key authentication, specify a user name,
99 and use most of the other features of PuTTY:
101 \c Z:\sysosd>plink my-ssh-session
102 \c Sent username "fred"
103 \c Authenticating with public key "fred@winbox"
104 \c Last login: Thu Dec 6 19:25:33 2001 from :0.0
107 \S{plink-usage-batch} Using Plink for automated connections
109 More typically Plink is used with the SSH protocol, to enable you to
110 talk directly to a program running on the server. To do this you
111 have to ensure Plink is \e{using} the SSH protocol. You can do this
114 \b Use the \c{-ssh} option as described in
115 \k{plink-usage-interactive}.
117 \b Set up a PuTTY saved session that describes the server you are
118 connecting to, and that also specifies the protocol as SSH.
120 \b Set the Windows environment variable \c{PLINK_PROTOCOL} to the
123 Usually Plink is not invoked directly by a user, but run
124 automatically by another process. Therefore you typically do not
125 want Plink to prompt you for a user name or a password.
127 To avoid being prompted for a user name, you can:
129 \b Use the \c{-l} option to specify a user name on the command line.
130 For example, \c{plink login.example.com -l fred}.
132 \b Set up a PuTTY saved session that describes the server you are
133 connecting to, and that also specifies the username to log in as
134 (see \k{config-username}).
136 To avoid being prompted for a password, you should almost certainly
137 set up public-key authentication. (See \k{pubkey} for a general
138 introduction to public-key authentication.) Again, you can do this
141 \b Set up a PuTTY saved session that describes the server you are
142 connecting to, and that also specifies a private key file (see
143 \k{config-ssh-privkey}). For this to work without prompting, your
144 private key will need to have no passphrase.
146 \b Store the private key in Pageant. See \k{pageant} for further
149 Once you have done all this, you should be able to run a remote
150 command on the SSH server machine and have it execute automatically
153 \c Z:\sysosd>plink login.example.com -l fred echo hello, world
158 Or, if you have set up a saved session with all the connection
161 \c Z:\sysosd>plink mysession echo hello, world
166 Then you can set up other programs to run this Plink command and
167 talk to it as if it were a process on the server machine.
169 \S{plink-options} Plink command line options
171 Plink accepts all the general command line options supported by the
172 PuTTY tools. See \k{using-general-opts} for a description of these
175 In addition to this, Plink accepts one other option: the \c{-batch}
176 option. If you use the \c{-batch} option, Plink will never give an
177 interactive prompt while establishing the connection. If the
178 server's host key is invalid, for example (see \k{gs-hostkey}), then
179 the connection will simply be abandoned instead of asking you what
182 This may help Plink's behaviour when it is used in automated
183 scripts: using \c{-batch}, if something goes wrong at connection
184 time, the batch job will fail rather than hang.
186 \H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
188 Once you have set up Plink to be able to log in to a remote server
189 without any interactive prompting (see \k{plink-usage-batch}), you
190 can use it for lots of scripting and batch purposes. For example, to
191 start a backup on a remote machine, you might use a command like:
193 \c plink root@myserver /etc/backups/do-backup.sh
195 Or perhaps you want to fetch all system log lines relating to a
198 \c plink mysession grep /~fjbloggs/ /var/log/httpd/access.log > fredlogs
200 Any non-interactive command you could usefully run on the server
201 command line, you can run in a batch file using Plink in this way.
203 \H{plink-cvs} Using Plink with \i{CVS}
205 To use Plink with CVS, you need to set the environment variable
206 \c{CVS_RSH} to point to Plink:
208 \c set CVS_RSH=\path\to\plink.exe
210 You also need to arrange to be able to connect to a remote host
211 without any interactive prompts, as described in
212 \k{plink-usage-batch}.
214 You should then be able to run CVS as follows:
216 \c cvs -d :ext:user@sessionname:/path/to/repository co module
218 If you specified a username in your saved session, you don't even
219 need to specify the \q{user} part of this, and you can just say:
221 \c cvs -d :ext:sessionname:/path/to/repository co module
223 \H{plink-wincvs} Using Plink with \i{WinCVS}
225 Plink can also be used with WinCVS. Firstly, arrange for Plink to be
226 able to connect to a remote host non-interactively, as described in
227 \k{plink-usage-batch}.
229 Then, in WinCVS, bring up the \q{Preferences} dialogue box from the
230 \e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there
231 labelled \q{Check for an alternate \cw{rsh} name} and in the text
232 entry field to the right enter the full path to \c{plink.exe}.
233 Select \q{OK} on the \q{Preferences} dialogue box.
235 Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type
236 a CVS command as in \k{plink-cvs}, for example:
238 \c cvs -d :ext:user@hostname:/path/to/repository co module
240 or (if you're using a saved session):
242 \c cvs -d :ext:user@sessionname:/path/to/repository co module
244 Select the folder you want to check out to with the \q{Change Folder}
245 button, and click \q{OK} to check out your module. Once you've got
246 modules checked out, WinCVS will happily invoke plink from the GUI for
249 \# \H{plink-whatelse} Using Plink with... ?