Mention the mirroring guidelines on the web.

[u/mdw/putty] / doc / using.but

\versionid $Id: using.but,v 1.27 2004/08/12 20:55:58 jacob Exp $

\C{using} Using PuTTY

This chapter provides a general introduction to some more advanced
features of PuTTY. For extreme detail and reference purposes,
\k{config} is likely to contain more information.

\H{using-session} During your session

A lot of PuTTY's complexity and features are in the configuration
panel. Once you have worked your way through that and started
a session, things should be reasonably simple after that.
Nevertheless, there are a few more useful features available.

\S{using-selection} Copying and pasting text

\I{copy and paste}Often in a PuTTY session you will find text on
your terminal screen which you want to type in again. Like most
other terminal emulators, PuTTY allows you to copy and paste the
text rather than having to type it again. Also, copy and paste uses
the \I{Windows clipboard}Windows \i{clipboard}, so that you can
paste (for example) URLs into a web browser, or paste from a word
processor or spreadsheet into your terminal session.

PuTTY's copy and paste works entirely with the \i{mouse}. In order
to copy text to the clipboard, you just click the \i{left mouse
button} in the terminal window, and drag to \I{selecting text}select
text. When you let go of the button, the text is \e{automatically}
copied to the clipboard. You do not need to press Ctrl-C or
Ctrl-Ins; in fact, if you do press Ctrl-C, PuTTY will send a Ctrl-C
character down your session to the server where it will probably
cause a process to be interrupted.

Pasting is done using the right button (or the middle mouse button,
if you have a three-button mouse and have set it up; see
\k{config-mouse}). (Pressing \i{Shift-Ins}, or selecting \q{Paste}
from the Ctrl+right-click context menu, have the same effect.) When
you click the \i{right mouse button}, PuTTY will read whatever is in
the Windows clipboard and paste it into your session, \e{exactly} as
if it had been typed at the keyboard. (Therefore, be careful of
pasting formatted text into an editor that does automatic indenting;
you may find that the spaces pasted from the clipboard plus the
spaces added by the editor add up to too many spaces and ruin the
formatting. There is nothing PuTTY can do about this.)

If you \i{double-click} the left mouse button, PuTTY will select a
whole word. If you double-click, hold down the second click, and
drag the mouse, PuTTY will select a sequence of whole words. (You
can adjust precisely what PuTTY considers to be part of a word; see
\k{config-charclasses}.) If you \e{triple}-click, or
\i{triple-click} and drag, then PuTTY will select a whole line or
sequence of lines.

If you want to select a \I{rectangular selection}rectangular region
instead of selecting to the end of each line, you can do this by
holding down Alt when you make your selection. (You can also
configure rectangular selection to be the default, and then holding
down Alt gives the normal behaviour instead. See
\k{config-rectselect} for details.)

If you have a \i{middle mouse button}, then you can use it to
\I{adjusting a selection}adjust an existing selection if you
selected something slightly wrong. (If you have configured the
middle mouse button to paste, then the right mouse button does this
instead.) Click the button on the screen, and you can pick up the
nearest end of the selection and drag it to somewhere else.

It's possible for the server to ask to handle mouse clicks in the
PuTTY window itself.  If this happens, the mouse cursor will turn
into an arrow, and using the mouse to copy and paste will only work if
you hold down Shift.  See \k{config-features-mouse} and
\k{config-mouseshift} for details of this feature and how to configure
it.

\S{using-scrollback} \I{scrollback}Scrolling the screen back

PuTTY keeps track of text that has scrolled up off the top of the
terminal. So if something appears on the screen that you want to
read, but it scrolls too fast and it's gone by the time you try to
look for it, you can use the scrollbar on the right side of the
window to look back up the session \i{history} and find it again.

As well as using the scrollbar, you can also page the scrollback up
and down by pressing \i{Shift-PgUp} and \i{Shift-PgDn}. You can
scroll a line at a time using \i{Ctrl-PgUp} and \i{Ctrl-PgDn}. These
are still available if you configure the scrollbar to be invisible.

