X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/putty/blobdiff_plain/9e201f72db4478da43d1b042639e2f294db08239..3980e64ffbb86a37d6810b004a04a21f338a408b:/doc/using.but diff --git a/doc/using.but b/doc/using.but index 663aa057..27a1c2a8 100644 --- 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 -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 -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 @@ -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 -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 -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: @@ -207,6 +215,9 @@ Only available in SSH-2, and only during a session. Sends various 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 @@ -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 -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 @@ -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. -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 @@ -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{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 @@ -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}.) +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 @@ -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. +\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 @@ -499,9 +547,9 @@ window}, or a \i{Windows shortcut}). \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}: @@ -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 -URLs} in web browsers): +URLs} in \i{web browsers}): \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}). @@ -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}, -\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: @@ -580,6 +632,8 @@ of these options: \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). @@ -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 -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. @@ -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. +\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} @@ -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 -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. @@ -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. +\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 @@ -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 -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 @@ -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}). +\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-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.