Protect against multiple Change Settings dialogues. We should probably also

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

diff --git a/doc/config.but b/doc/config.but
index 4a2d382..7dbe04d 100644 (file)
--- a/doc/config.but
+++ b/doc/config.but
@@ -53,10 +53,12 @@ you want them saved. Then come back to the Session panel. Select the
 \q{Default Settings} entry in the saved sessions list, with a single
 click. Then press the \q{Save} button.
 
 \q{Default Settings} entry in the saved sessions list, with a single
 click. Then press the \q{Save} button.
 

+\lcont{

 Note that PuTTY does not allow you to save a host name into the
 Default Settings entry. This ensures that when PuTTY is started up,
 the host name box is always empty, so a user can always just type in
 a host name and connect.
 Note that PuTTY does not allow you to save a host name into the
 Default Settings entry. This ensures that when PuTTY is started up,
 the host name box is always empty, so a user can always just type in
 a host name and connect.

+}

 
 If there is a specific host you want to store the details of how to
 connect to, you should create a saved session, which will be
 
 If there is a specific host you want to store the details of how to
 connect to, you should create a saved session, which will be


@@ -69,6 +71,14 @@ Sessions} input box. (The server name is often a good choice for a
 saved session name.) Then press the \q{Save} button. Your saved
 session name should now appear in the list box.
 
 saved session name.) Then press the \q{Save} button. Your saved
 session name should now appear in the list box.
 

+\lcont{
+You can also save settings in mid-session, from the \q{Change Settings}
+dialog. Settings changed since the start of the session will be saved
+with their current values; as well as settings changed through the
+dialog, this includes changes in window size, window title changes
+sent by the server, and so on.
+}
+

 \b To reload a saved session: single-click to select the session
 name in the list box, and then press the \q{Load} button. Your saved
 settings should all appear in the configuration panel.
 \b To reload a saved session: single-click to select the session
 name in the list box, and then press the \q{Load} button. Your saved
 settings should all appear in the configuration panel.


@@ -76,7 +86,7 @@ settings should all appear in the configuration panel.
 \b To modify a saved session: first load it as described above. Then
 make the changes you want. Come back to the Session panel, and press
 the \q{Save} button. The new settings will be saved over the top of
 \b To modify a saved session: first load it as described above. Then
 make the changes you want. Come back to the Session panel, and press
 the \q{Save} button. The new settings will be saved over the top of

-the old ones
+the old ones.

 
 \lcont{
 To save the new settings under a different name, you can enter the new
 
 \lcont{
 To save the new settings under a different name, you can enter the new


@@ -1568,7 +1578,7 @@ will be slightly more efficient; with it disabled, you may find you
 get a faster response to your keystrokes when connecting to some
 types of server.
 
 get a faster response to your keystrokes when connecting to some
 types of server.
 

-The Nagle algorithm is disabled by default.
+The Nagle algorithm is disabled by default for interactive connections.

 
 \S{config-tcp-keepalives} \q{Enable TCP keepalives}
 
 
 \S{config-tcp-keepalives} \q{Enable TCP keepalives}
 


@@ -1590,7 +1600,7 @@ typically two hours; this is set by the operating system, and cannot
 be configured within PuTTY.
 
 \b If the operating system does not receive a response to a keepalive,
 be configured within PuTTY.
 
 \b If the operating system does not receive a response to a keepalive,

-it may send out more in quick succession and if terminate the connection
+it may send out more in quick succession and terminate the connection

 if no response is received.
 
 TCP keepalives may be more useful for ensuring that half-open connections
 if no response is received.
 
 TCP keepalives may be more useful for ensuring that half-open connections


@@ -1619,7 +1629,7 @@ explicitly set this to \q{IPv4} or \q{IPv6}.
 The Data panel allows you to configure various pieces of data which
 can be sent to the server to affect your connection at the far end.
 
 The Data panel allows you to configure various pieces of data which
 can be sent to the server to affect your connection at the far end.
 

-Each options on this panel applies to more than one protocol.
+Each option on this panel applies to more than one protocol.

 Options which apply to only one protocol appear on that protocol's
 configuration panels.
 
 Options which apply to only one protocol appear on that protocol's
 configuration panels.
 


@@ -2205,6 +2215,20 @@ allowed to elapse before a rekey is initiated. If this is set to zero,
 PuTTY will not rekey due to elapsed time. The SSH-2 protocol
 specification recommends a timeout of at most 60 minutes.
 
 PuTTY will not rekey due to elapsed time. The SSH-2 protocol
 specification recommends a timeout of at most 60 minutes.
 

+You might have a need to disable time-based rekeys completely for the same
+reasons that keepalives aren't always helpful. If you anticipate
+suffering a network dropout of several hours in the middle of an SSH
+connection, but were not actually planning to send \e{data} down
+that connection during those hours, then an attempted rekey in the
+middle of the dropout will probably cause the connection to be
+abandoned, whereas if rekeys are disabled then the connection should
+in principle survive (in the absence of interfering firewalls). See
+\k{config-keepalive} for more discussion of these issues; for these
+purposes, rekeys have much the same properties as keepalives.
+(Except that rekeys have cryptographic value in themselves, so you
+should bear that in mind when deciding whether to turn them off.)
+Note, however, the the SSH \e{server} can still initiate rekeys.
+

 \b \q{Max data before rekey} specifies the amount of data (in bytes)
 that is permitted to flow in either direction before a rekey is
 initiated. If this is set to zero, PuTTY will not rekey due to
 \b \q{Max data before rekey} specifies the amount of data (in bytes)
 that is permitted to flow in either direction before a rekey is
 initiated. If this is set to zero, PuTTY will not rekey due to


@@ -2224,22 +2248,13 @@ used:
 
 }
 
 
 }
 

