When I turned fcntls into noncloexecs in r9940, I missed one.

[sgt/putty] / doc / using.but

diff --git a/doc/using.but b/doc/using.but
index 663aa05..27a1c2a 100644 (file)
--- a/doc/using.but
+++ b/doc/using.but
@@ -55,10 +55,14 @@ PuTTY will \I{selecting lines}select a whole line or sequence of lines.
 
 If you want to select a \I{rectangular selection}rectangular region
 instead of selecting to the end of each line, you can do this by
 
 If you want to select a \I{rectangular selection}rectangular region
 instead of selecting to the end of each line, you can do this by

-holding down Alt when you make your selection. (You can also
+holding down Alt when you make your selection. You can also

 configure rectangular selection to be the default, and then holding
 configure rectangular selection to be the default, and then holding

-down Alt gives the normal behaviour instead. See
-\k{config-rectselect} for details.)
+down Alt gives the normal behaviour instead: see
+\k{config-rectselect} for details.
+
+(In some Unix environments, Alt+drag is intercepted by the window
+manager. Shift+Alt+drag should work for rectangular selection as
+well, so you could try that instead.)

 
 If you have a \i{middle mouse button}, then you can use it to
 \I{adjusting a selection}adjust an existing selection if you
 
 If you have a \i{middle mouse button}, then you can use it to
 \I{adjusting a selection}adjust an existing selection if you


@@ -123,9 +127,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 +215,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 +342,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


@@ -355,11 +366,6 @@ point at display 10 or above on the SSH server machine itself:
 If this works, you should then be able to run X applications in the
 remote session and have them display their windows on your PC.
 
 If this works, you should then be able to run X applications in the
 remote session and have them display their windows on your PC.
 

-Note that if your PC X server requires \I{X11 authentication}authentication
-to connect, 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}).
-

 For more options relating to X11 forwarding, see \k{config-ssh-x11}.
 
 \H{using-port-forwarding} Using \i{port forwarding} in SSH
 For more options relating to X11 forwarding, see \k{config-ssh-x11}.
 
 \H{using-port-forwarding} Using \i{port forwarding} in SSH


@@ -416,15 +422,17 @@ number on the \e{server} (note that most servers will not allow you
 to use \I{privileged port}port numbers under 1024 for this purpose).
 
 An alternative way to forward local connections to remote hosts is
 to use \I{privileged port}port numbers under 1024 for this purpose).
 
 An alternative way to forward local connections to remote hosts is

-to use \I{dynamic port forwarding}dynamic SOCKS proxying. For
-this, you will need to select the \q{Dynamic} radio button instead
-of \q{Local}, and then you should not enter anything into the
-\q{Destination} box (it will be ignored). This will cause PuTTY to
-listen on the port you have specified, and provide a SOCKS proxy
-service to any programs which connect to that port. So, in
-particular, you can forward other PuTTY connections through it by
-setting up the Proxy control panel (see \k{config-proxy} for
-details).
+to use \I{dynamic port forwarding}dynamic SOCKS proxying. In this
+mode, PuTTY acts as a SOCKS server, which SOCKS-aware programs can
+connect to and open forwarded connections to the destination of their
+choice, so this can be an alternative to long lists of static
+forwardings. To use this mode, you will need to select the \q{Dynamic}
+radio button instead of \q{Local}, and then you should not enter
+anything into the \q{Destination} box (it will be ignored). PuTTY will
+then listen for SOCKS connections on the port you have specified.
+Most \i{web browsers} can be configured to connect to this SOCKS proxy
+service; also, you can forward other PuTTY connections through it by
+setting up the Proxy control panel (see \k{config-proxy} for details).

 
 The source port for a forwarded connection usually does not accept
 connections from any machine except the \I{localhost}SSH client or
 
 The source port for a forwarded connection usually does not accept
 connections from any machine except the \I{localhost}SSH client or


@@ -460,6 +468,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 +508,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


@@ -499,9 +547,9 @@ window}, or a \i{Windows shortcut}).
 
 \S{using-cmdline-session} Starting a session from the command line
 
 
 \S{using-cmdline-session} Starting a session from the command line
 

-\I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}These options allow
-you to bypass the configuration window and launch straight into a
-session.
+\I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}\I\c{-serial}These
+options allow you to bypass the configuration window and launch
+straight into a session.

 
 To start a connection to a server called \c{host}:
 
 
 To start a connection to a server called \c{host}:
 


@@ -514,10 +562,14 @@ default protocol (see \k{using-cmdline-protocol}).
 
 For telnet sessions, the following alternative syntax is supported
 (this makes PuTTY suitable for use as a URL handler for \i{telnet
 
 For telnet sessions, the following alternative syntax is supported
 (this makes PuTTY suitable for use as a URL handler for \i{telnet

-URLs} in web browsers):
+URLs} in \i{web browsers}):

 
 \c putty.exe telnet://host[:port]/
 
 
 \c putty.exe telnet://host[:port]/
 

