X notes

From Helpful
(Redirected from X windowing)
Jump to: navigation, search
Linux-related notes
Linux user notes

Shell, admin, and both:

Shell - command line and bash notes · shell login - profiles and scripts ·· find and xargs and parallel · screen and tmux ·· Shell and process nitty gritty

Linux admin - disk and filesystem · Init systems and service management (upstart notes, systemd notes) · users and permissions · Debugging · security enhanced linux · health and statistics · kernel modules · YP notes · unsorted and muck

Logging and graphing - Logging · RRDtool and munin notes
Network admin - Firewalling and other packet stuff ·

Remote desktops
VNC notes
XDMCP notes

This article/section is a stub — probably a pile of half-sorted notes, is not well-checked so may have incorrect bits. (Feel free to ignore, fix, or tell me)

See also Remote X windows


The terminology can be a little confusing:

  • X clients are the programs; they connect to an X server and tell it how to draw themselves.
  • An X server is the thing that accepts and actually draws programs.
    • On linux this is Xorg (do some other unices still use XFree86?(verify))
    • On windows you can get an X server via Xming (free), cygwin (free), Exceed (?), WinaXe (?),
    • The *nix VNC server is an X server
  • An X display corresponds to a particular viewport, independent of others. Displays are uniquely referencable, and are the things X clients actually connect to.
  • display manager - the graphical thing with which you log in locally. Mostly just a program run by the way X is usually started.
  • window manager - the environment after you log in ()

DISPLAYs elsewhere

The X protocol is networked by nature, so you can display programs on other computers. The localhost-display target of :0 is actually an abbreviated use; the fuller form is hostname:displaynumber.screennumber;

  • hostname defaults to localhost if omitted (which on unices will often mean the use of unix sockets rather than IP). Note that a number of X extension only work on localhost. Particularly some of the fancy graphics details.
  • screennumber defaults to 0. This is there only for multi-monitor setups (because they share input devices). You can usually ignore this completely.

You can send programs elsewhere...

  • explicitly, like xclock -display, or
  • by have it read from the enviroment, e.g. after you did a export DISPLAY=

The latter tends to be rather more convenient.

X11, Xorg, Weyland, Mir

This article/section is a stub — probably a pile of half-sorted notes, is not well-checked so may have incorrect bits. (Feel free to ignore, fix, or tell me)

See also:

X authentication

This article/section is a stub — probably a pile of half-sorted notes, is not well-checked so may have incorrect bits. (Feel free to ignore, fix, or tell me)

(mostly interesting in the context of ssh, su, and perhaps local-network trickery)

Authentication can be done...

  • per host
    • ...more specifically every connection originating on a host
    • using
      , which sets policies for a running X server (a runtime thing)
    • simple
    • most parts are too coarse-grained to be good on multi-user systems - but look at SI:

  • via cookie
    • ...which are (randomly generated) shared secrets
    • using the MIT-MAGIC-COOKIE-1 or XDM-AUTHORIZATION-1 method/protocol, which both store a secret in ~/.Xauthority
    • In SSH, this is part of the connection setup
    • it's not hard to do manually (which can be useful in the presence of things like su and screen)
  • per user
    • using the SUN-DES-1 protocol (RPC-based) (stores only the principal in ~/.Xauthority), or
    • using the MIT-KERBEROS-5 protocol


This article/section is a stub — probably a pile of half-sorted notes, is not well-checked so may have incorrect bits. (Feel free to ignore, fix, or tell me)

xhost manages a list of entries that allow specific remote hosts to connect to us.

Half the time this is too coarse-grained (and overlaps with basic firewalling), but has its uses.

Entries are in the form
, where families are:
inet      IPv4 host  (name resolved to numeric address on add (verify), except for localhost (verify))
inet6     IPv6 host  (name resolved to numeric address on add)
krb       Kerberos V5 principal
local     domain sockets? (or loopback?)  (note: ignores name value)
nis       NIS network name
dnet      DECnet host
si        Server Interpreted


  • local means domain sockets, which are what gets used when DISPLAY looks like
  • localhost is a special case of inet(verify)
  • SI is an interesting one, because it allows extensions like (more details in Xsecurity):
  • xhost +
    means "disable all checking, regardless of what's on my list"
