-\versionid $Id: plink.but,v 1.11 2001/11/25 17:32:39 simon Exp $
+\versionid $Id: plink.but,v 1.12 2001/12/06 20:05:39 simon Exp $
\C{plink} Using the command-line connection tool Plink
\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.
+UNIX \c{ssh}. It is mostly used for 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.
\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 and 2000 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
+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.
-\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 -P port connect to specified port
\c -pw passw login with specified password
-\S{plink-usage-basics} The basics
+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 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-batch} Using Plink for automated connections
+
+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:
+
+\b Use the \c{-ssh} option as described in
+\k{plink-usage-interactive}.
+
+\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
+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.
+
+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 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>
+
+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
-These are the command line options that Plink accepts.
+This section describes the command line options that Plink accepts.
\S2{plink-usage-options-v}\c{-v} show verbose messages
This information can be useful for diagnosing problems.
-\S2{plink-usage-options-ssh}\c{-ssh} force use of ssh protocol
+\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:
+
+\c plink -ssh login.example.com -P 5022
+
\S2{plink-usage-options-pw}\c{-pw passw} login with specified password
-\H{plink-pubkey} Using public key authentication with Plink
+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.
+
+\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-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.
+
+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}.
\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 /~fjbloggs/ /var/log/httpd/access.log > fredlogs
+
+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 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-ssh-privkey}). 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:
+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 Set the environment variable \cw{PLINK_PROTOCOL} to the string
-\c{ssh}, to make sure Plink will try to connect using SSH instead of
-Telnet.
-
-\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 \q{Preferences} dialogue box from the
+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 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.
+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 \q{Command Line} from the WinCVS \q{Admin} menu, and type
a CVS command as in \k{plink-cvs}, for example:
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... ?
projects / u / mdw / putty / blobdiff