39a938f7 |
1 | \define{versionidplink} \versionid $Id$ |
bace5431 |
2 | |
421406a4 |
3 | \C{plink} Using the command-line connection tool \i{Plink} |
e5b0d077 |
4 | |
717c214c |
5 | \i{Plink} (PuTTY Link) is a command-line connection tool similar to |
421406a4 |
6 | UNIX \c{ssh}. It is mostly used for \i{automated operations}, such as |
2f8d6d43 |
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 |
421406a4 |
10 | \i{interactive session} in a console window. |
bace5431 |
11 | |
12 | \H{plink-starting} Starting Plink |
13 | |
2f8d6d43 |
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 |
421406a4 |
17 | \q{MS-DOS Prompt}, and in Windows NT, 2000, and XP, it is called a |
2f8d6d43 |
18 | \q{Command Prompt}. It should be available from the Programs section |
bace5431 |
19 | of your Start Menu. |
20 | |
2f8d6d43 |
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: |
bace5431 |
25 | |
8452efbc |
26 | \c set PATH=C:\path\to\putty\directory;%PATH% |
bace5431 |
27 | |
28 | This will only work for the lifetime of that particular console |
421406a4 |
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. |
bace5431 |
33 | |
2f8d6d43 |
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. |
bace5431 |
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 |
b1eb1f95 |
46 | \c Release 0.62 |
bace5431 |
47 | \c Usage: plink [options] [user@]host [command] |
e2a197cf |
48 | \c ("host" can also be a PuTTY saved session name) |
bace5431 |
49 | \c Options: |
2285d016 |
50 | \c -V print version information and exit |
51 | \c -pgpfp print PGP key fingerprints and exit |
bace5431 |
52 | \c -v show verbose messages |
e2a197cf |
53 | \c -load sessname Load settings from saved session |
9621bbab |
54 | \c -ssh -telnet -rlogin -raw -serial |
afd4d0d2 |
55 | \c force use of a particular protocol |
bace5431 |
56 | \c -P port connect to specified port |
e2a197cf |
57 | \c -l user connect with specified username |
e2a197cf |
58 | \c -batch disable all interactive prompts |
59 | \c The following options only apply to SSH connections: |
bace5431 |
60 | \c -pw passw login with specified password |
dbe6c525 |
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 |
e2a197cf |
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 |
05581745 |
71 | \c -4 -6 force use of IPv4 or IPv6 |
e2a197cf |
72 | \c -C enable compression |
73 | \c -i key private key file for authentication |
e5708bc7 |
74 | \c -noagent disable use of Pageant |
75 | \c -agent enable use of Pageant |
54018d95 |
76 | \c -m file read remote command(s) from file |
4d1cdf5d |
77 | \c -s remote command is an SSH subsystem (SSH-2 only) |
b72c366d |
78 | \c -N don't start a shell/command (SSH-2 only) |
23828b7e |
79 | \c -nc host:port |
80 | \c open tunnel in place of session (SSH-2 only) |
9621bbab |
81 | \c -sercfg configuration-string (e.g. 19200,8,n,1,X) |
82 | \c Specify the serial configuration (serial only) |
bace5431 |
83 | |
2f8d6d43 |
84 | Once this works, you are ready to use Plink. |
85 | |
86 | \S{plink-usage-interactive} Using Plink for interactive logins |
87 | |
88 | To make a simple interactive connection to a remote server, just |
89 | type \c{plink} and then the host name: |
90 | |
91 | \c Z:\sysosd>plink login.example.com |
92 | \c |
93 | \c Debian GNU/Linux 2.2 flunky.example.com |
94 | \c flunky login: |
95 | |
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 |
421406a4 |
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 |
2f8d6d43 |
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. |
103 | |
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: |
107 | |
108 | \c Z:\sysosd>plink -ssh login.example.com |
109 | \c login as: |
110 | |
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: |
115 | |
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 |
120 | \c fred@flunky:~$ |
121 | |
939c2b22 |
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 |
126 | remote command.) |
127 | |
2f8d6d43 |
128 | \S{plink-usage-batch} Using Plink for automated connections |
129 | |
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 |
133 | in several ways: |
134 | |
135 | \b Use the \c{-ssh} option as described in |
136 | \k{plink-usage-interactive}. |
137 | |
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. |
140 | |
421406a4 |
141 | \b Set the Windows environment variable \i\c{PLINK_PROTOCOL} to the |
2f8d6d43 |
142 | word \c{ssh}. |
143 | |
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. |
147 | |
ae62952c |
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 |
151 | enter a password. |
152 | |
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. |
160 | |
2f8d6d43 |
161 | To avoid being prompted for a user name, you can: |
162 | |
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}. |
165 | |
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}). |
169 | |
170 | To avoid being prompted for a password, you should almost certainly |
421406a4 |
171 | set up \i{public-key authentication}. (See \k{pubkey} for a general |
2f8d6d43 |
172 | introduction to public-key authentication.) Again, you can do this |
173 | in two ways: |
174 | |
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. |
179 | |
180 | \b Store the private key in Pageant. See \k{pageant} for further |
181 | information. |
182 | |
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 |
185 | with no prompting: |
186 | |
187 | \c Z:\sysosd>plink login.example.com -l fred echo hello, world |
188 | \c hello, world |
189 | \c |
190 | \c Z:\sysosd> |
191 | |
192 | Or, if you have set up a saved session with all the connection |
193 | details: |
194 | |
195 | \c Z:\sysosd>plink mysession echo hello, world |
196 | \c hello, world |
197 | \c |
198 | \c Z:\sysosd> |
199 | |
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. |
bace5431 |
202 | |
e117a742 |
203 | \S{plink-options} Plink command line options |
ff2ae367 |
204 | |
e117a742 |
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 |
207 | options. |
bace5431 |
208 | |
4d1cdf5d |
209 | Plink also supports some of its own options. The following sections |
210 | describe Plink's specific command-line options. |
211 | |
421406a4 |
212 | \S2{plink-option-batch} \I{-batch-plink}\c{-batch}: disable all |
213 | interactive prompts |
4d1cdf5d |
214 | |
215 | If you use the \c{-batch} option, Plink will never give an |
ff2ae367 |
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 |
219 | to do next. |
220 | |
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. |
224 | |
421406a4 |
225 | \S2{plink-option-s} \I{-s-plink}\c{-s}: remote command is SSH subsystem |
4d1cdf5d |
226 | |
227 | If you specify the \c{-s} option, Plink passes the specified command |
421406a4 |
228 | as the name of an SSH \q{\i{subsystem}} rather than an ordinary command |
4d1cdf5d |
229 | line. |
230 | |
231 | (This option is only meaningful with the SSH-2 protocol.) |
232 | |
eaebbdf8 |
233 | \H{plink-batch} Using Plink in \i{batch files} and \i{scripts} |
bace5431 |
234 | |
2f8d6d43 |
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: |
239 | |
240 | \c plink root@myserver /etc/backups/do-backup.sh |
241 | |
242 | Or perhaps you want to fetch all system log lines relating to a |
243 | particular web area: |
244 | |
35cffede |
245 | \c plink mysession grep /~fred/ /var/log/httpd/access.log > fredlog |
2f8d6d43 |
246 | |
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. |
249 | |
eaebbdf8 |
250 | \H{plink-cvs} Using Plink with \i{CVS} |
251 | |
7638530e |
252 | To use Plink with CVS, you need to set the environment variable |
421406a4 |
253 | \i\c{CVS_RSH} to point to Plink: |
eaebbdf8 |
254 | |
255 | \c set CVS_RSH=\path\to\plink.exe |
7638530e |
256 | |
257 | You also need to arrange to be able to connect to a remote host |
2f8d6d43 |
258 | without any interactive prompts, as described in |
259 | \k{plink-usage-batch}. |
7638530e |
260 | |
2f8d6d43 |
261 | You should then be able to run CVS as follows: |
7638530e |
262 | |
263 | \c cvs -d :ext:user@sessionname:/path/to/repository co module |
264 | |
2f8d6d43 |
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: |
7638530e |
267 | |
268 | \c cvs -d :ext:sessionname:/path/to/repository co module |
269 | |
7638530e |
270 | \H{plink-wincvs} Using Plink with \i{WinCVS} |
271 | |
272 | Plink can also be used with WinCVS. Firstly, arrange for Plink to be |
2f8d6d43 |
273 | able to connect to a remote host non-interactively, as described in |
274 | \k{plink-usage-batch}. |
eaebbdf8 |
275 | |
2f8d6d43 |
276 | Then, in WinCVS, bring up the \q{Preferences} dialogue box from the |
d60c975d |
277 | \e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there |
2f8d6d43 |
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. |
eaebbdf8 |
281 | |
d60c975d |
282 | Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type |
7638530e |
283 | a CVS command as in \k{plink-cvs}, for example: |
284 | |
285 | \c cvs -d :ext:user@hostname:/path/to/repository co module |
eaebbdf8 |
286 | |
a88d77d6 |
287 | or (if you're using a saved session): |
288 | |
289 | \c cvs -d :ext:user@sessionname:/path/to/repository co module |
290 | |
d60c975d |
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 |
7638530e |
293 | modules checked out, WinCVS will happily invoke plink from the GUI for |
294 | CVS operations. |
bace5431 |
295 | |
2f8d6d43 |
296 | \# \H{plink-whatelse} Using Plink with... ? |