useful during debugging, e.g. when verifying whether it's e.g. your xhost settings or your firewall that's blocking things
but in general you never want to say "the entire world". Because you're counting on random firewalls to save your ass.

Show current list:


Add to list (default is +, so e.g. the first two are equivalent):

xhost +example.com
xhost example.com

xhost +local:
xhost +si:localuser:root

xhost +nis:john@
xhost +nis:unix.uid@domainname

Remove from list (match string from xhost list exactly):

xhost -example.com


  • some people suggest that local: take arguments, but this is ignored (just useful for your bookkeeping)


further notes

See also

Related warnings/errors

Warning: No xauth data; using fake authentication data for X11 forwarding

"MIT-MAGIC-COOKIE-1 data did not match"

"MIT-MAGIC-COOKIE-1 data did not match" usually means you've SSH'd in, then switched to another user (e.g. with su).

The technical reason is that the authorization it negotiated earlier is in the account you logged into, not the one you've switched to now.

If you can, consider SSHing to to that other user directly.

There are frequently reasons you can't, e.g. it's a passwordless account.

A workaround is to get the secret and put it in the new account, for example:

# before the su, find out the display that applies, and the cookie that belongs to it:
user@somehost $ echo $DISPLAY
user@host $ xauth list | grep 10
somehost/unix:10  MIT-MAGIC-COOKIE-1  50bffebd529039b0578209c48520f0ff
# now switch user and tell it the secret
$ su - otheruser
otheruser@host $ xauth add somehost/unix:10 MIT-MAGIC-COOKIE-1 50bffebd529039b0578209c48520f0ff


...which tries to list the specific applicable cookie, but in a way that may not always work

X startup and config

Startup scripts

This article/section is a stub — probably a pile of half-sorted notes, is not well-checked so may have incorrect bits. (Feel free to ignore, fix, or tell me)

(i.e. executed)

system and user xsession

details to specific display managers and window managers

Startup config files

(i.e. Parsed, not executed)

X keyboard

Unfortunately, there are like five people in the world who understand the X keyboard model--I'm not one of them--and three are insane. It's that bad. -- Tim Showalter


What your keyboard sends over its wire are (varying-sized) keycodes. Very usually, these cannot be changed at all.

Any particular keyboard may have more, fewer, and different keys than any other specific keyboard. Consider special alphabetic characters on region-specific keyboards, multimedia keys, a laptop's Fn, and more.

The way keys map to keycodes may vary between keyboards. Sometimes these details conflict somewhat, which is why you have to tell your computer about your keyboard if you have something regional or otherwise special.

