-\define{versionidusing} \versionid $Id$
-
\C{using} Using PuTTY
This chapter provides a general introduction to some more advanced
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
+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.)
+down Alt gives the normal behaviour instead: see
+\k{config-rectselect} for details.
+
+(In some Unix environments, Alt+drag is intercepted by the window
+manager. Shift+Alt+drag should work for rectangular selection as
+well, so you could try that instead.)
If you have a \i{middle mouse button}, then you can use it to
\I{adjusting a selection}adjust an existing selection if you
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
+By default the last 2000 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}.
are reporting a bug, it's often useful to paste the contents of the
Event Log into your bug report.
+(The Event Log is not the same as the facility to create a log file
+of your session; that's described in \k{using-logging}.)
+
\S2{using-specials} \ii{Special commands}
Depending on the protocol used for the current session, there may be
repeat key exchanges, see \k{config-ssh-kex-rekey}.
}
+\b \I{host key cache}Cache new host key type
+
+\lcont{
+Only available in SSH-2. This submenu appears only if the server has
+host keys of a type that PuTTY doesn't already have cached, and so
+won't consider. Selecting a key here will allow PuTTY to use that key
+now and in future: PuTTY will do a fresh key-exchange with the selected
+key, and immediately add that key to its permanent cache (relying on
+the host key used at the start of the connection to cross-certify the
+new key). That key will be used for the rest of the current session;
+it may not actually be used for future sessions, depending on your
+preferences (see \k{config-ssh-hostkey-order}).
+
+Normally, PuTTY will carry on using a host key it already knows, even
+if the server offers key formats that PuTTY would otherwise prefer,
+to avoid host key prompts. As a result, if you've been using a server
+for some years, you may still be using an older key than a new user
+would use, due to server upgrades in the meantime. The SSH protocol
+unfortunately does not have organised facilities for host key migration
+and rollover, but this allows you to \I{host keys, upgrading}manually
+upgrade.
+}
+
\b \I{Break, SSH special command}Break
\lcont{
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.
+set}. There are a lot of different character sets available, and no
+good way for PuTTY to know which to use, 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
\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.
+\i{graphical 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
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
+X11 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
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.
+The SSH protocol has the ability to forward arbitrary \I{network
+connection}network (TCP) 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
+\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:
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).
+to use \I{dynamic port forwarding}dynamic SOCKS proxying. In this
+mode, PuTTY acts as a SOCKS server, which SOCKS-aware programs can
+connect to and open forwarded connections to the destination of their
+choice, so this can be an alternative to long lists of static
+forwardings. To use this mode, 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). PuTTY will
+then listen for SOCKS connections on the port you have specified.
+Most \i{web browsers} can be configured to connect to this SOCKS proxy
+service; also, 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
to obtain a fix from Microsoft in order to use addresses like
\cw{127.0.0.5} - see \k{faq-alternate-localhost}.)
+For more options relating to port forwarding, see
+\k{config-ssh-portfwd}.
+
+If the connection you are forwarding over SSH is itself a second SSH
+connection made by another copy of PuTTY, you might find the
+\q{logical host name} configuration option useful to warn PuTTY of
+which host key it should be expecting. See \k{config-loghost} for
+details of this.
+
\H{using-rawprot} Making \i{raw TCP connections}
A lot of \I{debugging Internet protocols}Internet protocols are
\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.
+\I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}\I\c{-serial}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}:
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):
+URLs} in \i{web browsers}):
\c putty.exe telnet://host[:port]/
+To start a connection to a serial port, e.g. COM1:
+
+\c putty.exe -serial com1
+
In order to start an existing saved session called \c{sessionname},
use the \c{-load} option (described in \k{using-cmdline-load}).
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).
+confirming with the user). It will also attempt to remove information
+about recently launched sessions stored in the \q{jump list} on
+Windows 7 and up.
Note that on \i{multi-user systems}, \c{-cleanup} only removes
registry entries and files associated with the currently logged-in
option is deprecated.)
\S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh},
-\c{-telnet}, \c{-rlogin}, \c{-raw}
+\c{-telnet}, \c{-rlogin}, \c{-raw} \c{-serial}
To choose which protocol you want to connect with, you can use one
of these options:
\b \i\c{-raw} selects the raw protocol.
+\b \i\c{-serial} selects a serial connection.
+
These options are not available in the file transfer tools PSCP and
PSFTP (which only work with the SSH protocol).
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}).
+X11 panel of the PuTTY configuration box (see \k{config-ssh-x11}).
These options are not available in the file transfer tools PSCP and
PSFTP.
or version \I{SSH-2}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}).
+These options are equivalent to selecting the SSH protocol version in
+the SSH panel of the PuTTY configuration box (see \k{config-ssh-prot}).
\S2{using-cmdline-ipversion} \i\c{-4} and \i\c{-6}: specify an
\i{Internet protocol version}
The \c{-4} and \c{-6} options force PuTTY to use the older Internet
-protocol \i{IPv4} or the newer \i{IPv6}.
+protocol \i{IPv4} or the newer \i{IPv6} for most outgoing
+connections.
These options are equivalent to selecting your preferred Internet
protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of
file in \c{*.\i{PPK}} format which PuTTY will use to authenticate with the
server. This option is only meaningful if you are using SSH.
+If you are using Pageant, you can also specify a \e{public} key file
+(in RFC 4716 or OpenSSH format) to identify a specific key file to use.
+(This won't work if you're not running Pageant, of course.)
+
For general information on \i{public-key authentication}, see
\k{pubkey}.
authentication} box in the Auth panel of the PuTTY configuration box
(see \k{config-ssh-privkey}).
+\S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{logical host
+name}
+
+This option overrides PuTTY's normal SSH \I{host key cache}host key
+caching policy by telling it the name of the host you expect your
+connection to end up at (in cases where this differs from the location
+PuTTY thinks it's connecting to). It can be a plain host name, or a
+host name followed by a colon and a port number. See
+\k{config-loghost} for more detail on this.
+
+\S2{using-cmdline-hostkey} \i\c{-hostkey}: \I{manually configuring
+host keys}manually specify an expected host key
+
+This option overrides PuTTY's normal SSH \I{host key cache}host key
+caching policy by telling it exactly what host key to expect, which
+can be useful if the normal automatic host key store in the Registry
+is unavailable. The argument to this option should be either a host key
+fingerprint, or an SSH-2 public key blob. See
+\k{config-ssh-kex-manual-hostkeys} for more information.
+
+You can specify this option more than once if you want to configure
+more than one key to be accepted.
+
\S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display \i{PGP key fingerprint}s
This option causes the PuTTY tools not to run as normal, but instead
to display the fingerprints of the PuTTY PGP Master Keys, in order to
aid with \i{verifying new versions}. See \k{pgpkeys} for more information.
+
+\S2{using-cmdline-sercfg} \i\c{-sercfg}: specify serial port
+\i{configuration}
+
+This option specifies the configuration parameters for the serial
+port (baud rate, stop bits etc). Its argument is interpreted as a
+comma-separated list of configuration options, which can be as
+follows:
+
+\b Any single digit from 5 to 9 sets the number of data bits.
+
+\b \cq{1}, \cq{1.5} or \cq{2} sets the number of stop bits.
+
+\b Any other numeric string is interpreted as a baud rate.
+
+\b A single lower-case letter specifies the parity: \cq{n} for none,
+\cq{o} for odd, \cq{e} for even, \cq{m} for mark and \cq{s} for space.
+
+\b A single upper-case letter specifies the flow control: \cq{N} for
+none, \cq{X} for XON/XOFF, \cq{R} for RTS/CTS and \cq{D} for
+DSR/DTR.
+
+For example, \cq{-sercfg 19200,8,n,1,N} denotes a baud rate of
+19200, 8 data bits, no parity, 1 stop bit and no flow control.
+
+\S2{using-cmdline-sshlog} \i\c{-sessionlog}, \i\c{-sshlog},
+\i\c{-sshrawlog}: specify session logging
+
+These options cause the PuTTY network tools to write out a \i{log
+file}. Each of them expects a file name as an argument, e.g.
+\cq{-sshlog putty.log} causes an SSH packet log to be written to a
+file called \cq{putty.log}. The three different options select
+different logging modes, all available from the GUI too:
+
+\b \c{-sessionlog} selects \q{All session output} logging mode.
+
+\b \c{-sshlog} selects \q{SSH packets} logging mode.
+
+\b \c{-sshrawlog} selects \q{SSH packets and raw data} logging mode.
+
+For more information on logging configuration, see \k{config-logging}.
+
+\S2{using-cmdline-proxycmd} \i\c{-proxycmd}: specify a local proxy
+command
+
+This option enables PuTTY's mode for running a \I{Local proxy}command
+on the local machine and using it as a proxy for the network
+connection. It expects a shell command string as an argument.
+
+See \k{config-proxy-type} for more information on this, and on other
+proxy settings. In particular, note that since the special sequences
+described there are understood in the argument string, literal
+backslashes must be doubled (if you want \c{\\} in your command, you
+must put \c{\\\\} on the command line).
+
+\S2{using-cmdline-restrict-acl} \i\c{-restrict-acl}: restrict the
+\i{Windows process ACL}
+
+This option (on Windows only) causes PuTTY (or another PuTTY tool) to
+try to lock down the operating system's access control on its own
+process. If this succeeds, it should present an extra obstacle to
+malware that has managed to run under the same user id as the PuTTY
+process, by preventing it from attaching to PuTTY using the same
+interfaces debuggers use and either reading sensitive information out
+of its memory or hijacking its network session.
+
+This option is not enabled by default, because this form of
+interaction between Windows programs has many legitimate uses,
+including accessibility software such as screen readers. Also, it
+cannot provide full security against this class of attack in any case,
+because PuTTY can only lock down its own ACL \e{after} it has started
+up, and malware could still get in if it attacks the process between
+startup and lockdown. So it trades away noticeable convenience, and
+delivers less real security than you might want. However, if you do
+want to make that tradeoff anyway, the option is available.
+
+A PuTTY process started with \c{-restrict-acl} will pass that on to
+any processes started with Duplicate Session, New Session etc.
+(However, if you're invoking PuTTY tools explicitly, for instance as a
+proxy command, you'll need to arrange to pass them the
+\c{-restrict-acl} option yourself, if that's what you want.)
projects / PuTTY.git / blobdiff