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.