Skip to content

106.1 Install and configure X11

Weight: 2

Candidates should be able to install and configure X11.

Objectives

  • Understanding of the X11 architecture.
  • Basic understanding and knowledge of the X Window configuration file.
  • Overwrite specific aspects of Xorg configuration, such as keyboard layout.
  • Understand the components of desktop environments, such as display managers and window managers.
  • Manage access to the X server and display applications on remote X servers.
  • Awareness of Wayland.

Terms

/etc/X11/xorg.conf, /etc/X11/xorg.conf.d/, ~/.xsession-errors, xhost, xauth, DISPLAY, X

The graphical stack

Many people prefer a graphical user interface (GUI): icons, windows, folders and a mouse. On Linux this is built, like many things in Unix, from layers, each doing one job well:

   applications                   xterm, firefox, a game
          |
   desktop environment            GNOME, KDE, Xfce (panels, menus, settings)
   window manager                 draws window frames, moves and resizes them
          |
   display server                 X (Xorg) or Wayland
          |
   Linux kernel + drivers
          |
   hardware                       monitor, graphics card, keyboard, mouse

The display server is the key part. It takes the drawing requests of the programs (even over the network) and turns them into something the kernel and its drivers understand. It also handles the input from the keyboard, mouse and touchpad. There are two main display servers on Linux: the old X and the modern Wayland. This objective is mostly about X.

X, X11 and Xorg

The X Window System (or just X) has been the standard window system of Unix and Unix-like systems since the 1980s. It runs on Linux, the BSDs, Solaris, and there are versions for macOS and Windows. Its predecessor was called W, so the next one got the next letter.

The names can be confusing:

Name What it is
X the whole family of protocols that describe how a client (application) and the display server talk
X11 version 11 of the X protocol, the one used today
Xorg the X.Org Foundation's free implementation of the X server, the one on Linux. It followed the older XFree86. On many systems the command X is just a link to Xorg

X only provides the mechanism to draw shapes and windows. How things look is decided by each application, a window manager, or a full desktop environment (see 106.2).

The X client/server model

X is split into a client and a server:

  • The X server runs on the machine with the screen, keyboard and mouse, the one in front of you. It draws on the screen and reads the input devices.
  • The X clients are the applications: a terminal, a browser, a game. Each client tells the X server where its window is and how big, and what to draw inside it.

Usually both are on the same computer. But X is network transparent: clients on other computers can send drawing requests to your X server over the network. So you can use a graphical program that is installed only on a remote machine, with its windows shown on your screen.

   machine A (you)                                machine B (remote)
  +---------------------------+                  +----------------------+
  | X server                  | <-- X protocol --| X client: xeyes      |
  | screen, keyboard, mouse   |                  +----------------------+
  | local clients: xterm      |
  +---------------------------+

X is modular. New features were added as extensions, so the core X11 protocol stayed the same. The extensions live in Xorg libraries such as libX11, libXrandr, libXcursor and libxkbfile.

A display manager (like GDM, SDDM or LightDM) shows the graphical login screen. After you log in, it starts an X session for you and keeps the X server running. More on it in 106.2.

Seen from the X side alone:

   application (X client)          e.g. xterm, firefox
          |  X protocol (can cross the network)
   display server (X / Xorg)       draws pixels, reads keyboard/mouse
          |
   kernel + drivers
          |
   hardware (monitor, GPU, input)

The DISPLAY variable

Every running X server has a display name, in the form host:display.screen, or in full:

hostname:displaynumber.screennumber
Part Meaning
hostname the machine that shows the application. Empty means the local machine
displaynumber which X server session. The first one is 0
screennumber which screen of that display. Default 0. Left out (with its dot) when there is only one logical screen

The display name of your session is in the DISPLAY environment variable. Graphical programs read it to know where to draw:

$ echo $DISPLAY
:0

:0 means: local machine (nothing before the colon), first X session, one logical screen.

With two monitors you have two choices. If they are set up as one screen, windows move freely between them, and it is still :0. If each monitor is an independent screen, they are :0.0 and :0.1: they share the keyboard and mouse, but a window cannot move from one screen to the other. To start a program on the second screen:

$ DISPLAY=:0.1 firefox &

/etc/X11/xorg.conf

This was the main configuration file of X. Today Xorg configures itself when it starts, so the file may not exist at all. If a section is missing, the X server uses default values.

To create one, run Xorg -configure. It writes xorg.conf.new in the current directory, based on the hardware and drivers it finds. Then move it into place:

$ sudo Xorg -configure
$ sudo Xorg :1 -configure                       # if an X session is already running on :0
$ sudo mv xorg.conf.new /etc/X11/xorg.conf