+To start a connection to a serial port, e.g. COM1:
+
+\c putty.exe -serial com1
+

 In order to start an existing saved session called \c{sessionname},
 use the \c{-load} option (described in \k{using-cmdline-load}).
 
 In order to start an existing saved session called \c{sessionname},
 use the \c{-load} option (described in \k{using-cmdline-load}).
 


@@ -567,7 +619,7 @@ must be the very first thing on the command line. This form of the
 option is deprecated.)
 
 \S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh},
 option is deprecated.)
 
 \S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh},

-\c{-telnet}, \c{-rlogin}, \c{-raw}
+\c{-telnet}, \c{-rlogin}, \c{-raw} \c{-serial}

 
 To choose which protocol you want to connect with, you can use one
 of these options:
 
 To choose which protocol you want to connect with, you can use one
 of these options:


@@ -580,6 +632,8 @@ of these options:
 
 \b \i\c{-raw} selects the raw protocol.
 
 
 \b \i\c{-raw} selects the raw protocol.
 

+\b \i\c{-serial} selects a serial connection.
+

 These options are not available in the file transfer tools PSCP and
 PSFTP (which only work with the SSH protocol).
 
 These options are not available in the file transfer tools PSCP and
 PSFTP (which only work with the SSH protocol).
 


@@ -649,11 +703,14 @@ a remote command or script from a file
 The \i\c{-m} option performs a similar function to the \q{\ii{Remote
 command}} box in the SSH panel of the PuTTY configuration box (see
 \k{config-command}). However, the \c{-m} option expects to be given
 The \i\c{-m} option performs a similar function to the \q{\ii{Remote
 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
-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).
+a local file name, and it will read a command from that file.
+
+With some servers (particularly Unix systems), you can even put
+multiple lines in this file and execute more than one command in
+sequence, or a whole shell script; but this is arguably an abuse, and
+cannot be expected to work on all servers. In particular, it is known
+\e{not} to work with certain \q{embedded} servers, such as \i{Cisco}
+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.


@@ -685,6 +742,19 @@ Note that the \c{-pw} option only works when you are using the SSH
 protocol. Due to fundamental limitations of Telnet and Rlogin, these
 protocols do not support automated password authentication.
 
 protocol. Due to fundamental limitations of Telnet and Rlogin, these
 protocols do not support automated password authentication.
 

+\S2{using-cmdline-agentauth} \i\c{-agent} and \i\c{-noagent}:
+control use of Pageant for authentication
+
+The \c{-agent} option turns on SSH authentication using Pageant, and
+\c{-noagent} turns it off. These options are only meaningful if you
+are using SSH.
+
+See \k{pageant} for general information on \i{Pageant}.
+
+These options are equivalent to the agent authentication checkbox in
+the Auth panel of the PuTTY configuration box (see
+\k{config-ssh-tryagent}).
+

 \S2{using-cmdline-agent} \I{-A-upper}\c{-A} and \i\c{-a}: control \i{agent
 forwarding}
 
 \S2{using-cmdline-agent} \I{-A-upper}\c{-A} and \i\c{-a}: control \i{agent
 forwarding}
 


@@ -711,8 +781,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.


@@ -749,6 +818,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


@@ -773,7 +883,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


@@ -792,8 +903,42 @@ 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
 to display the fingerprints of the PuTTY PGP Master Keys, in order to
 aid with \i{verifying new versions}. See \k{pgpkeys} for more information.
 \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
 to display the fingerprints of the PuTTY PGP Master Keys, in order to
 aid with \i{verifying new versions}. See \k{pgpkeys} for more information.

+
+\S2{using-cmdline-sercfg} \i\c{-sercfg}: specify serial port
+\i{configuration}
+
+This option specifies the configuration parameters for the serial
+port (baud rate, stop bits etc). Its argument is interpreted as a
+comma-separated list of configuration options, which can be as
+follows:
+
+\b Any single digit from 5 to 9 sets the number of data bits.
+
+\b \cq{1}, \cq{1.5} or \cq{2} sets the number of stop bits.
+
+\b Any other numeric string is interpreted as a baud rate.
+
+\b A single lower-case letter specifies the parity: \cq{n} for none,
+\cq{o} for odd, \cq{e} for even, \cq{m} for mark and \cq{s} for space.
+
+\b A single upper-case letter specifies the flow control: \cq{N} for
+none, \cq{X} for XON/XOFF, \cq{R} for RTS/CTS and \cq{D} for
+DSR/DTR.
+
+For example, \cq{-sercfg 19200,8,n,1,N} denotes a baud rate of
+19200, 8 data bits, no parity, 1 stop bit and no flow control.