From ee46ef84bcb861f44717bf428701474406c5a51d Mon Sep 17 00:00:00 2001 From: simon Date: Wed, 24 Oct 2001 18:56:52 +0000 Subject: [PATCH] _Actually_ add the new-look PuTTY FAQ. When will I remember to run "cvs add"? git-svn-id: svn://svn.tartarus.org/sgt/putty@1318 cda61777-01e9-0310-a592-d414129be87e --- doc/faq.but | 622 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 622 insertions(+) create mode 100644 doc/faq.but diff --git a/doc/faq.but b/doc/faq.but new file mode 100644 index 00000000..9c2cff40 --- /dev/null +++ b/doc/faq.but @@ -0,0 +1,622 @@ +\A{faq} PuTTY FAQ + +This FAQ is published on the PuTTY web site, and also provided as an +appendix in the manual. + +\H{faq-support} Features supported in PuTTY + +In general, if you want to know if PuTTY supports a particular +feature, you should look for it on the +\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}{PuTTY web site}. +In particular: + +\b try the +\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{changes +page}, and see if you can find the feature on there. If a feature is +listed there, it's been implemented. If it's listed as a change made +\e{since} the latest version, it should be available in the +development snapshots, in which case testing will be very welcome. + +\b try the +\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist.html}{Wishlist +page}, and see if you can find the feature there. If it's on there, +it probably \e{hasn't} been implemented. + +\S{faq-ssh2} Does PuTTY support SSH v2? + +Yes. SSH v2 support has been available in PuTTY since version 0.50. +However, currently the \e{default} SSH protocol is v1; to select SSH +v2 if your server supports both, go to the SSH panel and change the +\e{Preferred SSH protocol version} option. + +Public key authentication (both RSA and DSA) in SSH v2 has been +added since version 0.51. + +\S{faq-ssh2-keyfmt} Does PuTTY support reading OpenSSH or +\cw{ssh.com} SSHv2 private key files? + +Not at present. OpenSSH and \cw{ssh.com} have totally different +formats for private key files, and neither one is particularly +pleasant, so PuTTY has its own. We do plan to write a converter at +some stage. + +\S{faq-ssh1} Does PuTTY support SSH v1? + +Yes. SSH 1 support has always been available in PuTTY. + +\S{faq-localecho} Does PuTTY support local echo? + +Yes. + +In version 0.51 and before, local echo cannot be separated from +local line editing (where you type a line of text locally, and it is +not sent to the server until you press Return, so you have the +chance to edit it and correct mistakes \e{before} the server sees +it). The two features can be enabled and disabled from the Terminal +panel, using the checkbox marked \q{Use local terminal line +discipline}. Note that due to a bug in those versions of PuTTY, +changing this feature in mid-session will have no effect; you have +to enable it \e{before} you open the connection. + +In later versions, local echo and local line editing are separate +options, and by default PuTTY will try to determine automatically +whether to enable them or not, based on which protocol you have +selected and also based on hints from the server. If you have a +problem with PuTTY's default choice, you can force each option to be +enabled or disabled as you choose. The controls are in the Terminal +panel, in the section marked \q{Line discipline options}. + +\S{faq-disksettings} Does PuTTY support storing its settings in a +disk file? + +Not at present, although \k{config-file} in the documentation gives +a method of achieving the same effect. + +\S{faq-fullscreen} Does PuTTY support full-screen mode, like a DOS +box? + +Not in the 0.51 release, but it has been added since then. + +\S{faq-password} Does PuTTY have the ability to remember my password +so I don't have to type it every time? + +No, it doesn't. + +Remembering your password is a bad plan for obvious security +reasons: anyone who gains access to your machine while you're away +from your desk can find out the remembered password, and use it, +abuse it or change it. + +In addition, it's not even \e{possible} for PuTTY to automatically +send your password in a Telnet session, because Telnet doesn't give +the client software any indication of which part of the login +process is the password prompt. PuTTY would have to guess, by +looking for words like \q{password} in the session data; and if your +login program is written in something other than English, this won't +work. + +In SSH, remembering your password would be possible in theory, but +there doesn't seem to be much point since SSH supports public key +authentication, which is more flexible and more secure. See +\k{pubkey} in the documentation for a full discussion of public key +authentication. + +\H{faq-ports} Ports to other operating systems + +The eventual goal is for PuTTY to be a multi-platform program, able +to run on at least Windows, MacOS and Unix. Whether this will +actually ever happen I have no idea, but it is the plan. A Mac port +has been started, but is only half-finished and currently not moving +very fast. + +Porting will become easier once PuTTY has a generalised porting +layer, drawing a clear line between platform-dependent and +platform-independent code. The general intention is for this porting +layer to evolve naturally as part of the process of doing the first +port. One particularly nasty part of this will be separating the +many configuration options into platform-dependent and +platform-independent ones; for example, the options controlling when +the Windows System menu appears will be pretty much meaningless +under X11 or perhaps other windowing systems, whereas Telnet Passive +Mode is universal and shouldn't need to be specified once for each +platform. + +\S{faq-wince} Will there be a port to Windows CE? + +Probably not in the particularly near future. Despite sharing large +parts of the Windows API, in practice WinCE doesn't appear to be +significantly easier to port to than a totally different operating +system. + +However, PuTTY on portable devices would clearly be a useful thing, +so in the long term I hope there will be a WinCE port. + +\S{faq-mac} Will there be a port to the Mac? + +A Mac port was started once and is half-finished, but development +has been static for some time and the main PuTTY code has moved on, +so it's not clear how quickly development would resume even if +developer effort were available. + +\S{faq-unix} Will there be a port to Unix? + +I hope so, if only so that I can have an \cw{xterm}-like program +that supports exactly the same terminal emulation as PuTTY. If and +when we do do a Unix port, it will have a local-terminal back end so +it can be used like an \cw{xterm}, rather than only being usable as +a network utility. + +\S{faq-epoc} Will there be a port to EPOC? + +I hope so, but given that ports aren't really progressing very fast +even on systems the developers \e{do} already know how to program +for, it might be a long time before any of us get round to learning +a new system and doing the port for that. + +\H{faq-embedding} Embedding PuTTY in other programs + +\S{faq-dll} Is the SSH or Telnet code available as a DLL? + +No, it isn't. It would take a reasonable amount of rewriting for +this to be possible, and since the PuTTY project itself doesn't +believe in DLLs (they make installation more error-prone) none of us +has taken the time to do it. + +Most of the code cleanup work would be a good thing to happen in +general, so if anyone feels like helping, we wouldn't say no. + +\S{faq-vb} Is the SSH or Telnet code available as a Visual Basic +component? + +No, it isn't. None of the PuTTY team uses Visual Basic, and none of +us has any particular need to make SSH connections from a Visual +Basic application. In addition, all the preliminary work to turn it +into a DLL would be necessary first; and furthermore, we don't even +know how to write VB components. + +If someone offers to do some of this work for us, we might consider +it, but unless that happens I can't see VB integration being +anywhere other than the very bottom of our priority list. + +\S{faq-ipc} How can I use PuTTY to make an SSH connection from +within another program? + +Probably your best bet is to use Plink, the command-line connection +tool. If you can start Plink as a second Windows process, and +arrange for your primary process to be able to send data to the +Plink process, and receive data from it, through pipes, then you +should be able to make SSH connections from your program. + +This is what CVS for Windows does, for example. + +\H{faq-details} Details of PuTTY's operation + +\S{faq-term} What terminal type does PuTTY use? + +For most purposes, PuTTY can be considered to be an \cw{xterm} +terminal, although full support for some of \cw{xterm}'s features, +such as passing mouse actions to the server-side program, is not +present in the 0.51 release (but has been added since). + +PuTTY also supports some terminal control sequences not supported by +the real \cw{xterm}: notably the Linux console sequences that +reconfigure the colour palette, and the title bar control sequences +used by \cw{DECterm} (which are different from the \cw{xterm} ones; +PuTTY supports both). + +By default, PuTTY announces its terminal type to the server as +\c{xterm}. If you have a problem with this, you can reconfigure it +to say something else; \c{vt220} might help if you have trouble. + +\S{faq-settings} Where does PuTTY store its data? + +PuTTY stores most of its data (saved sessions, SSH host keys) in the +Registry. The precise location is + +\c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY + +and within that area, saved sessions are stored under \c{Sessions} +while host keys are stored under \c{SshHostKeys}. + +PuTTY also requires a random number seed file, to improve the +unpredictability of randomly chosen data needed as part of the SSH +cryptography. This is stored by default in your Windows home +directory (\c{%HOMEDRIVE%\\%HOMEPATH%}), or in the actual Windows +directory (such as \c{C:\\WINDOWS}) if the home directory doesn't +exist, for example if you're using Win95. If you want to change the +location of the random number seed file, you can put your chosen +pathname in the Registry, at + +\c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\RandSeedFile + +\H{faq-howto} HOWTO questions + +\S{faq-startmax} How can I make PuTTY start up maximised? + +Create a Windows shortcut to start PuTTY from, and set it as \q{Run +Maximized}. + +\S{faq-startsess} How can I create a Windows shortcut to start a +particular saved session directly? + +To run a PuTTY session saved under the name \q{\cw{mysession}}, +create a Windows shortcut that invokes PuTTY with a command line +like + +\c \path\name\to\putty.exe @mysession + +\S{faq-startssh} How can I start an SSH session straight from the +command line? + +Use the command line \c{putty -ssh host.name}. Alternatively, create +a saved session that specifies the SSH protocol, and start the saved +session as shown in \k{faq-startsess}. + +\S{faq-cutpaste} How do I copy and paste between PuTTY and other +Windows applications? + +Copy and paste works similarly to the X Window System. You use the +left mouse button to select text in the PuTTY window. The act of +selection \e{automatically} copies the text to the clipboard: there +is no need to press Ctrl-Ins or Ctrl-C or anything else. In fact, +pressing Ctrl-C will send a Ctrl-C character to the other end of +your connection (just like it does the rest of the time), which may +have unpleasant effects. The \e{only} thing you need to do, to copy +text to the clipboard, is to select it. + +To paste the clipboard contents into a PuTTY window, by default you +click the right mouse button. If you have a three-button mouse and +are used to X applications, you can configure pasting to be done by +the middle button instead, but this is not the default because most +Windows users don't have a middle button at all. + +You can also paste by pressing Shift-Ins. + +\S{faq-pscp} How do I use PSCP.EXE? When I double-click it gives me +a command prompt window which then closes instantly. + +PSCP is a command-line application, not a GUI application. If you +run it without arguments, it will simply print a help message and +terminate. + +To use PSCP properly, run it from a Command Prompt window. See +\k{pscp} in the documentation for more details. + +\S{faq-pscp-spaces} How do I use PSCP to copy a file whose name has +spaces in? + +If PSCP is using the traditional SCP protocol, this is confusing. If +you're specifying a file at the local end, you just use one set of +quotes as you would normally do: + +\c pscp "local filename with spaces" user@host: +\c pscp user@host:myfile "local filename with spaces" + +But if the filename you're specifying is on the \e{remote} side, you +have to use backslashes and two sets of quotes: + +\c pscp user@host:"\"remote filename with spaces\"" local_filename +\c pscp local_filename user@host:"\"remote filename with spaces\"" + +Worse still, in a remote-to-local copy you have to specify the local +file name explicitly, otherwise PSCP will complain that they don't +match (unless you specified the \c{-unsafe} option). The following +command will give an error message: + +\c c:\>pscp user@host:"\"oo er\"" . +\c warning: remote host tried to write to a file called 'a b' +\c when we requested a file called '"a b"'. +\c If this is a wildcard, consider upgrading to SSH 2 or using +\c the '-unsafe' option. Renaming of this file has been disallowed. + +If PSCP is using the newer SFTP protocol, none of this is a problem, +and all filenames with spaces in are specified using a single pair +of quotes in the obvious way: + +\c pscp "local file" user@host: +\c pscp user@host:"remote file" . + +\H{faq-trouble} Troubleshooting + +\S{faq-mac} Why do I see \q{Incorrect MAC received on packet}? + +This is due to a bug in old SSH 2 servers distributed by +\cw{ssh.com}. Version 2.3.0 and below of their SSH 2 server +constructs Message Authentication Codes in the wrong way, and +expects the client to construct them in the same wrong way. PuTTY +constructs the MACs correctly by default, and hence these old +servers will fail to work with it. + +If you are using PuTTY version 0.51 or below, go to the SSH panel +and check the box labelled \q{Imitate SSH 2 MAC bug}. This will +cause PuTTY to construct its MACs in the same incorrect manner as +the buggy servers, so it will be able to work with them. + +Since version 0.51, PuTTY has been enhanced to detect buggy servers +automatically (when they announce their version) and enable the +workaround without the user needing to ask. Therefore you \e{should} +never have to use this option again after 0.52, but it is still +provided just in case another buggy server shows up. + +\S{faq-colours} I clicked on a colour in the Colours panel, and the +colour didn't change in my terminal. + +That isn't how you're supposed to use the Colours panel. + +During the course of a session, PuTTY potentially uses \e{all} the +colours listed in the Colours panel. It's not a question of using +only one of them and you choosing which one; PuTTY will use them +\e{all}. The purpose of the Colours panel is to let you adjust the +appearance of all the colours. So to change the colour of the +cursor, for example, you would select \q{Cursor Colour}, press the +\q{Modify} button, and select a new colour from the dialog box that +appeared. Similarly, if you want your session to appear in green, +you should select \q{Default Foreground} and press \q{Modify}. +Clicking on \q{ANSI Green} won't turn your session green; it will +only allow you to adjust the \e{shade} of green used when PuTTY is +instructed by the server to display green text. + +\S{faq-winsock2} Plink on Windows 95 says it can't find \cw{WS2_32.DLL}. + +Plink requires the extended Windows network library, WinSock version +2. This is installed as standard on Windows 98 and above, and on +Windows NT, and even on later versions of Windows 95; but early +Win95 installations don't have it. + +In order to use Plink on these systems, you will need to download +the +\W{http://www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/}{WinSock 2 upgrade}: + +\c http://www.microsoft.com/windows95/downloads/contents/wuadmintools/ +\c s_wunetworkingtools/w95sockets2/ + +\S{faq-rekey} My PuTTY sessions close after an hour and tell me +\q{Server failed host key check}. + +This is a bug in all versions of PuTTY up to and including 0.51. SSH +v2 servers from \cw{ssh.com} will require the key exchange to be +repeated one hour after the start of the connection, and PuTTY will +get this wrong. + +The bug has been fixed since version 0.51, so upgrading to a later +version or snapshot should solve the problem. + +\S{faq-outofmem} After trying to establish an SSH connection, PuTTY +says \q{Out of memory} and dies. + +If this happens just while the connection is starting up, this often +indicates that for some reason the client and server have failed to +establish a session encryption key. Somehow, they have performed +calculations that should have given each of them the same key, but +have ended up with different keys; so data encrypted by one and +decrypted by the other looks like random garbage. + +This causes an \q{out of memory} error because the first encrypted +data PuTTY expects to see is the length of an SSH message. Normally +this will be something well under 100 bytes. If the decryption has +failed, PuTTY will see a completely random length in the region of +two \e{gigabytes}, and will try to allocate enough memory to store +this non-existent message. This will immediately lead to it thinking +it doesn't have enough memory, and panicking. + +If this happens to you, it is quite likely to still be a PuTTY bug +and you should report it (although it might be a bug in your SSH +server instead); but it doesn't necessarily mean you've actually run +out of memory. + +\S{faq-altgr} I can't type characters that require the AltGr key. + +In PuTTY version 0.51, the AltGr key was broken. The bug has been +fixed since then. + +\S{faq-idleout} My PuTTY sessions unexpectedly close after they +are idle for a while. + +Some types of firewall, and almost any router doing Network Address +Translation (NAT, also known as IP masquerading), will forget about +a connection through them if the connection does nothing for too +long. This will cause the connection to be rudely cut off when +contact is resumed. + +You can try to combat this by telling PuTTY to send \e{keepalives}: +packets of data which have no effect on the actual session, but +which reassure the router or firewall that the network connection is +still active and worth remembering about. + +Keepalives don't solve everything, unfortunately; although they +cause greater robustness against this sort of router, they can also +cause a \e{loss} of robustness against network dropouts. See +\k{config-keepalive} in the documentation for more discussion of +this. + +\S{faq-timeout} PuTTY's network connections time out too quickly +when network connectivity is temporarily lost. + +This is a Windows problem, not a PuTTY problem. The timeout value +can't be set on per application or per session basis. To increase +the TCP timeout globally, you need to tinker with the Registry. + +On Windows 95, 98 or ME, the registry key you need to change is + +\c HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\ +\c MSTCP\MaxDataRetries + +(it must be of type DWORD in Win95, or String in Win98/ME). + +On Windows NT or 2000, the registry key is + +\c HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\ +\c Parameters\TcpMaxDataRetransmissions + +and it must be of type DWORD. + +Set the key's value to something like 10. This will cause Windows to +try harder to keep connections alive instead of abandoning them. + +\S{faq-puttyputty} When I \cw{cat} a binary file, I get +`PuTTYPuTTYPuTTY' on my command line. + +Don't \cw{cat} binary files, then. + +This is designed behaviour; when PuTTY receives the character +Control-E from the remote server, it interprets it as a request to +identify itself, and so it sends back the string \q{\cw{PuTTY}} as +if that string had been entered at the keyboard. Control-E should +only be sent by programs that are prepared to deal with the +response. Writing a binary file to your terminal is likely to output +many Control-E characters, and cause this behaviour. Don't do it. +It's a bad plan. + +\S{faq-puttyputty} When I \cw{cat} a binary file, my window title +changes to a nonsense string. + +Don't \cw{cat} binary files, then. + +It is designed behaviour that PuTTY should have the ability to +adjust the window title on instructions from the server. Normally +the control sequence that does this should only be sent +deliberately, by programs that know what they are doing and intend +to put meaningful text in the window title. Writing a binary file to +your terminal runs the risk of sending the same control sequence by +accident, and cause unexpected changes in the window title. Don't do +it. + +\H{faq-secure} Security questions + +\S{faq-publicpc} Is it safe for me to download PuTTY and use it on a +public PC? + +It depends on whether you trust that PC. If you don't trust the +public PC, don't use PuTTY on it, and don't use any other software +you plan to type passwords into either. It might be watching your +keystrokes, or it might tamper with the PuTTY binary you download. +There is \e{no} program safe enough that you can run it on an +actively malicious PC and get away with typing passwords into it. + +If you do trust the PC, then it's probably OK to use PuTTY on it +(but if you don't trust the network, then the PuTTY download might +be tampered with, so it would be better to carry PuTTY with you on a +floppy). + +\S{faq-cleanup} What does PuTTY leave on a system? How can I clean +up after it? + +PuTTY will leave some Registry entries, and a random seed file, on +the PC (see \k{faq-settings}). If you are using PuTTY on a public +PC, or somebody else's PC, you might want to clean these up when you +leave. You can do that automatically, by running the command +\c{putty -cleanup}. + +\S{faq-dsa} How come PuTTY now supports DSA, when the website used +to say how insecure it was? + +DSA has a major weakness \e{if badly implemented}: it relies on a +random number generator to far too great an extent. If the random +number generator produces a number an attacker can predict, the DSA +private key is exposed - meaning that the attacker can log in as you +on all systems that accept that key. + +The PuTTY policy changed because the developers were informed of +ways to implement DSA which do not suffer nearly as badly from this +weakness, and indeed which don't need to rely on random numbers at +all. For this reason we now believe PuTTY's DSA implementation is +probably OK. However, if you have the choice, we still recommend you +use RSA instead. + +\H{faq-admin} Administrative questions + +\S{faq-domain} Would you like me to register you a nicer domain name? + +No, thank you. Even if you can find one (most of them seem to have +been registered already, by people who didn't ask whether we +actually wanted it before they applied), we're happy with the PuTTY +web site being exactly where it is. It's not hard to find (just type +\q{putty} into \W{http://www.google.com/}{google.com} and we're the +first link returned), and we don't believe the administrative hassle +of moving the site would be worth the benefit. + +In addition, if we \e{did} want a custom domain name, we would want +to run it ourselves, so we knew for certain that it would continue +to point where we wanted it, and wouldn't suddenly change or do +strange things. Having it registered for us by a third party who we +don't even know is not the best way to achieve this. + +\S{faq-webhosting} Would you like free web hosting for the PuTTY web +site? + +We already have some, thanks. + +\S{faq-sourceforge} Why don't you move PuTTY to SourceForge? + +Partly, because we don't want to move the web site location (see +\k{faq-domain}). + +Also, security reasons. PuTTY is a security product, and as such it +is particularly important to guard the code and the web site against +unauthorised modifications which might introduce subtle security +flaws. Therefore, we prefer that the CVS repository, web site and +FTP site remain where they are, under the direct control of system +administrators we know and trust personally, rather than being run +by a large organisation full of people we've never met and which is +known to have had breakins in the past. + +No offence to SourceForge; I think they do a wonderful job. But +they're not ideal for everyone, and in particular they're not ideal +for us. + +\S{faq-mailinglist1} Why can't I subscribe to the putty-bugs mailing +list? + +Because you're not a member of the PuTTY core development team. The +putty-bugs mailing list is not a general newsgroup-like discussion +forum; it's a contact address for the core developers, and an +\e{internal} mailing list for us to discuss things among ourselves. +If we opened it up for everybody to subscribe to, it would turn into +something more like a newsgroup and we would be completely +overwhelmed by the volume of traffic. It's hard enough to keep up +with the list as it is. + +\S{faq-mailinglist2} If putty-bugs isn't a general-subscription +mailing list, what is? + +There isn't one, that we know of. + +If someone else wants to set up a mailing list for PuTTY users to +help each other with common problems, that would be fine with us; +but the PuTTY team would almost certainly not have the time to read +it, so any questions the list couldn't answer would have to be +forwarded on to us by the questioner. In any case, it's probably +better to use the established newsgroup \cw{comp.security.ssh} for +this purpose. + +\S{faq-donations} How can I donate to PuTTY development? + +Please, \e{please} don't feel you have to. PuTTY is completely free +software, and not shareware. We think it's very important that +\e{everybody} who wants to use PuTTY should be able to, whether they +have any money or not; so the last thing we would want is for a +PuTTY user to feel guilty because they haven't paid us any money. If +you want to keep your money, please do keep it. We wouldn't dream of +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 go to \W{http://www.e-gold.com}\cw{www.e-gold.com}, and 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!). + +Small donations (tens of dollars or tens of euros) will probably be +spent on beer or curry, which helps motivate our volunteer team to +continue doing this for the world. Larger donations will be spent on +something that actually helps development, if we can find anything +(perhaps new hardware, or a copy of Windows 2000), but if we can't +find anything then we'll just distribute the money among the +developers. If you want to be sure your donation is going towards +something worthwhile, ask us first. If you don't like these terms, +feel perfectly free not to donate. We don't mind. + +\S{faq-pronounce} How do I pronounce PuTTY? + +Exactly like the normal word \q{putty}. Just like the stuff you put +on window frames. (One of the reasons it's called PuTTY is because +it makes Windows usable. :-) -- 2.11.0