Using PuTTY with Debian GNU/Linux Systems

Contents

Disclaimer
Maintenance Log
Introduction
Obtaining and Installing PuTTY
Configuring PuTTY
     Terminal -> Features
     Window
     Window -> Translation
     Window -> Appearance
     Connection -> Data
Copying and Pasting with PuTTY
Using GNU screen with PuTTY
Conclusion

Disclaimer

This is not an official Debian site.  This document details the author's experiences and recommendations in configuring and using the PuTTY ssh client with Debian GNU/Linux systems.  All opinions expressed are those of the author and do not necessarily represent the opinions or the official positions of the Debian project, the author of PuTTY, or any other organization or individual.  This information is presented in the hope that it will be useful, but without any warranty or guarantee of any kind.  This information is presented free of charge, free of support, free of service, and free of liability.  Take this information with as many grains of salt as you think it's worth; and use it, if you choose to do so, entirely at your own risk.  The author hereby explicitly places this material in the public domain.  All trademarks, registered trademarks, service marks, etc. are the property of their respective owners.

Maintenance Log

Introduction

PuTTY is an open-source ssh (secure shell) client program which acts as a terminal emulator, and it can be used to login to a host system which runs an ssh server, such as a Debian GNU/Linux system on which the openssh-server package is installed and configured.  Although there is a Linux port of PuTTY available, the original PuTTY program was designed and written as a Windows® application.  Although some of the material presented here may be applicable to the Linux port of PuTTY, this web page is designed to address the environment of PuTTY running under the Microsoft® Windows® operating system and used to login to a remote host which is running Debian GNU/Linux.

Obtaining and Installing PuTTY

The official PuTTY web site is http://www.chiark.greenend.org.uk/~sgtatham/putty/.  There are also a number of mirror sites around the world.  From the official web site, click on "Mirrors" at the top of the web page to see a list of mirrors.  Here is a US mirror that I often use: http://www.silvertree.org/mirror/putty/.  In most cases, none of the FTP links on the Download page of a mirror have been mirrored — they still point to the same places as on the original web site.  (The HTTP links on the Download page have been mirrored.) 

Although there is an "installer" program available, this is really not necessary.  Simply download putty.exe (in binary of course) and put it somewhere.  I usually install my copy as "C:\Program Files\PuTTY\putty.exe".  Then I create a desktop shortcut for it.  (Of course I make the title of the shortcut "PuTTY".)  There is no prerequisite software that you need to install.  There are no .dll files to install with it.  The putty.exe file is all you need.  What could be simpler?

There are two advantages to using the installer: (1) PuTTY will show up in the official list of installed programs (Control Panel -> Programs and Features) and (2) Running the "uninstall" function for PuTTY on this screen will clean up the PuTTY environment, which includes Windows registry entries and a random seed file.  But this also means downloading stuff you don't need.  If you install putty.exe directly, you can clean up the PuTTY environment prior to erasing putty.exe by issuing the command "putty -clean".  This will remove PuTTY entries from the Windows registry and delete the random seed file.  (On a multi-user system, this will only clean up the PuTTY environment for the current logged-on user.  Logon as each user which has used PuTTY and cleanup the environment for that user before erasing putty.exe.)

Configuring PuTTY

To configure PuTTY, double left click on the desktop shortcut icon that you created for it in the previous step.  This will launch the PuTTY program, which will initially start out on the configuration menu.  On the left side of the configuration menu will be a window titled "Category".  This is the navigation portion of the configuration menu.  It works like the navigation portion of Windows Explorer.  Here you select the category and subcategory of options to configure.  On the right side are the options for the selected category and subcategory.  Initially, the "Session" category, with no subcategory, is selected.  I will not attempt to cover every configuration option, just the most important ones or the ones most likely to cause trouble if not configured correctly. 

Terminal -> Features

On the "Terminal -> Features" panel, under "Enabling and disabling advanced terminal features", most users should check the following boxes: "Disable Arabic text shaping" and "Disable bidirectional text display".  If you are using a right-to-left language, such as Hebrew, or you are making regular use of Arabic, you might want to leave one or both of these boxes unchecked.  See the PuTTY documentation for details.  Otherwise, you should check both boxes.  They are not checked by default.

Window

