Bump version number prior to tagging 0.63.

[sgt/putty] / doc / plink.but

diff --git a/doc/plink.but b/doc/plink.but
index a1ef625..197489e 100644 (file)
--- a/doc/plink.but
+++ b/doc/plink.but
@@ -1,20 +1,20 @@
-\versionid $Id: plink.but,v 1.13 2001/12/31 16:15:19 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
 
 \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
 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
 
 \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.
 
 \q{Command Prompt}. It should be available from the Programs section
 of your Start Menu.
 


@@ -26,10 +26,10 @@ 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
 \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
 
 
 \H{plink-usage} Using Plink
 


@@ -43,13 +43,43 @@ use Plink:
 
 \c Z:\sysosd>plink
 \c PuTTY Link: command-line connection utility
 
 \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 Usage: plink [options] [user@]host [command]

+\c        ("host" can also be a PuTTY saved session name)

 \c Options:
 \c Options:

+\c   -V        print version information and exit
+\c   -pgpfp    print PGP key fingerprints and exit

 \c   -v        show verbose messages
 \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   -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   -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.
 
 
 Once this works, you are ready to use Plink.
 


@@ -65,8 +95,8 @@ type \c{plink} and then the host name:
 
 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
 
 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.
 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.


@@ -89,6 +119,12 @@ and use most of the other features of PuTTY:
 \c Last login: Thu Dec  6 19:25:33 2001 from :0.0
 \c fred@flunky:~$
 
 \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
 \S{plink-usage-batch} Using Plink for automated connections
 
 More typically Plink is used with the SSH protocol, to enable you to


@@ -102,13 +138,26 @@ in several ways:
 \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 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.
 
 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.
 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.


@@ -119,7 +168,7 @@ 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
 (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:
 
 introduction to public-key authentication.) Again, you can do this
 in two ways:
 


@@ -151,66 +200,17 @@ details:
 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.
 
 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.
-
-\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
 
 If you use the \c{-batch} option, Plink will never give an
 interactive prompt while establishing the connection. If the


@@ -222,39 +222,13 @@ 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.
 
 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.
+\S2{plink-option-s} \I{-s-plink}\c{-s}: remote command is SSH subsystem

 
 

-To forward a local port (say 5110) to a remote destination (say
-\cw{popserver.example.com} port 110), you can write:
+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.

 
 

-\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}
 
 
 \H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
 


@@ -268,7 +242,7 @@ start a backup on a remote machine, you might use a command like:
 Or perhaps you want to fetch all system log lines relating to a
 particular web area:
 
 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.
 
 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.


@@ -276,7 +250,7 @@ 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
 \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 set CVS_RSH=\path\to\plink.exe
 


@@ -310,6 +284,10 @@ a CVS command as in \k{plink-cvs}, for example:
 
 \c cvs -d :ext:user@hostname:/path/to/repository co module
 
 
 \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
 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