Documentation: filled the last few gaps and cleaned a few things up.

PuTTY now has a complete manual. Stylistic review, content review
and indexing are yet to do, but at least there's some plausible text
in every section now.

[originally from svn r1460]

doc/config.but

@@ -1,4 +1,4 @@
-\versionid $Id: config.but,v 1.17 2001/12/06 13:28:02 simon Exp $
+\versionid $Id: config.but,v 1.18 2001/12/06 20:05:39 simon Exp $
 
 \C{config} Configuring PuTTY
 
@@ -31,10 +31,11 @@ rlogin connection or an SSH connection. (See \k{which-one} for a
 summary of the differences between SSH, Telnet and rlogin.)
 
 \b The \q{Port} box lets you specify which port number on the server
-to connect to. If you select Telnet, Rlogin, or SSH, this box will be
+to connect to. If you select Telnet, Rlogin, or SSH, this box will
-filled in automatically to the usual value, and you will only need to
+be filled in automatically to the usual value, and you will only
-change it if you have an unusual server. If you select Raw mode, you
+need to change it if you have an unusual server. If you select Raw
-will almost certainly need to fill in the \q{Port} box.
+mode (see \k{using-rawprot}), you will almost certainly need to fill
+in the \q{Port} box.
 
 \S{config-saving} Loading and storing saved sessions
 
@@ -207,8 +208,8 @@ could try turning this option off.
 Auto wrap mode can be turned on and off by control sequences sent by
 the server. This configuration option only controls the \e{default}
 state. If you modify this option in mid-session using \q{Change
-Settings}, you will need to reset the terminal \#{ FIXME } before
+Settings}, you will need to reset the terminal (see
-the change takes effect.
+\k{reset-terminal}) before the change takes effect.
 
 \S{config-decom} \q{DEC Origin Mode initially on}
 
@@ -233,11 +234,11 @@ a full-screen application is displaying pieces of text in what looks
 like the wrong part of the screen, you could try turning DEC Origin
 Mode on to see whether that helps.
 
-DEC Origin Mode can be turned on and off by control sequences sent by
+DEC Origin Mode can be turned on and off by control sequences sent
-the server. This configuration option only controls the \e{default}
+by the server. This configuration option only controls the
-state. If you modify this option in mid-session using \q{Change
+\e{default} state. If you modify this option in mid-session using
-Settings}, you will need to reset the terminal \#{ FIXME } before
+\q{Change Settings}, you will need to reset the terminal (see
-the change takes effect.
+\k{reset-terminal}) before the change takes effect.
 
 \S{config-crlf} \q{Implicit CR in every LF}
 
@@ -281,6 +282,12 @@ With this option disabled, screen clearing is always done in the
 default background colour. With this option enabled, it is done in
 the \e{current} background colour.
 
+Background-colour erase can be turned on and off by control
+sequences sent by the server. This configuration option only
+controls the \e{default} state. If you modify this option in
+mid-session using \q{Change Settings}, you will need to reset the
+terminal (see \k{reset-terminal}) before the change takes effect.
+
 \S{config-blink} \q{Enable blinking text}
 
 \cfg{winhelp-topic}{terminal.blink}
@@ -289,6 +296,16 @@ The server can ask PuTTY to display text that blinks on and off.
 This is very distracting, so PuTTY allows you to turn blinking text
 off completely.
 
+When blinking text is disabled and the server attempts to make some
+text blink, PuTTY will instead display the text with a bolded
+background colour.
+
+Blinking text can be turned on and off by control sequences sent by
+the server. This configuration option only controls the \e{default}
+state. If you modify this option in mid-session using \q{Change
+Settings}, you will need to reset the terminal (see
+\k{reset-terminal}) before the change takes effect.
+
 \S{config-answerback} \q{Answerback to ^E}
 
 \cfg{winhelp-topic}{terminal.answerback}
@@ -297,6 +314,14 @@ This option controls what PuTTY will send back to the server if the
 server sends it the ^E enquiry character. Normally it just sends
 the string \q{PuTTY}.
 
