Debian X Window System Frequently Asked Questions

This FAQ is old!

It is kept for its historical value; for up-to-date information, please visit this site instead: http://pkg-xorg.alioth.debian.org/

[General Questions]

[Specific Questions]

Acknowledgements

The author would like to thank Andreas Metzler, Guillem Jover, Ingo Saitz, Osamu Aoki, Matthew Arnison, Colin Walters, Steve Swales, Adam Jackson, Thomas Dickey, Paul Gotch, Albert Cahalan, Denis Barbier, Jeff Licquia, Fabio Massimo Di Nitto, Andrew Suffield, Frank Murphy, Marc-Aurèle Darche, Michel Dänzer and "ulisses" for their contributions to this document.


Copyright © 1998-2005 Branden Robinson.

This is free documentation; you may redistribute it and/or modify it under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation, with the following additional permissions:

This work is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License with the Debian operating system, in /usr/share/common-licenses/GPL; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

Notes on the License

In the copyright holder's understanding, re-imposition of the requirements of sections 2a and and 2c by those creating a derivative work is not allowed, since those restrictions never attached to this work; see section 6. This work can be combined with another work licensed under the GNU General Public License, version 2, but any section 2a and 2c restrictions on the resulting work would attach only due to the copyright license on the work(s) with which this work is combined and for which those restrictions are in force.

The copyright holder regards the XHTML form of this document, along with any adjunct style sheets, as the Source Code of this Work for the purposes of the GNU General Public License.

If you have a problem interpreting the GNU General Public License, please contact the debian-legal mailing list, the Free Software Foundation, or an attorney.

If you find the copyright holder's notes on the license confusing, please contact him and/or the debian-legal mailing list.

Further Information

The most recent version of this FAQ, as well as the latest news about Debian X Window System package development, future plans, and information about how you can help improve the quality of Debian's X Window System packages can be found via the X Strike Force wiki page.

By its nature, this document is not comprehensive. It attempts to address the questions that are most frequently asked of Debian Developers regarding the X Window System. It also covers some broad and fundamental concepts that are useful to explain some of the answers given. If your question is not answered here, try /usr/share/doc/packagename/README.Debian (and other files in the package's doc directory), manual pages, and the debian-user mailing list. See http://lists.debian.org/ for more information about the Debian mailing lists.

Another FAQ that may be of interest is available:

(There used to be an XFree86 FAQ, which was published by the XFree86 project, but unfortunately it has not been maintained for quite some time.)

As is standard in the Debian system, these FAQs are found in /usr/share/doc/packagename/. The Debian X FAQ is part of the xfree86-common package, and the XTerm FAQ is part of the xterm package.

How to Use this Document

The following table summarizes the semantic usage of visual markup in this document:

concept

representation

examples

command name

fixed font

xdpyinfo, xterm

file specification

fixed font

/etc/X11/XF86Config-4, /var/log/XFree86.0.log

Debian package name

fixed font

xserver-xfree86, xterm

manual page

fixed font

man(1), xterm(1x)

other literal (e.g., mailing list)

fixed font

debian-legal, debian-user

Suggestions for improving the utility and accessibility of this document are welcome. Feel free to update this Wiki page respecting the MoinMoin syntax and the above semantics.

General Questions

What is the X Window System?

In the words of its primary manual page, X(1x), 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. A brief history of the X Window System follows.

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. Project Athena prepared both a formal specification for the windowing system and a sample implementation (SI); both are generally referred to as "the X Window System". 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 (later just "X Consortium") was formed to direct future development of X standards in an atmosphere intended to be inclusive of many commercial and educational interests. The freely-licensed SI permitted anyone to produce proprietary derivatives, and many of the X Consortium members poured resources into competing with each other in part on the basis of their proprietary extensions to the SI. The X Window System thus became one of the many fronts in the so-called "Unix Wars". Nevertheless, some cooperation was achieved, and the X Consortium produced several incremental but 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 OSF (Open Software Foundation, though some joked that it really stood for "Oppose Sun Forever"), 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 (see below). In late 1998, the Open Group relicensed ?X11R6.4 again, this time under terms identical with the traditional license.

In May 1999, stewardship of the X Window System passed from the Open Group to The X.Org Group (commonly just "X.Org"; see below), a subsidiary but mostly autonomous organization within the Open Group. The X.Org Group focused exclusively on maintenance and further development of the X Window System, and released of ?X11R6.5.1 and ?X11R6.6.

In January 2004, a not-for-profit corporation called the X.Org Foundation was organized. While there is no transfer of assets (such as copyrights) planned from the Open Group to the X.Org Foundation, the expectation as of this writing (June 2004) is that the X.Org Foundation will be the de facto steward of the X Window System specification and SI. In the words of Steve Swales, the chair of The X.Org Group:

...the old X.Org will merge or dissolve into the new X.Org Foundation. The old executive board, for example, will effectively be the sponsor group, though individual [representatives] may change.

On 6 April 2004, the X.Org Foundation released ?X11R6.7, which was largely based on a release candidate snapshot of XFree86 4.4.0, shortly before the latter's relicensing (see below).

See Wikipedia's page on X for more details about all X.org releases.

What is `freedesktop.org`?

In its own words:

freedesktop.org is a free software project to work on interoperability and shared technology for desktop environments for the X Window System.

freedesktop.org hosts several X server implementations: among them the X.Org Foundation's Xorg, derived from the XFree86 X server; Xserver, a kdrive-based X server; and Debrix, a rework of the Xorg server using the GNU autotools instead of Imake.

What is X.Org?

X.Org was originally a technical working group within the Open Group, established after the Open Group absorbed the work of the X Consortium. In the period 1998 to 1999, X.Org established greater autonomy for itself in part due to the unpopularity among vendors and the community alike of the Open Group's decision to change the licensing of the X Window System SI back in 1998. However, as presently constitued, and as described in its by-laws, X.Org continues to be managed at an organizational level by the Open Group.

In January 2004, the members of X.Org announced the formation of the X.Org Foundation, a U.S. not-for-profit corporation and scientific charity which succeeds the X.Org working group of the Open Group in most respects. While many view X.Org as the current steward of the X Window System specifications and sample implementation, the copyrights in the specification documents and code previously held by the X Consortium and subsequently transferred to the Open Group continue to be held by the Open Group. Steve Swales of the X.Org Foundation observed in June 2004:

The main X11 IP practically held by [the Open Group] is the test suite, and the logo. They also are the registered owners of the x.org domain...There is currently no plan to transfer any of the IP or the domain name. I believe that [the] X.Org Foundation could add a copyright to their distribution, but this would not actually transfer the license. Transferring the license in any legal sense has been seen as a very costly waste of time, since there are dozens and dozens of copyright notices in the code, many from companies which no longer exist as separate entities.

The X.Org Foundation develops the X Window System specification and SI in explicit cooperation with freedesktop.org, and there is extensive overlap in membership between the two organizations.

What is XFree86?

As noted above, the various groups that have developed the X Window System over the years have had standardization as their primary goal, not software development. The liberal license terms used by the SI since its very early days have ensured that any organization (or even individual) can come up with their own implementation of the X Window System or one of its components, and have confidence that their code will interoperate with other code respecting the same standard. Furthermore, the MIT/X11 license as used by the X Window System SI permitted commingling of code with other works under practically any license.

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, the XFree86 implementation of the X Window System enjoyed immense popularity, and its members rapidly expanded their activities beyond merely producing X servers for IBM PC-compatible video hardware. XFree86 also benefitted from the near-simultaneity of two events: first, the collapse of the X Consortium, its vendors exhausted by the Unix Wars and undergoing eclipse by Microsoft's successful Windows 95 and NT 4.0 products; second, the exploding popularity of Unix on PC hardware, thanks to the development of the Linux kernel and lifting of the legal shroud over the BSD Unices that had been cast by the USL v. BSDI (a.k.a. AT&T v. BSD) lawsuit. (For more on the history of the BSDs, see Lance M. Westerhoff's article "Darwin/Mac OS X: The Fifth BSD".)

An article by Michael J. Hammel in the December 2001 issue of Linux Magazine contains a fairly comprehensive history of the XFree86 project to up to that point in time.

What is the story with XFree86 being forked?

After XFree86 rose to prominence, X.Org began to incorporate parts of its codebase into its own SI; however, this process tended to lag XFree86's own releases, and until 2004 X.Org's SI did not offer features compelling enough to motivate a switch, at least within the Free / Libre / Open Source community.

Recent events have challenged XFree86's pre-eminence, but they have their roots in long-standing trends and practices. Seldom, if ever, have there been more than a dozen people with commit access to XFree86's source code repository at any one time, and in general, XFree86's development has been dominated by one to four individuals. As XFree86's userbase increased dramatically over the years, some people became interested in taking the X Window System in directions that the XFree86 project leadership was not interested in going. Furthermore, some felt that the XFree86 project's infrastructure was not scaling to the needs of its users; for example, XFree86 did not have a bug tracking system until March 2003, and the mailing lists were periodically reorganized such that end users had difficulty figuring out which forum to use for their questions. On top of all that, the relatively slow release cycle of the XFree86 codebase led redistributors to extensively patch their shipping versions of the software, which complicated user support issues tremendously. Moreover, the patch submission and review process left many contributors including redistributors frustrated.

