nhyatt/putty-source
1
0
Fork 0
mirror of https://git.tartarus.org/simon/putty.git synced 2025-05-28 15:24:49 -05:00
Code Issues Projects Releases Wiki Activity

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

Browse Source 
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]
This commit is contained in:
Simon Tatham 2001-12-06 20:05:39 +00:00
parent bf6cfd2b01
commit fc2a4f845d
5 changed files with 405 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
doc/config.but
View File

@ -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
filled in automatically to the usual value, and you will only need to
change it if you have an unusual server. If you select Raw mode, you
will almost certainly need to fill in the \q{Port} box.
to connect to. If you select Telnet, Rlogin, or SSH, this box will
be filled in automatically to the usual value, and you will only
need to change it if you have an unusual server. If you select Raw
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
the change takes effect.
Settings}, you will need to reset the terminal (see
\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
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
the change takes effect.
DEC Origin 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 (see
\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}).
Pressing Alt-Enter again will restore the previous window size.
PuTTY window to become full-screen. Pressing Alt-Enter again will
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
button is set. Then enter a local port number (on your PC) in the
\q{Source port} box, and a hostname and port number (separated by a
colon) in the \q{Destination} box, and finally press the \q{Add}
button. For example, you might select a source port of 10079, and a
destination of \c{server2.example.com:79}.
The port forwarding section in the Tunnels panel shows a list of all
the port forwardings that PuTTY will try to set up when it connects
to the server. By default no port forwardings are set up, so this
list is empty.
If you do this, and then start the session, you should find that
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.
To add a port forwarding:
You can forward ports on the SSH server machine in the other
direction, too (so the connection will start at the server end and
be sent down the secure connection to PuTTY, which will make the
real connection to the destination). To work this way round, just
click the \q{Remote} radio button instead of \q{Local}.
\b Set one of the \q{Local} or \q{Remote} radio buttons, depending
on whether you want to forward a local port to a remote destination
(\q{Local}) or forward a remote port to a local destination
(\q{Remote}).
\# FIXME: perhaps move this to a general port-forwarding section and
\# just link to it here?
\b Enter a source port number into the \q{Source port} box. For
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

18
doc/gs.but
View File

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

251
doc/plink.but
View File

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

8
doc/pubkey.but
View File

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

120
doc/using.but
View File

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