Been meaning to do this for years: introduce a configuration option

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

diff --git a/doc/using.but b/doc/using.but
index d0b03c4..85e2343 100644 (file)
--- a/doc/using.but
+++ b/doc/using.but
@@ -123,9 +123,13 @@ 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
 
 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
+tokens, such as a \q{break} signal, that can be sent down a

 connection in addition to normal data. Their precise effect is usually
 connection in addition to normal data. Their precise effect is usually

-up to the server. Currently only Telnet and SSH have special commands.
+up to the server. Currently only Telnet, SSH, and serial connections
+have special commands.
+
+The \q{break} signal can also be invoked from the keyboard with
+\i{Ctrl-Break}.

 
 The following \I{Telnet special commands}special commands are
 available in Telnet:
 
 The following \I{Telnet special commands}special commands are
 available in Telnet:


@@ -207,6 +211,9 @@ Only available in SSH-2, and only during a session. Sends various
 POSIX signals. Not honoured by all servers.
 }
 
 POSIX signals. Not honoured by all servers.
 }
 

+With a serial connection, the only available special command is
+\I{Break, serial special command}\q{Break}.
+

 \S2{using-newsession} Starting new sessions
 
 PuTTY's system menu provides some shortcut ways to start new
 \S2{using-newsession} Starting new sessions
 
 PuTTY's system menu provides some shortcut ways to start new


@@ -331,7 +338,7 @@ 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
 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
+X11 panel (see \k{config-ssh-x11}) before starting your SSH

 session. The \i{\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
 session. The \i{\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


@@ -460,6 +467,15 @@ theory but servers will not necessarily cooperate.
 to obtain a fix from Microsoft in order to use addresses like
 \cw{127.0.0.5} - see \k{faq-alternate-localhost}.)
 
 to obtain a fix from Microsoft in order to use addresses like
 \cw{127.0.0.5} - see \k{faq-alternate-localhost}.)
 

+For more options relating to port forwarding, see
+\k{config-ssh-portfwd}.
+
+If the connection you are forwarding over SSH is itself a second SSH
+connection made by another copy of PuTTY, you might find the
+\q{logical host name} configuration option useful to warn PuTTY of
+which host key it should be expecting. See \k{config-loghost} for
+details of this.
+

 \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


@@ -491,6 +507,37 @@ protocol}\q{Raw}, from the \q{Protocol} buttons in the \q{Session}
 configuration panel. (See \k{config-hostname}.) You can then enter a
 host name and a port number, and make the connection.
 
 configuration panel. (See \k{config-hostname}.) You can then enter a
 host name and a port number, and make the connection.
 

+\H{using-serial} Connecting to a local serial line
+
+PuTTY can connect directly to a local serial line as an alternative
+to making a network connection. In this mode, text typed into the
+PuTTY window will be sent straight out of your computer's serial
+port, and data received through that port will be displayed in the
+PuTTY window. You might use this mode, for example, if your serial
+port is connected to another computer which has a serial connection.
+
+To make a connection of this type, simply select \q{Serial} from the
+\q{Connection type} radio buttons on the \q{Session} configuration
+panel (see \k{config-hostname}). The \q{Host Name} and \q{Port}
+boxes will transform into \q{Serial line} and \q{Speed}, allowing
+you to specify which serial line to use (if your computer has more
+than one) and what speed (baud rate) to use when transferring data.
+For further configuration options (data bits, stop bits, parity,
+flow control), you can use the \q{Serial} configuration panel (see
+\k{config-serial}).
+
+After you start up PuTTY in serial mode, you might find that you
+have to make the first move, by sending some data out of the serial
+line in order to notify the device at the other end that someone is
+there for it to talk to. This probably depends on the device. If you
+start up a PuTTY serial session and nothing appears in the window,
+try pressing Return a few times and see if that helps.
+
+A serial line provides no well defined means for one end of the
+connection to notify the other that the connection is finished.
+Therefore, PuTTY in serial mode will remain connected until you
+close the window using the close button.
+

 \H{using-cmdline} The PuTTY command line
 
 PuTTY can be made to do various things without user intervention by
 \H{using-cmdline} The PuTTY command line
 
 PuTTY can be made to do various things without user intervention by