The presence of these stressors gave rise to (or exacerbated) personality conflicts, and in 2003 a group of developers resolved to set up a separate development project, which was initially christened xwin.org, but later merged with an existing standardization project, freedesktop.org. (Another group, Xouvert, had also undertaken to fork the XFree86 codebase.) While this development was lauded by many redistributors and feature-hungry end users, its short-term practical impact was fairly small. OS distributors stuck with XFree86 because it was familiar and functional. Furthermore, the continued use of the MIT/X11 license terms ensured that cross-pollination between the projects would work to everyone's benefit. The redistributors, and thus most end users, were expected to continue using XFree86, at the very least until one of the forks had a replacement finished. No doubt, it was thought, some distributors would choose to stay with XFree86, anticipating that it would cherry-pick attractive new features, enhancements, and bug fixes from the forked codebases (the same process was expected to work in the other direction as well). Other distributors would likely ship both codebases and give their users the choice.

As of this writing (August 2007), most major distribution switched from XFree86 to X.org.

What is the story with XFree86's license?

The "wait-and-see" approach adopted by most vendors in the wake of Xouvert and freedesktop.org forks changed in January 2004, when the XFree86 project announced its intention to change the license on its codebase. The license, called the "XFree86 1.1 license", combined elements of the traditional MIT/X11 license, the original 4-clause BSD license (containing the infamous "advertising clause"), and the Apache Software License in a novel way. The new license was found to be GPL-incompatible by Richard Stallman of the Free Software Foundation and most OS distributors, including Debian, whereas the XFree86 project makes contradictory and confusing claims.

Compare:

And of course, a heartfelt thanks to all of you: distros, developers and fans, for your continued support for our free and GPL compatible software.

to:

What about GPL-compatibility? Is XFree86 GPL compatible?[[BR]The XFree86 Project maintains that the 4.4.0 release of XFree86 is as GPL compatible as any and all previous versions were.]

Both of the above statements come from XFree86's website. While the former is an unequivocal "yes" to the question of whether the software under the new XFree86 license is GPL-compatibile, the latter is, of course, neither a "yes" nor a "no". Moreover, it is the copyright holders in GPL-licensed works whose opinions matter, because it is their license terms, not XFree86's, which would be violated by intermixing code (in source or binary form) under the GNU GPL with code under the new XFree86 license.

On top of this, when OS distributors have requested clarification as to the precise and practical meaning of XFree86's new license from the XFree86 project, they have often found the replies insufficiently elucidating. A license that is not understood is not safe enough for most organizations to deal with for fear of civil or criminal claims of copyright infringement hence the decision by many OS vendors, including Debian, to avoid code under this license.

On 11 December 2003 prior to the mass-relicensing of the code in XFree86 CVS a license nearly identical to the new XFree86 license was applied to changes which had been made two months earlier, on 8 October 2003, and which were credited to X-Oz Technologies, Inc., a consulting company co-founded by the President of The XFree86 Project, Inc. This relicensing, which did not accompany any changes to code, went largely unnoticed at the time, but that license sometimes referred to as the "X-Oz License" suffers from the same deficiencies as the new XFree86 license. Debian will not include code under the terms of either the X-Oz or XFree86 1.1 licenses in its OS (see the Debian Social Contract).

Despite the outcry regarding the XFree86 project's decision (which reminded some of X.Org's own ill-fated change to its SI's license terms in 1998), the XFree86 Project went ahead and applied the new license to the code in its CVS repository on 13 Feburary 2004. Many OS distributors, including Debian, elected not to distribute any version of the XFree86 codebase using the new license. Consequently, those distributors sought alternatives. As of this writing (March 2005), most of the community appears to have settled around the "monolithic" X.Org X11 release series release series hosted at freedesktop.org.

What are Debian's plans with respect to X.Org and XFree86?

Thanks to Fabio Massimo Di Nitto for contributing much of this entry.

Because the XFree86 relicensing came at a time when Debian was trying to stabilize its XFree86 packages for the sarge release, there was some question among Debian's X Window System package maintenance team (the "X Strike Force") and much speculation among Debian's users as to what direction Debian would take.

There was never a serious proposal to attempt to ship anything other than XFree86 4.3.0 in sarge, so work on that continued while discussion on the debian-x mailing list took place. The following represents the consensus reached by the X Strike Force, without objection from the mailing list subscribers (among whom number many interested Debian developers and users).

In June 2004, Fabio Massimo Di Nitto, the XFree86 package release manager for Debian sarge and sid, started a thread to discuss the future of X Window System packages in Debian for an open discussion between users and the Debian package maintainers. The discussion spanned nearly one hundred messages from over a dozen participants, practically all of it constructive and very useful to the Debian maintenance team. The outcome of the thread was farly clear to everyone: Debian would move away from the XFree86 tree as soon as possible after the upcoming stable release due to its license issues (see above).

Furthermore, there was near-consensus that Debian should switch to the X.Org source tree, with the goal of migrating to the modularized tree over time. We expect that the monolithic X.Org distribution will be modularized in a piecewise fashion; as that happens, we will "switch off" the building of packages from the X.Org monolithic tree in favor of the modularized components that become available from freedesktop.org.

While moving from XFree86's monolithic tree to X.Org's is a relatively simple technical transition of itself, the transition to a fully-modularized set of packages took longer, depending on the speed of upstream's progress. But, as expected, the process brought the packages' quality to a higher level, thanks to the introduction of a fast release cycle for each single component. While Debian Sarge included the monolithic XFree86 4.3 packages, Etch has been the first Debian stable release to include a fully modularized X.Org packages.

