Merge out from trunk, to keep this branch viable. We are now up to

date as of r7913. [originally from svn r7914] [r7913 == d7eda6d99c]
2025-07-01 11:32:48 -05:00 · 2008-03-10 18:48:36 +00:00
parent 12e019bafc d7eda6d99c
commit 822628246e
81 changed files with 2085 additions and 933 deletions
--- a/doc/Makefile
+++ b/doc/Makefile
@ -35,7 +35,7 @@ VERSIONIDS=vids
 endif

 CHAPTERS := $(SITE) blurb intro gs using config pscp psftp plink pubkey
-CHAPTERS += pageant errors faq feedback licence udp pgpkeys
+CHAPTERS += pageant errors faq feedback licence udp pgpkeys sshnames
 CHAPTERS += index $(VERSIONIDS)

 INPUTS = $(patsubst %,%.but,$(CHAPTERS))
@ -46,6 +46,10 @@ HALIBUT = halibut
 index.html: $(INPUTS)
 	$(HALIBUT) --text --html --winhelp $(INPUTS)

+# During formal builds it's useful to be able to build this one alone.
+putty.hlp: $(INPUTS)
+	$(HALIBUT) --winhelp $(INPUTS)
+
 putty.info: $(INPUTS)
 	$(HALIBUT) --info $(INPUTS)

--- a/doc/blurb.but
+++ b/doc/blurb.but
@ -31,6 +31,6 @@ features not described here; and the \i\cw{pterm} and command-line
 Unix-specific documentation that currently exists is the
 \I{man pages for PuTTY tools}man pages.

-\copyright This manual is copyright 2001-2007 Simon Tatham. All
+\copyright This manual is copyright 2001-2008 Simon Tatham. All
 rights reserved. You may distribute this documentation under the MIT
 licence. See \k{licence} for the licence text in full.
--- a/doc/config.but
+++ b/doc/config.but
@ -61,13 +61,6 @@ you want them saved. Then come back to the Session panel. Select the
 \q{\i{Default Settings}} entry in the saved sessions list, with a single
 click. Then press the \q{Save} button.

-\lcont{
-Note that PuTTY does not allow you to save a host name into the
-Default Settings entry. This ensures that when PuTTY is started up,
-the host name box is always empty, so a user can always just type in
-a host name and connect.
-}
-
 If there is a specific host you want to store the details of how to
 connect to, you should create a saved session, which will be
 separate from the Default Settings.
@ -375,6 +368,19 @@ option, and things might go back to normal:
 \c Second line
 \c Third line

+\S{config-lfcr} \q{Implicit LF in every CR}
+
+\cfg{winhelp-topic}{terminal.crhaslf}
+
+Most servers send two control characters, \i{CR} and \i{LF}, to start a
+\i{new line} of the screen. The CR character makes the cursor return to the
+left-hand side of the screen. The LF character makes the cursor move
+one line down (and might make the screen scroll).
+
+Some servers only send CR, and so the newly 
+written line is overwritten by the following line. This option causes 
+a line feed so that all lines are displayed.
+
 \S{config-erase} \q{Use \i{background colour} to erase screen}

 \cfg{winhelp-topic}{terminal.bce}
@ -1003,7 +1009,7 @@ The Window configuration panel allows you to control aspects of the

 \cfg{winhelp-topic}{window.size}

-The \q{\ii{Rows}} and \q{\ii{Columns}} boxes let you set the PuTTY
+The \q{\ii{Columns}} and \q{\ii{Rows}} boxes let you set the PuTTY
 window to a precise size. Of course you can also \I{window resizing}drag
 the window to a new size while a session is running.

@ -1694,8 +1700,13 @@ TCP keepalives are disabled by default.
 \cfg{winhelp-topic}{connection.ipversion}

 This option allows the user to select between the old and new