On the "Window" panel, under "Set the size of the window", enter the number of columns and rows that you initially want in the terminal window when your session is launched.  80 columns by 25 rows is a good default choice for most users, as it corresponds to the size of the traditional text-mode Linux virtual console on a PC, but some people prefer a different size.  I prefer 80 columns by 34 rows myself, but pick what works best for you.  On this same panel, under "When the window is resized", I like to use the radio button "Change the number of rows and columns".

Window -> Translation

On the "Window -> Translation" panel, in the drop-down box under "Remote character set", select UTF-8 as the encoding scheme.  All modern Debian systems use a UTF-8 locale as the default.  To configure this in Debian, enter the command "dpkg-reconfigure locales" (as root of course).  For US users, the default locale should be en_US.UTF-8.  For machines with VGA-compatible video hardware, also enter the command "dpkg-reconfigure console-setup" to make sure that UTF-8 is the encoding scheme used by the Linux console as well.  It doesn't matter what your default locale is in Windows.  The remote character set encoding in PuTTY needs to be set to UTF-8, so that the encoding used by the Linux server matches the encoding expected by the PuTTY client.

Window -> Appearance

On the "Window -> Appearance" panel, under "Font settings", you will see "Font used in the terminal window".  PuTTY's default font is "Courier New, 10-point".  Courier New does contain a large number of characters from a number of different languages.  Unfortunately, a commonly-used special character is not included in Courier New.  When man(1) decides to hyphenate a word at the end of the line, it uses code point U+2010 HYPHEN as the hyphenation character, rather than U+002D HYPHEN-MINUS, as one might expect.  Courier New does not support this code point, so you see a square box at the end of the line instead of a hyphen.  The only standard monospaced font that comes with Windows that I was able to find which supports U+2010 HYPHEN is Consolas.  Therefore, among the standard Windows fonts, I recommend Consolas.  To change the font, click on the "Change" button next to the font name.  This opens up a new dialog box which will allow you to select the font that you want to use.

You might want to select a larger point size than 10 also.  A 10-point font produces a rather small terminal window.  If you select a point size which is too large, the terminal window won't fit on the screen; so don't overdo it either.  You may have to experiment to determine the optimal point size for your situation.  The resolution of your monitor in pixels, the number of text rows and columns you specified, and the properties of the font itself are the determining factors as to how large a point size you can specify and still have the terminal window fit on the screen.  With a monitor resolution of 1680 horizontal pixels by 1050 vertical pixels, a window size of 80 columns by 34 rows, and the Consolas font, I normally use 18 points.

PuTTY requires that all characters be selected from a single font, and it doesn't support "font linking".  (Apparently, font linking used to work at some point in the past; but due to some PuTTY code changes and/or changes in Windows, that capability has since been lost.)  Therefore, what we would ideally like would be a "Grand Unified Monospace" font which contains every character defined in unicode.  Unfortunately, such a font does not exist.  However, there are a number of monospace fonts available which contain a large number of characters and symbols that you may wish to try, such as FreeMono, Everson Mono (shareware), and DejaVu Sans Mono.  These fonts don't come standard with Windows, but you can download and install them and try them out.  I can verify that DejaVu Sans Mono and FreeMono both support U+2010 HYPHEN.  I haven't tried Everson Mono.

Probably the easiest way to get these fonts installed on your Windows system is to download them from your Debian system, since chances are these fonts are already installed on your Debian system.  The Debian package names are fonts-dejavu-core, fonts-dejavu-extra, and fonts-freefont-ttf.  For DejaVu Sans Mono, the font files are located in the /usr/share/fonts/truetype/dejavu directory; and the font files themselves are DejaVuSansMono.ttf, DejaVuSansMono-Bold.ttf, DejaVuSansMono-Oblique.ttf, and DejaVuSansMono-BoldOblique.ttf.  For FreeMono, the font files are located in the /usr/share/fonts/truetype/freefont directory; and the font files themselves are FreeMono.ttf, FreeMonoBold.ttf, FreeMonoOblique.ttf, and FreeMonoBoldOblique.ttf.  Download these files from your Debian system to a working directory on your Windows system using FTP.  (Be sure to use binary mode to transfer the files.)  Then, on your Windows system, open that working directory using Windows Explorer, right click on the font file, then left click on "Install" in the pop-up menu.  Do this for all font files.