+If you accidentally write the contents of a binary file to your
+terminal, you will probably find that it contains more than one ^E
+character, and as a result your next command line will probably read
+\q{PuTTYPuTTYPuTTY...} as if you had typed the answerback string
+multiple times at the keyboard. If you set the answerback string to
+be empty, this problem should go away, but doing so might cause
+other problems.
+
 \S{config-localecho} \q{Local echo}
 
 \cfg{winhelp-topic}{terminal.localecho}
@@ -807,8 +832,12 @@ other windows.
 \cfg{winhelp-topic}{behaviour.altenter}
 
 If this option is enabled, then pressing Alt-Enter will cause the
-PuTTY window to become full-screen. (See \k{using-fullscreen}).
+PuTTY window to become full-screen. Pressing Alt-Enter again will
-Pressing Alt-Enter again will restore the previous window size.
+restore the previous window size.
+
+The full-screen feature is also available from the System menu, even
+when it is configured not to be available on the Alt-Enter key. See
+\k{using-fullscreen}.
 
 \H{config-translation} The Translation panel
 
@@ -1471,49 +1500,51 @@ If your server lets you run X Window System applications, X11
 forwarding allows you to securely give those applications access to
 a local X display on your PC.
 
-This feature will only be useful if you have an X server on your PC,
-such as Exceed or XWin32.
-
 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
 If your X display is not the primary display on your local machine
 (which it almost certainly will be unless you have deliberately
 arranged otherwise), you need to enter its location in the \q{X
 display location} box.
 
-\# FIXME: perhaps link to some more general X forwarding info?
+See \k{using-x-forwarding} for more information about X11
+forwarding.
 
 \S{config-ssh-portfwd} Port forwarding
 
 \cfg{winhelp-topic}{ssh.tunnels.portfwd}
 
 Port forwarding allows you to tunnel other types of network
-connection down an SSH connection.
+connection down an SSH session. See \k{using-port-forwarding} for a
+general discussion of port forwarding and how it works.
 
-To set up a local port forwarding, make sure the \q{Local} radio
+The port forwarding section in the Tunnels panel shows a list of all
-button is set. Then enter a local port number (on your PC) in the
+the port forwardings that PuTTY will try to set up when it connects
-\q{Source port} box, and a hostname and port number (separated by a
+to the server. By default no port forwardings are set up, so this
-colon) in the \q{Destination} box, and finally press the \q{Add}
+list is empty.
-button. For example, you might select a source port of 10079, and a
-destination of \c{server2.example.com:79}.
 
-If you do this, and then start the session, you should find that
+To add a port forwarding:
-connecting to your local PC on port 10079 gives you a connection to
-port 79 (the finger server) on \c{server2.example.com}. The
-connection is actually going to PuTTY itself, which encrypts the
-connection data and sends it down the secure channel to the SSH
-server. The connection then proceeds in clear from there to the
-eventual destination. So you might use this (for example) to forward
-a connection between two non-hostile network zones that are only
-connected by a hostile zone such as the open Internet.
 
-You can forward ports on the SSH server machine in the other
+\b Set one of the \q{Local} or \q{Remote} radio buttons, depending
-direction, too (so the connection will start at the server end and
+on whether you want to forward a local port to a remote destination
-be sent down the secure connection to PuTTY, which will make the
+(\q{Local}) or forward a remote port to a local destination
-real connection to the destination). To work this way round, just
+(\q{Remote}).
-click the \q{Remote} radio button instead of \q{Local}.
 
-\# FIXME: perhaps move this to a general port-forwarding section and
+\b Enter a source port number into the \q{Source port} box. For
-\# just link to it here?
+local forwardings, PuTTY will listen on this port of your PC. For
+remote forwardings, your SSH server will listen on this port of the
+remote machine. Note that most servers will not allow you to listen
+on port numbers less than 1024.
+
+\b Enter a hostname and port number separated by a colon, in the
+\q{Destination} box. Connections received on the source port will be
+directed to this destination. For example, to connect to a POP-3
+server, you might enter \c{popserver.example.com:110}.
+
+\b Click the \q{Add} button. Your forwarding details should appear
+in the list box.
+
+To remove a port forwarding, simply select its details in the list
+box, and click the \q{Remove} button.
 
 \H{config-file} Storing configuration in a file
 

