OpenBSD FAQ - The X Window System [FAQ Index]

Introduction to X

The X Window System (sometimes just called "X", other times, incorrectly called "X Windows") is the environment which provides graphics services to OpenBSD and other Unix-based systems. However, by itself, X provides very little: one also must have a window manager to present a user interface. Most of the "personality" one will feel from X will be due to the window manager, rather than X itself. OpenBSD ships with the cwm(1), fvwm(1) and twm(1) window managers, although you may wish to use any of the others that are in ports and packages. Search for "window manager" for a list of the many available options.

X is considered a "client-server" structured protocol, however the terminology is sometimes confusing. The computer with the graphics on the screen is the X server. The application which tells the X server what to put on its screen is the X client, even though it may be a much more powerful computer in a data center. This model can be used to have large, processor-intensive applications (X clients) running on a very powerful machine, using the X server running on a small, low power machine on your desk for their user interface.

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 a SPARC'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

Good news: In the vast majority of hardware in most platforms, X requires no configuration at all. It Just Works.

The details of manual X configuration varies 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.

Several platforms require the xf86(4) X aperture driver, which provides access to the memory and I/O ports of a VGA board and the PCI configuration registers required by the X servers. This driver must be enabled before it is used, either by answering "yes" to this question during install:

Do you expect to run the X window System [no]
or by changing the value of machdep.allowaperture to the appropriate non-zero value in /etc/sysctl.conf for your platform and rebooting the machine (this sysctl cannot be changed after boot has been completed for security reasons). There are security implications to this, so do not do this if you do not need it.

Starting X

There are two common ways to run X:

On Demand:

Log in to a console as normal, then run startx(1).

Boot directly into X:

This is done using xdm(1), the X Display Manager. xdm(1) is started as root, normally by rc(8), and presents a login prompt. Upon successful login, it starts an X session for that user. If or when that X session should be terminated (including by hitting CTRL-ALT-Backspace), xdm(1) will return, prompting the user to log in again. For this reason, do NOT attempt to start xdm(1) from /etc/rc.conf.local until you have verified X works as you wish, or your machine may become very difficult to manage! (worst case: boot single user, as if you lost your password, and edit out the xdm_flags line in your /etc/rc.conf.local file.)

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

X won't start, I get lots of error messages

A common cause for X problems is the machdep.allowaperture sysctl(8) setting. Since this defaults to being disabled on OpenBSD, this is a fairly likely cause of the problem.

You need to edit /etc/sysctl.conf and set machdep.allowaperture=2 (or 1, depending upon your platform). This will allow X to access the aperture driver, xf86(4), upon the next reboot. It can not be made available after boot. This can also be set during install if you answer "Y" when you are asked whether you expect to run the X Window System.

OpenBSD requires that the aperture driver be activated on amd64, i386, macppc and sparc64 platforms to control access to the video boards. Other platforms use a safer way to handle the video system, and do not need this (and do not have it in their kernel). If you do not anticipate using X on your system, it is recommended that you not enable the aperture driver.

For more information about configuring and using X on your platform, see the /usr/X11R6/README file on your installed system.

Customizing X

OpenBSD's default X environment is fully functional, but you may wish to customize it. You may wish to change the background pattern or color, or you may wish to change the window manager (the program that most defines your X environment), or change the applications that are started when X starts.

The default window manager in OpenBSD is fvwm(1). Fvwm is a good, general purpose window manager, but it is hardly your only choice; it isn't even the only window manager included with OpenBSD (see cwm(1) and twm(1)). A large number of window managers are also available through packages and ports.

Similar to the system startup script, X has a process it goes through to set up the user environment. More accurately, it has more than one process; which process is used depends on how you start X. Understanding how X starts will help you understand how to customize your work environment the way you wish it to be.

Note that you can customize the environment on both a system-wide and user level. It is probably best to do user level changes rather than to change the system defaults, as the user scripts are stored in the user's home directory, so you will have less merging of files to do when upgrading to a new version of OpenBSD.

startx(1) startup

startx(1) looks for the file .xinitrc in the user's home directory. .xinitrc is usually a shell script, which can start as many X "client" (applications that use X) programs as desired. When this script exits, the X server shuts down. Generally, most of the programs run by this script should run in the background, though the last one should run in the foreground (typically the window manager); when it exits, the script will exit, and X will be shutdown.

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 &
That will start the xconsole(1), which provides a copy of any text that the kernel would have sent to the console (which is now covered by the graphical screen), an analog clock, oclock(1), and sets the background to a solid grey background with xsetroot(1), all before invoking the cwm(1) window manager. Note that only the window manager is not "backgrounded" with an "&" character. This means that X will stay running until cwm(1) exits.

If a user's home directory does not have a .xinitrc file in it, the system's /etc/X11/xinit/xinitrc file is used. This file can provide you some additional ideas for your .xinitrc script.

xdm(1) startup

xdm(1) is usually started by the system startup scripts, but for testing purposes (recommended, until you know your have your X config right!), it can be run as root.

xdm(1) has a lot of other functionality that won't be touched on here, but for our purposes, xdm will present the user with a login screen, get and verify a user name and password, and then give the user their X environment. When X shuts down, either deliberately or accidentally, xdm will start it back up again. This is why you want to make sure X is configured properly before using xdm(1), and certainly before having xdm(1) start at boot. Otherwise, you may have some difficulty getting control of the machine.

When xdm(1) starts, it runs the /etc/X11/xdm/Xsession, which will check to see if the user has a .xsession file in their home directory. So, if you wish to change your default window manager, simply invoke it (and maybe other things) in .xsession. Again, any programs you want started with X (for example, maybe three xterms) can be placed here, but all should be backgrounded except for your window manager, as again, when that exits, your X session will be ended. In this case, xdm(1) will restart X and bring you back to a login screen.

Trying a new window manager

You can invoke a particular window manager when you load X without altering any defaults like this:
$ startx /usr/local/bin/fluxbox
Several window managers (including cwm(1) and fvwm(1)) offer the ability to change window managers on the fly, without restarting X or any of your applications. Your new window manager replaces your old one; exiting the newly-loaded window manager terminates X. It does not return you back to your previous window manager. fvwm(1) allows you to start a different window manager by left clicking on the background ("root window"), chose "(Re)Start" and then pick your preferred window manager. However, note that you will need to add your alternative window managers to your .fvwmrc file (the system-wide default is /usr/X11R6/lib/X11/fvwm/.fvwmrc). cwm(1) allows you to invoke another window manager by hitting Ctrl-Alt-w and typing in the manager you wish to switch to.

Once you have found a window manager you like, you can set it as the final program run by your startup scripts as described above.