X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/2f8d6d437a189a7f0c059f0a30306c829a5e7cf6..4d9b8cfde347c30066cdcf1002fb6d4b02bdc808:/doc/plink.but diff --git a/doc/plink.but b/doc/plink.but index a5046394..197489e3 100644 --- a/doc/plink.but +++ b/doc/plink.but @@ -1,20 +1,20 @@ -\versionid $Id: plink.but,v 1.12 2001/12/06 20:05:39 simon Exp $ +\define{versionidplink} \versionid $Id$ -\C{plink} Using the command-line connection tool Plink +\C{plink} Using the command-line connection tool \i{Plink} \i{Plink} (PuTTY Link) is a command-line connection tool similar to -UNIX \c{ssh}. It is mostly used for automated operations, such as +UNIX \c{ssh}. It is mostly used for \i{automated operations}, such as making CVS access a repository on a remote server. Plink is probably not what you want if you want to run an -interactive session in a console window. +\i{interactive session} in a console window. \H{plink-starting} Starting Plink Plink is a command line application. This means that you cannot just double-click on its icon to run it and instead you have to bring up a \i{console window}. In Windows 95, 98, and ME, this is called an -\q{MS-DOS Prompt}, and in Windows NT and 2000 it is called a +\q{MS-DOS Prompt}, and in Windows NT, 2000, and XP, it is called a \q{Command Prompt}. It should be available from the Programs section of your Start Menu. @@ -26,10 +26,10 @@ type into the console window: \c set PATH=C:\path\to\putty\directory;%PATH% This will only work for the lifetime of that particular console -window. To set your \c{PATH} more permanently on Windows NT, use the -Environment tab of the System Control Panel. On Windows 95, 98, and -ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set} -command like the one above. +window. To set your \c{PATH} more permanently on Windows NT, 2000, +and XP, use the Environment tab of the System Control Panel. On +Windows 95, 98, and ME, you will need to edit your \i\c{AUTOEXEC.BAT} +to include a \c{set} command like the one above. \H{plink-usage} Using Plink @@ -43,13 +43,43 @@ use Plink: \c Z:\sysosd>plink \c PuTTY Link: command-line connection utility -\c Release 0.50 +\c Release 0.63 \c Usage: plink [options] [user@]host [command] +\c ("host" can also be a PuTTY saved session name) \c Options: +\c -V print version information and exit +\c -pgpfp print PGP key fingerprints and exit \c -v show verbose messages -\c -ssh force use of ssh protocol +\c -load sessname Load settings from saved session +\c -ssh -telnet -rlogin -raw -serial +\c force use of a particular protocol \c -P port connect to specified port +\c -l user connect with specified username +\c -batch disable all interactive prompts +\c The following options only apply to SSH connections: \c -pw passw login with specified password +\c -D [listen-IP:]listen-port +\c Dynamic SOCKS-based port forwarding +\c -L [listen-IP:]listen-port:host:port +\c Forward local port to remote address +\c -R [listen-IP:]listen-port:host:port +\c Forward remote port to local address +\c -X -x enable / disable X11 forwarding +\c -A -a enable / disable agent forwarding +\c -t -T enable / disable pty allocation +\c -1 -2 force use of particular protocol version +\c -4 -6 force use of IPv4 or IPv6 +\c -C enable compression +\c -i key private key file for authentication +\c -noagent disable use of Pageant +\c -agent enable use of Pageant +\c -m file read remote command(s) from file +\c -s remote command is an SSH subsystem (SSH-2 only) +\c -N don't start a shell/command (SSH-2 only) +\c -nc host:port +\c open tunnel in place of session (SSH-2 only) +\c -sercfg configuration-string (e.g. 19200,8,n,1,X) +\c Specify the serial configuration (serial only) Once this works, you are ready to use Plink. @@ -65,8 +95,8 @@ type \c{plink} and then the host name: You should then be able to log in as normal and run a session. The output sent by the server will be written straight to your command -prompt window, which will most likely not interpret terminal control -codes in the way the server expects it to. So if you run any +prompt window, which will most likely not interpret terminal \i{control +codes} in the way the server expects it to. So if you run any full-screen applications, for example, you can expect to see strange characters appearing in your window. Interactive connections like this are not the main point of Plink. @@ -89,6 +119,12 @@ and use most of the other features of PuTTY: \c Last login: Thu Dec 6 19:25:33 2001 from :0.0 \c fred@flunky:~$ +(You can also use the \c{-load} command-line option to load a saved +session; see \k{using-cmdline-load}. If you use \c{-load}, the saved +session exists, and it specifies a hostname, you cannot also specify a +\c{host} or \c{user@host} argument - it will be treated as part of the +remote command.) + \S{plink-usage-batch} Using Plink for automated connections More typically Plink is used with the SSH protocol, to enable you to @@ -102,13 +138,26 @@ in several ways: \b Set up a PuTTY saved session that describes the server you are connecting to, and that also specifies the protocol as SSH. -\b Set the Windows environment variable \c{PLINK_PROTOCOL} to the +\b Set the Windows environment variable \i\c{PLINK_PROTOCOL} to the word \c{ssh}. Usually Plink is not invoked directly by a user, but run automatically by another process. Therefore you typically do not want Plink to prompt you for a user name or a password. +Next, you are likely to need to avoid the various interactive +prompts Plink can produce. You might be prompted to verify the host +key of the server you're connecting to, to enter a user name, or to +enter a password. + +To avoid being prompted for the server host key when using Plink for +an automated connection, you should first make a \e{manual} +connection (using either of PuTTY or Plink) to the same server, +verify the host key (see \k{gs-hostkey} for more information), and +select Yes to add the host key to the Registry. After that, Plink +commands connecting to that server should not give a host key prompt +unless the host key changes. + To avoid being prompted for a user name, you can: \b Use the \c{-l} option to specify a user name on the command line. @@ -119,7 +168,7 @@ connecting to, and that also specifies the username to log in as (see \k{config-username}). To avoid being prompted for a password, you should almost certainly -set up public-key authentication. (See \k{pubkey} for a general +set up \i{public-key authentication}. (See \k{pubkey} for a general introduction to public-key authentication.) Again, you can do this in two ways: @@ -151,95 +200,35 @@ details: Then you can set up other programs to run this Plink command and talk to it as if it were a process on the server machine. -\S{plink-usage-options} Options - -This section describes the command line options that Plink accepts. - -\S2{plink-usage-options-v}\c{-v} show verbose messages - -By default, Plink only displays any password prompts and the output of -the remote command. The \c{-v} option makes it print extra -information about the connection being made, for example: - -\c Server version: SSH-1.5-OpenSSH-1.2.3 -\c We claim version: SSH-1.5-PuTTY -\c Using SSH protocol version 1 -\c Received public keys -\c Host key fingerprint is: -\c 1023 e3:65:44:44:bd:b1:04:59:bc:e2:3d:a1:4d:09:ce:99 -\c Encrypted session key -\c Using 3DES encryption -\c Trying to enable encryption... -\c Successfully started encryption -\c Sent username "fred". -\c Sent username "fred" -\c fred@example.com's password: - -This information can be useful for diagnosing problems. - -\S2{plink-usage-options-ssh} Protocol selection options - -Plink is most useful when using the SSH protocol. However, it allows -you to interface to all the protocols supported by PuTTY. You can -specify the option \c{-ssh} on the command line to select the SSH -protocol; you can also specify \c{-telnet}, \c{-rlogin} or \c{-raw} -to select other protocols. - -\S2{plink-usage-options-P}\c{-P port} connect to specified port +\S{plink-options} Plink command line options -If your server machine is running its SSH service on a port other -than the standard one, you can specify an alternative port number to -connect to using the \c{-P} option, like this: +Plink accepts all the general command line options supported by the +PuTTY tools. See \k{using-general-opts} for a description of these +options. -\c plink -ssh login.example.com -P 5022 +Plink also supports some of its own options. The following sections +describe Plink's specific command-line options. -\S2{plink-usage-options-pw}\c{-pw passw} login with specified password +\S2{plink-option-batch} \I{-batch-plink}\c{-batch}: disable all +interactive prompts -A simple way to automate a remote login is to supply your password -on the Plink command line. This is \e{not recommended} for reasons -of security. If you possibly can, we recommend you set up public-key -authentication instead. See \k{pubkey} for details. +If you use the \c{-batch} option, Plink will never give an +interactive prompt while establishing the connection. If the +server's host key is invalid, for example (see \k{gs-hostkey}), then +the connection will simply be abandoned instead of asking you what +to do next. -\S2{plink-usage-options-user}\c{-l username} login with specified -username +This may help Plink's behaviour when it is used in automated +scripts: using \c{-batch}, if something goes wrong at connection +time, the batch job will fail rather than hang. -As described in \k{plink-usage-batch}, you can specify the user name -to log in as on the remote server using the \c{-l} option. For -example, \c{plink login.example.com -l fred}. +\S2{plink-option-s} \I{-s-plink}\c{-s}: remote command is SSH subsystem -\S2{plink-usage-options-cmdfile} \c{-m filename} read command from a -file +If you specify the \c{-s} option, Plink passes the specified command +as the name of an SSH \q{\i{subsystem}} rather than an ordinary command +line. -If the command you want to run on the remote server is particularly -large, you can read it from a file using the \c{-m} option, instead -of putting it directly on Plink's command line. On most Unix -systems, you can even put multiple lines in this file and execute -more than one command in sequence, or a whole shell script. - -\S2{plink-usage-options-portfwd} \c{-L} and \c{-R} set up port -forwarding - -Plink allows you to use port forwarding just as PuTTY does; if you -have set up a PuTTY saved session that specifies port forwardings, -and you connect to that session using Plink, then the same port -forwardings will be set up. - -For convenience, Plink also offers the option to set up port -forwarding on the command line. The command-line options work just -like the ones in Unix \c{ssh} programs. - -To forward a local port (say 5110) to a remote destination (say -\cw{popserver.example.com} port 110), you can write: - -\c plink mysession -L 5110:popserver.example.com:110 - -And to forward a remote port to a local destination, just use the -\c{-R} option instead of \c{-L}: - -\c plink mysession -R 5023:mytelnetserver.myhouse.org:23 - -For general information on port forwarding, see -\k{using-port-forwarding}. +(This option is only meaningful with the SSH-2 protocol.) \H{plink-batch} Using Plink in \i{batch files} and \i{scripts} @@ -253,7 +242,7 @@ start a backup on a remote machine, you might use a command like: Or perhaps you want to fetch all system log lines relating to a particular web area: -\c plink mysession grep /~fjbloggs/ /var/log/httpd/access.log > fredlogs +\c plink mysession grep /~fred/ /var/log/httpd/access.log > fredlog Any non-interactive command you could usefully run on the server command line, you can run in a batch file using Plink in this way. @@ -261,7 +250,7 @@ command line, you can run in a batch file using Plink in this way. \H{plink-cvs} Using Plink with \i{CVS} To use Plink with CVS, you need to set the environment variable -\c{CVS_RSH} to point to Plink: +\i\c{CVS_RSH} to point to Plink: \c set CVS_RSH=\path\to\plink.exe @@ -295,6 +284,10 @@ a CVS command as in \k{plink-cvs}, for example: \c cvs -d :ext:user@hostname:/path/to/repository co module +or (if you're using a saved session): + +\c cvs -d :ext:user@sessionname:/path/to/repository co module + Select the folder you want to check out to with the \q{Change Folder} button, and click \q{OK} to check out your module. Once you've got modules checked out, WinCVS will happily invoke plink from the GUI for