doc/gs.but

@@ -1,4 +1,4 @@
-\versionid $Id: gs.but,v 1.5 2001/11/25 17:32:39 simon Exp $
+\versionid $Id: gs.but,v 1.6 2001/12/06 20:05:39 simon Exp $
 
 \C{gs} Getting started with PuTTY
 
@@ -40,9 +40,9 @@ possibly \q{Port} settings, you are ready to connect. Press the
 \q{Open} button at the bottom of the dialog box, and PuTTY will
 begin trying to connect you to the server.
 
-\H{gs-hostkey} Verifying the Host Key (SSH only)
+\H{gs-hostkey} Verifying the Host Key (SSH only)
 
-If you are not using the SSH protocol, you can skip this section.
+If you are not using the SSH protocol, you can skip this section.
 
 If you are using SSH to connect to a server for the first time, you
 will probably see a message looking something like this:
@@ -71,7 +71,7 @@ To prevent this attack, each server has a unique identifying code,
 called a \e{host key}. These keys are created in a way that prevents
 one server from forging another server's key. So if you connect to a
 server and it sends you a different host key from the one you were
-expecting, PuTTY can warn you that the server may have been switched
+expecting, PuTTY can warn you that the server may have been switched
 and that a spoofing attack might be in progress.
 
 PuTTY records the host key for each server you connect to, in the
@@ -82,7 +82,7 @@ and you will have the chance to abandon your connection before you
 type any private information (such as a password) into it.
 
 However, when you connect to a server you have not connected to
-before, PuTTY has no way of telling whether the host key is the
+before, PuTTY has no way of telling whether the host key is the
 right one or not. So it gives the warning shown above, and asks you
 whether you want to trust this host key or not.
 
@@ -94,7 +94,7 @@ If you are connecting across a hostile network (such as the
 Internet), you should check with your system administrator, perhaps
 by telephone or in person. (Some modern servers have more than one
 host key. If the system administrator sends you more than one
-fingerprint, you should make sure the one PuTTY shows you is on the
+fingerprint, you should make sure the one PuTTY shows you is on the
 list, but it doesn't matter which one it is.)
 
 \# FIXME: this is all very fine but of course in practice the world
@@ -113,7 +113,7 @@ right.
 
 If you are using SSH, be careful not to type your username wrongly,
 because you will not have a chance to correct it after you press
-Return. This is an unfortunate feature of the SSH protocol: it does
+Return. This is an unfortunate feature of the SSH protocol: it does
 not allow you to make two login attempts using different usernames.
 If you type your username wrongly, you must close PuTTY and start
 again.
@@ -139,9 +139,9 @@ When you have finished your session, you should log out by typing
 the server's own logout command. This might vary between servers; if
 in doubt, try \c{logout} or \c{exit}, or consult a manual or your
 system administrator. When the server processes your logout command,
-the PuTTY window should close itself automatically.
+the PuTTY window should close itself automatically.
 
-You \e{can} close a PuTTY session using the Close button in the
+You \e{can} close a PuTTY session using the Close button in the
 window border, but this might confuse the server - a bit like
 hanging up a telephone unexpectedly in the middle of a conversation.
 We recommend you do not do this unless the server has stopped

doc/plink.but

@@ -1,33 +1,40 @@
-\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
+UNIX \c{ssh}. It is mostly used for automated operations, such as
-an interactive session in a console window.
+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
+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
+double-click on its icon to run it and instead you have to bring up
-\i{console window}.  With Windows 95, 98, and ME, this is called an
+a \i{console window}. In Windows 95, 98, and ME, this is called an
-\q{MS-DOS Prompt} and with Windows NT and 2000 it is called a
+\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
+\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
+In order to use Plink, the file \c{plink.exe} will need either to be
-current directory.  To add the directory containing Plink to your
+on your \i{\c{PATH}} or in your current directory. To add the
-\c{PATH} environment variable, type into the console window:
+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
@@ -44,11 +51,109 @@ use Plink:
 \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
 
@@ -72,16 +177,87 @@ information about the connection being made, for example:
 
 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
@@ -90,45 +266,29 @@ 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
+You should then be able to run CVS as follows:
-\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:
+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}
+able to connect to a remote host non-interactively, as described in
-has instructions on this.
+\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
+labelled \q{Check for an alternate \cw{rsh} name} and in the text
-field to the right enter the full path to \c{plink.exe}.  Select
+entry field to the right enter the full path to \c{plink.exe}.
-\q{OK} on the \q{Preferences} dialogue box.
+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:
@@ -140,5 +300,4 @@ 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... ?
-