In order to use FreeMono in PuTTY, you will probably have to check the box labeled "Allow selection of variable-pitch fonts" next to the "Change" button before you click on the "Change" button.  Otherwise, FreeMono will not show up in the list of fonts that you may select.  Normally, this is not something that you should do, since most proportional (variable-pitch) fonts don't work well with PuTTY; but FreeMono is an exception case that does work well with PuTTY.  I have tried both DejaVu Sans Mono and FreeMono.  Overall, FreeMono seems to support more characters than DejaVu Sans Mono.  However, each font supports characters that the other does not; so which one is best for you depends on which characters you need and which ones you don't.  You might want to download this file, utf-8.txt, as a test file.  It contains all unicode code points between U+0000 and U+2E7F, inclusive.  (U+2E80 is the first CJK character.)  You can have two PuTTY sessions side by side, one using DejaVu Sans Mono and the other using FreeMono, both of which are displaying this file, and scroll through the file synchronously using both sessions to get a side-by-side comparison of how each font displays, or does not display, every code point.  Then you can make an informed decision about which font is best for you.

Zen Hei Mono includes a large number of Chinese, Japanese, Korean, and Vietnamese glyphs (CJK characters).  Unfortunately, Zen Hei Mono coexists in the same .ttc file as its proportional cousin, Zen Hei, which appears to make Zen Hei Mono unavailable to programs like PuTTY.  After making your font changes, click on the "OK" button to return to the PuTTY configuration screen.

Connection -> Data

On the "Connection -> Data" panel, under "Terminal type string", enter the terminal type that you want to use.  This corresponds to a terminal type definition in ncurses, so obviously the correct value to use depends on what terminal type PuTTY is emulating.  PuTTY emulates a modern version of xterm, with 256-color support, tmux support, etc.  However, the behavior of PuTTY differs from a modern xterm in one very important aspect: the handling of VT100 graphic character escape sequences.  PuTTY does not support these escape sequences when operating in UTF-8 mode.  In other words, PuTTY behaves like a modern xterm with the "vt100Graphics" resource set to "false".  The default value for this xterm resource is "true".  The default behavior of xterm in this regard is actually a standards violation.  (Or it is an extension to the standard, depending on your point of view.)  The "right" way to draw boxes in UTF-8 mode is to simply send the appropriate UTF-8 characters to draw the box.

A number of people have requested an enhancement to PuTTY to support VT100 graphic character escape sequences in UTF-8 mode; but at this point the author of PuTTY, Simon G. Tatham, is not inclined to implement it, both because it is a standards violation and also because it makes the program code more complicated and less reliable.  Click here for a more complete discussion of this topic.

So what terminal type definition should you use?  That's a good question.  PuTTY's default value for this field is "xterm", but this is not optimal.  This terminal type definition in ncurses is based on an older version of xterm.  For example, it only supports 8 colors, has no tmux support, and falsely advertises support for VT100 graphic character escape sequences in UTF-8 mode, which PuTTY does not support.  There is also an "xterm-utf8" terminal type definition in ncurses.  This is basically the same as "xterm", except that it does not support VT100 graphic character escape sequences in UTF-8 mode.  But it still supports only 8 colors and has no tmux support.  Furthermore, the dircolors command in the coreutils package does not list "xterm-utf8" as a terminal which supports color in its internal database.  (It should.)  There is also a "putty" terminal type definition in ncurses.  But it also falls short.  It only supports 8 colors and has no tmux support.  It also does not have support for the xterm control sequences which change the window title, which PuTTY does support. 

There is also a "putty-256color" terminal type definition in ncurses.  It does support 256 colors, but still has no tmux support and no support for the xterm control sequences which change the window title.  The terminal type definition in ncurses that comes the closest to PuTTY's capabilities is "xterm-256color".  It does have 256-color support, tmux support, and support for the xterm control sequences which change the window title.  The dircolors command of the coreutils package also recognizes "xterm-256color" as a terminal type which supports color.  I could find only one drawback: it falsely advertises support for VT100 graphic character escape sequences in UTF-8 mode, which PuTTY does not support.

