FAQ entry on rekeys: Jacob would like to pre-emptively try to avoid

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

diff --git a/doc/using.but b/doc/using.but
index 240f7ce..663fb5f 100644 (file)
--- a/doc/using.but
+++ b/doc/using.but
@@ -1,4 +1,4 @@
-\versionid $Id: using.but,v 1.32 2004/09/22 22:15:25 jacob Exp $
+\define{versionidusing} \versionid $Id$

 
 \C{using} Using PuTTY
 
 
 \C{using} Using PuTTY
 


@@ -175,17 +175,33 @@ PuTTY can also be configured to send this when Ctrl-Z is typed; see
 
 In an SSH connection, the following special commands are available:
 
 
 In an SSH connection, the following special commands are available:
 

+\b \I{IGNORE message, SSH special command}\I{No-op, in SSH}IGNORE message
+
+\lcont{
+Should have no effect.
+}
+
+\b \I{Repeat key exchange, SSH special command}Repeat key exchange
+
+\lcont{
+Only available in SSH-2. Forces a repeat key exchange immediately (and
+resets associated timers and counters). For more information about
+repeat key exchanges, see \k{config-ssh-kex-rekey}.
+}
+

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

-Optional extension; may not be supported by server. PuTTY requests the
-server's default break length.
+Only available in SSH-2, and only during a session. Optional
+extension; may not be supported by server. PuTTY requests the server's
+default break length.

 }
 
 }
 

-\b \I{IGNORE message, SSH special command}\I{No-op, in SSH}IGNORE message
+\b \I{Signal, SSH special command}Signals (SIGINT, SIGTERM etc)

 
 \lcont{
 
 \lcont{

-Should have no effect.
+Only available in SSH-2, and only during a session. Sends various
+POSIX signals. Not honoured by all servers.

 }
 
 \S2{using-newsession} Starting new sessions
 }
 
 \S2{using-newsession} Starting new sessions


@@ -196,10 +212,13 @@ sessions:
 \b Selecting \i{\q{New Session}} will start a completely new
 instance of PuTTY, and bring up the configuration box as normal.
 
 \b Selecting \i{\q{New Session}} will start a completely new
 instance of PuTTY, and bring up the configuration box as normal.
 

-\b Selecting \i{\q{Duplicate Session}} will start a session with
-precisely the same options as your current one - connecting to the
-same host using the same protocol, with all the same terminal
-settings and everything.
+\b Selecting \i{\q{Duplicate Session}} will start a session in a
+new window with precisely the same options as your current one -
+connecting to the same host using the same protocol, with all the
+same terminal settings and everything.
+
+\b In an inactive window, selecting \i{\q{Restart Session}} will
+do the same as \q{Duplicate Session}, but in the current window.

 
 \b The \i{\q{Saved Sessions} submenu} gives you quick access to any
 sets of stored session details you have previously saved. See
 
 \b The \i{\q{Saved Sessions} submenu} gives you quick access to any
 sets of stored session details you have previously saved. See


