Support sh/csh syntax switching for Unix Pageant.

[PuTTY.git] / doc / using.but

diff --git a/doc/using.but b/doc/using.but
index 893c1d7e37fdbe2562e50c8b7134a204fb8af026..343612b05a9465bb89be953f99e94bebf1361aa7 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.
 
+(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
@@ -198,6 +201,28 @@ resets associated timers and counters). For more information about
 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{
@@ -316,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
-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
@@ -908,7 +934,7 @@ authentication} box in the Auth panel of the PuTTY configuration box
 \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
+This option overrides PuTTY's normal SSH \i{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
@@ -918,7 +944,7 @@ 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 host key caching policy by
+This option overrides PuTTY's normal SSH \i{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