Since there is no terminal type definition in ncurses which matches PuTTY's capabilities, I decided to write my own.  Here is a link to a patch which adds a new terminal type definition to ncurses: "xterm-256color-utf8".  Its capabilities are the same as those of "xterm-256color", except that it does not support VT100 graphic character escape sequences in UTF-8 mode.  The above patch is for ncurses versions prior to 5.9+20150516-2.  It will not apply to version 5.9+20150516-2 or later.  Here is a link to a patch for newer versions of ncurses.  I won't go into the procedure for modifying and recompiling a Debian source package here.  There are other web pages available as links from my home page which document the procedure.  Recompiling the ncurses source package produces many binary packages.  The only one you need to install is the ncurses-term binary package.  It is the only package affected by the source change, and it doesn't have package dependency issues with mismatching version numbers between it and other ncurses packages.

As an alternative to patching the ncurses source package and recompiling it, you can use> the above patch to create a local terminal definition and compile it separately with the "tic" command.  See the man page for the tic command for details.

Along with the above patch, I also wrote a patch for the coreutils package to add "xterm-256color-utf8", my new terminal definition, to the internal database used by the dircolors command as a terminal which supports color.  (The "xterm-utf8" terminal definition is added to the database by this patch as well.)  Here is a link to the patch.  Recompiling the coreutils source package will produce multiple binary packages.  Only the coreutils binary package needs to be installed.  It is the only one affected.

