Debian X Window System Frequently Asked Questions

[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 and License

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

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

As with many similar documents, this FAQ uses visual markup to indicate words used in particular contexts. Unfortunately, much of this markup is lost in plain-text or non-visual representations. Nevertheless, the author thinks it is important to have a plain-text version of this FAQ available, for in the event that the graphical browsers available to the user can only be run in the X environment, and the user is having trouble configuring the X environment, he or she would otherwise be presented with a catch-22 when turning to this FAQ for help.

If you are reading the plain-text version of this FAQ and have access to a computer with a graphical Web browser (or, at least, a browser capable of sophisticated text rendering, using different colors and typefaces within an XHTML document), please consult the XHTML version instead. On Debian systems with the xfree86-common package installed, you can find this FAQ at file:///usr/share/doc/xfree86-common/FAQ.xhtml.

The most up-to-date copy of this FAQ is maintained in the Subversion repository where the Debian xfree86 source package is maintained.

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

concept

representation

examples

keyboard input

gray background

CTRL-ALT-BACKSPACE, apt-get install x-window-system

command name

olive text

xdpyinfo, xterm

file specification

purple text

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

Debian package name

blue-green text

xserver-xfree86, xterm

manual page

underlined text

man(1), xterm(1x)

other literal (e.g., mailing list)

dark red text

debian-legal, debian-user

I welcome suggestions for improving the utility and accessibility of this document; the best way to communicate this is by filing a wishlist-severity bug report against the xfree86-common package. I recommend the reportbug command from the Debian package of the same name for all bug reports.

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 is the status of Xgl in Debian?

Xgl has not yet been released upstream, and is depending on bleeding edge versions of other libraries, and thus, is not yet suitable for packaging in debian.

See http://lists.debian.org/debian-x/2006/04/msg02216.html for more details.

What are X servers and X clients?

This is the most important, and probably the first, concept a newcomer to the X Window System should learn.

X achieves its success by separating the details of display and input hardware from the programs that use them. When a program that uses the X Window System needs to, for instance, draw on the screen, or know what keys on the keyboard have just been pressed, it does not communicate directly with the hardware. Instead, it communicates with a single program, called the X server, whose job it is to deal with a computer's video card (and thus monitor), keyboard, and mouse (or other pointing device). The programs, then, that wish to use the windowing system to interact with the user are thus called X clients. The program that actually "delivers the goods", both to the user in the form of displayed graphics, and to the program in the form of information about pressed keys or a moving mouse, is the X server.

Commonly, an individual machine like a workstation or X terminal, only runs one X server, to which many X clients "connect" and perform their tasks. In fact, however, on a Linux machine, more than one X server can be running at one time.

Why is the X usage of "server" and "client" backwards from everyone else's?

People who have worked in LAN-type environments are easily confused by the X notions of client and server. In such a scenario, one might have dozens of "client" machines, each running an X server which uses the network to connect to X clients (application programs) running on the "server" in the machine room.

However, X's client/server terminology makes perfect sense if one thinks about what resources are in demand, and what program's job it is to service requests. On the computer where a human being is actually sitting down and working, the resources in demand are the video display, keyboard, and mouse (or other pointing device). All of the running programs can't monopolize these resources at once, or we lose the benefits of multitasking that a windowing system gives us. Furthermore, why should each and every piece of software, like a mail reader, a clock application, and so forth, have to worry about things like how many buttons the mouse has, or how many colors the display can show at once? The X server centralizes this information and manages the hardware resources, which it serves to the X clients.

What is an X session?

An X session is the set of X clients running that correspond to a single server process, which typically corresponds to one user's login.

In other words, when I start X from the command line with startx, or if a display manager like xdm is running and presents me with a graphical login screen and I type my username and password, what happens next is my X session. People generally customize their X sessions to start a set of familiar, desirable applications, like a clock, a graphical "biff" program that tells them when they have new email, one or more terminal sessions on various other computers, and so forth. The X session is terminated by "killing" the X server. The X server may be killed by the 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.

What is a session manager?

Rather than having a static list of X clients to be launched each time the X Window System starts, as is often the case in a user's .xsession file, it is possible to have a special X client run whose job it is to keep track of the other X clients, and "remember" the state of these programs between X sessions. Needless to say, an X client has to support the saving of its state between sessions, because when the X server dies, the clients that are connected to it die as well. When a session manager is run with X clients that support session management, a user can end his X session, and when he next starts it, he will be greeted with a screen that looks just the one he had when he left windows in the same locations, applications with the same files open, etc.

What is window focus?

The keyboard can only be used to "type into" one X client at a time. The mouse is used to determine which client has "focus", or receives keyboard events. There are two major kinds of focus: "pointer" and "explicit".

Pointer focus, also known as "focus-follows-mouse", means that wherever the mouse cursor is, that window has focus. Explicit focus, or "click-to-type", means that a mouse button (usually the first, or leftmost on a right-handed mouse) must be clicked on a window with the mouse pointer over it for focus to change to that window.

The focus policies available are determined by the window manager. Traditionally, pointer focus, or something very similar, is used in the X Window System but there is no reason explicit focus cannot be used, and X clients work equally well with either focus policy.

What are X resources?

X clients are typically customizable in their appearance and behavior in a very large number of ways. It would be very cumbersome to require X clients to be called with command-line arguments specifying each of the configurable parameters. Therefore, the X server maintains a database of X resources. When an X client connects to an X server, it inherits a set of properties from the X server that correspond to it.

The strength of X resources is at the same time what makes them intimidating; they are hierarchical and can be as general or as specific as is desired. Almost all X clients, for example, recognize resources called "foreground" and "background", and if the X server contains an appropriately general resource for these properties, every X client that recognizes them will use them.

Much more remains to be written about this question.

What are app-defaults?

Application defaults files ("app-defaults") are essentially a way of externalizing an X client's configurable parameters' defaults outside the client binary, so that they can be changed without recompiling the client.

App-defaults files are mostly, but not exclusively, used by X clients written using the Xt (X Toolkit Intrinsics) library. On Debian systems they can be found in /etc/X11/app-defaults (or a localized subdirectory of /etc/X11).

App-defaults are specified using a class/instance syntax and look very similar to X resource files (see 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. The file /usr/share/doc/x11-common/examples/xsession is an example file that may be used directly and contains a great deal of explicit instruction on customization.

Note that the system administrator can configure the X Window System such that users' .xsession files in their $HOME directories are ignored. See the Xsession.options(5) manual page for more information.

How do I change what appears in the root window?

There are many X clients that can draw on the root window. xsetroot, which comes with the basic X distribution, is one. It is found in the xbase-clients package, and can be used to set the root window to a solid color, a plaid pattern in two colors, or tile it with a monochrome bitmap.

What is the difference between "bits-per-pixel" and "color depth"?

Color depth refers to the number of bits available to each pixel for representation of distinct colors. Each pixel on the screen has a value which is translated to a color. The wider the range of possible values, the larger the variety of colors available to each pixel, and thus the whole screen.

(The specifics of how a pixel value is translated to a color are determined by the "visual", a concept not explained in this FAQ.)

For instance, at 1 bit of color depth, only a monochrome display is possible. (A bit can only be zero or one; therefore each pixel is either "off" or "on".) With 4 bits of color depth, 16 colors are available (two to the fourth power is sixteen.) With 24 bits of color depth, 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