-\versionid $Id: plink.but,v 1.6 2001/06/28 13:36:14 owen Exp $
+\define{versionidplink} \versionid $Id$
-\C{plink} Using the command-line connection tool Plink
+\C{plink} Using the command-line connection tool \i{Plink}
-\# Explain Plink
+\i{Plink} (PuTTY Link) is a command-line connection tool similar to
+UNIX \c{ssh}. It is mostly used for \i{automated operations}, such as
+making CVS access a repository on a remote server.
-\# Explain that Plink is probably not what you want if you want to
-\# run an interactive session in a Command Prompt window
-
-\# Explain that Plink is really for batch-file use, and that
-\# therefore it works best with public-key authentication; link to
-\# that chapter
-
-\# Give instructions on how to set up Plink with CVS
-
-\i{Plink} (PuTTY Link), is a command-line connection tool similar to
-UNIX \c{ssh}. It is probably not what you want if you want to run an
-interactive session in a console window.
+Plink is probably not what you want if you want to run an
+\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}. With Windows 95, 98, and ME, this is called an
-\q{MS-DOS Prompt} and with Windows NT and 2000 it is called a
-\q{Command Prompt}. It should be available from the Programs section
+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, 2000, and XP, it is called a
+\q{Command Prompt}. It should be available from the Programs section
of your Start Menu.
-To start Plink it will need either to be on your \i{\c{PATH}} or in your
-current directory. To add the directory containing Plink to your
-\c{PATH} environment variable, type into the console window:
+In order to use Plink, the file \c{plink.exe} will need either to be
+on your \i{\c{PATH}} or in your current directory. To add the
+directory containing Plink to your \c{PATH} environment variable,
+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} Plink Usage
+\H{plink-usage} Using Plink
+
+This section describes the basics of how to use Plink for
+interactive logins and for automated processes.
Once you've got a console window to type into, you can just type
\c{plink} on its own to bring up a usage message. This tells you the
\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.
+
+\S{plink-usage-interactive} Using Plink for interactive logins
+
+To make a simple interactive connection to a remote server, just
+type \c{plink} and then the host name:
+
+\c Z:\sysosd>plink login.example.com
+\c
+\c Debian GNU/Linux 2.2 flunky.example.com
+\c flunky login:
+
+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 \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.
+
+In order to connect with a different protocol, you can give the
+command line options \c{-ssh}, \c{-telnet}, \c{-rlogin} or \c{-raw}.
+To make an SSH connection, for example:
+
+\c Z:\sysosd>plink -ssh login.example.com
+\c login as:
+
+If you have already set up a PuTTY saved session, then instead of
+supplying a host name, you can give the saved session name. This
+allows you to use public-key authentication, specify a user name,
+and use most of the other features of PuTTY:
+
+\c Z:\sysosd>plink my-ssh-session
+\c Sent username "fred"
+\c Authenticating with public key "fred@winbox"
+\c Last login: Thu Dec 6 19:25:33 2001 from :0.0
+\c fred@flunky:~$
-\S{plink-usage-basics} The basics
+(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-options} Options
+\S{plink-usage-batch} Using Plink for automated connections
-These are the command line options that Plink accepts.
+More typically Plink is used with the SSH protocol, to enable you to
+talk directly to a program running on the server. To do this you
+have to ensure Plink is \e{using} the SSH protocol. You can do this
+in several ways:
-\S2{plink-usage-options-v}\c{-v} show verbose messages
+\b Use the \c{-ssh} option as described in
+\k{plink-usage-interactive}.
-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:
+\b Set up a PuTTY saved session that describes the server you are
+connecting to, and that also specifies the protocol as SSH.
-\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:
+\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.
+For example, \c{plink login.example.com -l fred}.
+
+\b Set up a PuTTY saved session that describes the server you are
+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 \i{public-key authentication}. (See \k{pubkey} for a general
+introduction to public-key authentication.) Again, you can do this
+in two ways:
+
+\b Set up a PuTTY saved session that describes the server you are
+connecting to, and that also specifies a private key file (see
+\k{config-ssh-privkey}). For this to work without prompting, your
+private key will need to have no passphrase.
+
+\b Store the private key in Pageant. See \k{pageant} for further
+information.
+
+Once you have done all this, you should be able to run a remote
+command on the SSH server machine and have it execute automatically
+with no prompting:
+
+\c Z:\sysosd>plink login.example.com -l fred echo hello, world
+\c hello, world
+\c
+\c Z:\sysosd>
+
+Or, if you have set up a saved session with all the connection
+details:
+
+\c Z:\sysosd>plink mysession echo hello, world
+\c hello, world
+\c
+\c Z:\sysosd>
-This information can be useful for diagnosing problems.
+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.
-\S2{plink-usage-options-ssh}\c{-ssh} force use of ssh protocol
+\S{plink-options} Plink command line options
-\S2{plink-usage-options-P}\c{-P port} connect to specified port
+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.
-\H{plink-pubkey} Using public key authentication with Plink
+\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
+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.
+
+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.
+
+\S2{plink-option-s} \I{-s-plink}\c{-s}: remote command is SSH subsystem
+
+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.
+
+(This option is only meaningful with the SSH-2 protocol.)
\H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
+Once you have set up Plink to be able to log in to a remote server
+without any interactive prompting (see \k{plink-usage-batch}), you
+can use it for lots of scripting and batch purposes. For example, to
+start a backup on a remote machine, you might use a command like:
+
+\c plink root@myserver /etc/backups/do-backup.sh
+
+Or perhaps you want to fetch all system log lines relating to a
+particular web area:
+
+\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
You also need to arrange to be able to connect to a remote host
-without a password. To do this, either:
+without any interactive prompts, as described in
+\k{plink-usage-batch}.
-\b Run PuTTY, and create a PuTTY saved session (see \k{config-saving})
-with the protocol set to SSH (see \k{config-hostname}) and specifies
-your private key file (see \k{config-auth}). You will probably also
-want to specify a username to log in as (see \k{config-username}).
You should then be able to run CVS as follows:
\c cvs -d :ext:user@sessionname:/path/to/repository co module
-If you specified a username in your saved session, you can just say:
+If you specified a username in your saved session, you don't even
+need to specify the \q{user} part of this, and you can just say:
\c cvs -d :ext:sessionname:/path/to/repository co module
-Alternatively, you can use Pageant if Pageant is running (see
-\k{pageant}). To do this, you would:
-
-\b Ensure Pageant is running, and has your private key stored in it.
-
-\b Run CVS as follows:
-
-\c cvs -d :ext:user@hostname:/path/to/repository co module
-
\H{plink-wincvs} Using Plink with \i{WinCVS}
Plink can also be used with WinCVS. Firstly, arrange for Plink to be
-able to connect to a remote host without a password. \k{plink-cvs}
-has instructions on this.
+able to connect to a remote host non-interactively, as described in
+\k{plink-usage-batch}.
-In WinCVS, bring up the \e{Preferences} dialogue box from the
-\e{Admin} menu, and switch to the \e{Ports} tab. Tick the box there
-labelled \e{Check for an alternate rsh name} and in the text entry
-field to the right enter the full path to \c{plink.exe}. Select
-\e{OK} on the \e{Preferences} dialogue box.
+Then, in WinCVS, bring up the \q{Preferences} dialogue box from the
+\e{Admin} menu, and switch to the \q{Ports} tab. Tick the box there
+labelled \q{Check for an alternate \cw{rsh} name} and in the text
+entry field to the right enter the full path to \c{plink.exe}.
+Select \q{OK} on the \q{Preferences} dialogue box.
-Next, select \e{Command Line} from the WinCVS \e{Admin} menu, and type
+Next, select \q{Command Line} from the WinCVS \q{Admin} menu, and type
a CVS command as in \k{plink-cvs}, for example:
\c cvs -d :ext:user@hostname:/path/to/repository co module
-Select the folder you want to check out to with the \e{Change Folder}
-button, and click \e{OK} to check out your module. Once you've got
+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
CVS operations.
-\H{plink-whatelse} Using Plink with... ?
-
+\# \H{plink-whatelse} Using Plink with... ?
~mdw / sgt / putty / blobdiff