(Side note: KeyCap refers to what is physically printed on the key. It's present in X keyboard configuration seemingly purely to be able to present a visual version of the keyboard (configuration) and for 'you are now pressing this' testing.).

KeySym and modifiers

Since each key has a single keycode, but those can differ between keyboards.

Also remember that most keys have more than one function. For example, on the US keyboard, comma and less-than are on the same physical key, but this isn't always the case.

Your computer has to decide what each keycode actually means for the keyboard in use, and what happens with which modifiers (Shift, Fn).

This is something every OS deals with, and 90% of it is you telling it what keyboard layout you have.

In X:

KeySyms are (usually well-named) things with an atomic meaning, such as a comma, less-than sign, small p, capital P, and so on.

For each unique keyboard type, you want to specify a map from KeyCodes to a (single) KeySym.

This is where things start less than intuitive, because most everyone thinks of keyboards in a very functional way, the most minimal, habitual way. However, a mental step back is required as keys and meanings are not actually so directly linked.

Consider that we are quite used to keys having multiple meanings: using shift to get a
, or a small p and capital P, out of the same key. On the keyboard interpretation side of things, you probably want to model the difference between alphabetic versus nonalphabetic keys: consider how you expect (Caps) Lock to only have effect on alphabetic keys, while Shift has effect on all keys that have a second meaning (which is almost all keys).

This is also where modifiers get involved.

Modifier intro

Modifiers deserve special mention, because they end up being much of the practical complexity in the X keyboard model.

There are three modifiers with pre-set semantics: Shift, Lock, and Control.

There are also five modifiers without explicit meaning: Mod1 through Mod5 (for, if you care about the internals, a total of eight modifier bits).

Note that most keyboards have a Shift and a Caps Lock, most have a Control, and keys such as Option, Apple, Windows, Amiga - and to some degree Alt - don't have pre-set meaning. (...and actually, there exists a Shift Lock, which behaves differently from Caps Lock -- consider how caps lock doesn't get < from the , key -- but I'm going to ignore it completely).

While Shift as a modifier has special status to the interpretation on the computer side, Shift as the key you can touch is nothing special on the hardware level, it sends (and repeats) a keycode like any other. If you wanted you could switch the meaning of your shift key and the letter u. If you're weird, that is.

Shift, Alt and such need to be mapped just like any other key, but (almost always) get special treatment because they are (almost always) treated as modifiers. In the case of Shift, you need map it to both the Shift modifier, and to a particular KeySym, like Shift_L or Shift_R.

Shift and Lock, and their involvement in KeySym entries

The X keyboard model designers decided that the Shift/Lock behaviour is important and usual enough to model directly. For this reason, KeySym entries can consist of multiple values, which define the alternatives, if any, you get when you use (only) the Shift or Lock modifier.

You map to an array of four KeySyms, seen as two groups with two entries each (Actually eight, in four pairs, but Group 3 and 4 are rarely used, and even group 2 isn't necessarily used), and you can use shorthands when declaring the KeySym array:

"K1"         means/expands to   "K1 NoSymbol K1 NoSymbol"
"K1 K2"      means/expands to   "K1 K2 K1 K2"
"K1 K2 K3"   means/expands to   "K1 K2 K3 NoSymbol"

This shorthand is followed up by more expansion to ease work for alphabetic keys: if a group's second entry is NoSymbol, and the first entry is alphabetic, then the first and second entry should be the lowercase and uppercase form of that character (respectively). If the first isn't alphabetic, both entries mean the same thing.

Now, when you actually use a key, you use one of the two entries (in the current group) based on the Lock and Shift modifiers:

No shift, no lock: first entry


Shift:             second entry

                   (Shift-pP, Shift--_)

Lock:              if second entry is alphabetic: second entry, otherwise the first entry

                   (Lock-pP, Lock---)

Shift+Caps:        If second entry is alphabetic: first entry, otherwise the second       

                   (Shift-Lock-pp, Shift-Lock--_)

(The rules are different if you have a Shift Lock key rather than a Caps Lock. I'm still ignoring that)

Groups and Mode_switch

The groups can be switched between using something that is mapped to KeySym Mode_switch. It effectively works as a second shift, meaning each key could have four different meanings (though often three in practice). Regional keyboards and laptops have a key to an effect like this, like AltGr or Fn.

You could get creative with this. You could, for example, add a non-latin alphabet, and map caps lock away from Lock (few people like or use their caps lock) and instead map it to Mod_switch, meaning it's now the key that accesses that 'second keyboard' -- or just use this to make CapsLock-E, CapsLock-5, or CapsLock-2 produce a Euro sign (usually printed on one of those keys). Or heck, you could make Mod_switch produce Phonetic characters or ROT13 text. Or Al-Bhed, if you're that muck of a geek anyway:)

Note, however, that special input is often more flexible, and more portable to other computers, if you use software to do this, such as UIM or SCIM, instead of redefining your keyboard map.

Multi_key (a.k.a Compose)

Multi_key, not to be confused with Switch_mode, allows you to compose a character from several others.

If you

  • map something (say, the right Menu key, or Caps Lock) to Multi_key,
  • define compositions that you want

...you can use, for example, Compose'a to produce á.

More modifiers details

As mentioned, the X model focuses quite a bit on modifiers. Shift and Lock are already explained.

Mod[1-5] are used to map Alt, Super (often the Windows key), Menu, Hyper (?) and such. Mod bits are not always mapped the same way.

If you use KDE or GNOME (possibly others) there is often a keyboard configuration application.

Alt_L and Alt_R and Meta (which is not the same as Alt - a few keyboards have both) are regularly mapped onto Mod1. Applications shouldn't assume this, but some do. For example, emacs does, and calls it Meta(verify), though they should technically check this with the X modifier map (run
to see yours).


Repeating seems to be per-key behaviour at X-level (maybe because it is filtered?), but often is not handled as reported(verify). -->

See also

Multiple X screens, xrandr

This hasn't been updated for a while, so could be outdated (particularly if it's about something that evolves constantly, such as software).