The file is made of sections. Each starts with Section "Name" and ends with EndSection. Every device gets an Identifier (a name), so other sections can refer to it:

Section Describes
Files paths X needs, like FontPath (where the fonts are)
Module extra modules to load, for example glx for 3D graphics
InputDevice one specific keyboard, mouse or touchpad
InputClass a whole class of devices, like "all keyboards". Usually in a file under /etc/X11/xorg.conf.d/
Monitor the physical monitor and where it is connected
Device the graphics card: its driver (kernel module) and its location on the board (BusID)
Screen ties a Device and a Monitor together, with color depth and resolutions
ServerLayout groups the screens and input devices into one X setup

An example, shortened:

Section "Files"
    FontPath    "/usr/share/X11/fonts/misc"
    FontPath    "/usr/share/X11/fonts/Type1"
EndSection

Section "Module"
    Load        "glx"
EndSection

Section "InputDevice"
    Identifier  "Generic Keyboard"
    Driver      "kbd"
    Option      "XkbModel"  "pc105"
    Option      "XkbLayout" "us"
EndSection

Section "InputDevice"
    Identifier  "Configured Mouse"
    Driver      "mouse"
    Option      "Device"    "/dev/input/mice"
EndSection

Section "Monitor"
    Identifier  "DP2"
    Option      "Primary"   "true"
EndSection

Section "Device"
    Identifier  "Device0"
    Driver      "i915"
    BusID       "PCI:0:2:0"
EndSection

Section "Screen"
    Identifier   "Screen0"
    Device       "Device0"
    Monitor      "DP2"
    DefaultDepth 24
    SubSection "Display"
        Depth    24
        Modes    "1024x768"
    EndSubSection
EndSection

Section "ServerLayout"
    Identifier   "Layout-1"
    Screen       "Screen0"
    InputDevice  "Generic Keyboard" "CoreKeyboard"
    InputDevice  "Configured Mouse" "CorePointer"
EndSection

Look how Screen uses the names Device0 and DP2, and ServerLayout uses Screen0 and the input devices. The vesa driver is a simple, low resolution driver that almost always works, so it is useful for troubleshooting a graphics card. A general understanding of these sections is enough for the exam.

A shorter example with an older graphics card:

$ Xorg -configure        # writes xorg.conf.new, then move it to /etc/X11/xorg.conf

Section "InputDevice"
    Identifier  "Generic Keyboard"
    Driver      "kbd"
    Option      "XkbModel"   "pc105"
    Option      "XkbLayout"  "us"
EndSection

Section "Device"            # the graphics card: driver, bus id, options
    Identifier  "Card0"
    Driver      "radeon"
EndSection

Section "Monitor"
    Identifier  "Generic Monitor"
EndSection

Section "Screen"            # ties a Device to a Monitor, sets depth and modes
    Identifier   "Screen0"
    Device       "Card0"
    Monitor      "Generic Monitor"
    DefaultDepth 24
EndSection

Section "ServerLayout"      # glues the screen and input devices together
    Identifier   "DefaultLayout"
    Screen       "Screen0"
    InputDevice  "Generic Keyboard"
EndSection

You rarely write one by hand now.

/etc/X11/xorg.conf.d/

If you edit a vendor's configuration file and then update the system, either your changes or the vendor's new version get lost. Both are bad. The solution, used by many programs, is a .conf.d directory: the vendor's main file stays untouched, and your local settings go into small separate files in the directory.

X works this way too:

Location Who uses it
/etc/X11/xorg.conf.d/ your local configuration files
/usr/share/X11/xorg.conf.d/ configuration files provided by the distribution
/etc/X11/xorg.conf the old single file, if it exists. The files in /etc/X11/xorg.conf.d/ are read before it

Changing the keyboard layout

This is the classic example of overriding one part of the Xorg configuration. The file /etc/X11/xorg.conf.d/00-keyboard.conf uses an InputClass section, so it applies to every keyboard:

Section "InputClass"
    Identifier      "system-keyboard"
    MatchIsKeyboard "on"
    Option          "XkbLayout" "us"
    Option          "XkbModel"  "pc105"
EndSection
  • XkbLayout is the layout of the keys: language, QWERTY or Dvorak, and so on. For example fr, or gr(polytonic) for Greek polytonic.
  • XkbModel is the type of keyboard, like pc105 or chromebook.

To set a French layout system-wide:

# /etc/X11/xorg.conf.d/00-keyboard.conf
Section "InputClass"
    Identifier  "system-keyboard"
    MatchIsKeyboard "on"
    Option      "XkbLayout" "fr"
EndSection

man xkeyboard-config lists all models and layouts, and the layout files are in /usr/share/X11/xkb.

Two other ways to change the layout:

$ setxkbmap -model chromebook -layout "gr(polytonic)"                # only for this X session
$ localectl --no-convert set-x11-keymap "gr(polytonic)" chromebook   # permanent

setxkbmap uses the X Keyboard Extension (XKB), and its change is lost when the X session ends. localectl (systemd) writes the 00-keyboard.conf file for you, and --no-convert stops it from also changing the text console keymap.

xdpyinfo

xdpyinfo shows information about the running X server: the display name (same as DISPLAY), the version, the extensions in use, and the screen details:

$ xdpyinfo
name of display:    :0
version number:    11.0
vendor string:    The X.Org Foundation
X.Org version: 1.20.4
...
number of extensions:    25
    BIG-REQUESTS
    Composite
    ...
    XKEYBOARD
...
screen #0:
  dimensions:    3840x1080 pixels (1016x286 millimeters)
  resolution:    96x96 dots per inch

~/.xsession-errors

If something goes wrong when X or your graphical session starts or runs, the errors are written to ~/.xsession-errors in your home directory. When the graphical login fails or a desktop program does not start, read this file first.

Remote X: xhost and DISPLAY

xhost controls which hosts may connect to your X server. Without options it shows the current state:

$ xhost
access control enabled, only authorized clients can connect
SI:localuser:nagato
$ xhost +                                       # everyone may connect (unsafe, only for tests)
access control disabled, clients can connect from any host
$ xhost -                                       # back to authorized clients only
access control enabled, only authorized clients can connect
$ xhost +192.168.42.85                          # allow one machine
192.168.42.85 being added to access control list
$ xhost
access control enabled, only authorized clients can connect
INET:192.168.42.85
SI:localuser:nagato

Now imagine this machine is 192.168.42.80 and we just allowed 192.168.42.85. On 192.168.42.85, point DISPLAY to the first machine and start a program:

$ export DISPLAY=192.168.42.80:0
$ xeyes                                         # the eyes appear on 192.168.42.80

In practice this often does not work, because most distributions configure X not to listen for remote connections, for security. The safe way to run remote graphical programs is SSH X11 forwarding (see 106.2 and 110.3).

xauth

xhost gives access by host. xauth gives access by a shared secret. X keeps a secret token (a "cookie") in the file ~/.Xauthority, and any client that knows this cookie may connect. xauth displays and edits this authorization information. Because it works per user instead of per machine, it is safer than xhost.

If X stops working for a user, one troubleshooting step is to delete ~/.Xauthority and restart X.

Wayland

X11 is very old and keeps working thanks to many patches. Wayland is the newer display protocol made to replace X, started in 2010, with work from current and former X.org developers. Many modern distributions use it by default and keep X11 as a fallback. It is lighter, has a smaller footprint, and is more secure and easier to maintain.

The big difference: in Wayland there is no server between the client and the kernel. Each client renders its own window (with its own code or a toolkit like GTK+ or Qt). The Wayland compositor handles the input devices, window management and composition: combining all rendered windows into the final picture on the screen.

  • GTK+ 3 and Qt 5 can render on both X and Wayland.
  • Programs that still need X run inside XWayland, a separate X server running as a Wayland client.
  • Wayland uses the WAYLAND_DISPLAY variable instead of DISPLAY. It does not exist on X systems:
$ echo $WAYLAND_DISPLAY
wayland-0

Summary

I think of the GUI as layers: hardware, kernel and drivers, a display server, then the display manager, window manager, desktop environment and applications. X (X11 is the protocol version, Xorg the implementation) is a network-transparent client/server system: the X server is the machine with the screen, keyboard and mouse in front of me, and the clients are the applications, which may run on another host and still draw on my display. DISPLAY holds the display name hostname:display.screen, so :0 is the first local display, DISPLAY=:0.1 starts a program on a second independent screen, and pointing DISPLAY at another server sends the window there. Xorg normally configures itself, but Xorg -configure writes xorg.conf.new for /etc/X11/xorg.conf, whose sections (Files, Module, InputDevice, InputClass, Monitor, Device, Screen, ServerLayout) refer to each other by Identifier. To change one thing I drop a small file into /etc/X11/xorg.conf.d/ and leave the vendor file alone, like 00-keyboard.conf with XkbLayout and XkbModel, which localectl set-x11-keymap can write for me, while setxkbmap changes the layout only for the session. I check the server with xdpyinfo and read ~/.xsession-errors when a session fails. For remote display, xhost allows hosts and xauth uses the secret cookie in ~/.Xauthority. Finally, Wayland is the modern, more secure replacement: no server in the middle, a compositor that combines the windows, XWayland for old X programs, and WAYLAND_DISPLAY instead of DISPLAY.