doc/pubkey.but

@@ -1,4 +1,4 @@
-\versionid $Id: pubkey.but,v 1.10 2001/11/25 17:32:39 simon Exp $
+\versionid $Id: pubkey.but,v 1.11 2001/12/06 20:05:39 simon Exp $
 
 \# FIXME: passphrases, examples (e.g what does a key for pasting into
 \# authorized_keys look like?), index entries, links.
@@ -22,13 +22,13 @@ Public key authentication solves this problem. You generate a \e{key
 pair}, consisting of a public key (which everybody is allowed to
 know) and a private key (which you keep secret and do not give to
 anybody). The private key is able to generate \e{signatures}.
-A signature created using your private key cannot be forged by
+A signature created using your private key cannot be forged by
 anybody who does not have that key; but anybody who has your public
 key can verify that a particular signature is genuine.
 
 So you generate a key pair on your own computer, and you copy the
 public key to the server. Then, when the server asks you to prove
-who you are, PuTTY can generate a signature using your private key.
+who you are, PuTTY can generate a signature using your private key.
 The server can verify that signature (since it has your public key)
 and allow you to log in. Now if the server is hacked or spoofed, the
 attacker does not gain your private key or password; they only gain
@@ -52,7 +52,7 @@ agent}, a separate program which holds decrypted private keys and
 generates signatures on request. PuTTY's authentication agent is
 called Pageant. When you begin a Windows session, you start Pageant
 and load your public key into it (typing your passphrase once). For
-the rest of your session, you can start PuTTY any number of times
+the rest of your session, you can start PuTTY any number of times
 and Pageant will automatically generate signatures without you
 having to do anything. When you close your Windows session, Pageant
 shuts down, without ever having stored your decrypted private key on

doc/using.but

@@ -1,4 +1,4 @@
-\versionid $Id: using.but,v 1.2 2001/11/25 19:22:47 simon Exp $
+\versionid $Id: using.but,v 1.3 2001/12/06 20:05:39 simon Exp $
 
 \C{using} Using PuTTY
 
@@ -198,12 +198,122 @@ If you click \q{Change Settings} and look at the \q{Translation}
 panel, you should see a large number of character sets which you can
 select. Now all you need is to find out which of them you want!
 
-\H{using-forwarding} Port forwarding and X forwarding in SSH
+\H{using-x-forwarding} Using X11 forwarding in SSH
 
-\# using X forwarding
+The SSH protocol has the ability to securely forward X Window System
+applications over your encrypted SSH connection, so that you can run
+an application on the SSH server machine and have it put its windows
+up on your local machine without sending any X network traffic in
+the clear.
 