Multiple monitors - different methods


The same on all outputs. Generally useless, other than in specific situations (e.g. monitor+projector combinations).

Separate X instances

Separate in terms of input, rendering surfaces, and whatnot.

Now regularly used for multi-user login.

Multiple X screens

X itself supports running multiple separate displays in the same X instance. Separate in terms of rendering targets. For example, windows cannot appear half on one, half on another.

Window managers usually treat these as completely separate too. You can move the mouse back and forth, so if you don't mind the separation, this may serve your needs.

Not so commonly used.

(Merged rendering)

There are a few different implementations of the idea of gluing different configured physical screens into one logical X screen. The fact that it will end up rendered on multiple physical things may be transparent to most of X.


  • Xinerama is the open version
  • MergedFB is technically better but not as supported
  • TwinView is nVidia's implementation
  • Big Desktop is ATI's name


An extension of X, and transparent to drivers, so this option may work the most setups. It is in some ways a simple-and-stupid hack, however (it e.g. duplicates resources to get around the fact that X Core has resources per screen).

Usual implications:

  • hardware 3D and/or video overlays may work only on one screen (at all, or at a time)
  • You cannot rotate parts of a xinerama setup - XRanrR is disabled when xinerama is enabled. May be supported in future versions. (written when?(verify))
  • You cannot change the configuration on the fly, or even easily base it on detection, which matters in some situations, such as when you use an external screen on a laptop.


Similar idea to Xinerama, better implementation: supports 3D on all heads, supports XRandR(verify).

However, the driver has to specifically support it. A number of open drivers have relatively experimental support, some usable. Commercial nVidia and ATI drivers do not ((verify)).


Needs binary nVidia driver.

Supports XRandR (verify)

Big Desktop

Needs binary ATI driver(verify).

Supports XRandR (verify)



XRandR, a.k.a RandR

The X Resize and Rotate Extension (a.k.a. X RandR, XRandR, RandR) allows resolution changes on-the-fly, and also rotation assuming your setup supports it.


To double-check whether X is loading it, check the X log:

grep -i randr /var/log/X*.log

You'ld see something like:

(==) RandR enabled
(II) Initializing built-in extension RANDR

or even

(II) intel(0): RandR 1.2 enabled, ignore the following RandR disabled message.
(--) RandR disabled
(II) Initializing built-in extension RANDR


xrandr is the command line interface to the RandR extension.

capability query

Without any options it will report what it can do. To query separate displays (e.g. on a dual-monitor setup):

xrandr -q

...and for specific displays, which is useful on multi-head monitors set up with different dispalys:

xrandr -q -d :0.0
xrandr -q -d :0.1

resolution change

You can change the resolution on-the-fly by specifying one of the numbers (if you do this automatically from some script, you could specify a specific resolution if you want that script to be portable between setups)

xrandr -q 1 


When you do a query, you will see the relevant options below the list of resolutions, something like:

Rotations possible - normal
Reflections possible - none

This particular output mens that reflection is not supported, and that there is only one rotation, 'normal' - in other words, that rotation is not supported. There seem to be various reasons, including:

  • the card does not support it
  • the driver does not support it
  • the current X config does not support it:
    • the combination of X extensions does not allow it (verify) (Which? XV? Xcomposite?)

TODO: Look at the effects of TwinView and xinerama. Do both imply you can't?


This article/section is a stub — probably a pile of half-sorted notes, is not well-checked so may have incorrect bits. (Feel free to ignore, fix, or tell me)


This article/section is a stub — probably a pile of half-sorted notes, is not well-checked so may have incorrect bits. (Feel free to ignore, fix, or tell me)


MergeFB Clone


Maximum number of clients reached