OpenBSD FAQ - The X Window System [FAQ Index]

Introduction to X

The X Window System (sometimes just called "X") is the environment which provides graphics services to OpenBSD and other Unix-based systems. By itself, X provides very little, since one also must have a window manager to present a user interface. OpenBSD ships with the cwm(1), fvwm(1) and twm(1) window managers, although many others are available via ports and packages.

It is possible to run X clients on a system without any graphical support. For example, one could have an application (the X client) running on an ARM system, displaying its output on an amd64's graphical display (the X server). Since X is a well-defined, cross-platform protocol, it is even possible to have an X application running on (for example) a Linux machine use an OpenBSD machine for its display. The client and server can also be running on the same machine, and for most of this section, that will be the assumption.

Configuring X

For the majority of hardware on the most common platforms, X requires no configuration at all.

The details of manual X configuration vary considerably from platform to platform. In all cases, there will be instructions and other platform-specific information in /usr/X11R6/README on the installed system.

Starting X

There are two common ways to run X: by manually invoking the startx(1) command at a console, or via xdm(1).

If you didn't enable xdm at install time, you can do so like any other system daemon:

# rcctl enable xdm
On some platforms, you will need to disable the console getty(8) to use xdm. This is not needed on amd64, i386 or macppc.

Customizing X

OpenBSD's default X environment is fully functional, but you may wish to customize it.

The startx(1) command looks for a .xinitrc file in the user's home directory. This is usually a shell script, which can start as many programs as desired. Generally, most of the programs run by this script should run in the background, though the last one (typically the window manager) should run in the foreground. When it exits, the script will exit, and X will be shut down.

In the simplest case, this can be as little as just the name of the window manager you wish to invoke:

Or you can get a little more fancy:
xconsole -geometry -0+0 -fn 5x7 &
oclock -geometry 75x75-0-0 &
xsetroot -solid grey &
Note that only the window manager is not being run in the background. This means that X will stay running until it exits.

If a user's home directory does not have a .xinitrc file, the system's /etc/X11/xinit/xinitrc file is used. When xdm(1) starts, it runs /etc/X11/xdm/Xsession, which will check to see if the user has a .xsession configuration file in their home directory. If you wish to change your default window manager, simply invoke it in .xsession. Any programs you want started with X can be placed here, but all should be backgrounded except for your window manager again.