By default the last 200 lines scrolled off the top are
preserved for you to look at. You can increase (or decrease) this
value using the configuration box; see \k{config-scrollback}.

\S{using-sysmenu} The \i{System menu}

If you click the left mouse button on the icon in the top left
corner of PuTTY's terminal window, or click the right mouse button
on the title bar, you will see the standard Windows system menu
containing items like Minimise, Move, Size and Close.

PuTTY's system menu contains extra program features in addition to
the Windows standard options. These extra menu commands are
described below.

(These options are also available in a context menu brought up
by holding Ctrl and clicking with the right mouse button anywhere
in the PuTTY window.)

\S2{using-eventlog} The PuTTY \i{Event Log}

If you choose \q{Event Log} from the system menu, a small window
will pop up in which PuTTY logs significant events during the
connection. Most of the events in the log will probably take place
during session startup, but a few can occur at any point in the
session, and one or two occur right at the end.

You can use the mouse to select one or more lines of the Event Log,
and hit the Copy button to copy them to the \i{clipboard}. If you
are reporting a bug, it's often useful to paste the contents of the
Event Log into your bug report.

\S2{using-specials} \ii{Special commands}

Depending on the protocol used for the current session, there may be
a submenu of \q{special commands}. These are protocol-specific
tokens, such as a \i{\q{break} signal}, that can be sent down a
connection in addition to normal data. Currently only Telnet and SSH
have special commands.

\# FIXME: possibly the full list of special commands should be
\# given here, if only so that it can be sensibly indexed and
\# someone looking up (e.g.) AYT can find out how to send one?

\S2{using-newsession} Starting new sessions

PuTTY's system menu provides some shortcut ways to start new
sessions:

\b Selecting \i{\q{New Session}} will start a completely new
instance of PuTTY, and bring up the configuration box as normal.

\b Selecting \i{\q{Duplicate Session}} will start a session with
precisely the same options as your current one - connecting to the
same host using the same protocol, with all the same terminal
settings and everything.

\b The \i{\q{Saved Sessions} submenu} gives you quick access to any
sets of stored session details you have previously saved. See
\k{config-saving} for details of how to create saved sessions.

\S2{using-changesettings} \I{settings, changing}Changing your
session settings

If you select \i{\q{Change Settings}} from the system menu, PuTTY will
display a cut-down version of its initial configuration box. This
allows you to adjust most properties of your current session. You
can change the terminal size, the font, the actions of various
keypresses, the colours, and so on.

