Cross-reference all the host key docs.

[PuTTY.git] / doc / using.but

diff --git a/doc/using.but b/doc/using.but
index 85e23431a8e475f0b471fe87752d4861c644ff6d..dc0d6b9b4a691194347eb2e0463d5418047c28e1 100644 (file)
--- a/doc/using.but
+++ b/doc/using.but
@@ -1,5 +1,3 @@
-\define{versionidusing} \versionid $Id$
-

 \C{using} Using PuTTY
 
 This chapter provides a general introduction to some more advanced
 \C{using} Using PuTTY
 
 This chapter provides a general introduction to some more advanced


@@ -55,10 +53,14 @@ PuTTY will \I{selecting lines}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
 
 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
 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
 
 If you have a \i{middle mouse button}, then you can use it to
 \I{adjusting a selection}adjust an existing selection if you


@@ -87,7 +89,7 @@ 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.
 
 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}.
 
 preserved for you to look at. You can increase (or decrease) this
 value using the configuration box; see \k{config-scrollback}.
 


@@ -119,6 +121,9 @@ 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.
 
 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
 \S2{using-specials} \ii{Special commands}
 
 Depending on the protocol used for the current session, there may be


@@ -196,6 +201,28 @@ resets associated timers and counters). For more information about
 repeat key exchanges, see \k{config-ssh-kex-rekey}.
 }
 
 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 use. Selecting a key here will allow PuTTY to use that key now
+and in future: PuTTY will do key here will cause a fresh key-exchange
+with the selected key, and immediately add that key to PuTTY's
+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.
+
+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 manually upgrade.
+}
+

 \b \I{Break, SSH special command}Break
 
 \lcont{
 \b \I{Break, SSH special command}Break
 
 \lcont{


@@ -314,8 +341,9 @@ 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
 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
 
 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


@@ -326,10 +354,10 @@ information.)
 \H{using-x-forwarding} Using \i{X11 forwarding} in SSH
 
 The SSH protocol has the ability to securely forward X Window System
 \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
 
 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


@@ -362,21 +390,16 @@ point at display 10 or above on the SSH server machine itself:
 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.
 
 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
 
 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:
 
 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:


@@ -423,15 +446,17 @@ 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{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
 
 The source port for a forwarded connection usually does not accept
 connections from any machine except the \I{localhost}SSH client or


@@ -546,9 +571,9 @@ window}, or a \i{Windows shortcut}).
 
 \S{using-cmdline-session} Starting a session from the command line
 
 
 \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}:
 
 
 To start a connection to a server called \c{host}:
 


@@ -561,10 +586,14 @@ 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
 
 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]/
 
 
 \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}).
 
 In order to start an existing saved session called \c{sessionname},
 use the \c{-load} option (described in \k{using-cmdline-load}).
 


@@ -614,7 +643,7 @@ 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},
 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:
 
 To choose which protocol you want to connect with, you can use one
 of these options:


@@ -627,6 +656,8 @@ of these options:
 
 \b \i\c{-raw} selects the raw protocol.
 
 
 \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).
 
 These options are not available in the file transfer tools PSCP and
 PSFTP (which only work with the SSH protocol).
 


@@ -889,6 +920,10 @@ The \c{-i} option allows you to specify the name of a private key
 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.
 
 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}.
 
 For general information on \i{public-key authentication}, see
 \k{pubkey}.
 


@@ -899,15 +934,69 @@ authentication} box in the Auth panel of the PuTTY configuration box
 \S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{logical host
 name}
 
 \S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{logical host
 name}
 

-This option overrides PuTTY's normal SSH 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.
+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-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}.