-\versionid $Id: plink.but,v 1.14 2002/02/04 13:29:04 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.
\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
\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.
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.
\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
\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.
(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:
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.
-You may also find it useful to use the \c{-batch} command-line
-option; see \k{plink-usage-options-batch}.
-
-\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
-
-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:
+\S{plink-options} Plink command line options
-\c plink -ssh login.example.com -P 5022
+Plink accepts all the general command line options supported by the
+PuTTY tools. See \k{using-general-opts} for a description of these
+options.
-\S2{plink-usage-options-pw}\c{-pw passw} login with specified password
+Plink also supports some of its own options. The following sections
+describe Plink's specific command-line options.
-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.
-
-Note that the \c{-pw} option only works when you are using the SSH
-protocol. Due to fundamental limitations of Telnet and Rlogin, these
-protocols do not support automated password authentication.
-
-\S2{plink-usage-options-user}\c{-l username} login with specified
-username
-
-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-usage-options-batch}\c{-batch} avoid interactive prompts
+\S2{plink-option-batch} \I{-batch-plink}\c{-batch}: disable all
+interactive prompts
If you use the \c{-batch} option, Plink will never give an
interactive prompt while establishing the connection. If the
scripts: using \c{-batch}, if something goes wrong at connection
time, the batch job will fail rather than hang.
-\S2{plink-usage-options-cmdfile} \c{-m filename} read command from a
-file
-
-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.
+\S2{plink-option-s} \I{-s-plink}\c{-s}: remote command is SSH subsystem
-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.
+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.
-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}
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.
\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
\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
~mdw / sgt / putty / blobdiff