At present, the Debian XFree86 package maintainers intend to support only the XOrg X server (which is based on XFree86's). The X Strike Force does not plan to discourage other people from packaging others. Debian developers that file intent-to-package notices (ITPs) for other X servers are asked to strictly cooperate with the X Strike Force to maintain similar packaging standards, simplify the bug handling on shared components (like X libraries) and discuss future changes and improvements.

The packaging of the X.Org X11 distribution for Debian is now maintained on http://git.debian.org in the pkg-xorg group.

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 piece of software that actually "delivers the goods", both to the user in the form of displayed graphics, and to the programs 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 CTRL-ALT-BACKSPACE 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 (>=lenny), creating and editing the .xsessionrc file in the user's home directory is the preferred method of customizing an menu started X session independent of Desktop environment.

{i} In the Debian GNU/Linux system, creating and editing the .xsession file in the user's home directory was the preferred method of customizing an X session. This requires you to insert "exec some-window/session-manager" explicitly to start your favorite X window/session manger. The above method retain menu selection by GDM.

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 X server 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.

Does Debian support window composition and desktop effects?

The technique of composing the desktop scene from the opened windows while applying effects to them is known as window composition. Modern window managers like Compiz, Kwin or Mutter use composition to provide desktop effects such as window transparency and shadow, window switching with previews, window maximization and minimization animations, presentation of all opened windows (a.k.a. "exposé"), presentation of all workspaces…

To achieve this, window managers require the graphic driver to support the GLX_EXT_texture_from_pixmap GLX extension. Earlier drivers would only support GLX_EXT_texture_from_pixmap in indirect OpenGL contexts. The AIGLX (Accelerated Indirect GLX) extension to the X server was then required to allow such drivers to be used for composited desktops. The X server implements AIGLX since version 7.1, meaning it's available starting with Lenny.

With more recent drivers, the GLX_EXT_texture_from_pixmap extension works in direct rendering OpenGL contexts, and so AIGLX is not needed anymore.

Most AMD/ATI and Intel graphic chips support desktop effects out of the box with their default Xorg drivers with or without the need for AIGLX. It should also work out of the box for nVidia users with the included nouveau driver starting with Wheezy. Older releases will need the proprietary nVidia driver. Other manufacturers have a poor history of OpenGL support in their Xorg drivers and probably won't work.

You may need to install Compiz, or to enable desktop effects in the KDE configuration utility. Gnome Shell in Gnome 3 requires window composition, and automatically falls back to a classical desktop when composition isn't available.

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. Historically, pointer focus or something very similar was used in the X Window System. The most common window managers presently use explicit focus by default, while still letting the user choose pointer focus by configuration. 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 the previous 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, 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.

How does the keyboard work in the X Window System?

It will take some time to write a comprehensive entry on this subject, but in the meantime it is hoped that the information presented here is useful. Thanks to Denis Barbier, Andrew Suffield, and Frank Murphy for their patience and explanations.

Glossary
* '''compose key'''

a key which causes the next two keys pressed to be treated specially such that they cause a single character to be printed (this is implemented in software); for example, pressing and releasing Compose, A, and then E in sequence would produce the ae ligature (æ); valid compose sequences are defined in locale-specific data files such as /usr/share/X11/locale/en_US.UTF-8/Compose;

* the X Window System's '''keysym''' for this key is `Multi_key`'''dead key'''

a key, typically engraved with an accent, diacritic, or other mark which produces no character by itself but instead modifies the character generated by the next key pressed (this is implemented in software); for example, on a keyboard with dead keys, pressing a key engraved with an acute accent (´) glyph followed by the A key would produce an "a" with an acute accent (á), whereas pressing the acute accent ("dead acute") key followed by a space would produce the acute accent by itself (´);

* contrast with '''spacing key''''''engraving'''

the visible marking(s) on a keycap, which indicate the key's behavior via a glyph (such as Q or \) or term describing a control function (such as Enter, Shift, or Scroll Lock)

* '''keycap'''

the surface of a key; the part of a key which is pressed and bears engravings

* '''keycode'''

a scan code after it has undergone translation (if any) by the operating system and X server

* '''keymap'''

a complete description of a keyboard device which is used by the X server to translate keycodes into keysyms and modifier masks; when XKB is used, this includes compat, geometry, keycodes, symbols, and types information

* '''keysym'''
a symbolic name for a key, independent of the operating system and keyboard hardware, which identifies a key to X clients
* '''layout'''

an XKB configuration parameter that identifies the territorial specifics of a keyboard model; two given keyboards may have the same physical key arrangment but different engravings on the keys, each keyboard customized to a different region or territory

* '''logo key'''

a platform- and trademark-independent term for keys typically engraved with the logo of an operating system or its manufacturer; for example, these keys are referred to as "Windows keys" on PCs and "Apple keys" or "command keys" on Macintoshes (furthermore, some enterprising keyboard suppliers have engraved these keys with Tux the penguin, the Linux mascot); since the X Window System keysym list antedates these keyboards, these keys are often mapped to one of the modifier keys (Meta, Super, or Hyper) from the notorious Symbolics "Space Cadet" keyboard, which was no doubt popular at MIT at the time the X Window System was developed

* '''model'''

an XKB configuration parameter that identifies what physical model of a keyboard is in use; used to determine what keycodes are supported by the model and what its geometry is

* '''modifier'''

a flag (up or down) which can influence how keycodes are translated to keysyms, and how X clients interpret key events

* '''modifier mask'''

a list of modifier states; these are bitwise-ORed together as the "state" value reported with key events by the xev command

* '''options'''

an XKB configuration parameter that permits the user to customize aspects of keyboard behavior that are not specific to a layout; for example, ctrl:nocaps is a popular option to make the Caps Lock key produce the Control_L keysym; that is, work like an additional (left) Control key

* '''rules'''

an XKB configuration parameter that identifies a data file (such as xorg) describing how model, layout, variant, and options specifications are translated into compat, geometry, keycodes, symbols, and types information

* '''scan code'''
a number which uniquely identifies a key on the keyboard, and which is transmitted by the hardware to the operating system; scan codes tend to be specific to the keyboard hardware
* '''spacing key'''

a key which causes a character corresponding to the glyph engraved on it to be printed; contrast with dead key

* '''variant'''

an XKB configuration parameter that allows for differing behavior of certain keys within a given layout; for example, nodeadkeys is a popular variant in many European layouts it causes dead keys to be treated as spacing keys

* '''XKB'''
the X KEYBOARD extension, an extension to the X protocol providing a more sophisticated means of describing keyboard events than that supported by the core protocol

When the X.org X server is started, it calls the setxkbmap utility to compile a keymap from the XKB configuration options (XkbRules, XkbModel, XkbLayout, XkbVariant, and XkbOptions) from its configuration file (usually /etc/X11/XF86Config-4). The XFree86 X server can be told to disable XKB with the option XkbDisable. Furthermore, X servers in general can be told not to load an XKB keymap with the option -noloadxkb, or to load a pre-compiled keymap with the -xkbmap option. This last option is useful for machines configured as X terminals, since they enable the X server to do without the setxkbmap command, which in turn depends on xkbcomp, the XKB data files, and the X libraries.

Many non-US keyboards need to support more than two glyphs per key. On a typical U.S. keyboard, there are at most two glyphs on each keycap one is accessed with a Shift or Caps Lock key, and one without. To enable access to third, fourth, or fifth glyphs, other modifiers are used.

PC Keyboards for Latin-script characters ususally have an ?AltGr (alternate graphic) key that replaces the right Alt key. When a key is pressed while the ?AltGr key is down will generate the third glyph, and when Shift and ?AltGr are down, it will generate the fourth glyph. For example, on many European keyboards, one can press ?AltGr + E to produce the Euro sign (). Sometimes the Alt key on the right-hand side of the keyboard is used as ?AltGr if there is no key actually engraved as ?AltGr.

Non-Latin keyboards can have most of the keys engraved with both non-Latin and Latin glyphs. For example, Russian keyboards often work this way because they must support both the Latin and Cyrillic alphabets. As a consequence, users of the X Window System need a way to combine layouts. Combined layouts are often useful for users who need to type in multiple languages. A Russian user might use a French keyboard layout (complete with third and fourth glyphs) to correspond with Western European friends via email, but then switch to another layout with Cyrillic letters to write messages to Russian friends.

There are two ways to specify a more than two glyphs: levels and groups. The core X protocol uses groups, but XKB (as of XFree86 4.3.0 and X.Org ?X11R6.7.0) uses levels. XKB changed in order to better support combined layouts. To specify a third glyph with groups, a second group is assigned to a key and the glyph is assigned to the first shift-level of the second group. To use levels, a third level is assigned to a key. The keysym used to generate these third glyphs also changes. When groups are used, the ?AltGr key is assigned the keysym Mode_switch, and with levels it uses the keysym ISO_Level3_Shift. By moving from the muliple-group to the shift-level method, combined layouts become much more flexible and easier to maintain. With the old multiple-group approach, it was impossible to combine layouts that had more than two glyphs per key.

XKB supports up to four keysyms per group and up to four groups per layout. In situations with three or four groups, rather than using Mode_switch, a keyboard can be configured to use the keysyms ISO_Next_Group and ISO_Prev_Group to cycle through the available groups.

Another approach to typing symbols not engraved on the keyboard which is completely independent of levels and groups, and which may be used with either of them is the compose sequence. The keysym Multi_key enables two keys to generate any symbol defined by Compose sequences for your locale. Keyboards that have a Compose key often have the Multi_key keysym bound to it. For example, to type Ç in the C locale, first type Multi_key, then comma followed by capital C. The order of the comma and C can be reversed. Yet another way to define these kinds of symbols is with the XIM (X Input Method) extension.

Specific Questions

How do I customize my X session?

On a Debian GNU/Linux system, the file $HOME/.xsession is used (if present) to set up the user's X session.

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, 224 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.

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?

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(5x) 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(1x) , XFree86(1x) , and startx(1x) 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 Osamu Aoki, Marc-Aurèle Darche and "ulisses" for providing much of the information in this entry.

For a quick fix in XFree86 3.x, you can use one of the following commands, depending on how many buttons your mouse has:

xmodmap -e "pointer = 2 1"

(for two-button mice)

xmodmap -e "pointer = 3 2 1"

(for three-button mice)

xmodmap -e "pointer = 3 2 1 4 5"

(for three-button mice with a scroll wheel)

Note that buttons 4 and 5 correspond to the "wheel up" and "wheel down" actions, and should not be modified for left-handed use.

To remap the mouse buttons for all of your X sessions (under XFree86 3.x, 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)

pointer = 3 2 1 4 5

(for three-button mice with a scroll wheel)

...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(1x).

The above xmodmap-based approach for setting up a left-handed mouse only works for the XFree86 3.x series. It results in bad behavior when used with the XFree86 4.x series and XOrg ?X11R6.7.0 and later. If you are using one of these more recent versions of the X Window System, use the gpm-based approach, described below.

The gpm approach is to feed X with the mouse data coming from gpm, a cut-and-paste utility and mouse server for virtual consoles. The gpm utility is of interest here because it can be configured to handle left-handed mouse devices. This approach has the drawback that all the users of the system have to share the same gpm configuration, while with xmodmap every user could have his or her own .Xmodmap file.

To use the gpm approach, you must modify two files: your gpm configuration and your X server configuration. The examples provided below are for a Logitech three-button mouse with a scroll wheel. One can easily adapt this configuration by changing device, type and Option "Protocol" parameters according to the type of mouse device you are using.

Example: /etc/gpm.conf

device=/dev/input/mice
repeat_type=ms3
type=imps2
append='-B 321'

Example: /etc/X11/XF86Config-4

Section "InputDevice"
        Identifier      "GPM repeater"
        Driver          "mouse"
        Option          "CorePointer"
        Option          "Device" "/dev/gpmdata"
        Option          "Protocol" "IntelliMouse"
        Option          "ZAxisMapping" "4 5"
EndSection

Note that in XFree86 4.3.0 (and therefore in X.Org ?X11R6.7.0 and later), the X server's mouse driver was rewritten in such a way that using any protocol other than IntelliMouse on the XFree86 side and ms3 on the GPM side does not work well. If you are using anything other than ms3 as the repeating protocol (repeat_type), you will likely want to change it to ms3. If your XF86Config-4 file is automatically handled by debconf and uses /dev/gpmdata as the port for the configured mouse, the protocol will automatically be migrated to IntelliMouse if necessary.

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.

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 the xdm and getty programs "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 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 his or her 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 conceptually simple 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 (ash, bash, dash, ksh, posh, zsh):
XAUTHORITY=/home/branden/.Xauthority xeyes

For C-shell-type shells (csh, tcsh):
( setenv XAUTHORITY /home/branden/.Xauthority; xeyes )

Users of the OpenSSH client'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. :) )

Another widely-used solution is the sux command from the package of the same name. Sux works much like su.

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 "< >" key work?

Thanks to Guillem Jover and Ingo Saitz for their assistance researching this entry.

In XFree86 4.3.0, the stock configuration data for the X Keyboard Extension (XKB) was overhauled. One of the few downsides to this much-needed update was that the "< >" key commonly found on European keyboards stopped functioning for some people who had not paid close attention to their XKB configuration in the past. Users of 102- or 105-key PC keyboards (as well as miniature and laptop keyboards compatible with these models) should ensure that their keyboard is configured accordingly in the XF86Config-4 file, using the pc102 or pc105 XkbModel instead of pc101 or pc104, respectively. U.S.-style PC keyboards do not have a "< >" key: it is this additional key that distinguishes a pc102 keyboard from a pc101 keyboard, and a pc105 keyboard from a pc104 keyboard.

If your keyboard has a "< >" key, you probably have a 102- or 105-key model. The "< >" key may not work if you do not configure your keyboard model correctly. You can use dpkg-reconfigure xserver-xfree86 to change this configuration parameter, or edit /etc/X11/XF86Config-4 directly.

If you have done this, or have already confirmed that your XkbModel is set to pc102 or pc105 in the XF86Config-4 file, but your "< >" key still doesn't work in X, then an X client is probably reconfiguring your keyboard after the server starts.

To confirm this, start the X server in a way that bypasses all client-side initialization, and use the xev program from the xbase-clients package to determine whether your "< >" key works when the X server initially starts.

Here's one way to do it from a virtual console:
xinit /usr/bin/X11/xev -- :1 vt8 > /tmp/xev.out

This starts the X server using server number 1 (in case you already have a session active on :0), on virtual console 8, and runs the xev client, redirecting xev's output to a temporary file.

Move the mouse cursor into the white window, then press and release the "< >" key. (There will be no visible response to your keystrokes.) Then kill the X server, either by using CTRL-ALT-BACKSPACE or by switching back to the virtual console from which you ran xinit, and typing CTRL-C.

Next, use your favorite pager program to view xev's output:
pager /tmp/xev.out

Near the end (after a whole lot of mouse events), you will see something like this:

KeyRelease event, serial 28, synthetic NO, window 0x1a00001,
      root 0x58, subw 0x0, time 19431502, (57,266), root:(553,290),
      state 0x0, keycode 94 (keysym 0x3c, less), same_screen YES,
      XLookupString gives 1 bytes:  "<"

Note particularly the "keycode" and "keysym" information.

If, instead, you see something like this:

KeyRelease event, serial 28, synthetic NO, window 0x1e00001,
      root 0x58, subw 0x0, time 20019010, (425,-87), root:(429,281),
      state 0x0, keycode 94 (keysym 0x0, NoSymbol), same_screen YES,
      XLookupString gives 0 bytes:  ""

Then the X server is not starting with the correct keymap for your locale, and you need to check your XF86Config-4 file again. You may have a subtle problem, such as multiple keyboard input devices defined in the file (and the wrong one is being used), or the XF86Config-4 file may have been disregarded in favor of a different configuration file. See the XF86Config-4(5x) manual page for more information on these types of problems.

Also note that the XFree86 X server log file (such as /var/log/XFree86.0.log) will not only tell you the name of the configuration file that was used, but also what the X server thinks the keyboard configuration is.

If the X server can see your "< >" key when it starts this way, but not normally, then you do have a problem with an X client changing it after the X server starts. Several X clients can do this, including:

The xmodmap client is deprecated for keyboard manipulation, but some people still use it. The best way to see if it is running is to check the system's X session scripts as well as your own. E.g.,
grep -irs xmodmap /etc/X11/xkb $HOME/.xsession

The setxkbmap client is pretty straightforward, and can be searched for the same way. Make sure it is not being invoked with the -model pc101 or -model pc104 arguments, for example. See setxkbmap(1x) for more information.

In KDE 3.2, the relevant Control Center menu is Regional & Accessibility -> Keyboard Layout.

In GNOME 2.4, right-click the GNOME keyboard applet and select "Settings...".

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 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.

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 DEC 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, and how do DEC VT220 and PC keyboards differ? A lengthy explanation follows.

Backspace

The first big difference is the key called "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 ("DEL") 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, particularly 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. Users don't care about ASCII users care about results. Bottom line: the "backspace" key, the one in the upper-right of the alphabetic section, should generate ASCII 127 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, this ASCII misconception discussed crept into widely-distributed termcap and terminfo data for xterm, 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, Thomas Dickey, the upstream xterm maintainer, took steps to move everybody back to the Good Side of the Force in XFree86 4.0. Debian's Keyboard Policy anticipated that move. So, if people do things correctly, there is no incompatibility between the Linux console and xterm. (Indeed, in the years since this FAQ entry was written, the number of complaints about this issue has declined almost to zero.)

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 ("DEL") 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.

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 VT 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 VT terminals have "PF1", "PF2", "PF3", and "PF4". (PF means "Pad Function".) These were the only function keys the VT100 had; the VT220 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 VT terminals had no "Num Lock" key, but had a toggle 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 "Home", "Ins", and so forth in addition to the digits 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.

Fn function keys

These don't even exist on a real DEC VT100, but they do on the VT220 (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", VT100s have no keys and VT220s and later have only two keys: a "Help" key and a double-wide "Do" key.

Status LEDs

Finally, VT220 and later keyboards have four additional function keys (F17 through F20) above the numeric keypad where most PC keyboards have the LEDs 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 <Key>F1: string("ssh remote.host.org")\n\
                               Shift <Key>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 "<Key>" 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:

Why are some fonts (or graphical rulers) sized incorrectly?

Programs that try to optimize font sizes for better screen output (such as ?FontConfig-based applications) and those that try to show real-world geometry (like inch/centimeter scales in the GIMP) need to know the pixel density of the display to be accurate. This value is the ratio of the display's pixel resolution to the physical size of your monitor generally between 70 and 120 DPI (dots per inch). If the DPI value used by the X server does not match the actual monitor characteristics, applications that use this information are likely to display fonts and other graphics that are scaled incorrectly based on this inaccurate information. You can use the xdpyinfo program in the xbase-clients package to check the assumed monitor size and dot resolution. The DPI value is retrieved by X client applications by querying the X server; therefore, the X server needs to know (or be told) what value to use.

See the next question to learn how to change the DPI value used by the X server and communicated to X clients.

How do I set the DPI (dots-per-inch) value used by the X server?

Two ways to get an accurate DPI value to your application are:

  1. pass the -dpi option to the X server (this also works for many non-XFree86 X servers); or
  2. let the XFree86 X server calculate the DPI value based on the ?DisplaySize parameter in its configuration file, XF86Config-4. See the XF86Config-4(5x) manual page for details.

The first method is recommended if you already know the DPI value of your monitor and wish to always run it at the same resolution; the second method is the more flexible way, but only available for the XFree86 X server.

Locate and edit the scripts which start the X server:

/etc/X11/xinit/xserverrc

for xinit and startx (in the xbase-clients package)

/etc/gdm/gdm.conf

for gdm

/etc/kde3/kdm/Xservers

for kdm

/etc/X11/wdm/Xservers

for wdm

/etc/X11/xdm/Xservers

for xdm

Passing the -dpi option to the X server:

In each of these files above, replace the value after -dpi with the correct number.

Letting the XFree86 X server calculate the DPI:

In each of the files above, remove the -dpi word and the following number. Then edit /etc/X11/XF86Config-4 and locate the Monitor section there. Add a line like:

DisplaySize     288 216

to it. The numbers above are horizonatal and vertical dimensions of the monitor's visible screen area (in millimeters) which you can often find in the monitor's manual. Manually measuring the visible screen area with a ruler or tape measure may be the most precise method, but keep in mind that depending on the modeline definitions, the exact measurements of the visible portions of the screen may differ from mode to mode.

When you've finished, restart the X server and use the xdpyinfo command from the xbase-clients package to check the new DPI settings.

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 http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html.

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 `Xephyr` and `Xnest`, the nested X servers?

All of the following applies to both Xephyr and Xnest. Xephyr is recommended, as it is currently maintained at X.org while Xnest has fallen in to disrepair. Furthermore, Xephyr supports newer X extensions that Xnest does not support. However, for those who choose to use Xnest, in all of the following Xnest may be substitutded for Xephyr.

Some people find that they can start Xephyr (e.g., with Xephyr :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 Xephyr: 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 XAUTHORITY cookie for the session by using the xauth command. 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 Xephyr if you're going to be using it much:

MCOOKIE=$(mcookie)
xauth add $(hostname)/unix$1 . $MCOOKIE
xauth add localhost/unix$1 . $MCOOKIE
Xephyr "$@"
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 Xephyr itself; all arguments to the script are passed through transparently to Xephyr (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 http://www.xfree86.org/pipermail/fonts/2001-March/000569.html):

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

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.

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.

David B. Harris of Debian also has these remarks:

Something worth noting is also the concept of leaking. This will be a term familiar to some and unknown to others. Basically, as processes run they may dynamically allocate memory for some purpose or other. If they allocate some memory, but never de-allocate it, even after they're done using it, then over time the memory used by that process will increase.

Since hardware/video drivers in XFree86 are responsible for some of this allocation and de-allocation, a badly-written driver can increase the memory used by the XFree86 process. The closed-source nVidia drivers are particularily bad for this; I've seen XFree86 memory usage triple during a week-long session.

Keep in mind that this isn't the end of the world. Unless it's an extremely badly-written driver, memory allocated by the driver which doesn't get de-allocated (but stops being actively used) will be swapped out. So the amount of physical RAM the XFree86 process will use won't increase much (if at all) due to these drivers.

Mike A. Harris of Red Hat Software offers the following advice:

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.

See, however, the remarks from Albert Cahalan below. B.R.

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.

Albert Cahalan makes a bit of a correction to the above, however:

Sorry, but procps does not currently report I/O memory as part of the memory being used by the X server. The X server is guilty as charged. Mine grows to about 300 MB on a system with only 16 MB of RAM. Of course I kill it at this point; it is reasonable to assume the server grows without limit until it crashes due to lack of swap or address space.

I kind of wonder if some dying app might be leaving stuff allocated on the X server, but it isn't obvious how I'd check for that...and anyway, it would be a design bug if that were possible.

Note that procps should be able to report memory usage with or without I/O regions included, but some foolish kernel hacker removed that ability in the mistaken belief that the /proc/*/statm behavior was unintentional.

Debian 3.1 ("sarge") and later ship the xrestop utility in the xrestop package, which should help identify resource leaks in the X server. This utility takes advantage of a new X extension called X-Resource, which is supported in XFree86 4.3.0 and later and X.Org 6.7.0 and later.

Why do the menus in `xterm` have the wrong font, size, background color, or foregound color?

Because, 99 times out of 100, you're not using X resources correctly.

If you have X resource specifications (say, in your $HOME/.Xresources file) that look like this:

XTerm*foreground: black
XTerm*background: white
XTerm*geometry: 200x55-0+20
XTerm*font: 10x20

...then be aware that you are, in fact, telling the menus, not just the VT100 widget, to use the 10x20 font with white-on-black text. That asterisk is a wildcard, not an ordinary separator. xterm is doing exactly what you are telling it to do. If you find X resources confusing, don't use them, or read the "RESOURCES" section of the X(7x) manual page.

If you want to set X resources for xterm that affect only its VT100 widget, then you need to say so:

XTerm.VT100.background: white
XTerm.VT100.foreground: black
XTerm.VT100.font: 10x20
XTerm.VT100.geometry: 200x55-0+20

Why is `xterm` using the "fixed" font for everything, disregarding the font configuration from the X resource database?

Thanks to Thomas Dickey for providing this explanation.

This is often another example of overly-aggressive wildcarding in X resource specifications (see above).

The wide-character widget hierarchy for xterm has resource names like

versus the users' expected

The former (utf8Fonts) override the latter when UTF-8 mode is selected (after the resources are evaluated, of course).

The utf8fonts should be ISO 10646 fonts, not ISO 8859-1. The wildcard xterm*font sets both resources to the same value.

Wildcards have their place, but generally not before the last level in the resource hierarchy. For example, xterm*vt100.font makes things work as expected with or without the toolbar option. That's specific enough that it doesn't introduce a problem.

I just upgraded the X server and it doesn't work; also, I'm using Matrox's proprietary `mga_hal` driver module or NVidia's proprietary `nvidia` driver module; what's going on?

Debian cannot officially support proprietary XFree86 driver modules such as these for a few reasons:

  1. In some cases, we don't ship them (usually because we cannot, as the license prevents us from doing so);
  2. they're not part of XFree86, but third-party add-ons;
  3. (most importantly) we don't have the source code, so we cannot find and fix bugs in them neither can (in general) the authors of XFree86 itself.

That said, one common problem with these proprietary modules is that you're using a newer version of the XFree86 X server than the module was compiled for. Take a look at your XFree86 log file, which is in the /var/log directory. The file name is often /var/log/XFree86.0.log (the number will be be different if the X server with a different server number, e.g. XFree86.1.log for DISPLAY=:1.)

Here's an example of server/driver version mismatch:

$ more /var/log/XFree86.0.log
[...]
  XFree86 Version 4.2.1.1 (Debian 4.2.1-5 20030122074040 buildd@cyberhq.internal.cyberhqz.com) / X Window System
[...]
  (II) LoadModule: "nvidia"
  (II) Loading /usr/X11R6/lib/modules/drivers/nvidia_drv.o
  (II) Module nvidia: vendor="NVIDIA Corporation"
          compiled for 4.0.2, module version = 1.0.4191
          Module class: XFree86 Video Driver

In the above, we see that the module was compiled for XFree86 4.0.2, but the user is running XFree86 4.2.1.1, which is somewhat more recent. There are roughly three courses of action a user with the above problem can take:

  1. downgrade the xserver-xfree86 package to a version compatible with the driver (this may not be possible depending on what is available on the Debian mirror network);

  2. contact the technical support service of the company distributing the proprietary server module, such as Matrox or NVidia, and request a newer version of the module;
  3. remove the proprietary server module and use free alternatives, such as the mga or nv drivers that ship as part of the xserver-xfree86 package you may need to use the dpkg-reconfigure xserver-xfree86 command or edit the /etc/X11/XF86Config-4 file to instruct the X server to use the free modules.

I'm using a Macintosh, and while the keyboard works correctly on a virtual terminal, in X it's all messed up. What's the matter?

In most cases of which I am aware, this happens because the X server has been configured with the XkbModel set to macintosh, when it should be using macintosh_old.

The cause of the problem is the difference between "ADB keycodes" (ADB means "Apple Desktop Bus") and "Linux keycodes". Traditionally, on Macintosh computers running Linux, the kernel transmitted ADB keycodes that listened to the keyboard in "raw" mode. ("Raw" mode is the mode the X server uses to listen for events from the keyboard.) This is because the keyboard was connected to the computer using the Apple Desktop Bus, and not USB, which has been the bus of choice for Apple machines starting with the "?NewWorld" architecture: the iMac in August 1998 and the "Blue and White" G3 in January 1999. However, since Debian GNU/Linux 3.0 ("woody") was released, the stock configuration for the PowerPC port has been to use Linux keycodes.

If you're using an m68k-based Macintosh, (that is, you know you're using a Mac and the output of uname -m command is not ppc), you should reconfigure the X server to use macintosh_old for your XkbModel. One way to do this with the command dpkg-reconfigure xserver-xfree86 as the root user.

As of 4 March 2003, no kernels with the feature of sending Linux keycodes are in stable release for m68k-based Macintoshes.

If you're using a PowerPC-based Macintosh, your system could configured to send either ADB or Linux keycodes when they keyboard is in "raw" mode. Furthermore, the kernel could be "locked" into one or the other, or permit run-time switching. To see if your kernel can switch between ADB and Linux keycodes, run the following command:

cat /proc/sys/dev/mac_hid/keyboard_sends_linux_keycodes

If you get back cat: /proc/sys/dev/mac_hid/keyboard_sends_linux_keycodes: No such file or directory, then your kernel cannot switch, and will only send one or the other.

If you get back , then your kernel can switch back and forth, and it is currently sending ADB keycodes.

If you get back 1, then your kernel can switch back and forth, and it is currently sending Linux keycodes.

On kernels that support switching, you can tell it to move back and forth by simply echoing zero or one to this file, though you must be root to do this.

For example, to switch off Linux keycodes and use ADB keycodes:
echo 0 > /proc/sys/dev/mac_hid/keyboard_sends_linux_keycodes

To switch off ADB keycodes and use Linux keycodes: echo 1 > /proc/sys/dev/mac_hid/keyboard_sends_linux_keycodes

If your kernel is not capable of switching back and forth, you can use the kernel's configuration file to determine which set of keycodes are in use by default. All official Debian kernels and kernels produced by the make-kpkg command make this configuration file available by placing it the kernel-image package which gets installed.

The following command will tell you how your kernel is configured:
grep CONFIG_MAC_ADBKEYCODES /boot/config-$(uname -r)

You will likely see one of the following in response:
CONFIG_MAC_ADBKEYCODES=y

The above means that your kernel is sending ADB keycodes in "raw" mode, and you should use an XkbModel of macintosh_old.

# CONFIG_MAC_ADBKEYCODES is not set

The above means that your kernel is sending Linux keycodes in "raw" mode, and you should use an XkbModel of macintosh.

For more information on this issue, see http://www.debian.org/ports/powerpc/keycodes.

Why do some programs give authorization errors even when they are running as the same user and on the same machine as the X server?

This entry was written by Matthew Arnison.

Particular programs seem to be quite sensitive to the security setup in X. I think it is when they use ?PostScript rendering.

For LyX, the symptoms are that EPS figures do not render (they show up blank) and the terminal window you launched LyX from will give a lot of errors like:

Xlib: connection to ":0.0" refused by server
Xlib: Client is not authorized to connect to Server

I have also had problems with Mathematica 4.x refusing to start at all, with similar error messages. Running xhost + localhost works as a brute force solution for Mathematica, but that sacrifices a lot of security.

The problem is that xauth and startx seem to get confused with old cookies, especially if you have changed your machine's hostname or IP address. In addition, startx does not have a systematic way of cleaning out stale authorisation cookies from your ~/.Xauthority. After you quit X, it cleans cookies that it created, but that leaves cookies uncleaned if your computer crashes while X is running.

So this is what worked for me:

If startx does not find an ~/.Xauthority file, it will make a fresh one.

I'm not sure how xdm handles ~/.Xauthority. Perhaps it does a better job.

Why am I not able to run `startx` as a non-root user?

This entry was written by Colin Walters.

In the Debian packages of XFree86, some important variables affecting the startup of the X server are located in /etc/X11/Xwrapper.config. In this particular case, you must change the option allowed_users to either console or anybody. See Xwrapper.config(5) for more information and examples.

How do the X.org packages manage their non-conffile configuration files like `/etc/X11/X`, `/etc/X11/Xwrapper.config`, and `/etc/X11/xorg.conf`?

First, a note on terminology: conffile is a Debian term for a configuration file that is shipped as part of a package's payload. Non-conffile configuration files are either not handled by the package system at all, or are created and removed by a package's maintainer scripts.

Each of these files has some corresponding state information in /var/lib/xfree86.

The files whose names end in .md5sum in that directory contain MD5 checksums, and the files ending in .roster contain a list of packages that might write a new version of the configuration file.

The Xwrapper.config and xorg.conf files' checksums are based upon their file contents. /etc/X11/X is a symbolic link, so its checksum is based on the output of the readlink command when run against that file. The checksums are stored in /var/lib/xfree86, and use the basename of the corresponding configuration file with the suffix .md5sum.

The post-installation script of the xserver-xorg package will not overwrite the aforementioned non-conffile configuration files if any of the following conditions is met:

If none of the foregoing conditions are met, the configuration file is automatically updated, and if it has changed, its new MD5 checksum is written to the appropriate location in /var/lib/xfree86.

The roster file is used simply to keep track of when it is safe to remove a non-conffile configuration file on package purge. As each package that is listed in a configuration file's roster is purged, that package's name is removed from the roster. When the last package name is removed, one final comparison between the configuration file's MD5 sum and the stored MD5 checksum is made, just as with the case when a configuration file is to be overwritten. If the same conditions are met under which the file would be rewritten (it exists, the checksum file exists, etc.), the file is removed. In any case, when the last package listed in a configuration file's roster is removed, the stored checksum file is removed. Therefore it is possible for a modified configuration file to remain on the system after all packages interested in potentially writing to it have been removed, and even their roster and checksum files are gone. This is regarded as the correct behavior because, by modifying the configuration file, the user has expressed his or her desire to have the packaging system abandon control of the file.

People writing installers for the Debian OS should note that pre-configuration of the XFree86 X server is now as simple as creating an /etc/X11/X symlink and /etc/X11/xorg.conf file before installing the xserver-xfree86 package. The presence of these files causes the question priority of the package's debconf questions to be capped at "medium"; the files' existence is regarded as defining a "reasonable default" to the corresponing debconf questions (see debconf(7)). Therefore, setting the DEBIAN_PRIORITY environment variable to "high" will bypass the asking of all X server-related debconf questions, and the existence of the /etc/X11/X and /etc/X11/XF86Config-4 files in the absence of stored checksum files will prevent them from being overwritten by maintainer scripts.

I've customized my `/etc/X11/X`, `/etc/X11/Xwrapper.config`, and/or `/etc/X11/xorg.conf` files so the packages don't automatically update them anymore. I'd like them automatically managed again, though; how can I achieve that?

Please be aware that your local customizations will be lost if you do this! Don't say you weren't warned...

You can "trick" the packages into thinking that the versions of the configuration files on disk were written by them by replacing the MD5 checksum that they have associated with the file. /etc/X11/X is a bit of a special case because it is a symbolic link, not a file with contents.

For /etc/X11/X, do the following as root:
readlink /etc/X11/X | md5sum > /var/lib/xfree86/X.md5sum
dpkg-reconfigure xserver-xfree86

(You may have xserver-xfree86-dbg installed instead, in which case, run dpkg-reconfigure on that package instead.)

For /etc/X11/xorg.conf, do the following as root:
md5sum /etc/X11/xorg.conf > /var/lib/xfree86/xorg.conf.md5sum
dpkg-reconfigure xserver-xorg

For /etc/X11/Xwrapper.config, do the following as root:
md5sum /etc/X11/Xwrapper.config > /var/lib/xfree86/Xwrapper.config.md5sum
dpkg-reconfigure xserver-xorg

Another way to accomplish the above is to purge the packages from your system and reinstall them, but that can be considerably more disruptive. Nevertheless, here's an example (like the commands above, it must be run as root):
dpkg --purge xserver-xorg
apt-get install xserver-xorg

How do I add custom sections to a `dexconf`-generated `xorg.conf` file?

You likely do not want to instruct dexconf to overwrite your existing xorg.conf file if you have modified it. The Debian package maintainer scripts will not overwrite the file if they detect that you have modified the file (see How do the X.org packages manage their non-conffile configuration files like `/etc/X11/X`, `/etc/X11/Xwrapper.config`, and `/etc/X11/xorg.conf`? above).

Since the Debian X.org packages' debconf questions are not intended to be fully-featured X server configuration tools, but merely to collect enough information to achieve a working single-headed setup, you may find that you wish to customize the generated xorg.conf file by editing any of the existing sections written by dexconf or by adding 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) does 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 is that the first ServerLayout section encountered in the xorg.conf 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 dexconf: 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 xorg.conf 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

See the xorg.conf(5) manual page for more information on X.org X server configuration.

The X server log says there was an error and it's disabling DRI. Is that why the X server won't start?

No. If DRI (Direct Rendering Infrastructure) is disabled, then 3D-accelerated applications such as games may not run satisfactorily or at full speed, but this doesn't prevent the X server from working. A disabled DRI doesn't prevent your desktop from coming up, or programs like XTerm or Mozilla from running.

If your X server is failing to start and you think this error message is the problem, look elsewhere; the problem is something else.

The X server log says there was an error opening my "core pointer" or the file `/dev/input/mice`. Is that why the X server won't start?

Errors saying failure to initialize core devices are usually fatal. Errors about failing to open /dev/input/mice usually aren't if they're not accompanied by a failure to initialize core devices message.

If you have non-USB mouse configured, the Debian default X.org X server configuration sets up an extra input device so that you can just plug a USB mouse in to one of your USB ports (if you have any) and use it as well.

It's easy enough to determine whether errors opening /dev/input/mice are really the cause of a failing X server. As root, run the following command:
X -allowMouseOpenFail

(If you get a message like Server already active for display 0, then you're probably already running X somewhere. Try specifying a display for the X server to run on:
X :50 -allowMouseOpenFail

See the Xserver(1) and Xorg(1) manual pages for more information.)

If the X server does not start, then the mouse device is not your problem. Search the X server's log (in the above examples, /var/log/Xorg.0.log or /var/log/Xorg.13.log) for other errors.

If the X server does start, then you do have a mouse problem. Use dpkg-reconfigure xserver-xorg to correct the configuration of your mouse. The mdetect package and utility of the same name may help you to determine how the X.org X server should be configured in this regard. Install the package and run the following command:
mdetect -x

Note that the X server will usually succeed in opening the /dev/input/mice device (if it exists), even if there is no mouse actually plugged into the port. That's because the Linux kernel's mousedev driver (which handles /dev/input/mice) serves as a go-between for userspace processes like the X server and your actual mouse hardware.

The X server log says it's skipping modules due to No symbols found errors. Is that why the X server won't start?

Generally, no.

(II) Loading /usr/X11R6/lib/modules/fonts/libspeedo.a
Skipping "/usr/X11R6/lib/modules/fonts/libspeedo.a:spencode.o":  No symbols found

Messages like the above are not fatal. If your X server refuses to start, it's most likely for some other reason.

The X server log says AddScreen/ScreenInit failed for driver 0. Is that why the X server won't start?

Usually, yes. Look for lines before that in the X server log that start with (EE). For instance, users of Intel i810-family chipsets often have this problem if they're running a Linux kernel that doesn't support GART access to the AGP port. (This facility is provided by a kernel module called agpgart in Linux 2.4.x, and by a set of chipset-specific modules such as agpgart-uninorth in Linux 2.6.x.)

If you're an i810 user and you see the following in the log:

(EE) Unable to open /dev/agpgart (No such device)

Then that is the exact problem you have. You need to install a Debian kernel-image package that contains support for AGP GART. Official Debian kernel-image packages for the x86 and compatible processors typically do.

How can I tell if it's the X server crashing, or my X session exiting abnormally?

Generally, when the X server has no more clients to manage, it will exit immediately. This can look a lot like a "crash" to the uninitiated, especially when the clients themselves crash.

It's easy to determine whether the X server itself works. As root, simply run the command X. If that brings up the little root window weave and the X cursor, then you do not have a fatal X server configuration problem. The X server is working. Use CTRL-ALT-BACKSPACE to kill it.

Alternatively, if you're using a display manager and you can see the greeter (login screen), then the X server is running: you do not have a fatal X server configuration problem. Most failures after that point are client-side problems. (Yes, there are bugs in the X server that can cause it to spontaneously crash, but if the X server "crashes" immediately upon logging in to your X session, it's probably a client-side problem.)

If the X server doesn't start with the command X, but you get a message like Server already active for display 0, then you're probably already running X somewhere. See the "The X server log says there was an error opening my "'core pointer' ..."-question above for more information on how to deal with this.

I'm having trouble getting dual-head support to work on my ATI Radeon card. Can you help?

Thanks to Paul Gotch for writing most of this entry.

Some users, particularly those who dual-boot GNU/Linux and one of the Microsoft Windows operating systems, find that their ATI Radeon cards appear to autodetect the presence of a second monitor differently depending on whether the machine was brought up "cold" into GNU/Linux, or simply restarted from Windows. However, the advice in this section is intended for all dual-head ATI Radeon users.

In your /etc/X11/xorg.conf file, you may need to use the MonitorLayout option in each of the Device sections corresponding to the "heads" (monitors) being driven by the video card. This option is documented in the radeon(4) manual page.

At system reset, the video card tries to determine what is connected to each of the ports. This is necessary because digital video output (DVI) is very different from analog video output (VGA).

If a display is connected to the DVI port, that becomes the primary display, and the VGA port the secondary display. Otherwise, the VGA port is the primary and the DVI port is not enabled.

If dual-head operation is then forcibly enabled when the video card doesn't think that there is anything connected to the second display, the secondary head is driven in "clone mode". This is either undocumented behaviour, or is a default in the Radeon driver if the card has failed to autodetect over the the DDC (Data Display Channel) connection to the monitor.

In my case I believe the problem was caused by the presence of a KVM switch between the card and the monitor. DDC seems to be very flaky. :/

The workaround of using the MonitorLayout option simply forces the card into a particular mode so that it ignores whatever is coming over DDC.

I've heard that it is possible to damage the card with an incorrect MonitorLayout line, but I can't think of a physical mechanism for this actually happening.

My keyboard configuration worked with previous versions of X; why is it messed up now? For example, my Windows keys don't work right in Emacs or my window manager anymore.

Thanks to Denis Barbier for contributing much of this entry.

Please see the glossary in "How does the keyboard work in the X Window System?" above for explanantions of unfamiliar terms.

The most significant recent change to keyboard configuration took place to XKB layouts in XFree86 4.3; they were significantly revised and updated. The most intuitive approach to supporting multiple levels on the keyboard is through combining layouts. Prior to XFree86 4.3, though, this was difficult because keyboard symbols (keysyms) were defined to be specific to a given group. For example, the us symbols file (in /etc/X11/xkb/symbols/) defined its keycode to keysym mappings specifically for group 1 the primary group. The us_group2 and us_group3 files repeated these definitions for group 2 and group 3, respectively. In addition to being wasteful, alternative group layouts were never copied in this fashion for any territory except the U.S. Combining Russian and French layouts, for example, was consequently impossible without modifying the XKB data files directly a skill most users do not possess.

There are now new definitions that are "multi-layout aware"; they can be used in arbitrary order so that us,ru and ru,us use the same symbols files. The multi-layout-capable definitions have been placed in /etc/X11/xkb/symbols/pc/ while the old ones are still available in their traditional location; that is, directly within the /etc/X11/xkb/symbols/ directory.

Some symbols files have not been converted to the new multi-layout approach, and thus can not be combined with others. These are listed as $old_layouts in /etc/X11/xkb/rules/xfree86. If you have trouble combining layouts, check that you are not trying to load a layout listed there.

Furthermore, modifiers also been affected by the multi-layout changes to make the system more modular. This is a change that was initially made to XFree86 CVS after XFree86 4.3.0 was released, but has been incorporated into Debian's packages of XFree86 4.3.0, further refined, and adopted upstream by both XFree86 and X.Org. One consequence is that fake keys have been introduced in XKB data files for Alt, Meta, Super and Hyper. (The fake keys are distinguished from real keys by not being pair-oriented to the "left" or "right". Even keyboards that have only one of a pair of such keys like laptop keyboards report the keys they do have as being either left or right, for compatibility with full-size models.) By default, the modifiers mod1 and mod4 use these fake keys instead of real ones. The logo keys (a.k.a. "Windows" keys) are often used for one of these modifiers. XKB-aware applications can handle those fake keys, but some applications are not XKB-aware they get confused and will not recognize some of your keys as activating the right modifiers.

GNU Emacs, XEmacs, Openbox, and Sawfish are known to be (or have been) buggy in this fashion, but there may be others. In window managers, the consequences of this bug vary, but one commonly seen result is that the transient window used to navigate workspaces does not go away when the keys that bring it up (such as Win+Tab) are released. The recommendation of Debian developers to frustrated Sawfish users appears to be to switch to Metacity.

A workaround you can use if your application has not yet been fixed is to set the altwin:super_win XKB option. To try it out, run the command setxkbmap -option "altwin:super_win"*. To make the change permanent, run dpkg-reconfigure xserver-xfree86 as root, and add altwin:super_win to your configured XKB options when prompted.

For further information, please see:

* This may not work if you are already using an XKB option that affects your Alt or logo keys.

Why does composing characters work in some applications but not others?

Thanks to Jeff Licquia for contributing much of this entry.

People sometimes find that they can use their Compose key as expected in some applications for instance, uxterm, xterm, and OpenOffice.Org Writer but not in others, such as Mozilla, Galeon, or gnome-terminal.

The difference is that the latter group of applications use the GTK+ input method framework, and the former group does not.

GTK+ has its own input method framework that is separate from the X input methods. This is necessary because GTK+ is supposed to be independent of X.

The default input method is, of course, Latin. When implementing this method, the GTK+ people focused on ISO 8859-1, and did not implement many of the other Latin character sets. This is why GTK+-based programs seem not to be able to type characters that other pure X programs can.

There are several things you can do about the problem. All of them involve using a different GTK+ input method. You can test these by opening some GTK+ app that takes input, such as gedit. Right-click on the edit box, and there should be a submenu for "Input Methods". The new input method should show up in that submenu.

If you want to make a certain input method the default system-wide, edit /etc/environment, and set the environment variable GTK_IM_MODULE there to the input method module you want (Use xim for the XIM shim). Of course, you can do the same thing for just yourself by setting that environment variable in .profile, .bashrc, or whatever your shell uses as an initialization file.

Sometimes I get garbage characters like `1;2c` in my `xterm` windows; what's happening?

Thanks to Thomas Dickey for contributing much of this entry.

Occasionally people are concerned that this is a security problem they fear that some rogue application may be trying to inject keystrokes at their shell prompt, for example. While xterm and other terminal emulators have had bugs like that in the past (see MITRE's CVE candidate CAN-2003-0063), this is not such a situation.

What you're seeing is part of the VT100 escape sequence that uses the cursor position of the lower-right corner to determine the screen size. You're only seeing part of it because the "wrong" application had eaten part of the response. (I get that sort of thing if I log into certain machines from the FreeBSD console it doesn't respond as a VT100 would.)

Normally I'd see this only due to a misconfiguration and/or combination with a timeout. It's annoying but relatively harmless. It's not like the answerback or title strings the response is determined by the terminal geometry and can't contain arbitrary text.

If resize cannot get useful information by a system call, it positions the cursor far right/down, and then asks the terminal where it really got to. Real VT100 terminals won't wrap when positioning the cursor to (999,999), but will just move it in that direction until it stops*.

The response looks like:

ESC [ ''row'' ; ''column'' R

where row and column are positive decimal integers. If one is in the habit of filling up their bin directory with malicious scripts named 79R, 80R, etc., that could be a problem but I think it's a fairly low probability.

* Some day I'll see a bug report from someone who's got a 1200x1200 xterm, and (with a script of course), they'll determine that resize doesn't give the correct result.

How can I set up my X server or X terminal to use XKB without any X libraries or XKB data installed?

What you want to do is use xkbcomp on a machine that has xbase-clients installed to compile a keymap file corresponding to the desired configuration, and then transfer that .xkm file to the X terminal (the machine running the X server), where you can use the X server's -xkbmap option to load it.

See xkbcomp(1x) and Xserver(1x) for more information.

How can I help debug the X server?

You can often help Debian and upstream driver maintainers fix problems by narrowing down exactly where a crash or lockup is. You don't need to do this when filing an initial bug report you can do it for any problem you can reproduce and follow-up to an existing bug report. The reportbug program will give you the opportunity to add information to an already-filed report when it displays the list of bugs already filed against a package.

The first thing to do is to see if you can reproduce the problem with the xserver-xfree86-dbg package. Install the package and tell debconf you want to use that X server. Then restart the X server and try to reproduce the bug (hopefully, this is easy). If it doesn't crash, let us know. If a bug is in the XFree86 X server's ELF module loader, you likely won't see it when you use the debugging server. Debian still wants to know that information. If it does crash, become root, enable core dumps (ulimit -c unlimited in bash), start the X server as root and reproduce the crash again:

startx $(which x-terminal-emulator) -- :1

If no X server is running at server number 0 (DISPLAY=:0), you can leave off the -- :1 arguments.

This will launch the X server running a lone terminal client with no window manager. Run the client that provokes the crash from the terminal prompt. If you can only reproduce the crash with a more elaborate environment, then go ahead and produce that environment. Be sure to tell us what you did to get it (e.g., launching GNOME or KDE, setting up a particular screensaver, running an SDL game whatever it takes). It is not wise to run X clients as root except when absolutely necessary, so if the session doesn't crash, don't leave it running. Shut it down as soon as you can. It might also be a good idea to scrub out root's home directory (/root) of hidden files and directories created by desktop environments and whatever X clients you attempted to reproduce the crash with. Look for /root/.gnome, /root/.kde, and so forth.

If the X server crashes, it should leave a core dump file called core in /etc/X11.

Next, run the GNU Debugger, GDB (from the gdb package), on the core file and Xorg executable. The information of most interest to us is a backtrace of execution. The X server has a signal handler in it so it can do things like exit gracefully (restoring the text console, and so forth), so we're not actually interested in all the stack frames just those "above" the signal handler.

Here's an example GDB session I logged after provoking an artificial server crash (with kill -SEGV).

  % gdb $(which Xorg) core
  GNU gdb 6.1-debian
  Copyright 2004 Free Software Foundation, Inc.
  GDB is free software, covered by the GNU General Public License, and you are
  welcome to change it and/or distribute copies of it under certain conditions.
  Type "show copying" to see the conditions.
  There is absolutely no warranty for GDB.  Type "show warranty" for details.
  This GDB was configured as "i386-linux"...Using host libthread_db library "/lib/libthread_db.so.1".

  Core was generated by `/usr/X11R6/bin/X :1'.
  Program terminated with signal 6, Aborted.
  Reading symbols from /usr/lib/libfreetype.so.6...done.
  Loaded symbols for /usr/lib/libfreetype.so.6
  Reading symbols from /usr/lib/libz.so.1...done.
  Loaded symbols for /usr/lib/libz.so.1
  Reading symbols from /lib/libm.so.6...done.
  Loaded symbols for /lib/libm.so.6
  Reading symbols from /lib/libc.so.6...done.
  Loaded symbols for /lib/libc.so.6
  Reading symbols from /lib/ld-linux.so.2...done.
  Loaded symbols for /lib/ld-linux.so.2
  #0  0x400f2721 in kill () from /lib/libc.so.6
  (gdb) bt
  #0  0x400f2721 in kill () from /lib/libc.so.6
  #1  0x400f24c5 in raise () from /lib/libc.so.6
  #2  0x400f39e8 in abort () from /lib/libc.so.6
  #3  0x08464b8c in ddxGiveUp () at xf86Init.c:1173
  #4  0x08464c6b in AbortDDX () at xf86Init.c:1224
  #5  0x08508bd7 in AbortServer () at utils.c:436
  #6  0x0850a563 in FatalError (f=0x8a26ea0 "Caught signal %d.  Server aborting\n") at utils.c:1421
  #7  0x0847fbf5 in xf86SigHandler (signo=11) at xf86Events.c:1198
  #8  <signal handler called>
  #9  0x40199dd2 in select () from /lib/libc.so.6
  #10 0x401f8550 in ?? () from /lib/libc.so.6
  #11 0x400164a0 in ?? () from /lib/ld-linux.so.2
  #12 0xbffff8f0 in ?? ()
  #13 0x08502520 in WaitForSomething (pClientsReady=0xbffff944) at WaitFor.c:350
  #14 0x084cff54 in Dispatch () at dispatch.c:379
  #15 0x084e763c in main (argc=2, argv=0xbffffe04, envp=0xbffffe10) at main.c:469
  (gdb) bt full -7
  #9  0x40199dd2 in select () from /lib/libc.so.6
  No symbol table info available.
  #10 0x401f8550 in ?? () from /lib/libc.so.6
  No symbol table info available.
  #11 0x400164a0 in ?? () from /lib/ld-linux.so.2
  No symbol table info available.
  #12 0xbffff8f0 in ?? ()
  No symbol table info available.
  #13 0x08502520 in WaitForSomething (pClientsReady=0xbffff944) at WaitFor.c:350
          i = 2
          waittime = {tv_sec = 118, tv_usec = 580000}
          wt = (struct timeval *) 0xbffff910
          timeout = 599999
          standbyTimeout = 1199999
          suspendTimeout = 1799999
          offTimeout = 2399999
          clientsReadable = {fds_bits = {0 <repeats 32 times>}}
          clientsWritable = {fds_bits = {1, 146318192, -1073743800, 140704020, 147350456, 147350040, 2, 312, 1, 1075418973, -1073743800, 139461033, 147374816, 1, -1073743680, 9, 1073833120, -1073742332,
      -1073743784, 139526463, 9, -1073743680, 1, 139458611, 147350456, 147350040, -1073743752, 139529154, 147339744, -1073743680, 1, 1074655182}}
          curclient = 147556952
          selecterr = 3
          nready = 0
          devicesReadable = {fds_bits = {1, 1, 6, 146327832, 147350508, 0, 315, 302, 9, 3, 315, 302, 9, 3, 0, 0, 146318192, 1075807568, -1073743880, 137843170, 146125816, 3, 313, 147556952, 0, 15066597, 3,
      -1, 147350500, 1, 0, 146319268}}
          now = 16069
          someReady = 0
  #14 0x084cff54 in Dispatch () at dispatch.c:379
          clientReady = (int *) 0xbffff944
          result = 0
          client = 0x8c8c2e0
          nready = -1
          icheck = (HWEventQueuePtr *) 0x8b45c68
          start_tick = 940
  #15 0x084e763c in main (argc=2, argv=0xbffffe04, envp=0xbffffe10) at main.c:469
          i = 1
          j = 2
          k = 2
          error = -1073742332
          xauthfile = 0xbfffffba "/root/.Xauthority"
          alwaysCheckForInput = {0, 1}
  (gdb) quit

In the example above, you can see I used bt full -7 to get the "outermost" seven stack frames, complete with local variable information, where available. Your stack trace may vary. We want to see all the stack frames below (numbered greater than) <signal handler called> in the list. If you get confused, just send us the output of bt full (with no number after it) and we'll sort it out.

Generally speaking, such stack traces are extremely helpful for finding the cause of server crashes.

If the X server is hanging or locking up instead of crashing, you can use GDB to attach to the running process, and still coax a backtrace out of it. Simply replace the name of the core file with a process ID when invoking GDB.

For example, here's a partial transcript of this procedure with an XFree86-debug X server running in its normal event loop (which is the code it executes while waiting for something to do). Typically, the result of a backtrace when the X server is wedged, stuck, or hung will look somewhat different.

  # ps -fC XFree86-debug
  UID        PID  PPID  C STIME TTY          TIME CMD
  root     32410 32406  4 13:12 ?        00:00:00 XFree86-debug :1 vt10
  506 {0} root@sisyphus:~# gdb $(which XFree86-debug) 32410
  GNU gdb 6.3-debian
  Copyright 2004 Free Software Foundation, Inc.
  GDB is free software, covered by the GNU General Public License, and you are
  welcome to change it and/or distribute copies of it under certain conditions.
  Type "show copying" to see the conditions.
  There is absolutely no warranty for GDB.  Type "show warranty" for details.
  This GDB was configured as "powerpc-linux"...Using host libthread_db library "/lib/libthread_db.so.1".

  Attaching to program: /usr/X11R6/bin/XFree86-debug, process 32410
  Reading symbols from /usr/lib/libfreetype.so.6...done.
  Loaded symbols for /usr/lib/libfreetype.so.6
  Reading symbols from /usr/lib/libz.so.1...done.

[...]

  (gdb) bt
  #0  0x0fe14f10 in select () from /lib/libc.so.6
  #1  0x1051a774 in WaitForSomething (pClientsReady=0x7fffeba0) at WaitFor.c:350
  #2  0x104d1848 in Dispatch () at dispatch.c:379
  #3  0x104f397c in main (argc=3, argv=0x7ffff084, envp=0x7ffff094) at main.c:469
  (gdb) quit

In real-world debugging situations, you'll need to use an external terminal session (such as from a serial terminal or network connection via ssh) to debug a running X server, because a wedged X server will not be able to "hear" your request to change the active virtual console from the keyboard. Once remotely connected, however, you can use the chvt command from the console-tools package to force the system to change virtual consoles. From there, or from your remote shell, you can kill the misbehaving X server. As always when taking administrative action on wayward or undesired processes, try the gentler termination signals such as TERM (the default), INT, HUP, and QUIT before resorting to the KILL signal. The X server tends to consume many resources, and some of these may be not be properly freed if it is ungraciously terminated (as happens with KILL).

How can I help debug 3D acceleration problems?

Thanks to Michel Dänzer for his help writing this entry.

Sometimes it's not always clear where the cause of a given problem lies, especially when it comes to 3D-accelerated applications. This is because the X server, the Mesa GL library, and the Linux kernel must all cooperate to implement DRI (Direct Rendering Infrastructure) correctly.

To help narrrow down which piece of technology is reponsible for the problem, try the following steps:

  1. First, try to reproduce the problem by running the troublesome application from a shell prompt in a terminal window with the following environment variable set:
      LIBGL_DEBUG=verbose; export LIBGL_DEBUG

    If the problem is not reproducible, it is probably too soon to file a bug report. Ask for assistance on the `debian-user` mailing list.

  2. Next, to reproduce the problem as above with an additional environment variable set:
      LIBGL_ALWAYS_INDIRECT=1; export LIBGL_ALWAYS_INDIRECT

    With LIBGL_DEBUG=verbose already set and exported, we can determine whether indirect rendering is actually being used. Note that if it is, there will not be any special output, whereas if it's not (that is, if DRI is being used), you will see output like:

      libGL: XF86DRIGetClientDriverName: 4.0.1 r200 (screen 0)
      libGL: OpenDriver:
      trying /home/michdaen/src/mesa-cvs/Mesa/lib/r200_dri.so
      drmOpenByBusid: Searching for BusID pci:0000:00:10.0
      drmOpenDevice: node name is /dev/dri/card0
      drmOpenDevice: open result is 4, (OK)
      drmOpenByBusid: drmOpenMinor returns 4
      drmOpenByBusid: drmGetBusid reports pci:0000:00:10.0

    If the problem is reproducible with indirect rendering, then there is likely a problem with the OpenGL/GLX implementation in the X server most likely, in the Mesa code shared between the X server and the DRI 3D drivers. The problem could also be in the underlying GL library on the system, however; if you have reason to suspect this is the case, use the command dpkg -S /usr/lib/libGL.so.1 to determine which package provides your GL library, and file a bug report against it (or skip the middleman and use reportbug --file /usr/lib/libGL.so.1). On the other hand, if the problem goes away when indirect rendering is used, then one of the following is at fault:

    • the X server's portions of DRI
    • the Mesa DRI module for your display adapter
    • the Linux DRM (Direct Rendering Manager) module for your display adapter
    • your display adapter (i.e., a hardware bug that either Mesa or Linux should try to work around, if possible)
  3. To rule out problems with the X server's portions of DRI, disable the Load "dri" line in your /etc/X11/xorg.conf file. There are two ways to do this; you can run dpkg-reconfigure xserver-xorg and remove dri from the list of modules to be loaded, or you can simply open /etc/X11/xorg.conf with your favorite text editor and comment the line out by putting a hash mark (#) at the beginning of it. If doing the above resolves the problem but the previous step did not, you have found a problem in the X server's portions of DRI; file a bug against xserver-xfree86 and report your findings.

  4. Occassionally people find that problems with 3D acceleration appear and disappear as they switch between Linux kernel versions. (This has particularly been seen in the 2.6.x kernel series.) While aggressive switching of kernel versions is not a process for the faint of heart, if you have upgraded your kernel recently but have not upgraded XFree86, and are finding that X has "suddenly broken" despite not being upgraded, you're most likely dealing with a Linux kernel problem. Try downgrading your Linux kernel to the version you were using before to confirm the fact; if you can confirm it, file a bug against kernel and report your findings.

  5. If the problem does not appear to be Linux-kernel-related (or you can't determine this one way or the other), the problem is not reproducible with DRI disabled, and:
    • you have the xlibmesa-dri package installed, then file your bug report against xlibmesa-dri.

    • you don't have the xlibmesa-dri package installed, then file your bug report against xserver-xfree86.