The X Window System

The X Window System

Synopsis #

The X Window System (commonly known as X11) provides the graphical user interface framework used on OpenBSD. It supports a wide range of graphics hardware, input devices, and window managers. X11 is integrated into the base system through specific file sets. This chapter covers the installation, configuration, and operation of X, including session management with xenodm(1) and startx(1), user session setup, desktop environments, font and input configuration, hardware support via drm(4) and wscons(4), multiple monitor setups, remote X access, and troubleshooting.

Installation and Configuration of X #

During installation, the OpenBSD installer prompts for file set selection. To use X, the following sets must be included: xbase, xshare, xfont, and xserv. These provide the core binaries, shared resources, fonts, and X server respectively. If omitted, the graphical environment must be added manually using sysupgrade(8) or by extracting sets from installation media. Note that sysupgrade requires either a network connection or access to mounted installation sets.

To verify if these sets are present:

$ pkg_info | grep xbase

If X was not installed, alternatively install Xorg components via packages:

# pkg_add xorg-server xorg-fonts xorg-apps xrandr

This includes the X server, common fonts, and core utilities such as xterm.

After installation, binaries reside in /usr/X11R6, and configuration files are located under /etc/X11. X usually autoconfigures hardware using drm(4) and wscons(4). Manual configuration is rarely required.

To generate and test a configuration manually:

$ X -configure
$ X -config ~/xorg.conf.new

If successful, install it:

# mv ~/xorg.conf.new /etc/X11/xorg.conf

Platform-specific notes may be found in /usr/X11R6/README.

Graphical Session Management #

OpenBSD supports two primary ways to start X: via xenodm(1) or manually using startx(1).

To use the display manager xenodm(1):

# rcctl enable xenodm
# rcctl start xenodm

This enables a graphical login on boot. Sessions are launched based on the user’s .xsession file. Custom appearance and login behavior can be configured under /etc/X11/xenodm/.

To use startx(1), login on a virtual terminal and run:

$ startx

This invokes .xinitrc in the user’s home directory. If it does not exist, xterm is started by default.

Note: For permission-related issues with startx, see the Troubleshooting section for details on group membership and device access.

User Session Configuration #

Create .xinitrc or .xsession in the user’s home directory to launch a window manager or desktop environment.

Example .xinitrc for cwm(1):

export ENV=$HOME/.kshrc
xsetroot -solid steelblue
exec cwm

Example .xsession for xfce:

exec startxfce4

To avoid breaking graphical sessions, back up existing .xinitrc or .xsession files before editing:

$ cp ~/.xinitrc ~/.xinitrc.bak

To implement a fallback in case the primary window manager fails:

if command -v i3 >/dev/null 2>&1; then
    exec i3
else
    exec xterm
fi

.xinitrc is used by startx(1); .xsession is used by xenodm(1).

Desktop Environments and Window Managers #

OpenBSD ships with ctwm(1) as the default window manager. Additional environments can be installed from packages.

To install and configure popular options:

XFCE:

# pkg_add xfce
$ echo "exec startxfce4" > ~/.xsession

GNOME:

# pkg_add gnome
$ echo "exec gnome-session" > ~/.xsession

KDE:

# pkg_add kde-plasma
$ echo "exec startplasma-x11" > ~/.xsession

Lightweight alternatives include cwm, fvwm, fluxbox, and i3.

Refer to /usr/local/share/doc/pkg-readmes for post-installation notes. Some environments, such as GNOME and KDE, require additional services like D-Bus or polkit to function fully. On low-memory systems, heavier desktops may be impractical.

Display Manager Alternatives #

While xenodm is the default and is included in xbase, alternatives such as slim or sddm can be installed:

# pkg_add slim
# rcctl enable slim
# rcctl start slim

Disable any other active display manager before enabling another:

# rcctl disable xenodm

sddm is typically used with KDE Plasma and may require additional configuration for other environments. Compatibility with some hardware setups may vary.

Configuration files for these managers are typically found in /etc/ or /usr/local/share/examples/.

Fonts and Input Devices #

X uses fontconfig and fc-list(1) to query font availability.

To install fonts:

# pkg_add font-awesome font-cantarell
$ fc-cache -fv

Note: regenerating the font cache may take time on systems with many fonts.

To query or test input devices:

$ xinput list
$ xinput test <device-id>

Permanent input configuration can be placed in /etc/X11/xorg.conf.d/.

Example 10-keyboard.conf to disable Caps Lock:

Section "InputClass"
    Identifier "keyboard overrides"
    MatchIsKeyboard "on"
    Option "XkbOptions" "ctrl:nocaps"
EndSection

To remap keys at runtime:

$ setxkbmap -option ctrl:nocaps

Graphics Hardware Support #

Modern graphics are supported by the drm(4) subsystem, including amdgpu(4), radeondrm(4), and intel(4). These are loaded automatically when supported hardware is detected.

To verify driver status:

$ dmesg | grep drm

For framebuffer devices and console switching, OpenBSD uses the wscons(4) framework. The wsdisplay(4) driver provides VT switching and console rendering.

Older hardware may require legacy drivers such as xf86-video-vesa or xf86-video-nouveau, which can be installed from packages.

Note: Interpreting dmesg output may require familiarity with the driver names used by the kernel.

Using Multiple Monitors #

Use xrandr(1) to query and configure displays.

To list active outputs:

$ xrandr

To configure a secondary monitor to the right of the primary:

$ xrandr --output HDMI-1 --right-of eDP-1 --auto

To mirror outputs:

$ xrandr --output HDMI-1 --same-as eDP-1 --auto

To scale a HiDPI display:

$ xrandr --output eDP-1 --scale 1.5x1.5

Add persistent configuration to .xsession or .xinitrc.

To use a graphical tool for layout configuration:

# pkg_add arandr
$ arandr

Remote X11 Access #

Remote X sessions can be forwarded securely over SSH. Direct TCP access to X is strongly discouraged due to inherent security risks.

To enable secure X11 forwarding:

$ ssh -X user@host.example.org

Trusted forwarding for some legacy applications:

$ ssh -Y user@host.example.org

On the remote system, ensure /etc/ssh/sshd_config includes:

X11Forwarding yes

To verify forwarding:

$ echo $DISPLAY
localhost:10.0

Avoid the use of xhost +, which disables all access control and exposes the display to remote connections.

Disable TCP listening for X if not needed, for example in .xserverrc or in the display manager configuration:

exec X -nolisten tcp

Security Note: The -Y option disables access control checks and should be used only when necessary. X11 forwarding can be slow or unresponsive over high-latency connections.

For local network setups requiring direct access, configure xauth(1) and enforce strict firewall rules.

Troubleshooting #

If X fails to start, examine /var/log/Xorg.0.log:

$ grep EE /var/log/Xorg.0.log
$ grep WW /var/log/Xorg.0.log

Check for driver or device errors in the system log:

$ dmesg | grep drm

To test a minimal X environment:

$ X -retro &
$ xterm

For display manager issues:

$ cat /var/log/xenodm.log

Ensure only one display manager is enabled:

# rcctl disable slim
# rcctl enable xenodm

If using startx(1), verify the user is in the video group:

# usermod -G video youruser

For missing input devices, create a basic InputDevice section in xorg.conf:

Section "InputDevice"
    Identifier "Keyboard0"
    Driver "kbd"
EndSection

If the window manager or desktop fails to launch, fallback to xterm:

exec xterm

Verify that required drivers or firmware are installed and match the kernel. Incompatibilities between drivers and the running kernel may cause X to fail silently or exit with obscure errors.

Report a bug