The X Window System

Synopsis #

The X Window System (X11) provides OpenBSD’s graphical interface and is installed through base-system file sets. Start sessions with xenodm(1) or startx(1), then configure the desktop, fonts, input devices, and monitors. See drm(4) and wscons(4) for hardware support. The sections below also cover 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, use the matching release installer to add the missing X sets, following Installing OpenBSD . They are base sets, not packages; pkg_info does not inventory them, and pkg_add xorg-server is not the installation method.

After installation, binaries reside in /usr/X11R6 and configuration files under /etc/X11. X normally detects supported hardware without a generated xorg.conf. Start with the default configuration and inspect the X server log before adding overrides. See the OpenBSD X Window System FAQ .

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):

doas rcctl enable xenodm
doas 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, the system xinitrc starts xclock(1), xconsole(1), xterm(1), and twm(1).

Prefer xenodm for normal use. Do not grant broad device access to work around a failing startx session.

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 use xterm when the i3 executable is not installed:

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 includes cwm(1), fvwm(1), and twm(1) in the base X sets. The default depends on how the session is started. When xenodm(1) starts a session and no non-empty .xsession exists, /etc/X11/xenodm/Xsession starts xterm(1) and then fvwm(1). The standard startx(1) session starts twm(1) when no .xinitrc exists. Additional environments can be installed from packages.

To install and configure popular options:

XFCE:

doas pkg_add xfce
echo "exec startxfce4" > ~/.xsession

GNOME:

doas pkg_add gnome
doas rcctl enable messagebus gdm
doas rcctl start messagebus
  # Disable and stop the previous display manager before starting GDM
doas rcctl start gdm

KDE:

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

Other window managers included in the base X sets are cwm and twm. Package alternatives include 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 can be installed:

doas pkg_add slim
doas rcctl enable slim
doas rcctl start slim

Disable any other active display manager before enabling another:

doas rcctl disable xenodm
doas rcctl stop xenodm

GDM is used for GNOME; follow its installed package README. SDDM is not present in the OpenBSD 8.0 amd64 package set.

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:

doas pkg_add font-awesome cantarell-fonts
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 inteldrm(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.

Driver availability depends on the architecture and X sets. There is no packaged Nouveau driver providing NVIDIA acceleration in this release.

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:

doas 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

Example output:

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 gives remote X clients trusted access to the display, bypassing X11 SECURITY extension restrictions 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:

startx /usr/X11R6/bin/xterm

For display manager issues:

cat /var/log/xenodm.log

Ensure only one display manager is enabled:

doas rcctl disable slim
doas rcctl enable xenodm

There is no default video group to add users to. Use xenodm and inspect driver and firmware messages when device initialization fails.

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