\versionid $Id: plink.but,v 1.9 2001/09/22 17:34:10 simon Exp $

\C{plink} Using the command-line connection tool Plink

\# Explain Plink

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

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

\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} Plink Usage

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

\S{plink-usage-basics} The basics

\S{plink-usage-options} Options

These are 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}\c{-ssh} force use of ssh protocol

\S2{plink-usage-options-P}\c{-P port} connect to specified port

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

\H{plink-pubkey} Using public key authentication with Plink

\H{plink-batch} Using Plink in \i{batch files} and \i{scripts}

\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 a password.  To do this, either:

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

\c cvs -d :ext:user@sessionname:/path/to/repository co module

If you specified a username in your saved session, 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.

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.

Next, select \e{Command Line} from the WinCVS \e{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
modules checked out, WinCVS will happily invoke plink from the GUI for
CVS operations.

\H{plink-whatelse} Using Plink with... ?