Some of the options that are available in the main configuration box
are not shown in the cut-down Change Settings box. These are usually
options which don't make sense to change in the middle of a session
(for example, you can't switch from SSH to Telnet in mid-session).

\S2{using-copyall} \i{Copy All to Clipboard}

This system menu option provides a convenient way to copy the whole
contents of the terminal screen (up to the last nonempty line) and
scrollback to the \i{clipboard} in one go.

\S2{reset-terminal} \I{scrollback, clearing}Clearing and
\I{terminal, resetting}resetting the terminal

The \i{\q{Clear Scrollback}} option on the system menu tells PuTTY
to discard all the lines of text that have been kept after they
scrolled off the top of the screen. This might be useful, for
example, if you displayed sensitive information and wanted to make
sure nobody could look over your shoulder and see it. (Note that
this only prevents a casual user from using the scrollbar to view
the information; the text is not guaranteed not to still be in
PuTTY's memory.)

The \i{\q{Reset Terminal}} option causes a full reset of the
terminal emulation. A VT-series terminal is a complex piece of
software and can easily get into a state where all the text printed
becomes unreadable. (This can happen, for example, if you
accidentally output a binary file to your terminal.) If this
happens, selecting Reset Terminal should sort it out.

\S2{using-fullscreen} \ii{Full screen} mode

If you find the title bar on a maximised window to be ugly or
distracting, you can select Full Screen mode to maximise PuTTY
\q{even more}. When you select this, PuTTY will expand to fill the
whole screen and its borders, title bar and scrollbar will
disappear. (You can configure the scrollbar not to disappear in
full-screen mode if you want to keep it; see \k{config-scrollback}.)

When you are in full-screen mode, you can still access the system
menu if you click the left mouse button in the \e{extreme} top left
corner of the screen.

\H{using-logging} Creating a \i{log file} of your \I{session
log}session

For some purposes you may find you want to log everything that
appears on your screen. You can do this using the \i{\q{Logging}
panel} in the configuration box.

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 control sequences, 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) 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 \i{\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-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 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 \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 \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 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 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. (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 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).

An alternative way to forward local connections to remote hosts is
to use \I{dynamic port forwarding}dynamic \I{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 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 support it (OpenSSH 3.0 does not, for example).

You can also specify an \i{IP address} to 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 loopback addresses
available only to the local machine. So if you forward (for example)
\c{127.0.0.5:79} to a remote machine's \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; SSH1 is unable to
support it for remote-to-local ports, while SSH2 can support it in
theory but servers will not necessarily cooperate.

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

If invoked with the \c{-cleanup} option, rather than running as
normal, PuTTY will remove its registry entries and random seed file
from the local machine (after confirming with the 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 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"

(Note that PuTTY itself supports an alternative form of this option,
for backwards compatibility. If you execute \c{putty @sessionname}
it will have the same effect as \c{putty -load "sessionname"}. With
the \c{@} form, no double quotes are required, and the \c{@} sign
must be the very first thing on the command line. This form of the
option is deprecated.)

\S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh},
\c{-telnet}, \c{-rlogin}, \c{-raw}

To choose which protocol you want to connect with, you can use one
of these options:

\b \i\c{-ssh} selects the SSH protocol.

\b \i\c{-telnet} selects the Telnet protocol.

\b \i\c{-rlogin} selects the Rlogin protocol.

\b \i\c{-raw} selects the raw protocol.

These options are not available in the file transfer tools PSCP and
PSFTP (which only work with the SSH protocol).

These options are equivalent to the \i{protocol selection} buttons
in the Session panel of the PuTTY configuration box (see
\k{config-hostname}).

\S2{using-cmdline-v} \i\c{-v}: increase verbosity

\I{verbose mode}Most of the PuTTY tools can be made to tell you more
about what they are doing by supplying the \c{-v} option. If you are
having trouble when making a connection, or you're simply curious,
you can turn this switch on and hope to find out more about what is
happening.

\S2{using-cmdline-l} \i\c{-l}: specify a \i{login name}

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

These options are equivalent to the username selection box in the
Connection panel of the PuTTY configuration box (see
\k{config-username}).

\S2{using-cmdline-portfwd} \I{-L-upper}\c{-L}, \I{-R-upper}\c{-R}
and \I{-D-upper}\c{-D}: set up \i{port forwardings}

As well as setting up port forwardings in the PuTTY configuration
(see \k{config-ssh-portfwd}), you can also set up forwardings 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 something like
one of these:

\c putty -L 5110:popserver.example.com:110 -load mysession
\c plink mysession -L 5110:popserver.example.com:110

To forward a remote port to a local destination, just use the \c{-R}
option instead of \c{-L}:

\c putty -R 5023:mytelnetserver.myhouse.org:23 -load mysession
\c plink mysession -R 5023:mytelnetserver.myhouse.org:23

To specify an IP address for the listening end of the tunnel,
prepend it to the argument:

\c plink -L 127.0.0.5:23:localhost:23 myhost

To set up SOCKS-based dynamic port forwarding on a local port, use
the \c{-D} option. For this one you only have to pass the port
number:

\c putty -D 4096 -load mysession

For general information on port forwarding, see
\k{using-port-forwarding}.

These options are not available in the file transfer tools PSCP and
PSFTP.

\S2{using-cmdline-m} \i\c{-m}: read a remote command or script from
a file

The \i\c{-m} option performs a similar function to the \q{Remote
command} box in the SSH panel of the PuTTY configuration box (see
\k{config-command}). However, the \c{-m} option expects to be given
a local file name, and it will read a command from that file. 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;
but this will not work on all servers (and is known not to work
with certain \q{embedded} servers such as routers).

This option is not available in the file transfer tools PSCP and
PSFTP.

\S2{using-cmdline-p} \I{-P-upper}\c{-P}: specify a \i{port number}

The \c{-P} option is used to specify the port number to connect to. If
you have a Telnet server running on port 9696 of a machine instead of
port 23, for example:

\c putty -telnet -P 9696 host.name
\c plink -telnet -P 9696 host.name

(Note that this option is more useful in Plink than in PuTTY,
because in PuTTY you can write \c{putty -telnet host.name 9696} in
any case.)

This option is equivalent to the port number control in the Session
panel of the PuTTY configuration box (see \k{config-hostname}).

\S2{using-cmdline-pw} \i\c{-pw}: specify a \i{password}

A simple way to automate a remote login is to supply your password
on the 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.

Note that the \c{-pw} option only works when you are using the SSH
protocol. Due to fundamental limitations of Telnet and Rlogin, these
protocols do not support automated password authentication.

\S2{using-cmdline-agent} \I{-A-upper}\c{-A} and \i\c{-a}: control \i{agent
forwarding}

The \c{-A} option turns on SSH agent forwarding, and \c{-a} turns it
off. These options are only meaningful if you are using SSH.

See \k{pageant} for general information on \i{Pageant}, and
\k{pageant-forward} for information on agent forwarding. Note that
there is a security risk involved with enabling this option; see
\k{pageant-security} for details.

These options are equivalent to the agent forwarding checkbox in the
Auth panel of the PuTTY configuration box (see \k{config-ssh-agentfwd}).

These options are not available in the file transfer tools PSCP and
PSFTP.

\S2{using-cmdline-x11} \I{-X-upper}\c{-X} and \i\c{-x}: control \i{X11
forwarding}

The \c{-X} option turns on X11 forwarding in SSH, and \c{-x} turns
it off. These options are only meaningful if you are using SSH.

For information on X11 forwarding, see \k{using-x-forwarding}.

These options are equivalent to the X11 forwarding checkbox in the
Tunnels panel of the PuTTY configuration box (see
\k{config-ssh-x11}).

These options are not available in the file transfer tools PSCP and
PSFTP.

\S2{using-cmdline-pty} \i\c{-t} and \I{-T-upper}\c{-T}: control
\i{pseudo-terminal allocation}

The \c{-t} option ensures PuTTY attempts to allocate a
pseudo-terminal at the server, and \c{-T} stops it from allocating
one. These options are only meaningful if you are using SSH.

These options are equivalent to the \q{Don't allocate a
pseudo-terminal} checkbox in the SSH panel of the PuTTY
configuration box (see \k{config-ssh-pty}).

These options are not available in the file transfer tools PSCP and
PSFTP.

\S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{compression}

The \c{-C} option enables compression of the data sent across the
network. This option is only meaningful if you are using SSH.

This option is equivalent to the \q{Enable compression} checkbox in
the SSH panel of the PuTTY configuration box (see
\k{config-ssh-comp}).

\S2{using-cmdline-sshprot} \i\c{-1} and \i\c{-2}: specify an \i{SSH
protocol version}

The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH1}1
or version \I{SSH2}2 of the SSH protocol. These options are only
meaningful if you are using SSH.

These options are equivalent to selecting your preferred SSH
protocol version as \q{1 only} or \q{2 only} in the SSH panel of the
PuTTY configuration box (see \k{config-ssh-prot}).

\S2{using-cmdline-identity} \i\c{-i}: specify an SSH \i{private key}

The \c{-i} option allows you to specify the name of a private key
file in \c{*.PPK} format which PuTTY will use to authenticate with the
server. This option is only meaningful if you are using SSH.

For general information on \i{public-key authentication}, see
\k{pubkey}.

This option is equivalent to the \q{Private key file for
authentication} box in the Auth panel of the PuTTY configuration box
(see \k{config-ssh-privkey}).