@@ -727,8 +774,7 @@ it off. These options are only meaningful if you are using SSH.
 For information on X11 forwarding, see \k{using-x-forwarding}.
 
 These options are equivalent to the X11 forwarding checkbox in the
 For information on X11 forwarding, see \k{using-x-forwarding}.
 
 These options are equivalent to the X11 forwarding checkbox in the

-Tunnels panel of the PuTTY configuration box (see
-\k{config-ssh-x11}).
+X11 panel of the PuTTY configuration box (see \k{config-ssh-x11}).

 
 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.


@@ -765,6 +811,47 @@ at all} checkbox in the SSH panel of the PuTTY configuration box
 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.
 

+\S2{using-cmdline-ncmode} \I{-nc}\c{-nc}: make a \i{remote network
+connection} in place of a remote shell or command
+
+The \c{-nc} option prevents Plink (or PuTTY) from attempting to
+start a shell or command on the remote server. Instead, it will
+instruct the remote server to open a network connection to a host
+name and port number specified by you, and treat that network
+connection as if it were the main session.
+
+You specify a host and port as an argument to the \c{-nc} option,
+with a colon separating the host name from the port number, like
+this:
+
+\c plink host1.example.com -nc host2.example.com:1234
+
+You might want to use this feature if you needed to make an SSH
+connection to a target host which you can only reach by going
+through a proxy host, and rather than using port forwarding you
+prefer to use the local proxy feature (see \k{config-proxy-type} for
+more about local proxies). In this situation you might select
+\q{Local} proxy type, set your local proxy command to be \cq{plink
+%proxyhost -nc %host:%port}, enter the target host name on the
+Session panel, and enter the directly reachable proxy host name on
+the Proxy panel.
+
+This feature is only available in SSH protocol version 2 (since the
+version 1 protocol assumes you will always want to run a shell). It
+is not available in the file transfer tools PSCP and PSFTP. It is
+available in PuTTY itself, although it is unlikely to be very useful
+in any tool other than Plink. Also, \c{-nc} uses the same server
+functionality as port forwarding, so it will not work if your server
+administrator has disabled port forwarding.
+
+(The option is named \c{-nc} after the Unix program
+\W{http://www.vulnwatch.org/netcat/}\c{nc}, short for \q{netcat}.
+The command \cq{plink host1 -nc host2:port} is very similar in
+functionality to \cq{plink host1 nc host2 port}, which invokes
+\c{nc} on the server and tells it to connect to the specified
+destination. However, Plink's built-in \c{-nc} option does not
+depend on the \c{nc} program being installed on the server.)
+

 \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


@@ -789,7 +876,8 @@ PuTTY configuration box (see \k{config-ssh-prot}).
 \i{Internet protocol version}
 
 The \c{-4} and \c{-6} options force PuTTY to use the older Internet
 \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}.
+protocol \i{IPv4} or the newer \i{IPv6} for most outgoing
+connections.

 
 These options are equivalent to selecting your preferred Internet
 protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of
 
 These options are equivalent to selecting your preferred Internet
 protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of


@@ -808,6 +896,16 @@ 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}).
 
 authentication} box in the Auth panel of the PuTTY configuration box
 (see \k{config-ssh-privkey}).
 

+\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
+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
+by a colon and a port number. See \k{config-loghost} for more detail
+on this.
+

 \S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display \i{PGP key fingerprint}s
 
 This option causes the PuTTY tools not to run as normal, but instead
 \S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display \i{PGP key fingerprint}s
 
 This option causes the PuTTY tools not to run as normal, but instead