Render timing.c robust in the face of strangeness. The strangenesses

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

diff --git a/doc/using.but b/doc/using.but
index 8320221..663fb5f 100644 (file)
--- a/doc/using.but
+++ b/doc/using.but
@@ -1,4 +1,4 @@
-\versionid $Id: using.but,v 1.27 2004/08/12 20:55:58 jacob Exp $
+\define{versionidusing} \versionid $Id$

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


@@ -123,12 +123,86 @@ Event Log into your bug report.
 Depending on the protocol used for the current session, there may be
 a submenu of \q{special commands}. These are protocol-specific
 tokens, such as a \i{\q{break} signal}, that can be sent down a
 Depending on the protocol used for the current session, there may be
 a submenu of \q{special commands}. These are protocol-specific
 tokens, such as a \i{\q{break} signal}, that can be sent down a

-connection in addition to normal data. Currently only Telnet and SSH
-have special commands.
+connection in addition to normal data. Their precise effect is usually
+up to the server. Currently only Telnet and SSH have special commands.

 
 

-\# FIXME: possibly the full list of special commands should be
-\# given here, if only so that it can be sensibly indexed and
-\# someone looking up (e.g.) AYT can find out how to send one?
+The following special commands are available in Telnet:
+
+\b \I{Are You There, Telnet special command}Are You There
+
+\b \I{Break, Telnet special command}Break
+
+\b \I{Synch, Telnet special command}Synch
+
+\b \I{Erase Character, Telnet special command}Erase Character
+
+\lcont{
+PuTTY can also be configured to send this when the Backspace key is
+pressed; see \k{config-telnetkey}.
+}
+
+\b \I{Erase Line, Telnet special command}Erase Line
+
+\b \I{Go Ahead, Telnet special command}Go Ahead
+
+\b \I{No Operation, Telnet special command}No Operation
+
+\lcont{
+Should have no effect.
+}
+
+\b \I{Abort Process, Telnet special command}Abort Process
+
+\b \I{Abort Output, Telnet special command}Abort Output
+
+\b \I{Interrupt Process, Telnet special command}Interrupt Process
+
+\lcont{
+PuTTY can also be configured to send this when Ctrl-C is typed; see
+\k{config-telnetkey}.
+}
+
+\b \I{Suspend Process, Telnet special command}Suspend Process
+
+\lcont{
+PuTTY can also be configured to send this when Ctrl-Z is typed; see
+\k{config-telnetkey}.
+}
+
+\b \I{End Of Record, Telnet special command}End Of Record
+
+\b \I{End Of File, Telnet special command}End Of File
+
+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{
+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{Signal, SSH special command}Signals (SIGINT, SIGTERM etc)
+
+\lcont{
+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
 


@@ -138,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


@@ -220,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
 


@@ -239,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


@@ -305,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:
 


@@ -351,8 +431,9 @@ 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 support it (OpenSSH 3.0 does not, for example).
+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
 Windows machine can be asked to listen on any single IP address in
 
 You can also specify an \i{IP address} to listen on. Typically a
 Windows machine can be asked to listen on any single IP address in


@@ -362,10 +443,14 @@ 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.
 
 theory but servers will not necessarily cooperate.
 

+(Note that if you're using Windows XP Service Pack 2, you may need
+to obtain a fix from Microsoft in order to use addresses like
+\cw{127.0.0.5} - see \k{faq-alternate-localhost}.)
+

 \H{using-rawprot} Making \i{raw TCP connections}
 
 A lot of \I{debugging Internet protocols}Internet protocols are
 \H{using-rawprot} Making \i{raw TCP connections}
 
 A lot of \I{debugging Internet protocols}Internet protocols are


@@ -431,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
 


@@ -459,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


@@ -630,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


@@ -642,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


@@ -662,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.