Integrate unfix.org's IPv6 patches up to level 10, with rather a lot

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

diff --git a/doc/using.but b/doc/using.but
index 2910ab5..db457ed 100644 (file)
--- a/doc/using.but
+++ b/doc/using.but
@@ -1,4 +1,4 @@
-\versionid $Id: using.but,v 1.23 2004/06/15 10:17:03 jacob Exp $
+\define{versionidusing} \versionid $Id$

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


@@ -93,9 +93,9 @@ value using the configuration box; see \k{config-scrollback}.
 \S{using-sysmenu} The \i{System menu}
 
 If you click the left mouse button on the icon in the top left
 \S{using-sysmenu} The \i{System menu}
 
 If you click the left mouse button on the icon in the top left

-corner of PuTTY's window, or click the right mouse button on the
-title bar, you will see the standard Windows system menu containing
-items like Minimise, Move, Size and Close.
+corner of PuTTY's terminal window, or click the right mouse button
+on the title bar, you will see the standard Windows system menu
+containing items like Minimise, Move, Size and Close.

 
 PuTTY's system menu contains extra program features in addition to
 the Windows standard options. These extra menu commands are
 
 PuTTY's system menu contains extra program features in addition to
 the Windows standard options. These extra menu commands are


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


@@ -246,9 +325,10 @@ 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
 
 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


@@ -273,6 +353,8 @@ then PuTTY cannot currently support it. If this is a problem for
 you, you should mail the PuTTY authors \#{FIXME} and give details
 (see \k{feedback}).
 
 you, you should mail the PuTTY authors \#{FIXME} and give details
 (see \k{feedback}).
 

+For more options relating to X11 forwarding, see \k{config-ssh-x11}.
+

 \H{using-port-forwarding} Using \i{port forwarding} in SSH
 
 The SSH protocol has the ability to forward arbitrary network
 \H{using-port-forwarding} Using \i{port forwarding} in SSH
 
 The SSH protocol has the ability to forward arbitrary network


@@ -350,7 +432,8 @@ your client PC can connect to the forwarded port.
 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
 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).
+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


@@ -364,6 +447,10 @@ available for local-to-remote forwarded ports; SSH1 is unable to
 support it for remote-to-local ports, while SSH2 can support it in
 theory but servers will not necessarily cooperate.
 
 support it for remote-to-local ports, while SSH2 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
+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


@@ -430,8 +517,9 @@ use the \c{-load} option (described in \k{using-cmdline-load}).
 \S{using-cleanup} \i\c{-cleanup}
 
 If invoked with the \c{-cleanup} option, rather than running as
 \S{using-cleanup} \i\c{-cleanup}
 
 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).

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


@@ -446,8 +534,7 @@ tool.
 \I{saved sessions, loading from command line}The \c{-load} option
 causes PuTTY to load configuration details out of a saved session.
 If these details include a host name, then this option is all you
 \I{saved sessions, loading from command line}The \c{-load} option
 causes PuTTY to load configuration details out of a saved session.
 If these details include a host name, then this option is all you

-need to make PuTTY start a session (although Plink still requires an
-explicitly specified host name).
+need to make PuTTY start a session.

 
 You need double quotes around the session name if it contains spaces.
 
 
 You need double quotes around the session name if it contains spaces.
 


@@ -458,7 +545,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


@@ -549,7 +636,9 @@ command} box in the SSH panel of the PuTTY configuration box (see
 \k{config-command}). However, the \c{-m} option expects to be given
 a local file name, and it will read a command from that file. On
 most Unix systems, you can even put multiple lines in this file and
 \k{config-command}). However, the \c{-m} option expects to be given
 a local file name, and it will read a command from that file. On
 most Unix systems, you can even put multiple lines in this file and

-execute more than one command in sequence, or a whole shell script.
+execute more than one command in sequence, or a whole shell script;
+but this will not work on all servers (and is known not to work
+with certain \q{embedded} servers such as routers).

 
 This option is not available in the file transfer tools PSCP and
 PSFTP.
 
 This option is not available in the file transfer tools PSCP and
 PSFTP.


@@ -627,6 +716,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


@@ -647,6 +754,16 @@ 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}).
 
 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