Debian X Window System Frequently Asked Questions (FAQ) List Copyright 1998-2002 Branden Robinson. This document is licensed under the GNU General Public License, version 2 (see /usr/share/common-licenses/GPL). By its nature, this document is not complete. If your question is not answered here, try /usr/share/doc//README.Debian (and other files in the package's doc directory), manual pages, and the debian-user mailing list. See http://www.debian.org/ for more information about the Debian mailing lists. Two other FAQ's of interest are available: *) The XFree86 FAQ, provided in the xfree86-common package; this FAQ focuses almost exclusively on configuration and hardware support problems with the X server. If you are having trouble getting the X server started, especially if you have newer video hardware, this FAQ often has an answer. *) The XTERM FAQ, provided in the xterm package; this FAQ addresses various issues with one of the most popular and important of X clients -- the terminal emulator that ships with the X Window System. Like all other documentation, these FAQ's are in /usr/share/doc//. Finally, for the latest news about Debian XFree86 packaging development, future plans, or to find out how you can help improve the quality of Debian's XFree86 packages, check out the X Strike Force: http://people.debian.org/~branden/ CONTENTS General Questions *) What is the X Window System? *) What is XFree86? *) What are X servers and X clients? *) Why is the X usage of "server" and "client" backwards from everyone else's? *) What is an X session? *) What is the root window? *) What is a window manager? *) What is a session manager? *) What is window focus? *) What are X resources? *) What are app-defaults? Specific Questions *) How do I customize my X session? *) How do I change what appears in the root window? *) What is the difference between "bits-per-pixel" and "color depth"? *) How do I change the color depth of my X server? *) How do I run more than one local X server simultaneously? *) How do I set up the mouse buttons for left-handed use? *) How do I stop xdm from starting at boot? *) How do I tell xdm to start the X server on a different virtual console? *) How do I run an X client as root when the X session is run by a user? *) Why doesn't my backspace, delete, or some other key work? *) How do I change xterm's default terminal type or key bindings? *) How do I keep my mouse from going crazy (or going away) when switching between X and the Linux virtual console? *) How do I get the X server to find the "fixed" font? *) Why doesn't the X server package just depend on the xfonts-base package? *) Why does the "single-quote" (') symbol in the fonts not look the way it used to? *) How do I use Xnest, the nested X server? *) I recently upgraded some packages, and now instead of readable text, some characters appear as little gray boxes. Why? *) How do I add custom sections to a dexconf-generated XF86Config or XF86Config-4 file? *) Why does the X server take up so much memory? GENERAL QUESTIONS *) What is the X Window System? In the words of its primary manual page, X(1), it is a "portable, network-transparent window system". Its primary distinction from other well-known window systems like Microsoft Windows and Apple's MacOS is that it was designed with the local area network in mind. You can run programs on one machine and display them on another. Historically, the X Window System was initially conceived in 1984, at the Massachusetts Institute of Technology as a joint project between their Laboratory for Computer Science and the Digital Equipment Corporation. The initial impetus for the X Window System was MIT's Project Athena, which sought to provide easy access to computing resources for all students; because MIT could not buy all the workstations needed, nor was any single vendor willing to donate them, a platform-independent graphics system was required. The first version of the X Window System to be widely deployed was Version 10 (X10). It was shortly superseded by Version 11 (X11), however, in 1987. In 1988, a non-profit group called the (MIT) X Consortium was formed to direct future development of X standards in an atmosphere inclusive of many commercial and educational interests. The X Consortium produced several significant revisions to X11, concluding with Release 6 in 1994 (X11R6). The X Consortium dissolved at the end of 1996, producing a final, small revision to X11R6 called X11R6.3. Ownership of X then passed to the Open Group, an outgrowth of the Open Software Foundation (OSF), who produced the popular Motif widget set for X. In early 1998, the Open Group released a further revision to X11R6, called X11R6.4 -- a departure from the traditional licensing terms, however, prevented adoption of this version of the X Window System by many vendors, including the XFree86 Project, Inc. (see below). In late 1998, the Open Group relicensed X11R6.4 under terms identical with the traditional license. In May 1999, stewardship of the X Window System passed from the Open Group to X.Org, a non-profit organization focused exclusively on maintenance and further development of the X Window System. X.Org has supervised the release of X11R6.5.1. *) What is XFree86? Strictly speaking, the various groups that have developed the X Window System over the years have been standardization groups, not software developers. However, they have also developed a reference implementation of the standards, and this source code is what is popularly called the X Window System. The license on this source code freely permits modification and redistribution, and many software vendors have taken advantage of its terms. The XFree86 Project, Inc., is a not-for-profit group whose original, self-determined charter was to develop X servers that would work on the wide variety of video hardware available for Intel x86-based machines (hence the "86" in "XFree86"). They also decided to release their X servers under licensing terms identical to that of the freely available X sources, hence the "Free" in the "XFree86". By keeping with the licensing terms of the original X source distribution, XFree86 has enjoyed immense popularity, and they no longer confine their activities to merely producing X servers for IBM PC-compatible video hardware. XFree86 is thus the superset of the X Window System that is used by the Debian GNU/Linux system. *) What are X servers and X clients? This is the most important, and probably the first, concept a newcomer to the X Window System should learn. X achieves its success by separating the details of display and input hardware from the programs that use them. When a program that uses the X Window System needs to, for instance, draw on the screen, or know what keys on the keyboard have just been pressed, it does not communicate directly with the hardware. Instead, it communicates with a single program, called the X server, whose job it is to deal with a computer's video card (and thus monitor), keyboard, and mouse (or other pointing device). The programs, then, that wish to use the windowing system to interact with the user are thus called X clients. The program that actually "delivers the goods", both to the user in the form of displayed graphics, and to the program in the form of information about pressed keys or a moving mouse, is the X server. Commonly, an individual machine like a workstation or X terminal, only runs one X server, to which many X clients "connect" and perform their tasks. In fact, however, on a Linux machine, more than one X server can be running at one time. *) Why is the X usage of "server" and "client" backwards from everyone else's? People who have worked in LAN-type environments are easily confused by the X notions of client and server. In such a scenario, one might have dozens of "client" machines, each running an X server which uses the network to connect to X clients (application programs) running on the "server" in the machine room. However, X's client/server terminology makes perfect sense if one thinks about what resources are in demand, and what program's job it is to service requests. On the computer where a human being is actually sitting down and working, the resources in demand are the video display, keyboard, and mouse (or other pointing device). All of the running programs can't monopolize these resources at once, or we lose the benefits of multitasking that a windowing system gives us. Furthermore, why should each and every piece of software, like a mail reader, a clock application, and so forth, have to worry about things like how many buttons the mouse has, or how many colors the display can show at once? The X server centralizes this information and manages the hardware resources, which it serves to the X clients. *) What is an X session? An X session is the set of X clients running that correspond to a single server process, which typically corresponds to one user's login. In other words, when I start X from the command line with "startx", or if a display manager like xdm is running and presents me with a graphical login screen and I type my username and password, what happens next is my X session. People generally customize their X sessions to start a set of familiar, desirable applications, like a clock, a graphical "biff" program that tells them when they have new email, one or more terminal sessions on various other computers, and so forth. The X session is terminated by "killing" the X server. The X server may be killed by the key sequence, or by stopping a particular program (like the window manager), which is "tied" to the X server. When that particular program ends, the X server automatically exits. (The X server may also terminate if some abnormal condition happens, like one of its X clients causes it to coredump.) If no display manager is running, the system returns to the command line prompt. If a display manager is running, the X server is restarted with no one logged in -- a graphical prompt for a username and password is displayed instead. Like Unix shell login sessions, which are customized by a file like .login or .profile in the user's home directory, X sessions can be customized on a per-user basis as well. In the Debian GNU/Linux system, creating and editing the .xsession file in the user's home directory is the preferred method of customizing an X session. See /usr/share/doc/xfree86-common/examples/xsession for more information. *) What is the root window? Like the Unix filesystem, windows in X are laid out like a tree with a single "root". The root window is the window that is "behind" all others, and covers the entire screen from corner to corner (in fact, if the virtual desktop feature of the XFree86 X servers is used, the root window can actually be larger than the screen). People often place an image of some sort in the root window ("wallpaper"), or run a program which draws something interesting and/or pleasing in the root window. *) What is a window manager? In other window systems like Microsoft Windows or MacOS, the concept of "window manager" is not obviously distinct from the rest of the window system. X, however, was designed from the beginning to maximize customizability, and to impose as little on the user as possible. The window manager is what copes with the fact that in a windowing system, one generally has more than window on the screen (if this were not the case, one might wonder why a windowing system were being used at all). Fundamentally, the window manager is in charge of window placement (moving, resizing, stacking order, and so forth). In practice, X window managers over the years have acquired more and more features. The typical window manager in use today draws borders around the windows which can be used to move and resize the window by grabbing, determines the focus policy, and presents menus which permit the iconification ("minimizing") or easy killing of X clients. Some window managers go farther and do some tasks of session management as well. *) What is a session manager? Rather than having a static list of X clients to be launched each time the X Window System starts, as is often the case in a user's .xsession file, it is possible to have a special X client run whose job it is to keep track of the other X clients, and "remember" the state of these programs between X sessions. Needless to say, an X client has to support the saving of its state between sessions, because when the X server dies, the clients that are connected to it die as well. When a session manager is run with X clients that support session management, a user can end his X session, and when he next starts it, he will be greeted with a screen that looks just the one he had when he left -- windows in the same locations, applications with the same files open, etc. *) What is window focus? The keyboard can only be used to "type into" one X client at a time. The mouse is used to determine which client has "focus", or receives keyboard events. There are two major kinds of focus, "pointer" and "explicit". Pointer focus, also known as "focus-follows-mouse", means that wherever the mouse cursor is, that window has focus. Explicit focus, or "click-to-type", means that a mouse button (usually the first, or leftmost on a right-handed mouse) must be clicked on a window with the mouse pointer over it for focus to change to that window. The focus policies available are determined by the window manager. Traditionally, pointer focus, or something very similar, is used in the X Window System -- but there is no reason explicit focus cannot be used, and X clients work equally well with either focus policy. *) What are X resources? X clients are typically customizable in their appearance and behavior in a very large number of ways. It would be very cumbersome to require X clients to be called with command-line arguments specifying each of the configurable parameters. Therefore, the X server maintains a database of X resources. When an X client connects to an X server, it inherits a set of properties from the X server that correspond to it. The strength of X resources is at the same time what makes them intimidating; they are hierarchical and can be as general or as specific as is desired. Almost all X clients, for example, recognize resources called "foreground" and "background", and if the X server contains an appropriately general resource for these properties, every X client that recognizes them will use them. [much more remains to be written about this question] *) What are app-defaults? Application defaults files ("app-defaults") are essentially a way of externalizing an X client's configurable parameters' defaults outside the client binary, so that they can be changed without recompiling the client. App-defaults files are mostly, but not exclusively, used by X clients written using the Xt (X Toolkit Intrinsics) library. On Debian systems they can be found in /etc/X11/app-defaults (or a localized subdirectory of /etc/X11). App-defaults are specified using a class/instance syntax and look very similar to X resource files (see next question), but there are three very important differences between app-defaults and X resources: 1) A client's app-defaults are generally essential for its useful operation, whereas X resources are always optional. In other words, you should be able to use an X client without specifying any X resources for it, but if you delete a client's app-defaults file, it may not be usable. 2) App-defaults implicitly bind to the class name specified in the file name of the app-defaults file. In other words, if I have an app-defaults file called "Foo", which contains the line: *Menu*background: red then this is interpreted as "Foo*Menu*background: red". This is unlike X resources, where a leading asterisk will cause a resource to bind globally to all clients that can resolve the resource name. 3) App-defaults are resolved only the by client, on the machine from which the client is running. X resources, on the other hand, are stored in the X server and can affect all clients that connect to that server. Again, the best way to think of app-defaults is as a set of externalized default settings for a client. They work as if they were part of the client binary itself. SPECIFIC QUESTIONS *) How do I customize my X session? On a Debian GNU/Linux system, the file $HOME/.xsession is used (if present) to setup the user's X session. The file /usr/share/doc/xfree86-common/examples/xsession is an example file that may be used directly and contains a great deal of explicit instruction on customization. Note that the system administrator can configure the X Window System such that users' .xsession files in their $HOME directories are ignored. See the Xsession.options(5) manual page for more information. *) How do I change what appears in the root window? There are many X clients that can draw on the root window. xsetroot, which comes with the basic X distribution, is one. It is found in the xbase-clients package, and can be used to set the root window to a solid color, a plaid pattern in two colors, or tile it with a monochrome bitmap. *) What is the difference between "bits-per-pixel" and "color depth"? Color depth refers to the number of bits available to each pixel for representation of distinct colors. Each pixel on the screen has a value which is translated to a color. The wider the range of possible values, the larger the variety of colors available to each pixel, and thus the whole screen. (The specifics of how a pixel value is translated to a color are determined by the "visual", a concept not explained in this FAQ.) For instance, at 1 bit of color depth, only a monochrome display is possible. (A bit can only be zero or one; therefore each pixel is either "off" or "on".) With 4 bits of color depth, 16 colors are available (two to the fourth power is sixteen.) With 24 bits of color depth, 2^24 colors are available -- almost 16.8 million distinct colors. However, for engineering and efficiency reasons, pixels may not be packed together with no wasted space. A pixel of 4 bits' depth may actually take up 8 bits of "room" when transmitted to the video hardware for display, because it is simpler for the video card to just take the 4 bits it needs out of the byte (8 bits) and ignore the rest, rather than try to regard each byte as containing two pixels. The same is often true for 24-bit color depth, which is often transmitted across 4 bytes (32 bits), with 8 bits ignored. The version 3.x XFree86 X server caused a great deal of confusion by using the term "depth" in its configuration file to refer to "bits-per-pixel" (while also using a command line option "bpp" -- short for "bits-per-pixel" -- to refer to the same thing). The version 4.x X server uses the terms consistently and correctly. In almost all cases, what the user cares about is color depth, not bits-per-pixel; the number of bits per pixel for a given color depth is usually an issue for only the author of a hardware driver to worry about. *) How do I change the color depth of my X server? There are two answers to this question; one for version 3.x XFree86 X servers, and one for version 4.x of the XFree86 X server. You can find out which version you are using by running "X -version" (you do not need to be root to execute this command). For version 3.x XFree86 X servers: The best way to change the default color depth of the X server is to add a "DefaultColorDepth" line to the "Screen" section that corresponds to the X server you use. Here is one example: Section "Screen" Driver "Accel" Device "ATI Xpert@Play" Monitor "Sony 200sf" DefaultColorDepth 32 SubSection "Display" Depth 8 Modes "1152x864" "1024x768" "800x600" "640x480" "512x384" EndSubSection SubSection "Display" Depth 16 Modes "1152x864" "1024x768" "800x600" "640x480" "512x384" EndSubSection SubSection "Display" Depth 32 Modes "1152x864" "1024x768" "800x600" "640x480" "512x384" EndSubSection EndSection See XF86Config-v3(5) for more information. To change the color depth on a per-invocation basis with startx, send the appropriate command line argument to the X server: startx -- -bpp 16 For version 4.x of the XFree86 X server: The best way to change the default color depth of the X server is to add a "DefaultDepth" line to the "Screen" section that corresponds to the X server you use. Here is one example: Section "Screen" Identifier "Simple Screen" Device "3Dfx Voodoo3" Monitor "Sony Multiscan 200sf" DefaultDepth 24 Subsection "Display" Depth 1 Modes "1152x864@85" "1024x768" "800x600" "640x480" EndSubsection Subsection "Display" Depth 4 Modes "1152x864@85" "1024x768" "800x600" "640x480" EndSubsection Subsection "Display" Depth 8 Modes "1152x864@85" "1024x768" "800x600" "640x480" EndSubsection Subsection "Display" Depth 15 EndSubsection Subsection "Display" Depth 16 Modes "1152x864@85" "1024x768" "800x600" "640x480" EndSubsection Subsection "Display" Depth 24 Modes "1152x864@85" "1024x768" "800x600" "640x480" EndSubsection EndSection See XF86Config(5) for more information. To change the color depth on a per-invocation basis with startx, send the appropriate command line argument to the X server: startx -- -depth 16 See Xserver(1), XFree86(1), and startx(1) for more information. With xdm, the /etc/X11/xdm/Xservers file must be edited; there is not a way to change the color depth on a per-session basis. One alternative is to have xdm manage more than one local X server, each with a different color depth (see below). *) How do I run more than one local X server simultaneously? This is not difficult if you understand that unless the X server is told otherwise, it attempts to be server number 0 for the local machine. To instruct the X server to use a different server number for itself, pass it the server number as an argument. Thus: startx -- :1 -bpp 16 Or, for xdm, edit the /etc/X11/xdm/Xservers file appropriately: :1 local /usr/X11R6/bin/X :1 vt8 -bpp 8 It is a good idea to explicitly tell the X server which virtual console to use (with the vt# argument) when writing the xdm Xservers file, because when xdm starts at boot time, getty may not have taken control of the virtual consoles it manages. XFree86 X servers automatically place themselves on the first available virtual console unless told otherwise. One may then get the distressing problem of getty attempting to respawn on a virtual console that xdm has claimed for itself; this usually results in a system that is unresponsive to the keyboard, and one must either connect to the system remotely to fix things, or take the system down via a hardware reset, which is not very nice. *) How do I set up the mouse buttons for left-handed use? (Thanks to "ulisses" for suggesting this question for the FAQ, and providing some of the information given.) This depends on how many buttons your mouse has. If it has two or three, I have an answer. If it has more than three, and/or a wheel, I'd appreciate submissions from lefties with such mice who have gotten them reconfigured. For a quick fix, you can execute the following while in an X session: xmodmap -e "pointer = 2 1" (for two-button mice) xmodmap -e "pointer = 3 2 1" (for three-button mice) To have the pointer buttons remapped for all of your X sessions, add the following line to your $HOME/.Xmodmap file (creating the file if necessary): pointer = 2 1 (for two-button mice) pointer = 3 2 1 (for three-button mice) and call "xmodmap $HOME/.Xmodmap" from your $HOME/.xsession file. Note, however, that the system administrator can configure the X Window System such that users' .xsession files in their $HOME directories are ignored. See the Xsession.options(5) manual page for more information. For more information about xmodmap, see xmodmap(1). *) How do I stop xdm from starting at boot? This is a very common question from people who have upgraded from Debian 2.0 or earlier, before the xdm program was separated out into its own package. Exactly how you deal with this depends on exactly what you want. Note that the following techniques all require root privileges. + I don't want xdm to run at all. In that case, simply remove or purge the xdm package with dpkg. If you have xbase installed, remove that before or simultaneously; xbase depends on xdm. See /usr/share/doc/xfree86-common/README.Debian-upgrade for more information. + I don't want xdm to manage any local servers. Edit /etc/X11/xdm/Xservers and remove any lines that correspond to the local host. This file ships with only one entry, for :0. If you comment that out, xdm will start but will not try to manage any X servers at all (unless you have added lines to the file). + I don't want xdm to manage any remote servers. Edit /etc/X11/xdm/Xservers appropriately. Note that as this file ships, it does not manage any remote servers, so unless you have already edited this file (or borrowed someone else's), no change is necessary from the package default to realize this state. *) How do I tell xdm to start the X server on a different virtual console? People who have customized /etc/inittab to add virtual consoles beyond the six that is the default Debian configuration often find that xdm and their getty program "collide" and often leave the console in an unusable state. Debian's xdm program ships with a configuration that tells it to start one local X server on virtual console 7. This works fine with the default Debian /etc/inittab, but not so well for people who have changed the inittab to start a getty on VC 7. If you have increased your number of virtual consoles, or otherwise require VC 7 for some purpose, simply edit /etc/X11/xdm/Xservers and change the "vt7" argument on the ":0" server line to whatever VC is appropriate for your machine (vt8, vt12, etc.). Note that while the XFree86 manual page says that if the "vt" argument is not specified, the X server will use the first available virtual console, it is not a good idea to omit this parameter when starting local X servers with xdm. This is because even though xdm starts at the very end of the init sequence, well after the getty processes that manage the virtual consoles, some machines get through the init sequence so quickly that getty has not yet claimed its VC's before xdm starts. This leads to exactly the same kind of console lockup you get as if you deliberately tell getty (via /etc/inittab) and xdm (via /etc/X11/xdm/Xservers) to use the same virtual console for their respective tasks. *) How do I run an X client as root when the X session is run by a user? If a normal user is running an X session (from startx or xdm), and that user, for instance, uses the su command from within an xterm to become root and then runs a program that tries to do something with the X server, the following error messages (or something similar) are usually seen: Xlib: connection to ":0.0" refused by server Xlib: Client is not authorized to connect to Server This happens because of an X security mechanism, which uses "magic cookies" stored in a file in the user's home directory (readable only by the user) called .Xauthority. If the environment variable XAUTHORITY is not set (see below), X clients attempt to authenticate themselves by using the .Xauthority file found in the directory specified by the HOME environment variable. Of course, if user "branden" is running the X session, and he then uses su to become root, $HOME will be "/root" instead of "/home/branden", and the correct .Xauthority file will not be found (even if there is an .Xauthority file in /root, it will not contain the correct magic cookies unless the root user has deliberately made it that way). There are therefore a number of ways to solve this problem. If only one user ever becomes root, and if root never starts an X session, there is a one-step, permanent solution (provided you don't rearrange your filesystem). Become root, then: cd ln -s /home/branden/.Xauthority .Xauthority Of course, you will want to replace "branden" in the above example with the name of whatever user has access to the root account. Alternatively, and more appropriate for more complex situations than the one described above, you may simply issue commands while root that will tell the X clients where to look for the .Xauthority file. If you set the XAUTHORITY environment variable to the path to the appropriate user .Xauthority file. If the su command is used, all of the environment of the invoking user is inherited except for $PATH; therefore, each user who has access to the root account could set the XAUTHORITY variable in their shell startup files, and this variable will be passed to the root shell. Other alternatives include modifying the root shell startup files to sense the invoking user and setting XAUTHORITY, making command aliases that set that variable for the invocation of specific commands, or configuring the super or sudo programs with appropriate rules. The most straightforward method (but not the one that requires the least typing), is simply to set XAUTHORITY with each command you issue as root that needs to access the X server. For Bourne-type shells (sh, bash, ksh, zsh): XAUTHORITY=/home/branden/.Xauthority xeyes For C-shell-type shells (csh, tcsh): ( setenv XAUTHORITY /home/branden/.Xauthority; xeyes ) Users of ssh's X11 forwarding feature should note that ssh sets the DISPLAY and XAUTHORITY variables itself, and does not use $HOME/.Xauthority for the latter. If you frequently employ this feature of ssh you should not unconditionally set XAUTHORITY in your shell's startup files. (You shouldn't do that with DISPLAY, either, but most people know better than to try. :) ) Finally, you should NEVER, EVER use the xhost command to manage X server access control unless you know exactly what you are doing (even then, there's hardly ever a good reason short of seeing just how many ways the security of your system can be compromised). Use the xauth command instead; the EXAMPLES section of its manual page is instructive for the most common tasks. *) Why doesn't my backspace, delete, or some other key work? Unfortunately, there are many places where things can go wrong if you think the wrong thing is happening when you press a key in X. Here is a procedure for diagnosing the problem: Use the xev program (in the xbase-clients package) to determine what keycodes and keysyms are being generated by the problematic keys. Run xev from an xterm (or other X terminal emulator) window. Move the mouse pointer into the window that appears and press the key(s) in question. xev catches all X events, not just key presses and releases, so you'll see other types of events as well. The ones of interest will look like this: KeyPress event, serial 18, synthetic NO, window 0x5800001, root 0x26, subw 0x0, time 3799560301, (110,117), root:(150,276), state 0x0, keycode 22 (keysym 0xff08, BackSpace), same_screen YES, XLookupString gives 1 characters: " KeyRelease event, serial 21, synthetic NO, window 0x5800001, root 0x26, subw 0x0, time 3799560385, (110,117), root:(150,276), state 0x0, keycode 22 (keysym 0xff08, BackSpace), same_screen YES, XLookupString gives 1 characters: " The parts on the third line about keycodes and (especially) keysyms are the data of interest. The keycodes are system-dependent (they vary according to the model of keyboard; Amiga keyboards and PC keyboards use different keycodes, for instance). If this data doesn't make sense (with one significant exception), then there is a problem with the X server's idea of your keyboard. If you're using XKB, you may be using the wrong parameters for your keyboard (or the XKB data could be wrong, especially if your keyboard isn't a North American PC model). If you're using Xmodmap, your Xmodmap configuration could be wrong. If you're not using either one, the X server will have fallen back on trying to get a keymap from the kernel when the server started. This process is prone to error; it is better to use XKB or Xmodmap if possible. The important exception -- the seemingly nonsensical keysym -- is sometimes BackSpace. The key in the upper-right corner of the alphabetic section of your keyboard, above the "Enter" or "Return" key, should always generate the "BackSpace" keysym, even if the key is physically engraved with the word "Delete" (e.g., on Macintosh keyboards). If, when pressing that key, you expect the cursor to move to the left (usually erasing as it goes), that's a backspace key; it doesn't matter what the keyboard manufacturer painted on it. If there is some other problem with the generated keysyms, consider asking about it on the Debian Users' mailing list (debian-user@lists.debian.org); if you're not subscribed to that mailing list, be sure you ask for personal replies. If what xev says makes sense to you, and yet your X clients (xemacs, xterm, etc.) are doing the wrong thing, the problem does not lie in the X server, it lies in the X client. It is the X server's job to deliver the keysym to the clients -- after that, everything is in the client's hands. The ways to deal with bad key behavior from clients are as varied as the clients themselves. The following discussion is relevant to X terminal emulation programs, specifically xterm. For help with other programs, consult the debian-user mailing list. For reasons of space, the following discussion delves a bit more into jargon than the rest of this FAQ; if you have trouble understanding it, it may be best to turn to debian-user for help. - xterm might be translating the key events into the wrong terminal control sequences; this part is all about X resources. As of xterm 4.0.1-1, xterm handles these translations correctly internally. - Whatever is running in the xterm (like the shell) can be getting bogus information from the terminfo file for the terminal type that xterm is using. If you're not using TERM=xterm, make sure you understand why. - If you still haven't found satisfaction, you may have run up against the stone wall that is inherent in emulation. For some keys, due to frustrating historical practice, there is simply going to be incompatibility with the Linux console. Why? Because xterm was initially written to emulate a VT100 terminal. PC keyboards have many more keys than a VT100. The PC keyboard resembles a VT220 keyboard much more closely. That's why Linus Torvalds based the kernel console driver on VT220 emulation. If you want xterm to behave more like the Linux console, use the terminal type "xterm-vt220". What keys are affected by this historical incompatibility? A list follows. Backspace (or whatever you have engraved on the key in the upper-right corner of the alphabetic section of your keyboard). All DEC VT series terminals generate ASCII 127 when this key is pressed. Everybody who presses that key expects a destructive backspace. At some point over the years, some misguided people assumed that, for this key, the key engraving should correspond to a similarly named ASCII code; namely, ASCII 8 or "BS" (backspace). This was extremely imprudent because user expectations are what matter, not the enforcement of some kind of mapping between ASCII and key engravings on non-glyph keys. For instance, ASCII does not address the notion of function keys; indeed, most of the first thirty-two codes in ASCII are only weakly applicable to terminals in the post-teletype age, let alone microcomputers that aren't even terminals at all. Bottom line: the "backspace" key, the one in the upper-right of the alphabetic section, should generate ASCII 127 ("DEL") if a DEC VT-series terminal is being emulated. End of story. No exceptions. Both the Linux console driver and xterm explicitly emulate DEC VT-series terminals, so the consequences for the backspace key should be clear. The real tragedy is that at some point, the misconception discussed crept into termcap and terminfo data for xterms, and people got used to the backspace key (engraved with "Delete" on VT terminals, Macintoshes, and some other keyboards) generating ASCII 8 (or control-H) instead of ASCII 127 (or control-?), in flagrant incompatibility with every DEC VT terminal ever made, one model of which (the VT100) xterm was expressly written to emulate from its very inception in 1984. The good news is, Tom Dickey, the upstream xterm maintainer, is taking steps to move everybody back to the Good Side of the Force with XFree86 4.0. Debian's Keyboard Policy has anticipated that move. So, if people do things correctly, there is no incompatibility between the Linux console and xterm. Delete. This is a key on the "editing" keypad of a PC keyboard, along with "Insert", "Home", "End", "Page Up", and "Page Down". The violence done to the backspace key had fallout here, with this key getting perverted to ASCII 127 instead of the control sequence ESC [ 3 ~ like every DEC VT terminal produced, starting with the VT220. Again, if people do things correctly, there is no incompatibility between the Linux console and xterm. (The DEC VT100 series had no editing keypad at all; just the alphabetic section and a numeric keypad.) Furthermore, the key engravings on this part of the keyboard are different on a VT220 or later and a PC, but there is sensible and de facto standard mapping from one to the other, which works fine if people don't butcher the delete key with ASCII 127. The numeric keypad. This is a place where incompatibility is probably going to have to be accepted. Why? Because they're laid out differently, for one thing. Instead of the double-height plus key that PC keyboards have, DEC terminals have two normal-sized ones, a minus and a comma. Also, instead of "Num Lock", slash, asterisk, and minus across the top row, DEC terminals have "PF1", "PF2", "PF3", and "PF4". (PF means "Pad Function".) These were the only function keys the VT100 had; the 220 and later had a complete row of F-keys similar to the PC keyboard along the top as well. Furthermore, whereas the "Num Lock" key on a PC toggles the keypad between numeric mode and mode duplicating the features of the editing keypad and cursor keys, the DEC terminals toggled between "keypad numeric mode" and "keypad application mode". Whereas the former maps fairly cleanly to a PC keypad with Num Lock on, the latter does stuff utterly differently. A DEC VT keypad in application mode generates control sequences totally different from the editing or cursor keypads. This makes sense, because the keys aren't engraved with "Insert", "Delete", and so forth on a VT keypad like the PC keys are. So, you get a choice on your PC: you can either act like a real VT, and thus confuse users who expect the numeric keypad keys to do what their engravings lead you to believe with the Num Lock off, or you can discard these "keypad application" functions that are present in the VT terminals, and possibly lose functionality from applications that expect a real VT terminal. The popular consensus seems to be with losing functionality, because there are few extant programs that actually use the DEC VT terminals' keypad application mode. The function keys along the top row of the keyboard. These don't even exist on a real DEC VT100, but they do on the 220 (and later models). Here we get more confusion. On a real DEC, F1 through F5 are used exclusively for communicating with the terminal's firmware for configuration, and no information that these keys have been pressed is ever sent to the remote host. So, in a sense, these keys "don't exist" on a real VT terminal for purposes of communicating with an application. What most terminal emulator authors have done is to map the PF keys from the numeric keypad to F1-F4 on the PC. This is a reasonable compromise, and certainly better than hijacking the Num Lock key away, which you'd have to do if you tried to do a physical mapping between the VT keyboard and the PC. What is done about F5 does not seem to be well-standardized. Where PC keyboards have "Print Screen", "Scroll Lock", and "Pause", VT100's have no keys and VT220's and later have only two keys: a double-wide "Help" key and a "Do" key. Finally, VT220 and later keyboards have four additional function keys above the numeric keypad where most PC keyboards have the LED's for Caps, Num, and Scroll Lock. *) How do I change xterm's default terminal type or key bindings? You can accomplish this by editing /etc/X11/app-defaults/XTerm (Individual users may customize $HOME/.Xresources instead.) XTerm.termName is the resource that controls what terminal type xterm reports itself as. XTerm.VT100.Translations is the resource that controls key bindings. Translation table syntax is not the simplest thing in the world and there are several pitfalls. Unfortunately, a tutorial has not yet been written. There is also a bug to keep in mind: multiple translation table overrides are not additive, despite the documentation. That means that if some overrides are specified in /etc/X11/Xresources/xterm and a user wants to add some, he or she needs to copy all of the overrides in /etc/X11/Xresources/xterm to $HOME/.Xresources before adding any, or the ones in /etc/X11/Xresources/xterm will be discarded. An example is probably the best documentation for the time being: *VT100.Translations: #override ~Shift F1: string("ssh remote.host.org")\n\ Shift F1: string("ssh -C remote.host.org") The "\n" ends the current definition, and the final "\" escapes the subsequent newline. For these overrides, a list of modifier keys precedes the string "" and the the X keysym name (you can use the xev program to determine the keysym generated by a particular key). If you don't list any modifiers, the translation for that key happens regardless of whether any are pressed. In this case, we want different translations for F1 and SHIFT-F1; so in the first we specify that the translation only applies if Shift is NOT pressed by prepending the modifier name with a tilde ("~"). We then on the next line define the translation that is to take place if the Shift key is pressed along with F1. Keep in mind that applications running within the VT100 widget will receive the translation defined, and not the default, which is a control sequence generated by DEC terminals. If they expect that control sequence as an indicator of when the F1 key has been pressed (and most of them have no other way of knowing), then this translation makes it impossible for the F1 key to be used with that application. However, examples like the above work fine with the shell. Finally, note that other applications besides xterm have a VT100 widget (like other X terminal emulation programs); people who want these applications to behave consistently will want to use the resource specification "*VT100.Translations" rather than "XTerm.VT100.Translations". *) How do I keep my mouse from going crazy (or going away) when switching between X and the Linux virtual console? If your mouse behaves erratically (or the mouse cursor goes away entirely) after switching back to a virtual console after starting X, and/or the gpm program spews messages about errors in the mouse protocol to your system logs when you switch, you may need to set up gpm as a repeater, and instruct the X server (via the /etc/X11/XF86Config file) to use the /dev/gpmdata device file as its mouse device. The gpm program documentation has more information about this. Alternatively, if this does not work or if you do not feel you need the mouse in text mode, simply remove or disable the gpm program. (If you have package dependencies on your system that prevent removal of the gpm package itself, you can always prevent it from starting at boot by renaming its init script, as described above in the question about disabling xdm.) *) How do I get the X server to find the "fixed" font? If the X server refuses to start, complaining that it cannot find the "fixed" font, then one (or more) of the following is likely true: + You don't have the xfonts-base package installed. Install it. + You don't have a valid FontPath in your /etc/X11/XF86Config or /etc/X11/XF86Config-4 file. At the very minimum, your FontPath should look something like this: FontPath "/usr/lib/X11/fonts/misc/,/usr/lib/X11/fonts/100dpi/,/usr/lib/X11/fonts/75dpi/" You will likely have several more directories listed. The "fixed" font is in the "misc" directory. + The fonts.dir or fonts.alias files in /usr/lib/X11/fonts/misc directory have been corrupted or are not present. This could be caused by a broken package which unpacks one or both of these files onto the system. A reinstallation of xfonts-base should fix the problem. + You're using a font server (either local or remote), and it is not running or not reachable. Note that Debian ships the xfs package with TCP listening turned off by default for security reasons. If you are running xfs locally and do not need to serve fonts to remote machines, you don't need to turn TCP listening back on. Instead, try a FontPath entry like this: FontPath "unix/:7100" If you are using a remote font server, determine whether or not it is running, is listening on the TCP port, and/or engage in some network troubleshooting. *) Why doesn't the X server package just depend on the xfonts-base package? (I often get this question, accompanied by rhetoric like, "1 CANT BEL1EVE U DONT MAKE THE SURVUR DEPEND ON THE BASE FONTZ PACKAGE BECAUSE IT ALWAYZ ALWAYZ ALWAYZ ALWAYZ ALWAYZ NEEDZ 1T!!11! U ARE SO STUPID 4 NOT MAKING 1T DO THAT!!1 U ARE EVEN STUP1DUR 4 NOT DOCUMENTING WHY IT DOESNT + 4 NOT FIXING TH1Z CRITICAL BUG YEARZ AGO!!11!1!1!! UR SUCH A MORON NO WONDUR PEOPLE USE REDHAT". Seriously.) For the past several years, the xserver-common package has contained the following text in its package description: X servers either need fonts installed on the local host, or need to know of a remote host that provides font services (with xfs, for instance). The former means that font packages are mandatory. The latter means that font packages may be gratuitous. To err on the side of caution, install at least the xfonts-base, xfonts-100dpi or xfonts-75dpi, and xfonts-scalable packages. I'll also note that recent versions of the Debian XFree86 packages (upstream version 4.1 and later) feature the "x-window-system" metapackage which relieves the user from having to have a full command of the interrelationships between the many XFree86 binary packages. So, when you don't understand why a given package relationship doesn't exist (why, for instance, Debian doesn't force the installation of an X server along with X clients, or vice-versa), it may be a good idea to just install the "x-window-system" package, which will probably give you the files you want -- from the XFree86 packages, anyway. *) Why does the "single-quote" (') symbol in the fonts not look the way it used to? First things first: this symbol is an apostrophe, not a single-quote. The glyph did indeed change between XFree86 3.x and XFree86 4.x, fixing a long-standing bug. The reasoning behind this change is extensive: see . I'll also note for the record that my DEC VT520 terminal, which easily predates the percolation of Unicode standardization efforts into Unix, draws the apostrophe as a short vertical line. Therefore I personally do not find "traditionalist" arguments very convincing. DEC VT terminals have a much greater claim to historical authenticity for Unix than VGA BIOS fonts do. *) How do I use Xnest, the nested X server? Some people find that they can start Xnest (e.g., with "Xnest :1"), but cannot start any clients inside it (e.g., with "DISPLAY=:1 xterm" or "xterm -display :1"), because the client connections are rejected by the X server's security mechanism, resulting in error messages like this: AUDIT: Fri Jun 22 11:44:23 2001: 28003 Xnest: client 1 rejected from local host Xlib: connection to ":1.0" refused by server Xlib: Client is not authorized to connect to Server xterm Xt error: Can't open display: :1 The problem is that you don't have any XAUTHORITY cookies for the nested server (you can use "xauth list" to confirm this). You need to set up an xauth cookie for the session. Since you're not using a display manager or startx to launch the server, this is not done for you. I suggest writing a small script to wrap Xnest if you're going to be using it much: #!/bin/sh MCOOKIE=$(mcookie) xauth add $(hostname)/unix$1 . $MCOOKIE xauth add localhost/unix$1 . $MCOOKIE Xnest "$@" xauth remove $(hostname)/unix$1 localhost/unix$1 exit 0 Simply invoke this script (using whatever name you give it) the same way you would invoke Xnest itself; all arguments to the script are passed through transparently to Xnest (remember to specify the display before any other server arguments). Needless to say, this script can be embroidered to suit your needs. *) I recently upgraded some packages, and now instead of readable text, some characters appear as little gray boxes. Why? A long-standing bug in many X clients and the widget libraries they use was recently brought to light by the addition of fonts encoded in ISO 10646-1 ("Unicode" in common parlance) to the X Window System. The details are highly technical. The short answer: It's a bug in the application, or the widget toolkit (e.g., GTK+) that it uses. The authors and maintainers of all commonly-used widget libraries are aware of the problem and a fix will likely appear in the future (or may already be available by the time you read this). It is not -- repeat *NOT* -- a bug in the X server, the X libraries, the X fonts, or anything having to do with the XFree86 packages. The long answer, courtesy of Markus Kuhn: (from ) ANNOUNCEMENT AND WARNING: The classic and widely used X11 BDF bitmap font families "-misc-fixed-*", "-adobe-*", and "-b&h-*" have been extended from ISO8859-1 to ISO10646-1 (Unicode) to accommodate users of more languages and mathematical symbols under X11 and to facilitate the migration towards UTF-8. They are available on http://www.cl.cam.ac.uk/~mgk25/ucs-fonts.html http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts-75dpi100dpi.tar.gz Most likely, XFree86 4.1 will include these "*-iso10646-1" fonts, so they will become quickly widely installed. Unfortunately, GTK+ 1.2.3 contained a bug that was triggered by the mere presence of a certain Unicode font, namely -Adobe-Helvetica-Medium-R-Normal--12-120-75-75-P-67-ISO10646-1 In gtk/gtkstyle.c, the line gdk_font_load ("-adobe-helvetica-medium-r-normal--*-120-*-*-*-*-*-*"); simply picks the first font in the alphabet that matches the wildcard. With the ISO10646-1 fonts present, this will be -Adobe-Helvetica-Medium-R-Normal--12-120-75-75-P-67-ISO10646-1 instead of -Adobe-Helvetica-Medium-R-Normal--12-120-75-75-P-67-ISO8859-1 Getting an ISO10646-1 font instead of an ISO8859-1 font should normally not make a big difference to an application. The latter is just a superset of the former, it contains in the first 256 glyph positions the same Latin-1 characters as the old ISO8859-1 font and just consumes a bit more memory. Almost all X clients survive the addition of an ISO10646-1 font or even the replacement of all ISO8859-1 fonts by ISO10646-1 fonts without any problem. GTK+ 1.2.3 broke badly, because gdk/gdkfont.c contained several unfortunate code pieces that tested whether a font contained any characters > 0xff and then treated any string written out in such a font as a (Japanese, etc.) EUC coded string of 16-bit values. So if you tried to print 8-bit text with an ISO10646-1 font, all you saw were default character boxes. For this reason, XFree86 delayed the introduction of ISO10646-1 versions of the Adobe fonts by a year after I reported this GTK+ bug in 1999-08-06 to gtk-bugs@gimp.org. This year is soon over. Newer versions of GTK+ (I just looked at 1.2.9) fixed this problem by explicitly specifying "*-iso8859-1" in the default font. So I hope nothing too bad will happen if XFree86 4.1 adds the new fonts soon. However there might still be numerous older GTK+ applications around for which an update or workaround will be necessary. You hereby have been warned! Other clients and toolkits have similar issues anytime they request a font with no specific character set or encoding in the request, but make assumptions about the properties of the font they get back (for instance, that it contains no more than 256 codepoints). The moral? Don't claim to not care about such things as character set encodings if you actually do care. If you want ISO 8859-1, ask for it. *) How do I add custom sections to a dexconf-generated XF86Config or XF86Config-4 file? As of xfree86v3 3.3.6-42 and xfree86 4.1.0-10, the dexconf utility only writes to part of the X server configuration file, instead of claiming the entire file for itself. For XFree86 3.x servers, this is mostly useful for adding XInput and ServerFlags sections, and for replacing the Files and Modules sections with something more to the user's liking. For XFree86 4.x, this enables the replacement of the Files and Modules sections, and the addition of an arbitrary number of supplementary Device, InputDevice, Monitor, Screen, and ServerLayout sections. Sections that are never written by dexconf (ServerFlags, VideoAdaptor, Modes, and Vendor) can also be added, of course. The most obvious application of this functionality is to support additional input devices and multi-headed configurations, but another is the replacement of, for instance, the Device section with something more customized. For example, the driver for your video card may be buggy and you may wish to add the 'Option "NoAccel"' flag to the Device section for your video card. Dexconf and the debconf questions associated with it do not support the plethora of possible options (many of them driver-specific), because it is not a very ambitious tool. The number one fact to remember about the XFree86 4.x server is that the first ServerLayout section encountered in the XF86Config-4 file is the one that is used by default. It is, of course, possible to add the "-layout" option to server invocations, either manually or by configuring xdm or xinit to do so by default (e.g., by editing the conffiles /etc/X11/xinit/xserverrc and/or /etc/X11/xdm/Xservers). To implement the above example, then, I would add three sections to the configuration file generated by debconf: a Device section with 'Option "NoAccel", a Screen section to use that Device in conjunction with a monitor, and a ServerLayout section to bind the Screen to input devices. If I want my new ServerLayout to be the default, I'll put it at the top of the XF86Config-4 file, before the debconf area. The Device and Screen sections can go either before or after the debconf area, but I'll put them before just to keep my customizations together. Also, I'll remember to give my new sections unique identifiers so that they don't collide with the identifiers used by debconf. Example: Section "Device" Identifier "Custom Device" Driver "ati" Option "NoAccel" EndSection Section "Screen" Identifier "Custom Screen" Device "Custom Device" Monitor "Generic Monitor" DefaultDepth 24 Subsection "Display" Depth 8 Modes "1280x960" "1152x864" "1024x768" "800x600" "640x480" EndSubsection Subsection "Display" Depth 16 Modes "1280x960" "1152x864" "1024x768" "800x600" "640x480" EndSubsection Subsection "Display" Depth 24 Modes "1280x960" "1152x864" "1024x768" "800x600" "640x480" EndSubsection EndSection Section "ServerLayout" Identifier "Custom" Screen "Custom Screen" InputDevice "Generic Keyboard" "CoreKeyboard" InputDevice "Configured Mouse" "CorePointer" EndSection ### BEGIN DEBCONF SECTION [snip] ### END DEBCONF SECTION Of course, my "Generic Monitor", "Generic Keyboard", and "Configured Mouse" should be defined in the debconf section of the file, but the identifier in the monitor section may be different, depending on what dexconf wrote to the file. *) Why does the X server take up so much memory? (Especially heard from KDE users with large monitors, many workspaces, and a different picture in the root window of each workspace.) Answer courtesy of Mark Vojkovich of the XFree86 Project, Inc.: The X Window System is a client-server window system. The memory for pixmap data resides on the server side instead of the client side. If you have 8 1600x1200 32bpp root window images that's 61 Megabytes. It resides in the server instead of the client, unless they are shared memory pixmaps, in which case it will be counted on both the server and client side. Obviously this data has to be stored someplace. It's not like it can just disappear when you're not using it. If they were stored on the client side instead, people would be complaining about KDE memory usage. Additionally, Sean McGlynn of the KDE Project offered assistance: Please direct such users over to KDE's mailing lists - http://www.kde.org/mailinglists.html - and we can try and investigate/resolve their issues fully. And finally, these remarks from Mike A. Harris of Red Hat Software: I'd like to add to that another frequently reported problem of XFree86 consuming a lot of memory. Many people report X uses 64Mb+ of memory and can't see any reason why it should. They blame X for being bloated, etc. Digging into it more however, 99 times out of 100, they are using the output of top or procps or similar utility do show how much memory XFree86 is consuming. Unfortunately, the memory reported as used in top/ps output is interpreted solely as being system RAM and/or swap, and that is very misleading as it is not true. The memory shown by top, which users are misled into believing is memory used up by X, is an amalgamation of the video card's own memory, and memory mapped I/O regions, as well as the actual memory used by the X server, pixmaps, and various other things. It is not at all uncommon for a modern 64Mb video card, to have X's memory usage appear to be 100Mb or more, when in reality, 64Mb of that is video RAM, and 16-32Mb possibly mmapped registers. Most developers such as ourselves are aware of this, however most end-users are not. On Linux a user can view the memory map breakdown by logging in as root and looking at the file: cat /proc/$(pidof X)/maps That gives a fairly detailed breakdown of the memory map of the X server process, and what actual amount of memory is being used, etc. The exact meaning of the contents of the proc maps file is left as an exercise for the curious reader. ;o) Reading the kernel sources which implement it is about the best manual I know of. Branden Robinson, 16 April 2002 vim:ai:et:sts=2:sw=2:tw=78: