Note the interaction of jump lists and -cleanup.

[PuTTY.git] / doc / using.but

diff --git a/doc/using.but b/doc/using.but
index a2d8c271a348034a7af1e3b1846bcad765ac8551..7d184b7c21c3cd32c3a1df42b93e7b118ab92e3a 100644 (file)
--- a/doc/using.but
+++ b/doc/using.but
@@ -121,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


@@ -198,6 +201,29 @@ 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 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{
 \b \I{Break, SSH special command}Break
 
 \lcont{


@@ -316,8 +342,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


@@ -580,7 +607,9 @@ 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
 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
 
 Note that on \i{multi-user systems}, \c{-cleanup} only removes
 registry entries and files associated with the currently logged-in


@@ -873,9 +902,8 @@ The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH-1}1
 or version \I{SSH-2}2 of the SSH protocol. These options are only
 meaningful if you are using SSH.
 
 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}
 
 \S2{using-cmdline-ipversion} \i\c{-4} and \i\c{-6}: specify an
 \i{Internet protocol version}


@@ -894,6 +922,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}.
 


@@ -904,22 +936,22 @@ 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
 
 
 \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 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.
+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.
 
 You can specify this option more than once if you want to configure
 more than one key to be accepted.


@@ -953,3 +985,60 @@ 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.
 
 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.)