@@ -278,15 +297,17 @@ See \k{config-logging} for more details and options.
 \H{using-translation} Altering your \i{character set} configuration
 
 If you find that special characters (\i{accented characters}, for
 \H{using-translation} Altering your \i{character set} configuration
 
 If you find that special characters (\i{accented characters}, for

-example) 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.
+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.

 
 If you click \q{Change Settings} and look at the \i{\q{Translation}
 
 If you click \q{Change Settings} and look at the \i{\q{Translation}

-panel}, you should see a large number of character sets which you
-can select. Now all you need is to find out which of them you want!
+panel}, you should see a large number of character sets which you can
+select, and other related options. Now all you need is to find out
+which of them you want! (See \k{config-translation} for more
+information.)

 
 \H{using-x-forwarding} Using \i{X11 forwarding} in SSH
 
 
 \H{using-x-forwarding} Using \i{X11 forwarding} in SSH
 


@@ -297,16 +318,17 @@ 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
 the clear.
 
 In order to use this feature, you will need an X display server for

-your Windows machine, such as X-Win32 or Exceed. This will probably
+your Windows machine, such as Cygwin/X, X-Win32, or Exceed. This will probably

 install itself as display number 0 on your local machine; if it
 doesn't, the manual for the \i{X server} should tell you what it
 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
 install itself as display number 0 on your local machine; if it
 doesn't, the manual for the \i{X server} should tell you what it
 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

-session. The \q{X display location} box reads \c{localhost:0} by
-default, which is the usual display location where your X server
-will be installed. If that needs changing, then change it.
+session. The \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
+installed. If that needs changing, then change it.

 
 Now you should be able to log in to the SSH server as normal. To
 check that X forwarding has been successfully negotiated during
 
 Now you should be able to log in to the SSH server as normal. To
 check that X forwarding has been successfully negotiated during


@@ -363,7 +385,7 @@ should appear in the list box.
 Now start your session and log in. (Port forwarding will not be
 enabled until after you have logged in; otherwise it would be easy
 to perform completely anonymous network attacks, and gain access to
 Now start your session and log in. (Port forwarding will not be
 enabled until after you have logged in; otherwise it would be easy
 to perform completely anonymous network attacks, and gain access to

-anyone's virtual private network). To check that PuTTY has set up
+anyone's virtual private network.) To check that PuTTY has set up

 the port forwarding correctly, you can look at the PuTTY Event Log
 (see \k{using-eventlog}). It should say something like this:
 
 the port forwarding correctly, you can look at the PuTTY Event Log
 (see \k{using-eventlog}). It should say something like this:
 


@@ -409,8 +431,8 @@ your client PC can connect to the forwarded port.
 \b The \q{Remote ports do the same} option does the same thing for
 remote-to-local port forwardings (so that machines other than the
 SSH server machine can connect to the forwarded port.) Note that
 \b The \q{Remote ports do the same} option does the same thing for
 remote-to-local port forwardings (so that machines other than the
 SSH server machine can connect to the forwarded port.) Note that

-this feature is only available in the SSH 2 protocol, and not all
-SSH 2 servers honour it (in OpenSSH, for example, it's usually
+this feature is only available in the SSH-2 protocol, and not all
+SSH-2 servers honour it (in OpenSSH, for example, it's usually

 disabled by default).
 
 You can also specify an \i{IP address} to listen on. Typically a
 disabled by default).
 
 You can also specify an \i{IP address} to listen on. Typically a


@@ -421,8 +443,8 @@ available only to the local machine. So if you forward (for example)
 should be able to run commands such as \c{finger fred@127.0.0.5}.
 This can be useful if the program connecting to the forwarded port
 doesn't allow you to change the port number it uses. This feature is
 should be able to run commands such as \c{finger fred@127.0.0.5}.
 This can be useful if the program connecting to the forwarded port
 doesn't allow you to change the port number it uses. This feature is

-available for local-to-remote forwarded ports; SSH1 is unable to
-support it for remote-to-local ports, while SSH2 can support it in
+available for local-to-remote forwarded ports; SSH-1 is unable to
+support it for remote-to-local ports, while SSH-2 can support it in

 theory but servers will not necessarily cooperate.
 
 (Note that if you're using Windows XP Service Pack 2, you may need
 theory but servers will not necessarily cooperate.
 
 (Note that if you're using Windows XP Service Pack 2, you may need


@@ -494,9 +516,16 @@ use the \c{-load} option (described in \k{using-cmdline-load}).
 
 \S{using-cleanup} \i\c{-cleanup}
 
 
 \S{using-cleanup} \i\c{-cleanup}
 

+\cfg{winhelp-topic}{options.cleanup}
+

 If invoked with the \c{-cleanup} option, rather than running as
 If invoked with the \c{-cleanup} option, rather than running as

-normal, PuTTY will remove its registry entries and random seed file
-from the local machine (after confirming with the user).
+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).
+
+Note that on \i{multi-user systems}, \c{-cleanup} only removes
+registry entries and files associated with the currently logged-in
+user.

 
 \S{using-general-opts} Standard command-line options
 
 
 \S{using-general-opts} Standard command-line options
 


@@ -522,7 +551,7 @@ call something like
 \c d:\path\to\putty.exe -load "my session"
 
 (Note that PuTTY itself supports an alternative form of this option,
 \c d:\path\to\putty.exe -load "my session"
 
 (Note that PuTTY itself supports an alternative form of this option,

-for backwards compatibility. If you execute \c{putty @sessionname}
+for backwards compatibility. If you execute \i\c{putty @sessionname}

 it will have the same effect as \c{putty -load "sessionname"}. With
 the \c{@} form, no double quotes are required, and the \c{@} sign
 must be the very first thing on the command line. This form of the
 it will have the same effect as \c{putty -load "sessionname"}. With
 the \c{@} form, no double quotes are required, and the \c{@} sign
 must be the very first thing on the command line. This form of the


@@ -693,6 +722,24 @@ configuration box (see \k{config-ssh-pty}).
 These options are not available in the file transfer tools PSCP and
 PSFTP.
 
 These options are not available in the file transfer tools PSCP and
 PSFTP.
 

+\S2{using-cmdline-noshell} \I{-N-upper}\c{-N}: suppress starting a
+\I{suppressing remote shell}shell or command
+
+The \c{-N} option prevents PuTTY from attempting to start a shell or
+command on the remote server. You might want to use this option if
+you are only using the SSH connection for port forwarding, and your
+user account on the server does not have the ability to run a shell.
+
+This feature is only available in SSH protocol version 2 (since the
+version 1 protocol assumes you will always want to run a shell).
+
+This option is equivalent to the \q{Don't start a shell or command
+at all} checkbox in the SSH panel of the PuTTY configuration box
+(see \k{config-ssh-noshell}).
+
+This option is not available in the file transfer tools PSCP and
+PSFTP.
+

 \S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{compression}
 
 The \c{-C} option enables compression of the data sent across the
 \S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{compression}
 
 The \c{-C} option enables compression of the data sent across the


@@ -705,14 +752,24 @@ the SSH panel of the PuTTY configuration box (see
 \S2{using-cmdline-sshprot} \i\c{-1} and \i\c{-2}: specify an \i{SSH
 protocol version}
 
 \S2{using-cmdline-sshprot} \i\c{-1} and \i\c{-2}: specify an \i{SSH
 protocol version}
 

-The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH1}1
-or version \I{SSH2}2 of the SSH protocol. These options are only
+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.
 
 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}).
 
 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}).
 

+\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}.
+
+These options are equivalent to selecting your preferred Internet
+protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of
+the PuTTY configuration box (see \k{config-address-family}).
+

 \S2{using-cmdline-identity} \i\c{-i}: specify an SSH \i{private key}
 
 The \c{-i} option allows you to specify the name of a private key
 \S2{using-cmdline-identity} \i\c{-i}: specify an SSH \i{private key}
 
 The \c{-i} option allows you to specify the name of a private key


@@ -725,3 +782,9 @@ For general information on \i{public-key authentication}, see
 This option is equivalent to the \q{Private key file for
 authentication} box in the Auth panel of the PuTTY configuration box
 (see \k{config-ssh-privkey}).
 This option is equivalent to the \q{Private key file for
 authentication} box in the Auth panel of the PuTTY configuration box
 (see \k{config-ssh-privkey}).

+
+\S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display PGP key fingerprints
+
+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 verifying new versions. See \k{pgpkeys} for more information.