1 \define{versionidfaq} \versionid $Id$
5 This FAQ is published on the PuTTY web site, and also provided as an
6 appendix in the manual.
8 \H{faq-intro} Introduction
10 \S{faq-what}{Question} What is PuTTY?
12 PuTTY is a client program for the SSH, Telnet and Rlogin network
15 These protocols are all used to run a remote session on a computer,
16 over a network. PuTTY implements the client end of that session: the
17 end at which the session is displayed, rather than the end at which
20 In really simple terms: you run PuTTY on a Windows machine, and tell
21 it to connect to (for example) a Unix machine. PuTTY opens a window.
22 Then, anything you type into that window is sent straight to the
23 Unix machine, and everything the Unix machine sends back is
24 displayed in the window. So you can work on the Unix machine as if
25 you were sitting at its console, while actually sitting somewhere
28 \H{faq-support} Features supported in PuTTY
30 In general, if you want to know if PuTTY supports a particular
31 feature, you should look for it on the
32 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}{PuTTY web site}.
36 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{changes
37 page}, and see if you can find the feature on there. If a feature is
38 listed there, it's been implemented. If it's listed as a change made
39 \e{since} the latest version, it should be available in the
40 development snapshots, in which case testing will be very welcome.
43 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/}{Wishlist
44 page}, and see if you can find the feature there. If it's on there,
45 and not in the \q{Recently fixed} section, it probably \e{hasn't} been
48 \S{faq-ssh2}{Question} Does PuTTY support SSH v2?
50 Yes. SSH v2 support has been available in PuTTY since version 0.50.
52 Public key authentication (both RSA and DSA) in SSH v2 is new in
55 \S{faq-ssh2-keyfmt}{Question} Does PuTTY support reading OpenSSH or
56 \cw{ssh.com} SSHv2 private key files?
58 PuTTY doesn't support this natively, but as of 0.53
59 PuTTYgen can convert both OpenSSH and \cw{ssh.com} private key
60 files into PuTTY's format.
62 \S{faq-ssh1}{Question} Does PuTTY support SSH v1?
64 Yes. SSH 1 support has always been available in PuTTY.
66 \S{faq-localecho}{Question} Does PuTTY support local echo?
68 Yes. Version 0.52 has proper support for local echo.
70 In version 0.51 and before, local echo could not be separated from
71 local line editing (where you type a line of text locally, and it is
72 not sent to the server until you press Return, so you have the
73 chance to edit it and correct mistakes \e{before} the server sees
74 it). New in version 0.52, local echo and local line editing are
75 separate options, and by default PuTTY will try to determine
76 automatically whether to enable them or not, based on which protocol
77 you have selected and also based on hints from the server. If you
78 have a problem with PuTTY's default choice, you can force each
79 option to be enabled or disabled as you choose. The controls are in
80 the Terminal panel, in the section marked \q{Line discipline
83 \S{faq-savedsettings}{Question} Does PuTTY support storing settings,
84 so I don't have to change them every time?
86 Yes, all of PuTTY's settings can be saved in named session profiles.
87 See \k{config-saving} in the documentation for how to do this.
89 \S{faq-disksettings}{Question} Does PuTTY support storing its
90 settings in a disk file?
92 Not at present, although \k{config-file} in the documentation gives
93 a method of achieving the same effect.
95 \S{faq-fullscreen}{Question} Does PuTTY support full-screen mode,
98 Yes; this is a new feature in version 0.52.
100 \S{faq-password-remember}{Question} Does PuTTY have the ability to
101 remember my password so I don't have to type it every time?
105 Remembering your password is a bad plan for obvious security
106 reasons: anyone who gains access to your machine while you're away
107 from your desk can find out the remembered password, and use it,
108 abuse it or change it.
110 In addition, it's not even \e{possible} for PuTTY to automatically
111 send your password in a Telnet session, because Telnet doesn't give
112 the client software any indication of which part of the login
113 process is the password prompt. PuTTY would have to guess, by
114 looking for words like \q{password} in the session data; and if your
115 login program is written in something other than English, this won't
118 In SSH, remembering your password would be possible in theory, but
119 there doesn't seem to be much point since SSH supports public key
120 authentication, which is more flexible and more secure. See
121 \k{pubkey} in the documentation for a full discussion of public key
124 \S{faq-hostkeys}{Question} Is there an option to turn off the
125 annoying host key prompts?
127 No, there isn't. And there won't be. Even if you write it yourself
128 and send us the patch, we won't accept it.
130 Those annoying host key prompts are the \e{whole point} of SSH.
131 Without them, all the cryptographic technology SSH uses to secure
132 your session is doing nothing more than making an attacker's job
133 slightly harder; instead of sitting between you and the server with
134 a packet sniffer, the attacker must actually subvert a router and
135 start modifying the packets going back and forth. But that's not all
136 that much harder than just sniffing; and without host key checking,
137 it will go completely undetected by client or server.
139 Host key checking is your guarantee that the encryption you put on
140 your data at the client end is the \e{same} encryption taken off the
141 data at the server end; it's your guarantee that it hasn't been
142 removed and replaced somewhere on the way. Host key checking makes
143 the attacker's job \e{astronomically} hard, compared to packet
144 sniffing, and even compared to subverting a router. Instead of
145 applying a little intelligence and keeping an eye on Bugtraq, the
146 attacker must now perform a brute-force attack against at least one
147 military-strength cipher. That insignificant host key prompt really
148 does make \e{that} much difference.
150 If you're having a specific problem with host key checking - perhaps
151 you want an automated batch job to make use of PSCP or Plink, and
152 the interactive host key prompt is hanging the batch process - then
153 the right way to fix it is to add the correct host key to the
154 Registry in advance. That way, you retain the \e{important} feature
155 of host key checking: the right key will be accepted and the wrong
156 ones will not. Adding an option to turn host key checking off
157 completely is the wrong solution and we will not do it.
159 If you have host keys available in the common \c{known_hosts} format,
160 we have a script called
161 \W{http://www.tartarus.org/~simon-anonsvn/viewcvs.cgi/putty/contrib/kh2reg.py?view=markup}\c{kh2reg.py}
162 to convert them to a Windows .REG file, which can be installed ahead of
163 time by double-clicking or using \c{REGEDIT}.
165 \S{faq-server}{Question} Will you write an SSH server for the PuTTY
166 suite, to go with the client?
168 No. The only reason we might want to would be if we could easily
169 re-use existing code and significantly cut down the effort. We don't
170 believe this is the case; there just isn't enough common ground
171 between an SSH client and server to make it worthwhile.
173 If someone else wants to use bits of PuTTY in the process of writing
174 a Windows SSH server, they'd be perfectly welcome to of course, but
175 I really can't see it being a lot less effort for us to do that than
176 it would be for us to write a server from the ground up. We don't
177 have time, and we don't have motivation. The code is available if
178 anyone else wants to try it.
180 \S{faq-pscp-ascii}{Question} Can PSCP or PSFTP transfer files in
185 Until recently, this was a limitation of the file transfer protocols:
186 the SCP and SFTP protocols had no notion of transferring a file in
187 anything other than binary mode. (This is still true of SCP.)
189 The current draft protocol spec of SFTP proposes a means of
190 implementing ASCII transfer. At some point PSCP/PSFTP may implement
193 \H{faq-ports} Ports to other operating systems
195 The eventual goal is for PuTTY to be a multi-platform program, able
196 to run on at least Windows, Mac OS and Unix.
198 Porting will become easier once PuTTY has a generalised porting
199 layer, drawing a clear line between platform-dependent and
200 platform-independent code. The general intention was for this
201 porting layer to evolve naturally as part of the process of doing
202 the first port; a Unix port has now been released and the plan
203 seems to be working so far.
205 \S{faq-ports-general}{Question} What ports of PuTTY exist?
207 Currently, release versions of PuTTY tools only run on full Win32
208 systems and Unix. \q{Win32} includes Windows 95, 98, and ME, and it
209 includes Windows NT, Windows 2000 and Windows XP.
211 In the development code, a partial port to the Mac OS (see
212 \k{faq-mac-port}) is under way.
214 Currently PuTTY does \e{not} run on Windows CE (see \k{faq-wince}),
215 and it does not quite run on the Win32s environment under Windows
216 3.1 (see \k{faq-win31}).
218 We do not have release-quality ports for any other systems at the
219 present time. If anyone told you we had an EPOC port, or an iPaq port,
220 or any other port of PuTTY, they were mistaken. We don't.
222 There are some third-party ports to various platforms, mentioned
223 on the Links page of our website.
225 \S{faq-unix}{Question} Is there a port to Unix?
227 As of 0.54, there are Unix ports of most of the traditional PuTTY
228 tools, and also one entirely new application.
230 If you look at the source release, you should find a \c{unix}
231 subdirectory containing \c{Makefile.gtk}, which should build you Unix
232 ports of Plink, PuTTY itself, PuTTYgen, PSCP, PSFTP, and also
233 \c{pterm} - an \cw{xterm}-type program which supports the same
234 terminal emulation as PuTTY. We do not yet have a Unix port of
237 If you don't have Gtk, you should still be able to build the
240 Note that Unix PuTTY has mostly only been tested on Linux so far;
241 portability problems such as BSD-style ptys or different header file
242 requirements are expected.
244 \S{faq-unix-why}{Question} What's the point of the Unix port? Unix
247 All sorts of little things. \c{pterm} is directly useful to anyone
248 who prefers PuTTY's terminal emulation to \c{xterm}'s, which at
249 least some people do. Unix Plink has apparently found a niche among
250 people who find the complexity of OpenSSL makes OpenSSH hard to
251 install (and who don't mind Plink not having as many features). Some
252 users want to generate a large number of SSH keys on Unix and then
253 copy them all into PuTTY, and the Unix PuTTYgen should allow them to
254 automate that conversion process.
256 There were development advantages as well; porting PuTTY to Unix was
257 a valuable path-finding effort for other future ports, and also
258 allowed us to use the excellent Linux tool
259 \W{http://valgrind.kde.org/}{Valgrind} to help with debugging, which
260 has already improved PuTTY's stability on \e{all} platforms.
262 However, if you're a Unix user and you can see no reason to switch
263 from OpenSSH to PuTTY/Plink, then you're probably right. We don't
264 expect our Unix port to be the right thing for everybody.
266 \S{faq-wince}{Question} Will there be a port to Windows CE or PocketPC?
268 It's currently being worked on, but it's only in its early stages yet,
269 and certainly isn't yet useful. PuTTY on portable devices would
270 clearly be a useful thing, so in the long term I hope it can be
271 brought up to release quality.
273 There's also a third-party port at
274 \W{http://pocketputty.duxy.net/}\c{http://pocketputty.duxy.net/}.
276 \S{faq-win31}{Question} Is there a port to Windows 3.1?
278 PuTTY is a 32-bit application from the ground up, so it won't run on
279 Windows 3.1 as a native 16-bit program; and it would be \e{very}
280 hard to port it to do so, because of Windows 3.1's vile memory
281 allocation mechanisms.
283 However, it is possible in theory to compile the existing PuTTY
284 source in such a way that it will run under Win32s (an extension to
285 Windows 3.1 to let you run 32-bit programs). In order to do this
286 you'll need the right kind of C compiler - modern versions of Visual
287 C at least have stopped being backwards compatible to Win32s. Also,
288 the last time we tried this it didn't work very well.
290 If you're interested in running PuTTY under Windows 3.1, help and
291 testing in this area would be very welcome!
293 \S{faq-mac-port}{Question} Will there be a port to the Mac?
295 There are several answers to this question:
297 \b The Unix/Gtk port is already fully working under Mac OS X as an X11
300 \b A native (Cocoa) Mac OS X port is in progress. It's just about
301 usable, but is of nowhere near release quality yet, and is likely to
302 behave in unexpected ways.
304 \b A separate port to the classic Mac OS (pre-OSX) is also in
305 progress; it too is not ready yet.
307 \S{faq-epoc}{Question} Will there be a port to EPOC?
309 I hope so, but given that ports aren't really progressing very fast
310 even on systems the developers \e{do} already know how to program
311 for, it might be a long time before any of us get round to learning
312 a new system and doing the port for that.
314 However, some of the work has been done by other people, and a beta
315 port of PuTTY for the Nokia 9200 Communicator series is available
316 from \W{http://s2putty.sourceforge.net/}\cw{http://s2putty.sourceforge.net/}
318 \H{faq-embedding} Embedding PuTTY in other programs
320 \S{faq-dll}{Question} Is the SSH or Telnet code available as a DLL?
322 No, it isn't. It would take a reasonable amount of rewriting for
323 this to be possible, and since the PuTTY project itself doesn't
324 believe in DLLs (they make installation more error-prone) none of us
325 has taken the time to do it.
327 Most of the code cleanup work would be a good thing to happen in
328 general, so if anyone feels like helping, we wouldn't say no.
330 \S{faq-vb}{Question} Is the SSH or Telnet code available as a Visual
333 No, it isn't. None of the PuTTY team uses Visual Basic, and none of
334 us has any particular need to make SSH connections from a Visual
335 Basic application. In addition, all the preliminary work to turn it
336 into a DLL would be necessary first; and furthermore, we don't even
337 know how to write VB components.
339 If someone offers to do some of this work for us, we might consider
340 it, but unless that happens I can't see VB integration being
341 anywhere other than the very bottom of our priority list.
343 \S{faq-ipc}{Question} How can I use PuTTY to make an SSH connection
344 from within another program?
346 Probably your best bet is to use Plink, the command-line connection
347 tool. If you can start Plink as a second Windows process, and
348 arrange for your primary process to be able to send data to the
349 Plink process, and receive data from it, through pipes, then you
350 should be able to make SSH connections from your program.
352 This is what CVS for Windows does, for example.
354 \H{faq-details} Details of PuTTY's operation
356 \S{faq-term}{Question} What terminal type does PuTTY use?
358 For most purposes, PuTTY can be considered to be an \cw{xterm}
361 PuTTY also supports some terminal control sequences not supported by
362 the real \cw{xterm}: notably the Linux console sequences that
363 reconfigure the colour palette, and the title bar control sequences
364 used by \cw{DECterm} (which are different from the \cw{xterm} ones;
365 PuTTY supports both).
367 By default, PuTTY announces its terminal type to the server as
368 \c{xterm}. If you have a problem with this, you can reconfigure it
369 to say something else; \c{vt220} might help if you have trouble.
371 \S{faq-settings}{Question} Where does PuTTY store its data?
373 On Windows, PuTTY stores most of its data (saved sessions, SSH host
374 keys) in the Registry. The precise location is
376 \c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
378 and within that area, saved sessions are stored under \c{Sessions}
379 while host keys are stored under \c{SshHostKeys}.
381 PuTTY also requires a random number seed file, to improve the
382 unpredictability of randomly chosen data needed as part of the SSH
383 cryptography. This is stored by default in your Windows home
384 directory (\c{%HOMEDRIVE%\\%HOMEPATH%}), or in the actual Windows
385 directory (such as \c{C:\\WINDOWS}) if the home directory doesn't
386 exist, for example if you're using Win95. If you want to change the
387 location of the random number seed file, you can put your chosen
388 pathname in the Registry, at
390 \c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\RandSeedFile
392 On Unix, PuTTY stores all of this data in a directory \cw{~/.putty}.
394 \H{faq-howto} HOWTO questions
396 \S{faq-commands}{Question} What commands can I type into my PuTTY
399 This is not a question you should be asking \e{us}. You need to read
400 the manuals, or ask the administrator, of \e{the computer you have
403 PuTTY does not process the commands you type into it. It's only a
404 communications tool. It makes a connection to another computer; it
405 passes the commands you type to that other computer; and it passes
406 the other computer's responses back to you. Therefore, the precise
407 range of commands you can use will not depend on PuTTY, but on what
408 kind of computer you have connected to and what software is running
409 on it. The PuTTY team cannot help you with that.
411 (Think of PuTTY as being a bit like a telephone. If you phone
412 somebody up and you don't know what language to speak to make them
413 understand you, it isn't \e{the telephone company}'s job to find
414 that out for you. We just provide the means for you to get in touch;
415 making yourself understood is somebody else's problem.)
417 If you are unsure of where to start looking for the administrator of
418 your server, a good place to start might be to remember how you
419 found out the host name in the PuTTY configuration. If you were
420 given that host name by e-mail, for example, you could try asking
421 the person who sent you that e-mail. If your company's IT department
422 provided you with ready-made PuTTY saved sessions, then that IT
423 department can probably also tell you something about what commands
424 you can type during those sessions. But the PuTTY maintainer team
425 does not administer any server you are likely to be connecting to,
426 and cannot help you with questions of this type.
428 \S{faq-startmax}{Question} How can I make PuTTY start up maximised?
430 Create a Windows shortcut to start PuTTY from, and set it as \q{Run
433 \S{faq-startsess}{Question} How can I create a Windows shortcut to
434 start a particular saved session directly?
436 To run a PuTTY session saved under the name \q{\cw{mysession}},
437 create a Windows shortcut that invokes PuTTY with a command line
440 \c \path\name\to\putty.exe -load mysession
442 (Note: prior to 0.53, the syntax was \c{@session}. This is now
443 deprecated and may be removed at some point.)
445 \S{faq-startssh}{Question} How can I start an SSH session straight
446 from the command line?
448 Use the command line \c{putty -ssh host.name}. Alternatively, create
449 a saved session that specifies the SSH protocol, and start the saved
450 session as shown in \k{faq-startsess}.
452 \S{faq-cutpaste}{Question} How do I copy and paste between PuTTY and
453 other Windows applications?
455 Copy and paste works similarly to the X Window System. You use the
456 left mouse button to select text in the PuTTY window. The act of
457 selection \e{automatically} copies the text to the clipboard: there
458 is no need to press Ctrl-Ins or Ctrl-C or anything else. In fact,
459 pressing Ctrl-C will send a Ctrl-C character to the other end of
460 your connection (just like it does the rest of the time), which may
461 have unpleasant effects. The \e{only} thing you need to do, to copy
462 text to the clipboard, is to select it.
464 To paste the clipboard contents into a PuTTY window, by default you
465 click the right mouse button. If you have a three-button mouse and
466 are used to X applications, you can configure pasting to be done by
467 the middle button instead, but this is not the default because most
468 Windows users don't have a middle button at all.
470 You can also paste by pressing Shift-Ins.
472 \S{faq-options}{Question} How do I use all PuTTY's features (public
473 keys, proxying, cipher selection, etc.) in PSCP, PSFTP and Plink?
475 Most major features (e.g., public keys, port forwarding) are available
476 through command line options. See the documentation.
478 Not all features are accessible from the command line yet, although
479 we'd like to fix this. In the meantime, you can use most of
480 PuTTY's features if you create a PuTTY saved session, and then use
481 the name of the saved session on the command line in place of a
482 hostname. This works for PSCP, PSFTP and Plink (but don't expect
483 port forwarding in the file transfer applications!).
485 \S{faq-pscp}{Question} How do I use PSCP.EXE? When I double-click it
486 gives me a command prompt window which then closes instantly.
488 PSCP is a command-line application, not a GUI application. If you
489 run it without arguments, it will simply print a help message and
492 To use PSCP properly, run it from a Command Prompt window. See
493 \k{pscp} in the documentation for more details.
495 \S{faq-pscp-spaces}{Question} How do I use PSCP to copy a file whose
498 If PSCP is using the traditional SCP protocol, this is confusing. If
499 you're specifying a file at the local end, you just use one set of
500 quotes as you would normally do:
502 \c pscp "local filename with spaces" user@host:
503 \c pscp user@host:myfile "local filename with spaces"
505 But if the filename you're specifying is on the \e{remote} side, you
506 have to use backslashes and two sets of quotes:
508 \c pscp user@host:"\"remote filename with spaces\"" local_filename
509 \c pscp local_filename user@host:"\"remote filename with spaces\""
511 Worse still, in a remote-to-local copy you have to specify the local
512 file name explicitly, otherwise PSCP will complain that they don't
513 match (unless you specified the \c{-unsafe} option). The following
514 command will give an error message:
516 \c c:\>pscp user@host:"\"oo er\"" .
517 \c warning: remote host tried to write to a file called 'oo er'
518 \c when we requested a file called '"oo er"'.
520 Instead, you need to specify the local file name in full:
522 \c c:\>pscp user@host:"\"oo er\"" "oo er"
524 If PSCP is using the newer SFTP protocol, none of this is a problem,
525 and all filenames with spaces in are specified using a single pair
526 of quotes in the obvious way:
528 \c pscp "local file" user@host:
529 \c pscp user@host:"remote file" .
531 \H{faq-trouble} Troubleshooting
533 \S{faq-incorrect-mac}{Question} Why do I see \q{Incorrect MAC
536 One possible cause of this that used to be common is a bug in old
537 SSH 2 servers distributed by \cw{ssh.com}. (This is not the only
538 possible cause; see \k{errors-crc} in the documentation.)
539 Version 2.3.0 and below of their SSH 2 server
540 constructs Message Authentication Codes in the wrong way, and
541 expects the client to construct them in the same wrong way. PuTTY
542 constructs the MACs correctly by default, and hence these old
543 servers will fail to work with it.
545 If you are using PuTTY version 0.52 or better, this should work
546 automatically: PuTTY should detect the buggy servers from their
547 version number announcement, and automatically start to construct
548 its MACs in the same incorrect manner as they do, so it will be able
551 If you are using PuTTY version 0.51 or below, you can enable the
552 workaround by going to the SSH panel and ticking the box labelled
553 \q{Imitate SSH 2 MAC bug}. It's possible that you might have to do
554 this with 0.52 as well, if a buggy server exists that PuTTY doesn't
557 In this context MAC stands for Message Authentication Code. It's a
558 cryptographic term, and it has nothing at all to do with Ethernet
559 MAC (Media Access Control) addresses.
561 \S{faq-pscp-protocol}{Question} Why do I see \q{Fatal: Protocol
562 error: Expected control record} in PSCP?
564 This happens because PSCP was expecting to see data from the server
565 that was part of the PSCP protocol exchange, and instead it saw data
566 that it couldn't make any sense of at all.
568 This almost always happens because the startup scripts in your
569 account on the server machine are generating output. This is
570 impossible for PSCP, or any other SCP client, to work around. You
571 should never use startup files (\c{.bashrc}, \c{.cshrc} and so on)
572 which generate output in non-interactive sessions.
574 This is not actually a PuTTY problem. If PSCP fails in this way,
575 then all other SCP clients are likely to fail in exactly the same
576 way. The problem is at the server end.
578 \S{faq-colours}{Question} I clicked on a colour in the Colours
579 panel, and the colour didn't change in my terminal.
581 That isn't how you're supposed to use the Colours panel.
583 During the course of a session, PuTTY potentially uses \e{all} the
584 colours listed in the Colours panel. It's not a question of using
585 only one of them and you choosing which one; PuTTY will use them
586 \e{all}. The purpose of the Colours panel is to let you adjust the
587 appearance of all the colours. So to change the colour of the
588 cursor, for example, you would select \q{Cursor Colour}, press the
589 \q{Modify} button, and select a new colour from the dialog box that
590 appeared. Similarly, if you want your session to appear in green,
591 you should select \q{Default Foreground} and press \q{Modify}.
592 Clicking on \q{ANSI Green} won't turn your session green; it will
593 only allow you to adjust the \e{shade} of green used when PuTTY is
594 instructed by the server to display green text.
596 \S{faq-winsock2}{Question} Plink on Windows 95 says it can't find
599 Plink requires the extended Windows network library, WinSock version
600 2. This is installed as standard on Windows 98 and above, and on
601 Windows NT, and even on later versions of Windows 95; but early
602 Win95 installations don't have it.
604 In order to use Plink on these systems, you will need to download
606 \W{http://www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/}{WinSock 2 upgrade}:
608 \c http://www.microsoft.com/windows95/downloads/contents/
609 \c wuadmintools/s_wunetworkingtools/w95sockets2/
611 \S{faq-outofmem}{Question} After trying to establish an SSH 2
612 connection, PuTTY says \q{Out of memory} and dies.
614 If this happens just while the connection is starting up, this often
615 indicates that for some reason the client and server have failed to
616 establish a session encryption key. Somehow, they have performed
617 calculations that should have given each of them the same key, but
618 have ended up with different keys; so data encrypted by one and
619 decrypted by the other looks like random garbage.
621 This causes an \q{out of memory} error because the first encrypted
622 data PuTTY expects to see is the length of an SSH message. Normally
623 this will be something well under 100 bytes. If the decryption has
624 failed, PuTTY will see a completely random length in the region of
625 two \e{gigabytes}, and will try to allocate enough memory to store
626 this non-existent message. This will immediately lead to it thinking
627 it doesn't have enough memory, and panicking.
629 If this happens to you, it is quite likely to still be a PuTTY bug
630 and you should report it (although it might be a bug in your SSH
631 server instead); but it doesn't necessarily mean you've actually run
634 \S{faq-outofmem2}{Question} When attempting a file transfer, either
635 PSCP or PSFTP says \q{Out of memory} and dies.
637 This is almost always caused by your login scripts on the server
638 generating output. PSCP or PSFTP will receive that output when they
639 were expecting to see the start of a file transfer protocol, and
640 they will attempt to interpret the output as file-transfer protocol.
641 This will usually lead to an \q{out of memory} error for much the
642 same reasons as given in \k{faq-outofmem}.
644 This is a setup problem in your account on your server, \e{not} a
645 PSCP/PSFTP bug. Your login scripts should \e{never} generate output
646 during non-interactive sessions; secure file transfer is not the
647 only form of remote access that will break if they do.
649 On Unix, a simple fix is to ensure that all the parts of your login
650 script that might generate output are in \c{.profile} (if you use a
651 Bourne shell derivative) or \c{.login} (if you use a C shell).
652 Putting them in more general files such as \c{.bashrc} or \c{.cshrc}
653 is liable to lead to problems.
655 \S{faq-psftp-slow}{Question} PSFTP transfers files much slower than PSCP.
657 The throughput of PSFTP 0.54 should be much better than 0.53b and
658 prior; we've added code to the SFTP backend to queue several blocks
659 of data rather than waiting for an acknowledgement for each. (The
660 SCP backend did not suffer from this performance issue because SCP
661 is a much simpler protocol.)
663 \S{faq-bce}{Question} When I run full-colour applications, I see
664 areas of black space where colour ought to be, or vice versa.
666 You almost certainly need to change the \q{Use background colour to
667 erase screen} setting in the Terminal panel. If there is too much
668 black space (the commoner situation), you should enable it, while if
669 there is too much colour, you should disable it. (See \k{config-erase}.)
671 In old versions of PuTTY, this was disabled by default, and would not
672 take effect until you reset the terminal (see \k{faq-resetterm}).
673 Since 0.54, it is enabled by default, and changes take effect
676 \S{faq-resetterm}{Question} When I change some terminal settings,
679 Some of the terminal options (notably Auto Wrap and
680 background-colour screen erase) actually represent the \e{default}
681 setting, rather than the currently active setting. The server can
682 send sequences that modify these options in mid-session, but when
683 the terminal is reset (by server action, or by you choosing \q{Reset
684 Terminal} from the System menu) the defaults are restored.
686 In versions 0.53b and prior, if you change one of these options in
687 the middle of a session, you will find that the change does not
688 immediately take effect. It will only take effect once you reset
691 In version 0.54, the behaviour has changed - changes to these
692 settings take effect immediately.
694 \S{faq-idleout}{Question} My PuTTY sessions unexpectedly close after
695 they are idle for a while.
697 Some types of firewall, and almost any router doing Network Address
698 Translation (NAT, also known as IP masquerading), will forget about
699 a connection through them if the connection does nothing for too
700 long. This will cause the connection to be rudely cut off when
703 You can try to combat this by telling PuTTY to send \e{keepalives}:
704 packets of data which have no effect on the actual session, but
705 which reassure the router or firewall that the network connection is
706 still active and worth remembering about.
708 Keepalives don't solve everything, unfortunately; although they
709 cause greater robustness against this sort of router, they can also
710 cause a \e{loss} of robustness against network dropouts. See
711 \k{config-keepalive} in the documentation for more discussion of
714 \S{faq-timeout}{Question} PuTTY's network connections time out too
715 quickly when network connectivity is temporarily lost.
717 This is a Windows problem, not a PuTTY problem. The timeout value
718 can't be set on per application or per session basis. To increase
719 the TCP timeout globally, you need to tinker with the Registry.
721 On Windows 95, 98 or ME, the registry key you need to create or
724 \c HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\
725 \c MSTCP\MaxDataRetries
727 (it must be of type DWORD in Win95, or String in Win98/ME).
728 (See MS Knowledge Base article
729 \W{http://support.microsoft.com/default.aspx?scid=kb;en-us;158474}{158474}
730 for more information.)
732 On Windows NT or 2000, the registry key is
734 \c HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\
735 \c Parameters\TcpMaxDataRetransmissions
737 and it must be of type DWORD.
738 (See MS Knowledge Base article
739 \W{http://support.microsoft.com/default.aspx?scid=kb;en-us;120642}{120642}
740 for more information.)
742 Set the key's value to something like 10. This will cause Windows to
743 try harder to keep connections alive instead of abandoning them.
745 \S{faq-puttyputty}{Question} When I \cw{cat} a binary file, I get
746 \q{PuTTYPuTTYPuTTY} on my command line.
750 This is designed behaviour; when PuTTY receives the character
751 Control-E from the remote server, it interprets it as a request to
752 identify itself, and so it sends back the string \q{\cw{PuTTY}} as
753 if that string had been entered at the keyboard. Control-E should
754 only be sent by programs that are prepared to deal with the
755 response. Writing a binary file to your terminal is likely to output
756 many Control-E characters, and cause this behaviour. Don't do it.
759 To mitigate the effects, you could configure the answerback string
760 to be empty (see \k{config-answerback}); but writing binary files to
761 your terminal is likely to cause various other unpleasant behaviour,
762 so this is only a small remedy.
764 \S{faq-wintitle}{Question} When I \cw{cat} a binary file, my window
765 title changes to a nonsense string.
769 It is designed behaviour that PuTTY should have the ability to
770 adjust the window title on instructions from the server. Normally
771 the control sequence that does this should only be sent
772 deliberately, by programs that know what they are doing and intend
773 to put meaningful text in the window title. Writing a binary file to
774 your terminal runs the risk of sending the same control sequence by
775 accident, and cause unexpected changes in the window title. Don't do
778 \S{faq-password-fails}{Question} My keyboard stops working once
779 PuTTY displays the password prompt.
781 No, it doesn't. PuTTY just doesn't display the password you type, so
782 that someone looking at your screen can't see what it is.
784 Unlike the Windows login prompts, PuTTY doesn't display the password
785 as a row of asterisks either. This is so that someone looking at
786 your screen can't even tell how \e{long} your password is, which
787 might be valuable information.
789 \S{faq-keyboard}{Question} One or more function keys don't do what I
790 expected in a server-side application.
792 If you've already tried all the relevant options in the PuTTY
793 Keyboard panel, you may need to mail the PuTTY maintainers and ask.
795 It is \e{not} usually helpful just to tell us which application,
796 which server operating system, and which key isn't working; in order
797 to replicate the problem we would need to have a copy of every
798 operating system, and every application, that anyone has ever
801 PuTTY responds to function key presses by sending a sequence of
802 control characters to the server. If a function key isn't doing what
803 you expect, it's likely that the character sequence your application
804 is expecting to receive is not the same as the one PuTTY is sending.
805 Therefore what we really need to know is \e{what} sequence the
806 application is expecting.
808 The simplest way to investigate this is to find some other terminal
809 environment, in which that function key \e{does} work; and then
810 investigate what sequence the function key is sending in that
811 situation. One reasonably easy way to do this on a Unix system is to
812 type the command \c{cat}, and then press the function key. This is
813 likely to produce output of the form \c{^[[11~}. You can also do
814 this in PuTTY, to find out what sequence the function key is
815 producing in that. Then you can mail the PuTTY maintainers and tell
816 us \q{I wanted the F1 key to send \c{^[[11~}, but instead it's
817 sending \c{^[OP}, can this be done?}, or something similar.
819 You should still read the
820 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/feedback.html}{Feedback
821 page} on the PuTTY website (also provided as \k{feedback} in the
822 manual), and follow the guidelines contained in that.
824 \S{faq-openssh-bad-openssl}{Question} Since my SSH server was upgraded
825 to OpenSSH 3.1p1/3.4p1, I can no longer connect with PuTTY.
827 There is a known problem when OpenSSH has been built against an
828 incorrect version of OpenSSL; the quick workaround is to configure
829 PuTTY to use SSH protocol 2 and the Blowfish cipher.
831 For more details and OpenSSH patches, see
832 \W{http://bugzilla.mindrot.org/show_bug.cgi?id=138}{bug 138} in the
835 This is not a PuTTY-specific problem; if you try to connect with
836 another client you'll likely have similar problems. (Although PuTTY's
837 default cipher differs from many other clients.)
839 \e{OpenSSH 3.1p1:} configurations known to be broken (and symptoms):
841 \b SSH 2 with AES cipher (PuTTY says "Assertion failed! Expression:
842 (len & 15) == 0" in sshaes.c, or "Out of memory", or crashes)
844 \b SSH 2 with 3DES (PuTTY says "Incorrect MAC received on packet")
846 \b SSH 1 with Blowfish (PuTTY says "Incorrect CRC received on
851 \e{OpenSSH 3.4p1:} as of 3.4p1, only the problem with SSH 1 and
852 Blowfish remains. Rebuild your server, apply the patch linked to from
853 bug 138 above, or use another cipher (e.g., 3DES) instead.
855 \e{Other versions:} we occasionally get reports of the same symptom
856 and workarounds with older versions of OpenSSH, although it's not
857 clear the underlying cause is the same.
859 \S{faq-ssh2key-ssh1conn}{Question} Why do I see "Couldn't load private
860 key from ..."? Why can PuTTYgen load my key but not PuTTY?
862 It's likely that you've generated an SSH protocol 2 key with PuTTYgen,
863 but you're trying to use it in an SSH 1 connection. SSH1 and SSH2 keys
864 have different formats, and (at least in 0.52) PuTTY's reporting of a
865 key in the wrong format isn't optimal.
867 To connect using SSH 2 to a server that supports both versions, you
868 need to change the configuration from the default (see \k{faq-ssh2}).
870 \S{faq-rh8-utf8}{Question} When I'm connected to a Red Hat Linux 8.0
871 system, some characters don't display properly.
873 A common complaint is that hyphens in man pages show up as a-acute.
875 With release 8.0, Red Hat appear to have made UTF-8 the default
876 character set. There appears to be no way for terminal emulators such
877 as PuTTY to know this (as far as we know, the appropriate escape
878 sequence to switch into UTF-8 mode isn't sent).
880 A fix is to configure sessions to RH8 systems to use UTF-8
881 translation - see \k{config-charset} in the documentation. (Note that
882 if you use \q{Change Settings}, changes may not take place immediately
883 - see \k{faq-resetterm}.)
885 If you really want to change the character set used by the server, the
886 right place is \c{/etc/sysconfig/i18n}, but this shouldn't be
889 \S{faq-screen}{Question} Since I upgraded to PuTTY 0.54, the
890 scrollback has stopped working when I run \c{screen}.
892 PuTTY's terminal emulator has always had the policy that when the
893 \q{alternate screen} is in use, nothing is added to the scrollback.
894 This is because the usual sorts of programs which use the alternate
895 screen are things like text editors, which tend to scroll back and
896 forth in the same document a lot; so (a) they would fill up the
897 scrollback with a large amount of unhelpfully disordered text, and
898 (b) they contain their \e{own} method for the user to scroll back to
899 the bit they were interested in. We have generally found this policy
900 to do the Right Thing in almost all situations.
902 Unfortunately, \c{screen} is one exception: it uses the alternate
903 screen, but it's still usually helpful to have PuTTY's scrollback
904 continue working. The simplest solution is to go to the Features
905 control panel and tick \q{Disable switching to alternate terminal
906 screen}. (See \k{config-features-altscreen} for more details.)
907 Alternatively, you can tell \c{screen} itself not to use the
908 alternate screen: the
909 \W{http://www4.informatik.uni-erlangen.de/~jnweiger/screen-faq.html}{\c{screen}
910 FAQ} suggests adding the line \cq{termcapinfo xterm ti@:te@} to your
913 The reason why this only started to be a problem in 0.54 is because
914 \c{screen} typically uses an unusual control sequence to switch to
915 the alternate screen, and previous versions of PuTTY did not support
918 \S{faq-alternate-localhost}{Question} Since I upgraded Windows XP
919 to Service Pack 2, I can't use addresses like \cw{127.0.0.2}.
921 Some people who ask PuTTY to listen on localhost addresses other
922 than \cw{127.0.0.1} to forward services such as SMB and Windows
923 Terminal Services have found that doing so no longer works since
924 they upgraded to WinXP SP2.
926 This is apparently an issue with SP2 that is acknowledged by Microsoft
927 in MS Knowledge Base article
928 \W{http://support.microsoft.com/default.aspx?scid=kb;en-us;884020}{884020}.
929 The article links to a fix you can download.
931 (\e{However}, we've been told that SP2 \e{also} fixes the bug that
932 means you need to use non-\cw{127.0.0.1} addresses to forward
933 Terminal Services in the first place.)
935 \S{faq-missing-slash}{Question} PSFTP commands seem to be missing a
936 directory separator (slash).
938 Some people have reported the following incorrect behaviour with
943 \c Remote directory is /dir1/dir2
944 \c psftp> get filename.ext
946 \c /dir1/dir2filename.ext: no such file or directory
948 This is not a bug in PSFTP. There is a known bug in some versions of
950 (\W{http://bugzilla.mindrot.org/show_bug.cgi?id=697}{bug 697}) that
951 causes these symptoms; it appears to have been introduced around
952 3.7.x. It manifests only on certain platforms (AIX is what has been
955 There is a patch for OpenSSH attached to that bug; it's also fixed in
956 recent versions of portable OpenSSH (from around 3.8).
958 \S{faq-connaborted}{Question} Do you want to hear about \q{Software
959 caused connection abort}?
961 In the documentation for PuTTY 0.53 and 0.53b, we mentioned that we'd
962 like to hear about any occurrences of this error. Since the release
963 of PuTTY 0.54, however, we've been convinced that this error doesn't
964 indicate that PuTTY's doing anything wrong, and we don't need to hear
965 about further occurrences. See \k{errors-connaborted} for our current
966 documentation of this error.
968 \H{faq-secure} Security questions
970 \S{faq-publicpc}{Question} Is it safe for me to download PuTTY and
971 use it on a public PC?
973 It depends on whether you trust that PC. If you don't trust the
974 public PC, don't use PuTTY on it, and don't use any other software
975 you plan to type passwords into either. It might be watching your
976 keystrokes, or it might tamper with the PuTTY binary you download.
977 There is \e{no} program safe enough that you can run it on an
978 actively malicious PC and get away with typing passwords into it.
980 If you do trust the PC, then it's probably OK to use PuTTY on it
981 (but if you don't trust the network, then the PuTTY download might
982 be tampered with, so it would be better to carry PuTTY with you on a
985 \S{faq-cleanup}{Question} What does PuTTY leave on a system? How can
988 PuTTY will leave some Registry entries, and a random seed file, on
989 the PC (see \k{faq-settings}). If you are using PuTTY on a public
990 PC, or somebody else's PC, you might want to clean these up when you
991 leave. You can do that automatically, by running the command
992 \c{putty -cleanup}. (Note that this only removes settings for
993 the currently logged-in user on \i{multi-user systems}.)
995 If PuTTY was installed from the installer package, it will also
996 appear in \q{Add/Remove Programs}. Uninstallation does not currently
997 remove the above-mentioned registry entries and file.
999 \S{faq-dsa}{Question} How come PuTTY now supports DSA, when the
1000 website used to say how insecure it was?
1002 DSA has a major weakness \e{if badly implemented}: it relies on a
1003 random number generator to far too great an extent. If the random
1004 number generator produces a number an attacker can predict, the DSA
1005 private key is exposed - meaning that the attacker can log in as you
1006 on all systems that accept that key.
1008 The PuTTY policy changed because the developers were informed of
1009 ways to implement DSA which do not suffer nearly as badly from this
1010 weakness, and indeed which don't need to rely on random numbers at
1011 all. For this reason we now believe PuTTY's DSA implementation is
1012 probably OK. However, if you have the choice, we still recommend you
1015 \S{faq-virtuallock}{Question} Couldn't Pageant use
1016 \cw{VirtualLock()} to stop private keys being written to disk?
1018 Unfortunately not. The \cw{VirtualLock()} function in the Windows
1019 API doesn't do a proper job: it may prevent small pieces of a
1020 process's memory from being paged to disk while the process is
1021 running, but it doesn't stop the process's memory as a whole from
1022 being swapped completely out to disk when the process is long-term
1023 inactive. And Pageant spends most of its time inactive.
1025 \H{faq-admin} Administrative questions
1027 \S{faq-domain}{Question} Would you like me to register you a nicer
1030 No, thank you. Even if you can find one (most of them seem to have
1031 been registered already, by people who didn't ask whether we
1032 actually wanted it before they applied), we're happy with the PuTTY
1033 web site being exactly where it is. It's not hard to find (just type
1034 \q{putty} into \W{http://www.google.com/}{google.com} and we're the
1035 first link returned), and we don't believe the administrative hassle
1036 of moving the site would be worth the benefit.
1038 In addition, if we \e{did} want a custom domain name, we would want
1039 to run it ourselves, so we knew for certain that it would continue
1040 to point where we wanted it, and wouldn't suddenly change or do
1041 strange things. Having it registered for us by a third party who we
1042 don't even know is not the best way to achieve this.
1044 \S{faq-webhosting}{Question} Would you like free web hosting for the
1047 We already have some, thanks.
1049 \S{faq-link}{Question} Would you link to my web site from the PuTTY
1052 Only if the content of your web page is of definite direct interest
1053 to PuTTY users. If your content is unrelated, or only tangentially
1054 related, to PuTTY, then the link would simply be advertising for
1057 One very nice effect of the Google ranking mechanism is that by and
1058 large, the most popular web sites get the highest rankings. This
1059 means that when an ordinary person does a search, the top item in
1060 the search is very likely to be a high-quality site or the site they
1061 actually wanted, rather than the site which paid the most money for
1064 The PuTTY web site is held in high esteem by Google, for precisely
1065 this reason: lots of people have linked to it simply because they
1066 like PuTTY, without us ever having to ask anyone to link to us. We
1067 feel that it would be an abuse of this esteem to use it to boost the
1068 ranking of random advertisers' web sites. If you want your web site
1069 to have a high Google ranking, we'd prefer that you achieve this the
1070 way we did - by being good enough at what you do that people will
1071 link to you simply because they like you.
1073 In particular, we aren't interested in trading links for money (see
1074 above), and we \e{certainly} aren't interested in trading links for
1075 other links (since we have no advertising on our web site, our
1076 Google ranking is not even directly worth anything to us). If we
1077 don't want to link to you for free, then we probably won't want to
1080 If you have software based on PuTTY, or specifically designed to
1081 interoperate with PuTTY, or in some other way of genuine interest to
1082 PuTTY users, then we will probably be happy to add a link to you on
1083 our Links page. And if you're running a mirror of the PuTTY web
1084 site, we're \e{definitely} interested.
1086 \S{faq-sourceforge}{Question} Why don't you move PuTTY to
1089 Partly, because we don't want to move the web site location (see
1092 Also, security reasons. PuTTY is a security product, and as such it
1093 is particularly important to guard the code and the web site against
1094 unauthorised modifications which might introduce subtle security
1095 flaws. Therefore, we prefer that the Subversion repository, web site and
1096 FTP site remain where they are, under the direct control of system
1097 administrators we know and trust personally, rather than being run
1098 by a large organisation full of people we've never met and which is
1099 known to have had breakins in the past.
1101 No offence to SourceForge; I think they do a wonderful job. But
1102 they're not ideal for everyone, and in particular they're not ideal
1105 \S{faq-mailinglist1}{Question} Why can't I subscribe to the
1106 putty-bugs mailing list?
1108 Because you're not a member of the PuTTY core development team. The
1109 putty-bugs mailing list is not a general newsgroup-like discussion
1110 forum; it's a contact address for the core developers, and an
1111 \e{internal} mailing list for us to discuss things among ourselves.
1112 If we opened it up for everybody to subscribe to, it would turn into
1113 something more like a newsgroup and we would be completely
1114 overwhelmed by the volume of traffic. It's hard enough to keep up
1115 with the list as it is.
1117 \S{faq-mailinglist2}{Question} If putty-bugs isn't a
1118 general-subscription mailing list, what is?
1120 There isn't one, that we know of.
1122 If someone else wants to set up a mailing list or other forum for
1123 PuTTY users to help each other with common problems, that would be
1124 fine with us, though the PuTTY team would almost certainly not have the
1125 time to read it. It's probably better to use one of the established
1126 newsgroups for this purpose (see \k{feedback-other-fora}).
1128 \S{faq-donations}{Question} How can I donate to PuTTY development?
1130 Please, \e{please} don't feel you have to. PuTTY is completely free
1131 software, and not shareware. We think it's very important that
1132 \e{everybody} who wants to use PuTTY should be able to, whether they
1133 have any money or not; so the last thing we would want is for a
1134 PuTTY user to feel guilty because they haven't paid us any money. If
1135 you want to keep your money, please do keep it. We wouldn't dream of
1138 Having said all that, if you still really \e{want} to give us money,
1139 we won't argue :-) The easiest way for us to accept donations is if
1140 you send money to \cw{<anakin@pobox.com>} using PayPal
1141 (\W{http://www.paypal.com/}\cw{www.paypal.com}). Alternatively, if
1142 you don't trust PayPal, you could donate through e-gold
1143 (\W{http://www.e-gold.com}\cw{www.e-gold.com}): deposit your
1144 donation in account number 174769, then send us e-mail to let us
1145 know you've done so (otherwise we might not notice for months!).
1147 Small donations (tens of dollars or tens of euros) will probably be
1148 spent on beer or curry, which helps motivate our volunteer team to
1149 continue doing this for the world. Larger donations will be spent on
1150 something that actually helps development, if we can find anything
1151 (perhaps new hardware, or a copy of Windows XP), but if we can't
1152 find anything then we'll just distribute the money among the
1153 developers. If you want to be sure your donation is going towards
1154 something worthwhile, ask us first. If you don't like these terms,
1155 feel perfectly free not to donate. We don't mind.
1157 \S{faq-permission}{Question} Can I have permission to put PuTTY on a
1158 cover disk / distribute it with other software / etc?
1160 Yes. You need not bother asking us explicitly for permission. You
1161 already have permission. Redistribution of the unmodified PuTTY
1162 binary in this way is entirely permitted by our licence (see
1163 \k{licence}), and you are welcome to do it as much as you like.
1165 If you are distributing PuTTY within your own organisation, or for
1166 use with your own product, then we recommend (but do not insist)
1167 that you offer your own first-line technical support, to answer
1168 questions directly relating to the interaction of PuTTY with your
1169 particular environment. If your users mail us directly, we won't be
1170 able to give them very much help about things specific to your own
1173 \H{faq-misc} Miscellaneous questions
1175 \S{faq-openssh}{Question} Is PuTTY a port of OpenSSH, or based on
1178 No, it isn't. PuTTY is almost completely composed of code written
1179 from scratch for PuTTY. The only code we share with OpenSSH is the
1180 detector for SSH1 CRC compensation attacks, written by CORE SDI S.A.
1182 \S{faq-sillyputty}{Question} Where can I buy silly putty?
1184 You're looking at the wrong web site; the only PuTTY we know about
1185 here is the name of a computer program.
1187 If you want the kind of putty you can buy as an executive toy, the
1188 PuTTY team can personally recommend Thinking Putty, which you can
1189 buy from Crazy Aaron's Putty World, at
1190 \W{http://www.puttyworld.com}\cw{www.puttyworld.com}.
1192 \S{faq-meaning}{Question} What does \q{PuTTY} mean?
1194 It's the name of a popular SSH and Telnet client. Any other meaning
1195 is in the eye of the beholder. It's been rumoured that \q{PuTTY}
1196 is the antonym of \q{\cw{getty}}, or that it's the stuff that makes your
1197 Windows useful, or that it's a kind of plutonium Teletype. We
1198 couldn't possibly comment on such allegations.
1200 \S{faq-pronounce}{Question} How do I pronounce \q{PuTTY}?
1202 Exactly like the English word \q{putty}, which we pronounce
1203 /\u02C8{'}p\u028C{V}t\u026A{I}/.