-\# using port forwarding
+In order to use this feature, you will need an X display server for
+your Windows machine, such as X-Win32 or Exceed. This will probably
+install itself as display number 0 on your local machine; if it
+doesn't, the manual for the X server should tell you what it does
+do.
+
+You should then tick the \q{Enable X11 forwarding} box in the
+Tunnels panel (see \k{config-ssh-x11}) before starting your SSH
+session. The \q{X display location} box reads \c{localhost:0} by
+default, which is the usual display location where your X server
+will be installed. If that needs changing, then change it.
+
+Now you should be able to log in to the SSH server as normal. To
+check that X forwarding has been successfully negotiated during
+connection startup, you can check the PuTTY Event Log (see
+\k{using-eventlog}). It should say something like this:
+
+\c 2001-12-05 17:22:01 Requesting X11 forwarding
+\c 2001-12-05 17:22:02 X11 forwarding enabled
+
+If the remote system is Unix or Unix-like, you should also be able
+to see that the \c{DISPLAY} environment variable has been set to
+point at display 10 or above on the SSH server machine itself:
+
+\c fred@unixbox:~$ echo $DISPLAY
+\c unixbox:10.0
+
+If this works, you should then be able to run X applications in the
+remote session and have them display their windows on your PC.
+
+Note that if your PC X server requires authentication to connect,
+then PuTTY cannot currently support it. If this is a problem for
+you, you should mail the authors \#{FIXME} and give details.
+
+\H{using-port-forwarding} Using port forwarding in SSH
+
+The SSH protocol has the ability to forward arbitrary network
+connections over your encrypted SSH connection, to avoid the network
+traffic being sent in clear. For example, you could use this to
+connect from your home computer to a POP-3 server on a remote
+machine without your POP-3 password being visible to network
+sniffers.
+
+In order to use port forwarding to connect from your local machine
+to a port on a remote server, you need to:
+
+\b Choose a port number on your local machine where PuTTY should
+listen for incoming connections. There are likely to be plenty of
+unused port numbers above 3000.
+
+\b Now, before you start your SSH connection, go to the Tunnels
+panel (see \k{config-ssh-portfwd}). Make sure the \q{Local} radio
+button is set. Enter the local port number into the \q{Source port}
+box. Enter the destination host name and port number into the
+\q{Destination} box, separated by a colon (for example,
+\c{popserver.example.com:110} to connect to a POP-3 server).
+
+\b Now click the \q{Add} button. The details of your port forwarding
+should appear in the list box.
+
+Now start your session. To check that PuTTY has set up the port
+forwarding correctly, you can look at the PuTTY Event Log (see
+\k{using-eventlog}). It should say something like this:
+
+\c 2001-12-05 17:22:10 Local port 3110 forwarding to
+\c          popserver.example.com:110
+
+Now if you connect to the source port number on your local PC, you
+should find that it answers you exactly as if it were the service
+running on the destination machine. So in this example, you could
+then configure an e-mail client to use \c{localhost:3110} as a POP-3
+server instead of \c{popserver.example.com:110}. (Of course, the
+forwarding will stop happening when your PuTTY session closes down.)
+
+You can also forward ports in the other direction: arrange for a
+particular port number on the \e{server} machine to be forwarded
+back to your PC as a connection to a service on your PC or near it.
+To do this, just select the \q{Remote} radio button instead of the
+\q{Local} one. The \q{Source port} box will now specify a port
+number on the \e{server} (note that most servers will not allow you
+to use port numbers under 1024 for this purpose).
 
 \H{using-rawprot} Making raw TCP connections
 
-\# Raw protocol
+A lot of Internet protocols are composed of commands and responses
+in plain text. For example, SMTP (the protocol used to transfer
+e-mail), NNTP (the protocol used to transfer Usenet news), and HTTP
+(the protocol used to serve Web pages) all consist of commands in
+readable plain text.
+
+Sometimes it can be useful to connect directly to one of these
+services and speak the protocol \q{by hand}, by typing protocol
+commands and watching the responses. On Unix machines, you can do
+this using the system's \c{telnet} command to connect to the right
+port number. For example, \c{telnet mailserver.example.com 25} might
+enable you to talk directly to the SMTP service running on a mail
+server.
+
+Although the Unix \c{telnet} program provides this functionality,
+the protocol being used is not really Telnet. Really there is no
+actual protocol at all; the bytes sent down the connection are
+exactly the ones you type, and the bytes shown on the screen are
+exactly the ones sent by the server. Unix \c{telnet} will attempt to
+detect or guess whether the service it is talking to is a real
+Telnet service or not; PuTTY prefers to be told for certain.
+
+In order to make a debugging connection to a service of this type,
+you simply select the fourth protocol name, \q{Raw}, from the
+\q{Protocol} buttons in the \q{Session} configuration panel. (See
+\k{config-hostname}.) You can then enter a host name and a port
+number, and make the connection.