I have no brain at all. The SSH1 auth loop was trying all Pageant
[sgt/putty] / doc / plink.but
CommitLineData
2f8d6d43 1\versionid $Id: plink.but,v 1.12 2001/12/06 20:05:39 simon Exp $
bace5431 2
e5b0d077 3\C{plink} Using the command-line connection tool Plink
4
717c214c 5\i{Plink} (PuTTY Link) is a command-line connection tool similar to
2f8d6d43 6UNIX \c{ssh}. It is mostly used for automated operations, such as
7making CVS access a repository on a remote server.
8
9Plink is probably not what you want if you want to run an
10interactive session in a console window.
bace5431 11
12\H{plink-starting} Starting Plink
13
2f8d6d43 14Plink is a command line application. This means that you cannot just
15double-click on its icon to run it and instead you have to bring up
16a \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
bace5431 19of your Start Menu.
20
2f8d6d43 21In order to use Plink, the file \c{plink.exe} will need either to be
22on your \i{\c{PATH}} or in your current directory. To add the
23directory containing Plink to your \c{PATH} environment variable,
24type into the console window:
bace5431 25
8452efbc 26\c set PATH=C:\path\to\putty\directory;%PATH%
bace5431 27
28This will only work for the lifetime of that particular console
2f8d6d43 29window. To set your \c{PATH} more permanently on Windows NT, use the
bace5431 30Environment tab of the System Control Panel. On Windows 95, 98, and
31ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set}
32command like the one above.
33
2f8d6d43 34\H{plink-usage} Using Plink
35
36This section describes the basics of how to use Plink for
37interactive logins and for automated processes.
bace5431 38
39Once 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
41version of Plink you're using, and gives you a brief summary of how to
42use 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
2f8d6d43 54Once this works, you are ready to use Plink.
55
56\S{plink-usage-interactive} Using Plink for interactive logins
57
58To make a simple interactive connection to a remote server, just
59type \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
66You should then be able to log in as normal and run a session. The
67output sent by the server will be written straight to your command
68prompt window, which will most likely not interpret terminal control
69codes in the way the server expects it to. So if you run any
70full-screen applications, for example, you can expect to see strange
71characters appearing in your window. Interactive connections like
72this are not the main point of Plink.
73
74In order to connect with a different protocol, you can give the
75command line options \c{-ssh}, \c{-telnet}, \c{-rlogin} or \c{-raw}.
76To make an SSH connection, for example:
77
78\c Z:\sysosd>plink -ssh login.example.com
79\c login as:
80
81If you have already set up a PuTTY saved session, then instead of
82supplying a host name, you can give the saved session name. This
83allows you to use public-key authentication, specify a user name,
84and 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
94More typically Plink is used with the SSH protocol, to enable you to
95talk directly to a program running on the server. To do this you
96have to ensure Plink is \e{using} the SSH protocol. You can do this
97in 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
103connecting to, and that also specifies the protocol as SSH.
104
105\b Set the Windows environment variable \c{PLINK_PROTOCOL} to the
106word \c{ssh}.
107
108Usually Plink is not invoked directly by a user, but run
109automatically by another process. Therefore you typically do not
110want Plink to prompt you for a user name or a password.
111
112To 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.
115For example, \c{plink login.example.com -l fred}.
116
117\b Set up a PuTTY saved session that describes the server you are
118connecting to, and that also specifies the username to log in as
119(see \k{config-username}).
120
121To avoid being prompted for a password, you should almost certainly
122set up public-key authentication. (See \k{pubkey} for a general
123introduction to public-key authentication.) Again, you can do this
124in two ways:
125
126\b Set up a PuTTY saved session that describes the server you are
127connecting to, and that also specifies a private key file (see
128\k{config-ssh-privkey}). For this to work without prompting, your
129private key will need to have no passphrase.
130
131\b Store the private key in Pageant. See \k{pageant} for further
132information.
133
134Once you have done all this, you should be able to run a remote
135command on the SSH server machine and have it execute automatically
136with 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
143Or, if you have set up a saved session with all the connection
144details:
145
146\c Z:\sysosd>plink mysession echo hello, world
147\c hello, world
148\c
149\c Z:\sysosd>
150
151Then you can set up other programs to run this Plink command and
152talk to it as if it were a process on the server machine.
bace5431 153
154\S{plink-usage-options} Options
155
2f8d6d43 156This section describes the command line options that Plink accepts.
bace5431 157
7638530e 158\S2{plink-usage-options-v}\c{-v} show verbose messages
159
160By default, Plink only displays any password prompts and the output of
161the remote command. The \c{-v} option makes it print extra
162information 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
178This information can be useful for diagnosing problems.
179
2f8d6d43 180\S2{plink-usage-options-ssh} Protocol selection options
181
182Plink is most useful when using the SSH protocol. However, it allows
183you to interface to all the protocols supported by PuTTY. You can
184specify the option \c{-ssh} on the command line to select the SSH
185protocol; you can also specify \c{-telnet}, \c{-rlogin} or \c{-raw}
186to select other protocols.
7638530e 187
188\S2{plink-usage-options-P}\c{-P port} connect to specified port
189
2f8d6d43 190If your server machine is running its SSH service on a port other
191than the standard one, you can specify an alternative port number to
192connect to using the \c{-P} option, like this:
193
194\c plink -ssh login.example.com -P 5022
195
7638530e 196\S2{plink-usage-options-pw}\c{-pw passw} login with specified password
197
2f8d6d43 198A simple way to automate a remote login is to supply your password
199on the Plink command line. This is \e{not recommended} for reasons
200of security. If you possibly can, we recommend you set up public-key
201authentication instead. See \k{pubkey} for details.
202
203\S2{plink-usage-options-user}\c{-l username} login with specified
204username
205
206As described in \k{plink-usage-batch}, you can specify the user name
207to log in as on the remote server using the \c{-l} option. For
208example, \c{plink login.example.com -l fred}.
209
210\S2{plink-usage-options-cmdfile} \c{-m filename} read command from a
211file
212
213If the command you want to run on the remote server is particularly
214large, you can read it from a file using the \c{-m} option, instead
215of putting it directly on Plink's command line. On most Unix
216systems, you can even put multiple lines in this file and execute
217more 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
220forwarding
221
222Plink allows you to use port forwarding just as PuTTY does; if you
223have set up a PuTTY saved session that specifies port forwardings,
224and you connect to that session using Plink, then the same port
225forwardings will be set up.
226
227For convenience, Plink also offers the option to set up port
228forwarding on the command line. The command-line options work just
229like the ones in Unix \c{ssh} programs.
230
231To 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
236And 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
241For general information on port forwarding, see
242\k{using-port-forwarding}.
bace5431 243
eaebbdf8 244\H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
bace5431 245
2f8d6d43 246Once you have set up Plink to be able to log in to a remote server
247without any interactive prompting (see \k{plink-usage-batch}), you
248can use it for lots of scripting and batch purposes. For example, to
249start a backup on a remote machine, you might use a command like:
250
251\c plink root@myserver /etc/backups/do-backup.sh
252
253Or perhaps you want to fetch all system log lines relating to a
254particular web area:
255
256\c plink mysession grep /~fjbloggs/ /var/log/httpd/access.log > fredlogs
257
258Any non-interactive command you could usefully run on the server
259command line, you can run in a batch file using Plink in this way.
260
eaebbdf8 261\H{plink-cvs} Using Plink with \i{CVS}
262
7638530e 263To use Plink with CVS, you need to set the environment variable
264\c{CVS_RSH} to point to Plink:
eaebbdf8 265
266\c set CVS_RSH=\path\to\plink.exe
7638530e 267
268You also need to arrange to be able to connect to a remote host
2f8d6d43 269without any interactive prompts, as described in
270\k{plink-usage-batch}.
7638530e 271
2f8d6d43 272You should then be able to run CVS as follows:
7638530e 273
274\c cvs -d :ext:user@sessionname:/path/to/repository co module
275
2f8d6d43 276If you specified a username in your saved session, you don't even
277need to specify the \q{user} part of this, and you can just say:
7638530e 278
279\c cvs -d :ext:sessionname:/path/to/repository co module
280
7638530e 281\H{plink-wincvs} Using Plink with \i{WinCVS}
282
283Plink can also be used with WinCVS. Firstly, arrange for Plink to be
2f8d6d43 284able to connect to a remote host non-interactively, as described in
285\k{plink-usage-batch}.
eaebbdf8 286
2f8d6d43 287Then, in WinCVS, bring up the \q{Preferences} dialogue box from the
d60c975d 288\e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there
2f8d6d43 289labelled \q{Check for an alternate \cw{rsh} name} and in the text
290entry field to the right enter the full path to \c{plink.exe}.
291Select \q{OK} on the \q{Preferences} dialogue box.
eaebbdf8 292
d60c975d 293Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type
7638530e 294a CVS command as in \k{plink-cvs}, for example:
295
296\c cvs -d :ext:user@hostname:/path/to/repository co module
eaebbdf8 297
d60c975d 298Select the folder you want to check out to with the \q{Change Folder}
299button, and click \q{OK} to check out your module. Once you've got
7638530e 300modules checked out, WinCVS will happily invoke plink from the GUI for
301CVS operations.
bace5431 302
2f8d6d43 303\# \H{plink-whatelse} Using Plink with... ?