After recompiling these two source packages and installing the binary packages with dpkg, you can set the terminal type string in PuTTY to "xterm-256color-utf8" and have a good match to PuTTY's capabilities.  But what if you are not the system administrator of the Debian system to which you are logging in, or can't (or don't want to) modify these source packages for some reason?  Well, in that case, the next best thing is to use terminal type "xterm-256color", then set the following environment variable:
 

     NCURSES_NO_UTF8_ACS=1

~/.bashrc is a good place to set this.  This is an environment variable used by ncurses which means, "Never mind what the terminal definition says, this terminal does not support VT100 graphic character escape sequences in UTF-8 mode".  But it really is better to have this property defined in the terminal definition itself, if possible.  In ~/.bashrc, you can examine the TERM environment variable and find that it is "xterm-256color", but you don't know if the login is from PuTTY or from a real xterm.  Therefore, you don't know whether or not to set NCURSES_NO_UTF8_ACS.  (Of course, the xterm-256color-utf8 terminal definition can also be used with a real xterm if the VT100Graphics resource is set to false.)

Of course, it is an application responsibility to query the terminal's capabilities and act accordingly.  If the application sends VT100 graphic character escape sequences to a terminal which does not support it, such as PuTTY, you will see something like this:
 

     lqqqqqqqqqqqqqqqqqqqqqqqqu Configuring libc6:s390x tqqqqqqqqqqqqqqqqqqqqqqqqk
     x Running services and programs that are using NSS need to be restarted,    x
     x otherwise they might not be able to do lookup or authentication any more  x
     x (for services such as ssh, this can affect your ability to login).        x
     x Please review the following space-separated list of init.d scripts for    x
     x services to be restarted now, and correct it if needed.                   x
     x                                                                           x
     x Note: restarting sshd/telnetd should not affect any existing              x
     x connections.                                                              x
     x                                                                           x
     x Services to restart for GNU libc library upgrade:                         x
     x                                                                           x
     x vsftpd exim4 cron atd____________________________________________________ x
     x                                                                           x
     x                                  <Ok>                                     x
     x                                                                           x
     mqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj

instead of something like this:
 

     ┌─────────────────────┤ Configuring libssl1.0.0:s390x ├─────────────────────┐
     │ This release of OpenSSL fixes some security issues. Services will not     │
     │ use these fixes until they are restarted. Please note that restarting     │
     │ the SSH server (sshd) should not affect any existing connections.         │
     │                                                                           │
     │ Please check the list of detected services that need to be restarted and  │
     │ correct it, if needed. The services names must be identical to the        │
     │ initialization script names in /etc/init.d and separated by spaces. No    │
     │ services will be restarted if the list is empty.                          │
     │                                                                           │
     │ Any service that later fails unexpectedly after this upgrade should be    │
     │ restarted. It is recommended to reboot this host to avoid any             │
     │ SSL-related trouble.                                                      │
     │                                                                           │
     │ Services to restart to make them use the new libraries:                   │
     │                                                                           │
     │ vsftpd ssh exim4_________________________________________________________ │
     │                                                                           │
     │                                  <Ok>                                     │
     │                                                                           │
     └───────────────────────────────────────────────────────────────────────────┘

The box-drawing characters can be displayed with PuTTY, but not via VT100 graphic character escape sequences.  Instead, the application must send the proper UTF-8 codes to produce the box-drawing characters, just as this web page has done.  If you encounter problems such as this, report it as an application bug.

Sometimes, one can get problems such as in the example above during a Debian system upgrade.  If the locales package is upgraded, the old version of the package has been removed, the new version of the package is not yet configured, and the locales package is needed to draw a box, you may get results such as above.  The problem can usually be circumvented by manually upgrading the locales package first, then upgrading the rest of the system.  See Debian bug report 754596 for details.

It is worth noting that the "make menuconfig" and "make nconfig" Linux kernel configuration applications do not have support for using UTF-8 box drawing characters.  If the terminal has support for VT100 graphic character escape sequences, then these applications will use the VT100 graphic character escape sequences to draw pretty boxes.  If the terminal does not have support for VT100 graphic character escape sequences, then these applications will use ordinary ASCII characters, such as U+002D HYPHEN-MINUS for a horizontal line, U+007C VERTICAL LINE for a vertical line, and U+002B PLUS SIGN for an intersection, to draw the boxes.  These boxes are not as pretty as boxes drawn with the special box-drawing characters.  These applications do not check to see if UTF-8 box-drawing characters can be used to draw the boxes.  These are not application bugs, or a bug in PuTTY.  These are simply applications with no support for UTF-8 box drawing.  I think that would be a useful enhancement, don't you?  Is anyone on the kernel team listening?

Copying and Pasting with PuTTY

Copying and pasting work differently with PuTTY than with other Windows applications.  In particular, you don't use Ctrl+C (^C) to copy and you don't use Ctrl+V (^V) to paste!  Ctrl+C and Ctrl+V have special meanings in the shell and other Linux applications, so it's important not to use them for copy and paste.  In order to copy text from the PuTTY window to the clipboard, move the mouse pointer to the first character that you want to copy, press and hold down the left mouse button, drag the mouse pointer to the last character that you want to copy, then release the left mouse button.  That's it.  Selecting text and copying text are one and the same.  As soon as you release the left mouse button, the selected text is copied to the clipboard.  To paste, single click the right mouse button anywhere in the PuTTY window, and whatever is in the Windows clipboard will be inserted at the current cursor position.  (Make sure that your editor is in insert mode before you click.)  You can also paste by using Shift+Insert, if the PuTTY window already has the focus.  To deselect selected text, single click the left mouse button anywhere in the PuTTY window.

By default, if the last character selected is on a different line than the line containing the first character selected, then the selected text includes all intervening characters, wrapping at the end of each line and starting at the beginning of the next line.  If what you want is a box of characters, with the beginning and ending characters defining diagonally opposite corners, hold down the Alt key while making your selection.  Pasting is equivalent to typing the characters from the clipboard at the current cursor position.  Therefore, beware of using Linux editors that do automating indenting.  If the text in the clipboard already contains indenting, then the resulting formatting may not be what you expected.  You may need to disable automatic indenting before you paste or correct the formatting after you paste.

Using GNU screen with PuTTY

GNU screen is a program that allows a single terminal to behave like multiple logical terminals.  I don't know much about GNU screen; and I don't use it myself; but based on reports I have received from those who do use it, screen has a configuration file, called ~/.screenrc.  In it, there is typically an entry like this:
 

     termcapinfo xterm 'is=\E[r\E[m\E[2J\E[H\E[?7h\E[?1;4;6l'

This works fine if your terminal type is xterm; but if it is xterm-256color-utf8, or anything else other than xterm, it doesn't match.  You may get strange results, such as GNU screen not honoring a non-standard screen width.  The solution is to add an asterisk at the end of the terminal type definition, like this:
 

     termcapinfo xterm* 'is=\E[r\E[m\E[2J\E[H\E[?7h\E[?1;4;6l'

This causes a match for any terminal type which starts with xterm.

Conclusion

Have fun using your properly-configured PuTTY terminal with your properly-configured Debian host system!  And many thanks to Simon G. Tatham, the author of PuTTY, for his excellent open-source ssh client for Windows.

Return to my home page