PuTTY User Manual ================= PuTTY is a free (MIT-licensed) Win32 Telnet and SSH client. This manual documents PuTTY, and its companion utilities PSCP, Plink, Pageant and PuTTYgen. Copyright 2001 Simon Tatham. All rights reserved. You may distribute this documentation under the MIT licence. Chapter 1: Introduction to PuTTY -------------------------------- PuTTY is a free SSH, Telnet and Rlogin client for 32-bit Windows systems. 1.1 What are SSH, Telnet and Rlogin? If you already know what SSH, Telnet and Rlogin are, you can safely skip on to the next section. SSH, Telnet and Rlogin are three ways of doing the same thing: logging in to a multi-user computer from another computer, over a network. Multi-user operating systems, such as Unix and VMS, usually present a command-line interface to the user, much like the `Command Prompt' or `MS-DOS Prompt' in Windows. The system prints a prompt, and you type commands which the system will obey. Using this type of interface, there is no need for you to be sitting at the same machine you are typing commands to. The commands, and responses, can be sent over a network, so you can sit at one computer and give commands to another one, or even to more than one. SSH, Telnet and Rlogin are _network protocols_ that allow you to do this. On the computer you sit at, you run a _client_, which makes a network connection to the other computer (the _server_). The network connection carries your keystrokes and commands from the client to the server, and carries the server's responses back to you. These protocols can also be used for other types of keyboard-based interactive session. In particular, there are a lot of bulletin boards, talker systems and MUDs (Multi-User Dungeons) which support access using Telnet. There are even a few that support SSH. You might want to use SSH, Telnet or Rlogin if: - you have an account on a Unix or VMS system which you want to be able to access from somewhere else - your Internet Service Provider provides you with a login account on a web server. (This might also be known as a _shell account_. A _shell_ is the program that runs on the server and interprets your commands for you.) - you want to use a bulletin board system, talker or MUD which can be accessed using Telnet. You probably do _not_ want to use SSH, Telnet or Rlogin if: - you only use Windows. Windows computers have their own ways of networking between themselves, and unless you are doing something fairly unusual, you will not need to use any of these remote login protocols. 1.2 How do SSH, Telnet and Rlogin differ? This list summarises some of the differences between SSH, Telnet and Rlogin. - SSH is a recently designed, high-security protocol. It uses strong cryptography to protect your connection against eavesdropping, hijacking and other attacks. Telnet and Rlogin are both older protocols offering minimal security. - Telnet allows you to pass some settings on to the server, such as environment variables. (These control various aspects of the server's behaviour. You can usually set them by entering commands into the server once you're connected, but it's easier to have Telnet do it automatically.) SSH and Rlogin do not support this. However, most modern Telnet servers don't allow it either, because it has been a constant source of security problems. - SSH and Rlogin both allow you to log in to the server without having to type a password. (Rlogin's method of doing this is insecure, and can allow an attacker to access your account on the server. SSH's method is much more secure, and typically breaking the security requires the attacker to have gained access to your actual client machine.) - SSH allows you to connect to the server and automatically send a command, so that the server will run that command and then disconnect. So you can use it in automated processing. The Internet is a hostile environment and security is everybody's responsibility. If you are connecting across the open Internet, then we recommend you use SSH. If the server you want to connect to doesn't support SSH, it might be worth trying to persuade the administrator to install it. If you are behind a good firewall, it is more likely to be safe to use Telnet or Rlogin, but we still recommend you use SSH. Chapter 2: Getting started with PuTTY ------------------------------------- This chapter gives a quick guide to the simplest types of interactive login session using PuTTY. 2.1 Starting a session When you start PuTTY, you will see a dialog box. This dialog box allows you to control everything PuTTY can do. See chapter 3 for details of all the things you can control. You don't usually need to change most of the configuration options. To start the simplest kind of session, all you need to do is to enter a few basic parameters. In the _Host Name_ box, enter the Internet host name of the server you want to connect to. You should have been told this by the provider of your login account. Now select a login protocol to use, from the _Protocol_ buttons. For a login session, you should select Telnet, Rlogin or SSH. See section 1.2 for a description of the differences between the three protocols, and advice on which one to use. The fourth protocol, _Raw_, is not used for interactive login sessions; you would usually use this for debugging other Internet services. When you change the selected protocol, the number in the _Port_ box will change. This is normal: it happens because the various login services are usually provided on different network ports by the server machine. Most servers will use the standard port numbers, so you will not need to change the port setting. If your server provides login services on a non-standard port, your system administrator should have told you which one. (For example, many MUDs run Telnet service on a port other than 23.) Once you have filled in the _Host Name_, _Protocol_, and possibly _Port_ settings, you are ready to connect. Press the _Open_ button at the bottom of the dialog box, and PuTTY will begin trying to connect you to the server. 2.2 Verifying the Host Key (SSH only) If you are not using the SSH protocol, you can skip this section. If you are using SSH to connect to a server for the first time, you will probably see a message looking something like this: This is a feature of the SSH protocol. It is designed to protect you against a network attack known as _spoofing_: secretly redirecting your connection to a different computer, so that you send your password to the wrong machine. Using this technique, an attacker would be able to learn the password that guards your login account, and could then log in as if they were you and use the account for their own purposes. To prevent this attack, each server has a unique identifying code, called a _host key_. These keys are created in a way that prevents one server from forging another server's key. So if you connect to a server and it sends you a different host key from the one you were expecting, PuTTY can warn you that the server may have been switched and that a spoofing attack might be in progress. PuTTY records the host key for each server you connect to, in the Windows Registry. Every time you connect to a server, it checks that the host key presented by the server is the same host key as it was the last time you connected. If it is not, you will see a warning, and you will have the chance to abandon your connection before you type any private information (such as a password) into it. However, when you connect to a server you have not connected to before, PuTTY has no way of telling whether the host key is the right one or not. So it gives the warning shown above, and asks you whether you want to trust this host key or not. Whether or not to trust the host key is your choice. If you are connecting within a company network, you might feel that all the network users are on the same side and spoofing attacks are unlikely, so you might choose to trust the key without checking it. If you are connecting across a hostile network (such as the Internet), you should check with your system administrator, perhaps by telephone or in person. (Some modern servers have more than one host key. If the system administrator sends you more than one fingerprint, you should make sure the one PuTTY shows you is on the list, but it doesn't matter which one it is.) 2.3 Logging In After you have connected, and perhaps verified the server's host key, you will be asked to log in, probably using a username and a password. Your system administrator should have provided you with these. Enter the username and the password, and the server should grant you access and begin your session. If you have mistyped your password, most servers will give you several chances to get it right. If you are using SSH, be careful not to type your username wrongly, because you will not have a chance to correct it after you press Return. This is an unfortunate feature of the SSH protocol: it does not allow you to make two login attempts using different usernames. If you type your username wrongly, you must close PuTTY and start again. If your password is refused but you are sure you have typed it correctly, check that Caps Lock is not enabled. Many login servers, particularly Unix computers, treat upper case and lower case as different when checking your password; so if Caps Lock is on, your password will probably be refused. 2.4 After Logging In After you log in to the server, what happens next is up to the server! Most servers will print some sort of login message and then present a prompt, at which you can type commands which the server will carry out. Some servers will offer you on-line help; others might not. If you are in doubt about what to do next, consult your system administrator. 2.5 Logging Out When you have finished your session, you should log out by typing the server's own logout command. This might vary between servers; if in doubt, try `logout' or `exit', or consult a manual or your system administrator. When the server processes your logout command, the PuTTY window should close itself automatically. You _can_ close a PuTTY session using the Close button in the window border, but this might confuse the server - a bit like hanging up a telephone unexpectedly in the middle of a conversation. We recommend you do not do this unless the server has stopped responding to you and you cannot close the window any other way. Chapter 3: Configuring PuTTY ---------------------------- This chapter describes all the configuration options in PuTTY. PuTTY is configured using the control panel that comes up before you start a session. Some options can also be changed in the middle of a session, by selecting _Change Settings_ from the window menu. 3.1 The Session panel The Session configuration panel contains the basic options you need to specify in order to open a session at all, and also allows you to save your settings to be reloaded later. 3.1.1 The host name section The top box on the Session panel, labelled `Specify your connection by host name', contains the details that need to be filled in before PuTTY can open a session at all. - The _Host Name_ box is where you type the name, or the IP address, of the server you want to connect to. - The _Protocol_ radio buttons let you choose what type of connection you want to make: a raw connection, a Telnet connection, an rlogin connection or an SSH connection. - The _Port_ box lets you specify which port number on the server to connect to. If you select Telnet, Rlogin, or SSH, this box will be filled in automatically to the usual value, and you will only need to change it if you have an unusual server. If you select Raw mode, you will almost certainly need to fill in the _Port_ box. 3.1.2 Loading and storing saved sessions The next part of the Session configuration panel allows you to save your preferred PuTTY options so they will appear automatically the next time you start PuTTY. It also allows you to create _saved sessions_, which contain a full set of configuration options plus a host name and protocol. A saved session contains all the information PuTTY needs to start exactly the session you want. - To save your default settings: first set up the settings the way you want them saved. Then come back to the Session panel. Select the `Default Settings' entry in the saved sessions list, with a single click. Then press the _Save_ button. - To save a session: first go through the rest of the configuration box setting up all the options you want. Then come back to the Session panel. Enter a name for the saved session in the _Saved Sessions_ input box. (The server name is often a good choice for a saved session name.) Then press the _Save_ button. Your saved session name should now appear in the list box. - To reload a saved session: single-click to select the session name in the list box, and then press the _Load_ button. Your saved settings should all appear in the configuration panel. - To modify a saved session: first load it as described above. Then make the changes you want. Come back to the Session panel, single- click to select the session name in the list box, and press the _Save_ button. The new settings will be saved over the top of the old ones. - To start a saved session immediately: double-click on the session name in the list box. - To delete a saved session: single-click to select the session name in the list box, and then press the _Delete_ button. Each saved session is independent of the Default Settings configuration. If you change your preferences and update Default Settings, you must also update every saved session separately. 3.1.3 `Close Window on Exit' Finally in the Session panel, there is a check box labelled `Close Window on Exit'. If this is turned on, the PuTTY session window will disappear as soon as the session inside it terminates. Otherwise, the window will remain on the desktop until you close it yourself, so you can still read and copy text out of it. 3.2 The Terminal panel The Terminal configuration panel allows you to control the behaviour of PuTTY's terminal emulation. 3.2.1 `Auto wrap mode initially on' Auto wrap mode controls what happens when text printed in a PuTTY window reaches the right-hand edge of the window. With auto wrap mode on, if a long line of text reaches the right- hand edge, it will wrap over on to the next line so you can still see all the text. With auto wrap mode off, the cursor will stay at the right-hand edge of the screen, and all the characters in the line will be printed on top of each other. If you are running a full-screen application and you occasionally find the screen scrolling up when it looks as if it shouldn't, you could try turning this option off. Auto wrap mode can be turned on and off by control sequences sent by the server. This configuration option only controls the _default_ state. If you modify this option in mid-session using _Change Settings_, you will need to reset the terminal before the change takes effect. 3.2.2 `DEC Origin Mode initially on' DEC Origin Mode is a minor option which controls how PuTTY interprets cursor-position control sequences sent by the server. The server can send a control sequence that restricts the scrolling region of the display. For example, in an editor, the server might reserve a line at the top of the screen and a line at the bottom, and might send a control sequence that causes scrolling operations to affect only the remaining lines. With DEC Origin Mode on, cursor coordinates are counted from the top of the scrolling region. With it turned off, cursor coordinates are counted from the top of the whole screen regardless of the scrolling region. It is unlikely you would need to change this option, but if you find a full-screen application is displaying pieces of text in what looks like the wrong part of the screen, you could try turning DEC Origin Mode on to see whether that helps. DEC Origin Mode can be turned on and off by control sequences sent by the server. This configuration option only controls the _default_ state. If you modify this option in mid-session using _Change Settings_, you will need to reset the terminal before the change takes effect. 3.2.3 `Implicit CR in every LF' Most servers send two control characters, CR and LF, to start a 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 LF, and expect the terminal to move the cursor over to the left automatically. If you come across a server that does this, you will see a stepped effect on the screen, like this: First line of text Second line Third line If this happens to you, try enabling the `Implicit CR in every LF' option, and things might go back to normal: First line of text Second line Third line 3.2.4 `Beep enabled' This option lets you turn off beeps in PuTTY. If your server is beeping too much or attracting unwelcome attention, you can turn the beeps off. 3.2.5 `Use background colour to erase screen' Not all terminals agree on what colour to turn the screen when the server sends a `clear screen' sequence. Some terminals believe the screen should always be cleared to the _default_ background colour. Others believe the screen should be cleared to whatever the server has selected as a background colour. There exist applications that expect both kinds of behaviour. Therefore, PuTTY can be configured to do either. With this option disabled, screen clearing is always done in the default background colour. With this option enabled, it is done in the _current_ background colour. 3.2.6 `Enable blinking text' The server can ask PuTTY to display text that blinks on and off. This is very distracting, so PuTTY allows you to turn blinking text off completely. 3.2.7 `Use local terminal line discipline' Normally, every character you type into the PuTTY window is sent straight to the server. If you enable local terminal line discipline, this changes. PuTTY will let you edit a whole line at a time locally, and the line will only be sent to the server when you press Return. If you make a mistake, you can use the Backspace key to correct it before you press Return, and the server will never see the mistake. Since it would be hard to edit a line locally without being able to see it, local terminal line discipline also makes PuTTY echo what you type. This makes it ideal for use in raw mode or when connecting to MUDs or talkers. 3.2.8 Controlling session logging PuTTY has the ability to log the output from your session into a file. You might want this if you were saving a particular piece of output to mail to somebody, for example in a bug report. You can choose between: - not logging anything (the default) - logging only the printable characters in a session (ignoring control sequences to change colours or clear the screen) - logging everything sent to the terminal by the server. You can turn logging on and off in mid-session using _Change Settings_. 3.3 The Keyboard panel The Keyboard configuration panel allows you to control the behaviour of the keyboard in PuTTY. 3.3.1 Changing the action of the Backspace key Some terminals believe that the Backspace key should send the same thing to the server as Control-H (ASCII code 8). Other terminals believe that the Backspace key should send ASCII code 127 (usually known as Control-?) so that it can be distinguished from Control-H. This option allows you to choose which code PuTTY generates when you press Backspace. If you are connecting to a Unix system, you will probably find that the Unix `stty' command lets you configure which the server expects to see, so you might not need to change which one PuTTY generates. On other systems, the server's expectation might be fixed and you might have no choice but to configure PuTTY. If you do have the choice, we recommend configuring PuTTY to generate Control-? and configuring the server to expect it, because that allows applications such as `emacs' to use Control-H for help. 3.3.2 Changing the action of the Home and End keys The Unix terminal emulator `rxvt' disagrees with the rest of the world about what character sequences should be sent to the server by the Home and End keys. `xterm', and other terminals, send `ESC [1~' for the Home key, and `ESC [4~' for the End key. `rxvt' sends `ESC [H' for the Home key and `ESC [Ow' for the End key. If you find an application on which the Home and End keys aren't working, you could try switching this option to see if it helps. 3.3.3 Changing the action of the function keys and keypad This option affects the function keys (F1 to F12) and the top row of the numeric keypad. - In the default mode, labelled `ESC [n~', the function keys generate sequences like `ESC [11~', `ESC [12~' and so on. This matches the general behaviour of Digital's terminals. - In Linux mode, F6 to F12 behave just like the default mode, but F1 to F5 generate `ESC [[A' through to `ESC [[E'. This mimics the Linux virtual console. - In Xterm R6 mode, F5 to F12 behave like the default mode, but F1 to F4 generate `ESC OP' through to `ESC OS', which are the sequences produced by the top row of the _keypad_ on Digital's terminals. - In VT400 mode, all the function keys behave like the default mode, but the actual top row of the numeric keypad generates `ESC OP' through to `ESC OS'. - In VT100+ mode, the function keys generate `ESC OP' through to `ESC O[' - In SCO mode, the function keys F1 to F12 generate `ESC [M' through to `ESC [X'. Together with shift, they generate `ESC [Y' through to `ESC [j'. With control they generate `ESC [k' through to `ESC [v', and with shift and control together they generate `ESC [w' through to `ESC [{'. If you don't know what any of this means, you probably don't need to fiddle with it. 3.3.4 Controlling Application Cursor Keys mode Application Cursor Keys mode is a way for the server to change the control sequences sent by the arrow keys. In normal mode, the arrow keys send `ESC [A' through to `ESC [D'. In application mode, they send `ESC OA' through to `ESC OD'. Application Cursor Keys mode can be turned on and off by the server, depending on the application. PuTTY allows you to configure the initial state, and also allows you to disable application mode completely. 3.3.5 Controlling Application Keypad mode Application Keypad mode is a way for the server to change the behaviour of the numeric keypad. In normal mode, the keypad behaves like a normal Windows keypad: with NumLock on, the number keys generate numbers, and with NumLock off they act like the arrow keys and Home, End etc. In application mode, all the keypad keys send special control sequences, _including_ Num Lock. Num Lock stops behaving like Num Lock and becomes another function key. Depending on which version of Windows you run, you may find the Num Lock light still flashes on and off every time you press Num Lock, even when application mode is active and Num Lock is acting like a function key. This is unavoidable. Application keypad mode can be turned on and off by the server, depending on the application. PuTTY allows you to configure the initial state, and also allows you to disable application mode completely. 3.3.6 Using NetHack keypad mode PuTTY has a special mode for playing NetHack. You can enable it by selecting `NetHack' in the `Initial state of numeric keypad' control. In this mode, the numeric keypad keys 1-9 generate the NetHack movement commands (hjklyubn). The 5 key generates the `.' command (do nothing). Better still, pressing Shift with the keypad keys generates the capital forms of the commands (HJKLYUBN), which tells NetHack to keep moving you in the same direction until you encounter something interesting. For some reason, this feature only works properly when Num Lock is on. We don't know why. 3.3.7 Enabling a DEC-like Compose key DEC terminals have a Compose key, which provides an easy-to-remember way of typing accented characters. You press Compose and then type two more characters. The two characters are `combined' to produce an accented character. The choices of character are designed to be easy to remember; for example, composing `e' and ``' produces the `è' character. If you enable the `Application and AltGr act as Compose key' option, the Windows Application key and the AltGr key will both have this behaviour. 3.4 The Bell panel The Bell configuration panel allows you to control how PuTTY should respond to a terminal bell. 3.4.1 Set the style of bell When a terminal bell occurs, PuTTY can do one of the following things: - Nothing. The bell is disabled. Taskbar bell indication still works, however. - Play Windows Default Sound. The Windows Default Sound (which can be configured from the Sounds control panel) will be played. - Play a custom sound file. Select a `.wav' sound file using the _Custom sound file to play as a bell_ text box, or browse for the file to play using the _Browse..._ button. - Flash the terminal window as a visual bell. No sound will be played. In addition, the PuTTY window's title bar and its entry in the taskbar can be configured to flash or invert to indicate that a terminal bell has occurred. 3.4.2 Control the bell overload behaviour Sometimes mistakes, for example trying to `cat' a binary file on a Unix machine, can lead to a large number of terminal bells being received by PuTTY. It might take a long time for PuTTY to catch up with reacting to these bells, and the noise or flashing could be very irritating for the user. PuTTY's bell overload handling is designed to avoid this problem. If turned on using the _Bell is temporarily disabled when over-used_ tick box, the bell will be disabled if it occurs more than a specified number of times in a specified number of seconds. When no bells have occurred for a number of seconds, PuTTY re-enables the bell. 3.5 The Window panel The Window configuration panel allows you to control aspects of the PuTTY window and its behaviour. 3.5.1 Setting the size of the PuTTY window The _Rows_ and _Columns_ boxes let you set the PuTTY window to a precise size. Of course you can also drag the window to a new size while a session is running. If you are running an application which is unable to deal with changes in window size, you might want to enable the `Lock window size against resizing' option, which prevents the user from accidentally changing the size of the window. 3.5.2 Controlling scrollback Text that scrolls off the top of the PuTTY terminal window is kept for reference. The scrollbar on the right of the window lets you view the scrolled-off text. You can also page through the scrollback using the keyboard, by pressing Shift-PgUp and Shift-PgDn. The `Lines of scrollback' box lets you configure how many lines of text PuTTY keeps. The `Display scrollbar' option allows you to hide the scrollbar (although you can still view the scrollback using Shift-PgUp and Shift-PgDn). If you are viewing part of the scrollback when the server sends more text to PuTTY, the screen will revert to showing the current terminal contents. You can disable this behaviour by turning off `Reset scrollback on display activity'. You can also make the screen revert when you press a key, by turning on `Reset scrollback on keypress'. 3.5.3 `Warn before closing window' If you press the Close button in a PuTTY window that contains a running session, PuTTY will put up a warning window asking if you really meant to close the window. A window whose session has already terminated can always be closed without a warning. If you want to be able to close a window quickly, you can disable the `Warn before closing window' option. 3.5.4 `Window closes on ALT-F4' By default, pressing ALT-F4 causes the window to close (or a warning box to appear; see section 3.5.3). If you disable the `Window closes on ALT-F4' option, then pressing ALT-F4 will simply send a key sequence to the server. 3.5.5 `System menu appears on ALT-Space' If this option is enabled, then pressing ALT-Space will bring up the PuTTY window's menu, like clicking on the top left corner. If it is disabled, then pressing ALT-Space will just send `ESC SPACE' to the server. Some accessibility programs for Windows may need this option enabling to be able to control PuTTY's window successfully. For instance, Dragon NaturallySpeaking requires it both to open the system menu via voice, and to close, minimise, maximise and restore the window. 3.5.6 `System menu appears on Alt alone' If this option is enabled, then pressing and releasing ALT will bring up the PuTTY window's menu, like clicking on the top left corner. If it is disabled, then pressing and releasing ALT will have no effect. 3.5.7 `Ensure window is always on top' If this option is enabled, the PuTTY window will stay on top of all other windows. 3.6 The Appearance panel The Appearance configuration panel allows you to control aspects of PuTTY's appearance. 3.6.1 Controlling the appearance of the cursor The `Cursor appearance' option lets you configure the cursor to be a block, an underline, or a vertical line. A block cursor becomes an empty box when the window loses focus; an underline or a vertical line becomes dotted. The `Cursor blinks' option makes the cursor blink on and off. This works in any of the cursor modes. 3.6.2 Controlling the font used in the terminal window 3.6.3 Controlling the window title 3.7 The Translation panel The Translation configuration panel allows you to control the translation between the character set understood by the server and the character set understood by PuTTY. 3.7.1 Line drawing characters 3.7.2 Character set translation of output data 3.7.3 Character set translation of input data 3.8 The Selection panel The Selection panel allows you to control the way copy and paste work in the PuTTY window. 3.8.1 Changing the actions of the mouse buttons 3.8.2 Configuring word-by-word selection 3.9 The Colours panel The Colours panel allows you to control PuTTY's use of colour. 3.9.1 `Bolded text is a different colour' 3.9.2 `Attempt to use logical palettes' 3.9.3 Adjusting the colours in the terminal window 3.10 The Connection panel The Connection panel allows you to configure options that apply to more than one type of connection. 3.10.1 `Terminal-type string' 3.10.2 `Auto-login username' 3.10.3 Using keepalives to prevent disconnection If you find your sessions are closing unexpectedly (`Connection reset by peer') after they have been idle for a while, you might want to try using this option. Some network routers and firewalls need keep track of all connections through them. Usually, these firewalls will assume a connection is dead if no data is transferred in either direction after a certain time interval. This can cause PuTTY sessions to be unexpectedly closed by the firewall if no traffic is seen in the session for some time. The keepalive option (`Seconds between keepalives') allows you to configure PuTTY to send data through the session at regular intervals, in a way that does not disrupt the actual terminal session. If you find your firewall is cutting idle connections off, you can try entering a non-zero value in this field. The value is measured in seconds; so, for example, if your firewall cuts connections off after ten minutes then you might want to enter 300 seconds (5 minutes) in the box. Note that keepalives are not always helpful. They help if you have a firewall which drops your connection after an idle period; but if the network between you and the server suffers from breaks in connectivity then keepalives can actually make things worse. If a session is idle, and connectivity is temporarily lost between the endpoints, but the connectivity is restored before either side tries to send anything, then there will be no problem - neither endpoint will notice that anything was wrong. However, if one side does send something during the break, it will repeatedly try to re-send, and eventually give up and abandon the connection. Then when connectivity is restored, the other side will find that the first side doesn't believe there is an open connection any more. Keepalives can make this sort of problem worse, because they increase the probability that PuTTY will attempt to send data during a break in connectivity. Therefore, you might find they help connection loss, or you might find they make it worse, depending on what _kind_ of network problems you have between you and the server. Keepalives are only supported in Telnet and SSH; the Rlogin and Raw protocols offer no way of implementing them. 3.11 The Telnet panel The Telnet panel allows you to configure options that only apply to Telnet sessions. 3.11.1 `Terminal-speed string' 3.11.2 Setting environment variables on the server 3.11.3 `Handling of OLD_ENVIRON ambiguity' 3.12 The SSH panel The SSH panel allows you to configure options that only apply to SSH sessions. 3.12.1 Executing a specific command on the server 3.12.2 SSH authentication options 3.12.3 SSH protocol options 3.13 Storing configuration in a file PuTTY does not currently support storing its configuration in a file instead of the Registry. However, you can work around this with a couple of batch files. You will need a file called (say) `PUTTY.BAT' which imports the contents of a file into the Registry, then runs PuTTY, exports the contents of the Registry back into the file, and deletes the Registry entries. This can all be done using the Regedit command line options, so it's all automatic. Here is what you need in `PUTTY.BAT': @ECHO OFF regedit /s putty.reg regedit /s puttyrnd.reg start /w putty.exe regedit /e puttynew.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY copy puttynew.reg putty.reg del puttynew.reg regedit /s puttydel.reg This batch file needs two auxiliary files: `PUTTYRND.REG' which sets up an initial safe location for the `PUTTY.RND' random seed file, and `PUTTYDEL.REG' which destroys everything in the Registry once it's been successfully saved back to the file. Here is `PUTTYDEL.REG': REGEDIT4 [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY] Here is an example `PUTTYRND.REG' file: REGEDIT4 [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY] "RandSeedFile"="a:\putty.rnd" You should replace `a:\putty.rnd' with the location where you want to store your random number data. If the aim is to carry around PuTTY and its settings on one floppy, you probably want to store it on the floppy. Chapter 4: Using PSCP to transfer files securely ------------------------------------------------ PSCP, the PuTTY Secure Copy client, is a tool for transferring files securely between computers using an SSH connection. 4.1 Starting PSCP PSCP is a command line application. This means that you cannot just double-click on its icon to run it and instead you have to bring up a console window. With Windows 95, 98, and ME, this is called an `MS-DOS Prompt' and with Windows NT and 2000 it is called a `Command Prompt'. It should be available from the Programs section of your Start Menu. To start PSCP it will need either to be on your `PATH' or in your current directory. To add the directory containing PSCP to your `PATH' environment variable, type into the console window: set PATH=C:\path\to\putty\directory;%PATH% This will only work for the lifetime of that particular console window. To set your `PATH' more permanently on Windows NT, use the Environment tab of the System Control Panel. On Windows 95, 98, and ME, you will need to edit your `AUTOEXEC.BAT' to include a `set' command like the one above. 4.2 PSCP Usage Once you've got a console window to type into, you can just type `pscp' on its own to bring up a usage message. This tells you the version of PSCP you're using, and gives you a brief summary of how to use PSCP: Z:\owendadmin>pscp PuTTY Secure Copy client Release 0.50 Usage: pscp [options] [user@]host:source target pscp [options] source [source...] [user@]host:target pscp [options] -ls user@host:filespec Options: -p preserve file attributes -q quiet, don't show statistics -r copy directories recursively -v show verbose messages -P port connect to specified port -pw passw login with specified password (PSCP's interface is much like the Unix `scp' command, if you're familiar with that.) 4.2.1 The basics To receive (a) file(s) from a remote server: pscp [options] [user@]host:source target So to copy the file `/etc/hosts' from the server `example.com' as user `fred' to the file `c:\temp\example-hosts.txt', you would type: pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt To send (a) file(s) to a remote server: pscp [options] source [source...] [user@]host:target So to copy the local file `c:\documents\csh-whynot.txt' to the server `example.com' as user `fred' to the file `/tmp/csh-whynot' you would type: pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot You can use wildcards to transfer multiple files in either direction, like this: pscp c:\documents\*.doc fred@example.com:docfiles pscp fred@example.com:source/*.c c:\source However, in the second case (using a wildcard for multiple remote files) you may see a warning like this: warning: remote host tried to write to a file called 'terminal.c' when we requested a file called '*.c'. If this is a wildcard, consider upgrading to SSH 2 or using the '-unsafe' option. Renaming of this file has been disallowed. This is due to a fundamental insecurity in the old-style SCP protocol: the client sends the wildcard string (`*.c') to the server, and the server sends back a sequence of file names that match the wildcard pattern. However, there is nothing to stop the server sending back a _different_ pattern and writing over one of your other files: if you request `*.c', the server might send back the file name `AUTOEXEC.BAT' and install a virus for you. Since the wildcard matching rules are decided by the server, the client cannot reliably verify that the filenames sent back match the pattern. PSCP will attempt to use the newer SFTP protocol (part of SSH 2) where possible, which does not suffer from this security flaw. If you are talking to an SSH 2 server which supports SFTP, you will never see this warning. If you really need to use a server-side wildcard with an SSH 1 server, you can use the `-unsafe' command line option with PSCP: pscp -unsafe fred@example.com:source/*.c c:\source This will suppress the warning message and the file transfer will happen. However, you should be aware that by using this option you are giving the server the ability to write to _any_ file in the target directory, so you should only use this option if you trust the server administrator not to be malicious (and not to let the server machine be cracked by malicious people). 4.2.1.1 `user' The login name on the remote server. If this is omitted, and `host' is a PuTTY saved session, PSCP will use any username specified by that saved session. Otherwise, PSCP will attempt to use the local Windows username. 4.2.1.2 `host' The name of the remote server, or the name of an existing PuTTY saved session. In the latter case, the session's settings for hostname, port number, cipher type and username will be used. 4.2.1.3 `source' One or more source files. Wildcards are allowed. The syntax of wildcards depends on the system to which they apply, so if you are copying _from_ a Windows system _to_ a UNIX system, you should use Windows wildcard syntax (e.g. `*.*'), but if you are copying _from_ a UNIX system _to_ a Windows system, you would use the wildcard syntax allowed by your UNIX shell (e.g. `*'). If the source is a remote server and you do not specify a full pathname (in UNIX, a pathname beginning with a `/' (slash) character), what you specify as a source will be interpreted relative to your home directory on the remote server. 4.2.1.4 `target' The filename or directory to put the file(s). When copying from a remote server to a local host, you may wish simply to place the file(s) in the current directory. To do this, you should specify a target of `.'. For example: pscp fred@example.com:/home/tom/.emacs . ...would copy `/home/tom/.emacs' on the remote server to the current directory. As with the `source' parameter, if the target is on a remote server and is not a full path name, it is interpreted relative to your home directory on the remote server. 4.2.2 Options These are the command line options that PSCP accepts. 4.2.2.1 `-p' preserve file attributes By default, files copied with PSCP are timestamped with the date and time they were copied. The `-p' option preserves the original timestamp on copied files. 4.2.2.2 `-q' quiet, don't show statistics By default, PSCP displays a meter displaying the progress of the current transfer: mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13% The fields in this display are (from left to right), filename, size (in kilobytes) of file transferred so far, estimate of how fast the file is being transferred (in kilobytes per second), estimated time that the transfer will be complete, and percentage of the file so far transferred. The `-q' option to PSCP suppresses the printing of these statistics. 4.2.2.3 `-r' copies directories recursively By default, PSCP will only copy files. Any directories you specify to copy will be skipped, as will their contents. The `-r' option tells PSCP to descend into any directories you specify, and to copy them and their contents. This allows you to use PSCP to transfer whole directory structures between machines. 4.2.2.4 `-v' show verbose messages The `-v' option to PSCP makes it print extra information about the file transfer. For example: Logging in as "fred". fred@example.com's password: Sending command: scp -v -f mibs.tar Connected to example.com Sending file modes: C0644 1320960 mibs.tar mibs.tar | 1290 kB | 67.9 kB/s | ETA: 00:00:00 | 100% Remote exit status 0 Closing connection This information may be useful for debugging problems with PSCP. 4.2.2.5 `-P port' connect to specified port If the `host' you specify is a saved session, PSCP uses any port number specified in that saved session. If not, PSCP uses the default SSH port, 22. The `-P' option allows you specify the port number to connect to for PSCP's SSH connection. 4.2.2.6 `-pw passw' login with specified password If a password is required to connect to the `host', PSCP will interactively prompt you for it. However, this may not always be appropriate. If you are running PSCP as part of some automated job, it will not be possible to enter a password by hand. The `-pw' option to PSCP lets you specify the password to use on the command line. Since specifying passwords in scripts is a bad idea for security reasons, you might want instead to consider using public-key authentication; see section 4.2.3. 4.2.3 Return value PSCP returns an ERRORLEVEL of zero (success) only if the files were correctly transferred. You can test for this in a batch file, using code such as this: pscp file*.* user@hostname: if errorlevel 1 echo There was an error 4.2.4 Using public key authentication with PSCP Like PuTTY, PSCP can authenticate using a public key instead of a password. There are two ways you can do this. Firstly, PSCP can use PuTTY saved sessions in place of hostnames (see section 4.2.1.2). So you would do this: - Run PuTTY, and create a PuTTY saved session (see section 3.1.2) which specifies your private key file (see section 3.12.2). You will probably also want to specify a username to log in as (see section 3.10.2). - In PSCP, you can now use the name of the session instead of a hostname: type `pscp sessionname:file localfile', where `sessionname' is replaced by the name of your saved session. Secondly, PSCP will attempt to authenticate using Pageant if Pageant is running (see chapter 7). So you would do this: - Ensure Pageant is running, and has your private key stored in it. - Specify a user and host name to PSCP as normal. PSCP will automatically detect Pageant and try to use the keys within it. For more general information on public-key authentication, see chapter 6. 4.3 Secure iXplorer Lars Gunnarson has written a graphical interface for PSCP. You can get it from his web site, at www.i-tree.org. Chapter 5: Using the command-line connection tool Plink ------------------------------------------------------- Plink (PuTTY Link), is a command-line connection tool similar to UNIX `ssh'. It is probably not what you want if you want to run an interactive session in a console window. 5.1 Starting Plink Plink is a command line application. This means that you cannot just double-click on its icon to run it and instead you have to bring up a console window. With Windows 95, 98, and ME, this is called an `MS-DOS Prompt' and with Windows NT and 2000 it is called a `Command Prompt'. It should be available from the Programs section of your Start Menu. To start Plink it will need either to be on your `PATH' or in your current directory. To add the directory containing Plink to your `PATH' environment variable, type into the console window: set PATH=C:\path\to\putty\directory;%PATH% This will only work for the lifetime of that particular console window. To set your `PATH' more permanently on Windows NT, use the Environment tab of the System Control Panel. On Windows 95, 98, and ME, you will need to edit your `AUTOEXEC.BAT' to include a `set' command like the one above. 5.2 Plink Usage Once you've got a console window to type into, you can just type `plink' on its own to bring up a usage message. This tells you the version of Plink you're using, and gives you a brief summary of how to use Plink: Z:\sysosd>plink PuTTY Link: command-line connection utility Release 0.50 Usage: plink [options] [user@]host [command] Options: -v show verbose messages -ssh force use of ssh protocol -P port connect to specified port -pw passw login with specified password 5.2.1 The basics 5.2.2 Options These are the command line options that Plink accepts. 5.2.2.1 `-v' show verbose messages By default, Plink only displays any password prompts and the output of the remote command. The `-v' option makes it print extra information about the connection being made, for example: Server version: SSH-1.5-OpenSSH-1.2.3 We claim version: SSH-1.5-PuTTY Using SSH protocol version 1 Received public keys Host key fingerprint is: 1023 e3:65:44:44:bd:b1:04:59:bc:e2:3d:a1:4d:09:ce:99 Encrypted session key Using 3DES encryption Trying to enable encryption... Successfully started encryption Sent username "fred". Sent username "fred" fred@example.com's password: This information can be useful for diagnosing problems. 5.2.2.2 `-ssh' force use of ssh protocol 5.2.2.3 `-P port' connect to specified port 5.2.2.4 `-pw passw' login with specified password 5.3 Using public key authentication with Plink 5.4 Using Plink in batch files and scripts 5.5 Using Plink with CVS To use Plink with CVS, you need to set the environment variable `CVS_RSH' to point to Plink: set CVS_RSH=\path\to\plink.exe You also need to arrange to be able to connect to a remote host without a password. To do this, either: - Run PuTTY, and create a PuTTY saved session (see section 3.1.2) with the protocol set to SSH (see section 3.1.1) and specifies your private key file (see section 3.12.2). You will probably also want to specify a username to log in as (see section 3.10.2). You should then be able to run CVS as follows: cvs -d :ext:user@sessionname:/path/to/repository co module If you specified a username in your saved session, you can just say: cvs -d :ext:sessionname:/path/to/repository co module Alternatively, you can use Pageant if Pageant is running (see chapter 7). To do this, you would: - Ensure Pageant is running, and has your private key stored in it. - Set the environment variable PLINK_PROTOCOL to the string `ssh', to make sure Plink will try to connect using SSH instead of Telnet. - Run CVS as follows: cvs -d :ext:user@hostname:/path/to/repository co module 5.6 Using Plink with WinCVS Plink can also be used with WinCVS. Firstly, arrange for Plink to be able to connect to a remote host without a password. section 5.5 has instructions on this. In WinCVS, bring up the _Preferences_ dialogue box from the _Admin_ menu, and switch to the _Ports_ tab. Tick the box there labelled _Check for an alternate rsh name_ and in the text entry field to the right enter the full path to `plink.exe'. Select _OK_ on the _Preferences_ dialogue box. Next, select _Command Line_ from the WinCVS _Admin_ menu, and type a CVS command as in section 5.5, for example: cvs -d :ext:user@hostname:/path/to/repository co module Select the folder you want to check out to with the _Change Folder_ button, and click _OK_ to check out your module. Once you've got modules checked out, WinCVS will happily invoke plink from the GUI for CVS operations. 5.7 Using Plink with... ? Chapter 6: Using public keys for SSH authentication --------------------------------------------------- 6.1 Public key authentication - an introduction Public key authentication is an alternative means of identifying yourself to a login server, instead of typing a password. It is more secure and more flexible, but more difficult to set up. In conventional password authentication, you prove you are who you claim to be by proving that you know the correct password. The only way to prove you know the password is to tell the server what you think the password is. This means that if the server has been hacked, or _spoofed_ (see section 2.2), an attacker can learn your password. Public key authentication solves this problem. You generate a _key pair_, consisting of a public key (which everybody is allowed to know) and a private key (which you keep secret and do not give to anybody). The private key is able to generate _signatures_. A signature created using your private key cannot be forged by anybody who does not have that key; but anybody who has your public key can verify that a particular signature is genuine. So you generate a key pair on your own computer, and you copy the public key to the server. Then, when the server asks you to prove who you are, PuTTY can generate a signature using your private key. The server can verify that signature (since it has your public key) and allow you to log in. Now if the server is hacked or spoofed, the attacker does not gain your private key or password; they only gain one signature. And signatures cannot be re-used, so they have gained nothing. There is a problem with this: if your private key is stored unprotected on your own computer, then anybody who gains access to _that_ will be able to generate signatures as if they were you. So they will be able to log in to your server under your account. For this reason, your private key is usually _encrypted_ when it is stored on your local machine, using a passphrase of your choice. In order to generate a signature, PuTTY must decrypt the key, so you have to type your passphrase. This can make public-key authentication less convenient than password authentication: every time you log in to the server, instead of typing a short password, you have to type a longer passphrase. One solution to this is to use an _authentication agent_, a separate program which holds decrypted private keys and generates signatures on request. PuTTY's authentication agent is called Pageant. When you begin a Windows session, you start Pageant and load your public key into it (typing your passphrase once). For the rest of your session, you can start PuTTY any number of times and Pageant will automatically generate signatures without you having to do anything. When you close your Windows session, Pageant shuts down, without ever having stored your decrypted private key on disk. Many people feel this is a good compromise between security and convenience. See chapter 7 for further details. 6.2 PuTTYgen: RSA key generator for PuTTY PuTTYgen is a key generator. It generates pairs of public and private keys to be used with PuTTY, PSCP, and Plink, as well as the PuTTY authentication agent, Pageant (see chapter 7). PuTTYgen generates RSA keys. When you run PuTTYgen you will see a window where you have two choices: _Generate_ new public/private key pair or _Load_ an existing private key. 6.2.1 Generate a new key Before generating a new key you have to choose the strength of the encryption. With _Parameters_ you define the strength of the key. The default of 1024 should be OK for most users. Pressing the _Generate_ button starts the process of generating a new key pair. You then have to move the mouse over the blank area in order to generate random data for the algorithm. Continue until the progress bar is complete. As soon as enough random data is available the key is generated. This may take a little while, especially on slow machines. Once the key is generated, its details appear in the _Key_ part of the PuTTYgen window. Now you can change the _Key comment_ to something more meaningful than the default (which is based on the current date). e.g. add the name of the host you will use it for. When using multiple keys a meaningful comment may help you remember which passphrase to use! You should always enter a _Key passphrase_ and _Confirm passphrase_ to protect your keys. Finally save the key by pressing the _Save_ button. Do not close the window but proceed with step section 6.2.3, otherwise you will have to _Load_ the private key again as described below. 6.2.2 Load and modify a key PuTTYgen does not store the public key in a file by default. If you have to distribute the public key you can press the _Load_ button, select the private key file, and PuTTYgen will give you the public key again. You can also change the comment and passphrase for your private key this way. Just modify the values and _Save_ the key. 6.2.3 Getting ready for public key authentication Connect to your SSH server using PuTTY with the SSH protocol. When the connection succeeds you will be prompted for your user name and password to login. Once logged in change into the `.ssh' directory and open the file `authorized_keys' with your favorite editor (you may have to create this file if this is the first key to add). Switch to the PuTTYgen window and select all of the content below _Public key for pasting into authorized_keys file_. It should look something like this: 1023 37 6729869421817809239524123307444843676495258040197688586095026 218017964219524574384185171134405192751574887749443098978024260520998 258039707512750527690352945038240173825485476926644212943563622886152 496520554071589241413002317263954326761291523174825533887082646711419 7732169207606577939681765894398086955929 rsa-key-20010206 Copy it to the clipboard (`Ctrl+C'). Then, switch back to the PuTTY window and insert the data into the open file. Save the file. From now on you can use the private key for authentication to this host. Either select the private key in PuTTY's _Connection_, _SSH_ panel: _Private key file for authentication_ dialog or use it with Pageant as described in chapter 7. Chapter 7: Using Pageant for authentication ------------------------------------------- Pageant is an SSH authentication agent. It holds your private keys in memory, already decoded, so that you can use them often without needing to type a passphrase. Currently, Pageant only works with SSH v1. 7.1 Getting started with Pageant Before you run Pageant, you need to have a private key. See chapter 6 to find out how to generate and use one. When you run Pageant, it will put an icon of a computer wearing a hat into the System tray. It will then sit and do nothing. If you click the Pageant icon with the right mouse button, you will see a menu. Select _View Keys_ from this menu. The Pageant main window will appear. (You can also bring this window up by double- clicking on the Pageant icon.) The Pageant window contains a list box. This shows the private keys Pageant is holding. When you start Pageant, it has no keys, so the list box will be empty. To add a key to Pageant, press the _Add Key_ button. Pageant will bring up a file dialog, labelled `Select Private Key File'. Find your private key file in this dialog, and press _Open_. Pageant will now load the private key. If the key is protected by a passphrase, Pageant will ask you to type the passphrase. When the key has been loaded, it will appear in the list in the Pageant window. Now start PuTTY and open an SSH session to a site that accepts your key. PuTTY will notice that Pageant is running, retrieve the key automatically from Pageant, and use it to authenticate. You can now open as many PuTTY sessions as you like without having to type your passphrase again. When you want to shut down Pageant, click the right button on the Pageant icon in the System tray, and select _Exit_ from the menu. Closing the Pageant main window does _not_ shut down Pageant. 7.2 Using agent forwarding 7.3 Security considerations Chapter 8: Troubleshooting PuTTY -------------------------------- [$Id: pscp.but,v 1.13 2001/08/28 09:53:51 simon Exp $] [$Id: plink.but,v 1.7 2001/08/04 13:06:08 simon Exp $] [$Id: pubkey.but,v 1.3 2001/06/15 19:31:10 simon Exp $]