using.but

putty

To begin a session log, select \q{Change Settings} from the system
menu and go to the Logging panel. Enter a log file name, and select
a logging mode. (You can log all session output including the
terminal \i{control sequence}s, or you can just log the printable text.
It depends what you want the log for.) Click \q{Apply} and your log
will be started. Later on, you can go back to the Logging panel and
select \q{Logging turned off completely} to stop logging; then PuTTY
will close the log file and you can safely read it.

See \k{config-logging} for more details and options.

\H{using-translation} Altering your \i{character set} configuration

If you find that special characters (\i{accented characters}, for
example, or \i{line-drawing characters}) are not being displayed
correctly in your PuTTY session, it may be that PuTTY is interpreting
the characters sent by the server according to the wrong \e{character
set}. There are a lot of different character sets available, so it's
entirely possible for this to happen.

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, and other related options. Now all you need is to find out
which of them you want! (See \k{config-translation} for more
information.)

\H{using-x-forwarding} Using \i{X11 forwarding} in SSH

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.

In order to use this feature, you will need an X display server for
your Windows machine, such as Cygwin/X, 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 \i{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 \i{\q{X display location}} box is blank by default, which
means that PuTTY will try to use a sensible default such as \c{:0},
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 \i{\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 \I{X11 authentication}authentication
to connect, then PuTTY cannot currently support it. If this is a problem for
you, you should mail the PuTTY authors \#{FIXME} and give details
(see \k{feedback}).

For more options relating to X11 forwarding, see \k{config-ssh-x11}.

\H{using-port-forwarding} Using \i{port forwarding} in SSH

The SSH protocol has the ability to forward arbitrary \i{network
connection}s 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 \i{POP-3} server on a remote
machine without your POP-3 password being visible to network
sniffers.

In order to use port forwarding to \I{local port forwarding}connect
from your local machine to a port on a remote server, you need to:

\b Choose a \i{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. (You can also use a local loopback
address here; see below for more details.)

\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 and log in. (Port forwarding will not be
enabled until after you have logged in; otherwise it would be easy
to perform completely anonymous network attacks, and gain access to
anyone's virtual private network.) 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 \I{remote
port forwarding}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 \I{privileged port}port numbers under 1024 for this purpose).

An alternative way to forward local connections to remote hosts is
to use \I{dynamic port forwarding}dynamic SOCKS proxying. For
this, you will need to select the \q{Dynamic} radio button instead
of \q{Local}, and then you should not enter anything into the
\q{Destination} box (it will be ignored). This will cause PuTTY to
listen on the port you have specified, and provide a SOCKS proxy
service to any programs which connect to that port. So, in
particular, you can forward other PuTTY connections through it by
setting up the Proxy control panel (see \k{config-proxy} for
details).

The source port for a forwarded connection usually does not accept
connections from any machine except the \I{localhost}SSH client or
server machine itself (for local and remote forwardings respectively).
There are controls in the Tunnels panel to change this:

\b The \q{Local ports accept connections from other hosts} option
allows you to set up local-to-remote port forwardings (including
dynamic port forwardings) in such a way that machines other than
your client PC can connect to the forwarded port.

\b The \q{Remote ports do the same} option does the same thing for
remote-to-local port forwardings (so that machines other than the
SSH server machine can connect to the forwarded port.) Note that
this feature is only available in the SSH-2 protocol, and not all
SSH-2 servers honour it (in \i{OpenSSH}, for example, it's usually
disabled by default).

You can also specify an \i{IP address} to \I{listen address}listen
on. Typically a Windows machine can be asked to listen on any single
IP address in the \cw{127.*.*.*} range, and all of these are
\i{loopback address}es available only to the local machine. So if
you forward (for example) \c{127.0.0.5:79} to a remote machine's
\i\cw{finger} port, then you should be able to run commands such as
\c{finger fred@127.0.0.5}.
This can be useful if the program connecting to the forwarded port
doesn't allow you to change the port number it uses. This feature is
available for local-to-remote forwarded ports; SSH-1 is unable to
support it for remote-to-local ports, while SSH-2 can support it in
theory but servers will not necessarily cooperate.

(Note that if you're using Windows XP Service Pack 2, you may need
to obtain a fix from Microsoft in order to use addresses like
\cw{127.0.0.5} - see \k{faq-alternate-localhost}.)

\H{using-rawprot} Making \i{raw TCP connections}

A lot of \I{debugging Internet protocols}Internet protocols are
composed of commands and responses in plain text. For example,
\i{SMTP} (the protocol used to transfer e-mail), \i{NNTP} (the
protocol used to transfer Usenet news), and \i{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, \I{\q{Raw}
protocol}\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.

\H{using-serial} Connecting to a local serial line

PuTTY can connect directly to a local serial line as an alternative
to making a network connection. In this mode, text typed into the
PuTTY window will be sent straight out of your computer's serial
port, and data received through that port will be displayed in the
PuTTY window. You might use this mode, for example, if your serial
port is connected to another computer which has a serial connection.

To make a connection of this type, simply select \q{Serial} from the
\q{Connection type} radio buttons on the \q{Session} configuration
panel (see \k{config-hostname}). The \q{Host Name} and \q{Port}
boxes will transform into \q{Serial line} and \q{Speed}, allowing
you to specify which serial line to use (if your computer has more
than one) and what speed (baud rate) to use when transferring data.
For further configuration options (data bits, stop bits, parity,
flow control), you can use the \q{Serial} configuration panel (see
\k{config-serial}).

After you start up PuTTY in serial mode, you might find that you
have to make the first move, by sending some data out of the serial
line in order to notify the device at the other end that someone is
there for it to talk to. This probably depends on the device. If you
start up a PuTTY serial session and nothing appears in the window,
try pressing Return a few times and see if that helps.

A serial line provides no well defined means for one end of the
connection to notify the other that the connection is finished.
Therefore, PuTTY in serial mode will remain connected until you
close the window using the close button.

\H{using-cmdline} The PuTTY command line

PuTTY can be made to do various things without user intervention by
supplying \i{command-line arguments} (e.g., from a \i{command prompt
window}, or a \i{Windows shortcut}).

\S{using-cmdline-session} Starting a session from the command line

\I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}These options allow
you to bypass the configuration window and launch straight into a
session.

To start a connection to a server called \c{host}:

\c putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host

If this syntax is used, settings are taken from the \i{Default Settings}
(see \k{config-saving}); \c{user} overrides these settings if
supplied. Also, you can specify a protocol, which will override the
default protocol (see \k{using-cmdline-protocol}).

For telnet sessions, the following alternative syntax is supported
(this makes PuTTY suitable for use as a URL handler for \i{telnet
URLs} in web browsers):

\c putty.exe telnet://host[:port]/

In order to start an existing saved session called \c{sessionname},
use the \c{-load} option (described in \k{using-cmdline-load}).

\c putty.exe -load "session name"

\S{using-cleanup} \i\c{-cleanup}

\cfg{winhelp-topic}{options.cleanup}

If invoked with the \c{-cleanup} option, rather than running as
normal, PuTTY will remove its \I{removing registry entries}registry
entries and \i{random seed file} from the local machine (after
confirming with the user).

Note that on \i{multi-user systems}, \c{-cleanup} only removes
registry entries and files associated with the currently logged-in
user.

\S{using-general-opts} Standard command-line options

PuTTY and its associated tools support a range of command-line
options, most of which are consistent across all the tools. This
section lists the available options in all tools. Options which are
specific to a particular tool are covered in the chapter about that
tool.

\S2{using-cmdline-load} \i\c{-load}: load a saved session

\I{saved sessions, loading from command line}The \c{-load} option
causes PuTTY to load configuration details out of a saved session.
If these details include a host name, then this option is all you
need to make PuTTY start a session.

You need double quotes around the session name if it contains spaces.

If you want to create a \i{Windows shortcut} to start a PuTTY saved
session, this is the option you should use: your shortcut should
call something like

\c d:\path\to\putty.exe -load "my session"