-PuTTY can be prevented from initiating a rekey entirely by setting
-both of these values to zero. (Note, however, that the SSH
-\e{server} may still initiate rekeys.)
-
-You might have a need to disable rekeys completely for the same
-reasons that keepalives aren't always helpful. If you anticipate
-suffering a network dropout of several hours in the middle of an SSH
-connection, but were not actually planning to send \e{data} down
-that connection during those hours, then an attempted rekey in the
-middle of the dropout will probably cause the connection to be
-abandoned, whereas if rekeys are disabled then the connection should
-in principle survive (in the absence of interfering firewalls). See
-\k{config-keepalive} for more discussion of these issues; for these
-purposes, rekeys have much the same properties as keepalives.
-(Except that rekeys have cryptographic value in themselves, so you
-should bear that in mind when deciding whether to turn them off.)
+Disabling data-based rekeys entirely is a bad idea.  The integrity,
+and to a lesser extent, confidentiality of the SSH-2 protocol depend
+in part on rekeys occuring before a 32-bit packet sequence number
+wraps around.  Unlike time-based rekeys, data-based rekeys won't occur
+when the SSH connection is idle, so they shouldn't cause the same
+problems.  The SSH-1 protocol, incidentally, has even weaker integrity
+protection than SSH-2 without rekeys.

 
 \H{config-ssh-auth} The Auth panel
 
 
 \H{config-ssh-auth} The Auth panel
 


@@ -2321,7 +2336,9 @@ This box is where you enter the name of your private key file if you
 are using public key authentication. See \k{pubkey} for information
 about public key authentication in SSH.
 
 are using public key authentication. See \k{pubkey} for information
 about public key authentication in SSH.
 

-This key must be in PuTTY's native format (\c{*.PPK}).
+This key must be in PuTTY's native format (\c{*.PPK}). If you have a
+private key in another format that you want to use with PuTTY, see
+\k{puttygen-conversions}.

 
 \H{config-ssh-x11} The X11 panel
 
 
 \H{config-ssh-x11} The X11 panel
 


@@ -2337,7 +2354,7 @@ a local X display on your PC.
 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
 If your X display is somewhere unusual, you will need to enter its
 location in the \q{X display location} box; if this is left blank,
 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
 If your X display is somewhere unusual, you will need to enter its
 location in the \q{X display location} box; if this is left blank,

-PuTTY try to find a sensible default in the environment, or use the
+PuTTY will try to find a sensible default in the environment, or use the

 primary local display (\c{:0}) if that fails.
 
 See \k{using-x-forwarding} for more information about X11
 primary local display (\c{:0}) if that fails.
 
 See \k{using-x-forwarding} for more information about X11


@@ -2438,11 +2455,15 @@ address to listen on, by specifying (for instance) \c{127.0.0.5:79}.
 See \k{using-port-forwarding} for more information on how this
 works and its restrictions.
 
 See \k{using-port-forwarding} for more information on how this
 works and its restrictions.
 

