Create the long-awaited console.c, and move the common routines out

[sgt/putty] / doc / plink.but

\versionid $Id: plink.but,v 1.13 2001/12/31 16:15:19 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 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}. 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.

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.

\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
version of Plink you're using, and gives you a brief summary of how to
use Plink:

\c Z:\sysosd>plink
\c PuTTY Link: command-line connection utility
\c Release 0.50
\c Usage: plink [options] [user@]host [command]
\c Options:
\c   -v        show verbose messages
\c   -ssh      force use of ssh protocol
\c   -P port   connect to specified port
\c   -pw passw login with specified password

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.

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:

\c plink -ssh login.example.com -P 5022

\S2{plink-usage-options-pw}\c{-pw passw} login with specified password

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-batch}\c{-batch} avoid 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-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{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 any interactive prompts, as described in
\k{plink-usage-batch}.

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 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

\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 non-interactively, as described in
\k{plink-usage-batch}.

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 \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 \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... ?