-Internet protocols and addressing schemes (\i{IPv4} and \i{IPv6}). The
-default setting is \q{Auto}, which means PuTTY will do something
+Internet protocols and addressing schemes (\i{IPv4} and \i{IPv6}).
+The selected protocol will be used for most outgoing network
+connections (including connections to \I{proxy}proxies); however,
+tunnels have their own configuration, for which see
+\k{config-ssh-portfwd-address-family}.
+
+The default setting is \q{Auto}, which means PuTTY will do something
 sensible and try to guess which protocol you wanted. (If you specify
 a literal \i{Internet address}, it will use whichever protocol that
 address implies. If you provide a \i{hostname}, it will see what kinds
@ -1808,6 +1819,11 @@ this panel affect the primary network connection forming your PuTTY
 session, and also any extra connections made as a result of SSH \i{port
 forwarding} (see \k{using-port-forwarding}).

+Note that unlike some software (such as web browsers), PuTTY does not
+attempt to automatically determine whether to use a proxy and (if so)
+which one to use for a given destination. If you need to use a proxy,
+it must always be explicitly configured.
+
 \S{config-proxy-type} Setting the proxy type

 \cfg{winhelp-topic}{proxy.type}
@ -2282,6 +2298,10 @@ exchange; the server can avoid groups known to be weak, and possibly
 invent new ones over time, without any changes required to PuTTY's
 configuration. We recommend use of this method, if possible.

+In addition, PuTTY supports \i{RSA key exchange}, which requires much less
+computational effort on the part of the client, and somewhat less on
+the part of the server, than Diffie-Hellman key exchange.
+
 If the first algorithm PuTTY finds is below the \q{warn below here}
 line, you will see a warning box when you make the connection, similar
 to that for cipher selection (see \k{config-ssh-encryption}).
@ -2404,11 +2424,12 @@ forms of simple \I{challenge/response authentication}challenge/response
 authentication available in SSH protocol version 1 only. You might use
 them if you were using \i{S/Key} \i{one-time passwords}, for example,
 or if you had a physical \i{security token} that generated responses
-to authentication challenges.
+to authentication challenges.  They can even be used to prompt for
+simple passwords.

 With this switch enabled, PuTTY will attempt these forms of
 authentication if the server is willing to try them. You will be
-presented with a challenge string (which will be different every
+presented with a challenge string (which may be different every
 time) and must supply the correct response in order to log in. If
 your server supports this, you should talk to your system
 administrator about precisely what form these challenges and
@ -2772,6 +2793,9 @@ incoming connections in both IPv4 and (if available) IPv6
 \b for a remote-to-local port forwarding, PuTTY will choose a
 sensible protocol for the outgoing connection.

+This overrides the general Internet protocol version preference
+on the Connection panel (see \k{config-address-family}).
+
 Note that some operating systems may listen for incoming connections
 in IPv4 even if you specifically asked for IPv6, because their IPv4
 and IPv6 protocol stacks are linked together. Apparently \i{Linux} does
@ -2962,6 +2986,22 @@ would expect.

 This is an SSH-2-specific bug.

+\S{config-ssh-bug-maxpkt2} \q{Ignores SSH-2 \i{maximum packet size}}
+
+\cfg{winhelp-topic}{ssh.bugs.maxpkt2}
+
+When an SSH-2 channel is set up, each end announces the maximum size
+of data packet that it is willing to receive for that channel.  Some
+servers ignore PuTTY's announcement and send packets larger than PuTTY
+is willing to accept, causing it to report \q{Incoming packet was
+garbled on decryption}.
+
+If this bug is detected, PuTTY never allows the channel's
+\i{flow-control window} to grow large enough to allow the server to
+send an over-sized packet.  If this bug is enabled when talking to a
+correct server, the session will work correctly, but download
+performance will be less than it could be.
+
 \H{config-serial} The Serial panel

 The \i{Serial} panel allows you to configure options that only apply
@ -2975,7 +3015,7 @@ The \q{Serial line to connect to} box allows you to choose which
 serial line you want PuTTY to talk to, if your computer has more
 than one serial port.

-On Windows, the first serial line is called \cw{COM1}, and if there
+On Windows, the first serial line is called \i\cw{COM1}, and if there
 is a second it is called \cw{COM2}, and so on.

 This configuration setting is also visible on the Session panel,
--- a/doc/errors.but
+++ b/doc/errors.but
@ -200,8 +200,15 @@ the various strategies we use for camouflaging passwords in transit.
 Upgrade your server, or use the workarounds described in
 \k{config-ssh-bug-ignore1} and possibly \k{config-ssh-bug-plainpw1}.

+\H{errors-no-auth} \q{No supported authentication methods available}
+
+This error indicates that PuTTY has run out of ways to authenticate
+you to an SSH server.  This may be because PuTTY has TIS or
+keyboard-interactive authentication disabled, in which case
+\k{config-ssh-tis} and \k{config-ssh-ki}.
+
 \H{errors-crc} \q{Incorrect \i{CRC} received on packet} or \q{Incorrect
-MAC received on packet}
+\i{MAC} received on packet}

 This error occurs when PuTTY decrypts an SSH packet and its checksum
 is not correct. This probably means something has gone wrong in the
@ -209,6 +216,14 @@ encryption or decryption process. It's difficult to tell from this
 error message whether the problem is in the client, in the server,
 or in between.

+In particular, if the network is corrupting data at the TCP level, it
+may only be obvious with cryptographic protocols such as SSH, which
+explicitly check the integrity of the transferred data and complain
+loudly if the checks fail. Corruption of protocols without integrity
+protection (such as HTTP) will manifest in more subtle failures (such
+as misdisplayed text or images in a web browser) which may not be
+noticed.
+
 A known server problem which can cause this error is described in
 \k{faq-openssh-bad-openssl} in the FAQ.

@ -220,9 +235,10 @@ gone wrong in the encryption or decryption process. It's difficult
 to tell from this error message whether the problem is in the client,
 in the server, or in between.

-If you get this error, one thing you could try would be to fiddle
-with the setting of \q{Miscomputes SSH-2 encryption keys} on the Bugs
-panel (see \k{config-ssh-bug-derivekey2}).
+If you get this error, one thing you could try would be to fiddle with
+the setting of \q{Miscomputes SSH-2 encryption keys} (see
+\k{config-ssh-bug-derivekey2}) or \q{Ignores SSH-2 maximum packet
+size} (see \k{config-ssh-bug-maxpkt2}) on the Bugs panel .

 Another known server problem which can cause this error is described
 in \k{faq-openssh-bad-openssl} in the FAQ.
--- a/doc/faq.but
+++ b/doc/faq.but
@ -161,7 +161,7 @@ completely is the wrong solution and we will not do it.

 If you have host keys available in the common \i\c{known_hosts} format,
 we have a script called 
-\W{http://www.tartarus.org/~simon-anonsvn/viewcvs.cgi/putty/contrib/kh2reg.py?view=markup}\c{kh2reg.py}
+\W{http://svn.tartarus.org/putty/contrib/kh2reg.py?view=markup}\c{kh2reg.py}
 to convert them to a Windows .REG file, which can be installed ahead of
 time by double-clicking or using \c{REGEDIT}.

@ -1133,8 +1133,9 @@ link to you at all.
 If you have software based on PuTTY, or specifically designed to
 interoperate with PuTTY, or in some other way of genuine interest to
 PuTTY users, then we will probably be happy to add a link to you on
-our Links page. And if you're running a mirror of the PuTTY web
-site, we're \e{definitely} interested.
+our Links page. And if you're running a particularly valuable mirror
+of the PuTTY web site, we might be interested in linking to you from
+our Mirrors page.

 \S{faq-sourceforge}{Question} Why don't you move PuTTY to
 SourceForge?
@ -1191,11 +1192,8 @@ asking for any.
 Having said all that, if you still really \e{want} to give us money,
 we won't argue :-) The easiest way for us to accept donations is if
 you send money to \cw{<anakin@pobox.com>} using PayPal
-(\W{http://www.paypal.com/}\cw{www.paypal.com}). Alternatively, if
-you don't trust PayPal, you could donate through e-gold
-(\W{http://www.e-gold.com}\cw{www.e-gold.com}): deposit your
-donation in account number 174769, then send us e-mail to let us
-know you've done so (otherwise we might not notice for months!).
+(\W{http://www.paypal.com/}\cw{www.paypal.com}). If you don't like
+PayPal, talk to us; we can probably arrange some alternative means.

 Small donations (tens of dollars or tens of euros) will probably be
 spent on beer or curry, which helps motivate our volunteer team to
--- a/doc/feedback.but
+++ b/doc/feedback.but
@ -375,18 +375,27 @@ clear that we \e{could} stop you doing this, even if we wanted to!)

 \H{feedback-mirrors} Mirroring the PuTTY web site

-\#{This paragraph also in putty-website/mirrors.html}
-Mirrors of the PuTTY web site are welcome, especially in regions not
-well covered by existing mirrors. (However, if you're in a region that is
-already well served by mirrors, you should consider whether yet another one
-will be worth the effort.) Please don't bother asking us for permission before
+\# the next two paragraphs also on the Mirrors page itself, with
+\# minor context changes
+
+If you want to set up a mirror of the PuTTY website, go ahead and
+set one up. Please don't bother asking us for permission before
 setting up a mirror. You already have permission.

-If you mail us \e{after} you have set up the mirror and checked that
-it works, and remember to let us know which country your mirror is in,
-then we'll add it to the
-\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/mirrors.html}{Mirrors
-page} on the PuTTY website.
+If the mirror is in a country where we don't already have plenty of
+mirrors, we may be willing to add it to the list on our
+\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/mirrors.html}{mirrors
+page}. Read the guidelines on that page, make sure your mirror
+works, and email us the information listed at the bottom of the
+page.
+
+Note that we do not \e{promise} to list your mirror: we get a lot of
+mirror notifications and yours may not happen to find its way to the
+top of the list.
+
+Also note that we link to all our mirror sites using the
+\c{rel="nofollow"} attribute. Running a PuTTY mirror is not intended
+to be a cheap way to gain search rankings.

 If you have technical questions about the process of mirroring, then
 you might want to mail us before setting up the mirror (see also the
--- a/doc/index.but
+++ b/doc/index.but
@ -672,8 +672,8 @@ saved sessions from
 \IM{ignore message} SSH \q{ignore} messages
 \IM{ignore message} \q{ignore} messages, in SSH

-\IM{message authentication code} message authentication code
-\IM{message authentication code} MAC (message authentication code)
+\IM{message authentication code}{MAC} message authentication code (MAC)
+\IM{message authentication code}{MAC} MAC (message authentication code)

 \IM{signatures} signature
 \IM{signatures} digital signature
--- a/doc/licence.but
+++ b/doc/licence.but
@ -2,7 +2,7 @@

 \A{licence} PuTTY \ii{Licence}

-PuTTY is \i{copyright} 1997-2007 Simon Tatham.
+PuTTY is \i{copyright} 1997-2008 Simon Tatham.

 Portions copyright Robert de Bath, Joris van Rantwijk, Delian
 Delchev, Andreas Schultz, Jeroen Massar, Wez Furlong, Nicolas Barry,
--- a/doc/plink.but
+++ b/doc/plink.but
@ -43,7 +43,7 @@ use Plink:

 \c Z:\sysosd>plink
 \c PuTTY Link: command-line connection utility
-\c Release 0.59
+\c Release 0.60
 \c Usage: plink [options] [user@]host [command]
 \c        ("host" can also be a PuTTY saved session name)
 \c Options:
--- a/doc/pscp.but
+++ b/doc/pscp.but
@ -41,7 +41,7 @@ use PSCP:

 \c Z:\owendadmin>pscp
 \c PuTTY Secure Copy client
-\c Release 0.59
+\c Release 0.60
 \c Usage: pscp [options] [user@]host:source target
 \c        pscp [options] source [source...] [user@]host:target
 \c        pscp [options] -ls [user@]host:filespec
--- a/doc/sshnames.but
+++ b/doc/sshnames.but
@ -0,0 +1,77 @@
+\define{versionidsshnames} \versionid $Id$
+
+\A{sshnames} SSH-2 names specified for PuTTY
+
+There are various parts of the SSH-2 protocol where things are specified
+using a textual name.  Names ending in \cw{@putty.projects.tartarus.org}
+are reserved for allocation by the PuTTY team.  Allocated names are
+documented here.
+
+\H{sshnames-global} Connection protocol global request name
+
+This name can be sent in a \cw{SSH_MSG_GLOBAL_REQUEST} message.
+
+\dt \cw{simple@putty.projects.tartarus.org}
+
+\dd This is sent by a client to announce that it will not have more that
+one channel open at a time in the current connection.  The intention
+is that the server, knowing this, can set the window on that one
+channel to something very large, and leave flow control to TCP.  The
+format of the request is:
+
+\lcont{
+
+\c byte      SSH_MSG_GLOBAL_REQUEST
+\c uint32    recipient channel
+\c string    "simple@putty.projects.tartarus.org"
+\c boolean   want reply
+
+}
+
+\H{sshnames-channel} Connection protocol channel request name
+
+This name can be sent in a \cw{SSH_MSG_CHANNEL_REQUEST} message.
+
+\dt \cw{winadj@putty.projects.tartarus.org}
+
+\dd PuTTY sends this request along with some
+\cw{SSH_MSG_CHANNEL_WINDOW_ADJUST} messages as part of its window-size
+tuning.  It can be sent on any type of channel.  Servers MUST treat it
+as an unrecognised request and respond with
+\cw{SSH_MSG_CHANNEL_FAILURE}.
+
+\H{sshnames-kex} Key exchange method names
+
+\dt \cw{rsa-sha1-draft-00@putty.projects.tartarus.org}
+
+\dt \cw{rsa-sha256-draft-00@putty.projects.tartarus.org}
+
+\dt \cw{rsa1024-sha1-draft-01@putty.projects.tartarus.org}
+
+\dt \cw{rsa1024-sha256-draft-01@putty.projects.tartarus.org}
+
+\dt \cw{rsa2048-sha256-draft-01@putty.projects.tartarus.org}
+
+\dt \cw{rsa1024-sha1-draft-02@putty.projects.tartarus.org}
+
+\dt \cw{rsa2048-sha512-draft-02@putty.projects.tartarus.org}
+
+\dt \cw{rsa1024-sha1-draft-03@putty.projects.tartarus.org}
+
+\dt \cw{rsa2048-sha256-draft-03@putty.projects.tartarus.org}
+
+\dt \cw{rsa1024-sha1-draft-04@putty.projects.tartarus.org}
+
+\dt \cw{rsa2048-sha256-draft-04@putty.projects.tartarus.org}
+
+\dd These appeared in various drafts of what eventually became RFC\_4432.
+They have been superseded by \cw{rsa1024-sha1} and \cw{rsa2048-sha256}.
+
+\H{sshnames-encrypt} Encryption algorithm names
+
+\dt \cw{arcfour128-draft-00@putty.projects.tartarus.org}
+
+\dt \cw{arcfour256-draft-00@putty.projects.tartarus.org}
+
+\dd These were used in drafts of what eventually became RFC\_4345.
+They have been superseded by \cw{arcfour128} and \cw{arcfour256}.
--- a/doc/using.but
+++ b/doc/using.but
@ -128,6 +128,9 @@ connection in addition to normal data. Their precise effect is usually
 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:

@ -335,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
-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
@ -464,6 +467,9 @@ 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}.
+
 \H{using-rawprot} Making \i{raw TCP connections}

 A lot of \I{debugging Internet protocols}Internet protocols are
@ -762,8 +768,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.
@ -865,7 +870,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