+In place of port numbers, you can enter service names, if they are
+known to the local system. For instance, in the \q{Destination} box,
+you could enter \c{popserver.example.com:pop3}.
+

 You can modify the currently active set of port forwardings in
 You can modify the currently active set of port forwardings in

-mid-session using \q{Change Settings}. If you delete a local or
-dynamic port forwarding in mid-session, PuTTY will stop listening
-for connections on that port, so it can be re-used by another
-program. If you delete a remote port forwarding, note that:
+mid-session using \q{Change Settings} (see \k{using-changesettings}).
+If you delete a local or dynamic port forwarding in mid-session, PuTTY
+will stop listening for connections on that port, so it can be re-used
+by another program. If you delete a remote port forwarding, note that:

 
 \b The SSHv1 protocol contains no mechanism for asking the server to
 stop listening on a remote port.
 
 \b The SSHv1 protocol contains no mechanism for asking the server to
 stop listening on a remote port.


@@ -2458,6 +2479,11 @@ although the port cannot be reused by another program, you can at
 least be reasonably sure that server-side programs can no longer
 access the service at your end of the port forwarding.
 
 least be reasonably sure that server-side programs can no longer
 access the service at your end of the port forwarding.
 

+If you delete a forwarding, any existing connections established using
+that forwarding remain open. Similarly, changes to global settings
+such as \q{Local ports accept connections from other hosts} only take
+effect on new forwardings.
+

 \S{config-ssh-portfwd-localhost} Controlling the visibility of
 forwarded ports
 
 \S{config-ssh-portfwd-localhost} Controlling the visibility of
 forwarded ports
 


@@ -2494,12 +2520,15 @@ incoming connections in both IPv4 and (if available) IPv6
 \b for a remote-to-local port forwarding, PuTTY will choose a
 sensible protocol for the outgoing connection.
 
 \b for a remote-to-local port forwarding, PuTTY will choose a
 sensible protocol for the outgoing connection.
 

-\# FIXME: work out what this paragraph means, reword it for clarity,
-\# and reinstate it.
-Note that on Windows the address space for IPv4 and IPv6 is
-completely disjunct, so listening on IPv6 won't make PuTTY listen on
-IPv4. This behaviour may be different on most remote hosts when they
-are not operating Windows.
+Note that some operating systems may listen for incoming connections
+in IPv4 even if you specifically asked for IPv6, because their IPv4
+and IPv6 protocol stacks are linked together. Apparently Linux does
+this, and Windows does not. So if you're running PuTTY on Windows
+and you tick \q{IPv6} for a local or dynamic port forwarding, it
+will \e{only} be usable by connecting to it using IPv6; whereas if
+you do the same on Linux, you can also use it with IPv4. However,
+ticking \q{Auto} should always give you a port which you can connect
+to using either protocol.

 
 \H{config-ssh-bugs} The Bugs panel
 
 
 \H{config-ssh-bugs} The Bugs panel
 


@@ -2659,6 +2688,26 @@ SSH2 public-key authentication will fail.
 
 This is an SSH2-specific bug.
 
 
 This is an SSH2-specific bug.
 

+\S{config-ssh-bug-rekey} \q{Handles key re-exchange badly}
+
+\cfg{winhelp-topic}{ssh.bugs.rekey2}
+
+Some SSH servers cannot cope with repeat key exchange at
+all, and will ignore attempts by the client to start one. Since
+PuTTY pauses the session while performing a repeat key exchange, the
+effect of this would be to cause the session to hang after an hour
+(unless you have your rekey timeout set differently; see
+\k{config-ssh-kex-rekey} for more about rekeys).
+Other, very old, SSH servers handle repeat key exchange even more
+badly, and disconnect upon receiving a repeat key exchange request.
+
+If this bug is detected, PuTTY will never initiate a repeat key
+exchange. If this bug is enabled when talking to a correct server,
+the session should still function, but may be less secure than you
+would expect.
+
+This is an SSH2-specific bug.
+

 \H{config-file} Storing configuration in a file
 
 PuTTY does not currently support storing its configuration in a file
 \H{config-file} Storing configuration in a file
 
 PuTTY does not currently support storing its configuration in a file