[FAQ Index] [To Section 10 - System Management] [To Section 12 - Hardware and Platform-Specific Questions]

11 - The X Window System

Table of Contents

11.1 - 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 a free version of the fvwm(1) window manager, although you may wish to use any of the other window managers that are in packages. Search using a key of "window manager" for a list of the many window managers available.

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 directs 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 mvme88k, displaying its output on an alpha'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 Solaris 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.

11.1.1 - How much computer do I need to run X?

X itself is a pretty large program, a fast computer will be appreciated if you are starting it and stopping it regularly. However, once running, it performs pretty responsively on a very modest computer. To get responsive display performance on some platforms, even for just text, you will want to run X. These platforms, such as sparc and sparc64 were intended to be used with a graphical interface, and the text console performance is very poor.

That being said, the point of running X is usually to run X applications. Some X applications are very lean, others will seemingly take and use all the processor and RAM you can give them. Of course, some users just like to use X to provide a large number of xterm(1)s, which can be done on very modest hardware.

11.1.2 - Can I have any kind of graphics without X?

Assuming you won't accept ASCII graphics, that requires some kind of framebuffer console driver. Some operating systems provide this, but there is not currently one for OpenBSD, nor is there much interest among developers for one.

11.2 - Configuring X

The configuration of X varies considerably from platform to platform. In all cases, there will be instructions and other platform-specific information in /usr/X11R6/README in 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.

11.2.1 - alpha

/usr/X11R6/README for alpha.

Set machdep.allowaperture=1 in /etc/sysctl.conf.

The TGA and some VGA cards are supported. No further configuration should be needed.

11.2.2 - amd64

/usr/X11R6/README for amd64.

Set machdep.allowaperture=2 in /etc/sysctl.conf.

X on amd64 often auto-configures very successfully, so no further configuration is needed in many cases. If further configuration is needed, use the X -configure process below.

11.2.3 - armish

No X servers, only X clients.

11.2.4 - hp300

/usr/X11R6/README for hp300.

11.2.5 - hppa

No X server, only X clients.

11.2.6 - i386

/usr/X11R6/README for i386.

Set machdep.allowaperture=2 in /etc/sysctl.conf.

Due to the incredibly wide range of video cards, mice, keyboards, and other hardware, configuring an i386 system to run X can be exciting. Exciting enough that a separate section is provided.

Fortunately, things are not always as bad as they may seem -- in many cases, X "Just Works" by invoking "startx". In these cases, your hardware will be detected and queried for its abilities, and X will run very well.

11.2.7 - landisk

No X servers, only X clients.

11.2.8 - luna88k

No X servers, only X clients.

11.2.9 - mac68k

/usr/X11R6/README for mac68k.

Mac68k systems will "just work" with X, no configuration needed.

Mouse: The standard Macintosh mouse has only one button, which is a problem, as X assumes a three-button mouse. Some third party mice will give you a second button which will work with X. Failing that, see the Xmac68k(1) page for information on mouse button emulation.

11.2.10 - macppc

/usr/X11R6/README for macppc.

Set machdep.allowaperture=2 in /etc/sysctl.conf.

Supported Macintosh PPC systems can be run in one of two different ways: "accelerated" and "framebuffer" (unaccelerated).

In the "framebuffer" mode, the system will be running with 8 bits per pixel, and the video resolution is controlled by the Macintosh environment, so you will probably want to keep a small MacOS section on your disk to adjust these settings. This mode has the advantage of "Just Working", however it can be frustratingly inflexible (for example, altering resolution may require booting MacOS).

If your Macintosh has an ATI-based video system, it can run using an accelerated X server, which gives better performance and more control in the OpenBSD environment. The NVIDIA video cards in some macppc systems will also work in many cases. The README file has details on configuring the accelerated driver, start using the sample file there.

While the README file details using the standard Apple one-button mouse with X, unless you are using a laptop, it is highly recommended that you just buy a modern third-party USB mouse.

11.2.11 - mvme68k

No X servers, only X clients.

11.2.12 - mvme88k

No X servers, only X clients.

11.2.13 - sgi

No X servers, only X clients.

11.2.14 - sparc

/usr/X11R6/README for sparc.

With a single supported framebuffer, there is no configuration needed. If you wish to use a multi-headed configuration, see the above README file for details.

Resolution is controlled by the firmware before booting OpenBSD.

11.2.15 - sparc64

/usr/X11R6/README for sparc64.

There are a number of variations on these machines, you will need to know what kind of bus your system has (PCI or SBus), what kind of port your mouse is attached to (zstty, com, or USB/PS2), and what kind of video card you have. Start with the sample xorg.conf file in the README file, then modify as indicated for your actual hardware and need. Do not expect the sample file to work unmodified on your machine!

11.2.16 - vax

/usr/X11R6/README for vax.

The X server currently only works on VAXstation 4000 models with either a lcg(4) or lcspx(4) framebuffer.

11.2.17 - zaurus

/usr/X11R6/README for zaurus.

No configuration needed, X "Just Works".

11.3 - Configuring X on amd64 and i386

The variety of hardware options on these platforms makes the X configuration process "tricky".

11.3.1 - X.Org configuration

X.Org has made great improvements in making their servers "Just Work". In many cases, it does Just Work without any /etc/X11/xorg.conf file. But not always, and sometimes, you need to customize something that does work, anyway.

There are two programs that can be used to semi-automatically create a configuration file for X.Org's i386 X servers. Unfortunately, neither of them are guaranteed to create a usable xorg.conf file.

In addition to the above applications, another time-honored way to configure X is to use your favorite search engine to hunt for someone else who already solved your problem. While that's not a bad way, that method won't be emphasized here.

11.3.2 - Our example machine

As a demonstration of setting up X, we will use an old Celeron 400MHz system, with an AGP video slot. The video card is an old AGP card, shown in the dmesg as:
vga1 at pci1 dev 0 function 0 "3DFX Interactive Banshee" rev 0x03
This is a once high-end video card, with 16M RAM, but is now mostly unsupported on modern versions of "mainstream" operating systems. The monitor attached to the system is a Sony Multiscan G400 19" CRT monitor, and it would be nice to run this monitor at 1280x1024, with a decent refresh rate, and 24 bit color.

First, after installing OpenBSD with X (and making sure the aperture driver is enabled in the kernel), let's see what X.Org's auto detection and configuration does, after all, we might get lucky. So, we simply log in and use the command startx(1). The screen goes blank for a few moments, the we get the X "checkerboard" background, the "X" cursor, and then an xterm window.

It works!

More or less. While the system is fully functional, it doesn't appear to have picked up any of the capabilities of the monitor, and is running at what is clearly a low resolution (640x480). We hope to do better than this. Much better, in fact. This does mean we need to make our own xorg.conf file, however.

Let's use the "X -configure" process to generate a starting xorg.conf file. You will need to do this as root:

# X -configure [...] Your xorg.conf file is /root/xorg.conf.new To test the server, run 'X -config /root/xorg.conf.new'
By the way, the message is serious -- use the entire path to your xorg.conf.new file, even if it is sitting in your current default directory. Failing to do so will result in X(7) not finding the file, and it will silently use the default configuration, which may have nothing to do with the file you are currently working with. This can set back your troubleshooting quite a bit. Trust us on this.

Let's do as it says, and see what we get:

# X -config /root/xorg.conf.new
Now, all we get is a black screen. Things had started out so well...

This might be a really good time to talk about ways of exiting X when started in this way. In order of preference:

Fortunately for us, CTRL-ALT-Backspace does the job here, and we are returned to a command prompt. So now we need to see if we can figure out what is wrong. First, we should look at what Xorg thinks is going on, and that is recorded in the file /var/log/Xorg.0.log. In this case, it appears that X thinks all is running fine, there are no obviously significant errors shown in the log (lines that start with an "(EE)" are errors).

Here is where knowing your hardware comes in handy. Attaching this system to a different monitor while it is showing the blank screen produces a "Sync. Out of Range" message on the display. So, apparently the configuration X gave us will not run on this monitor, and may not run on ANY monitor, if a video mode was selected that isn't possible for this particular card (keep in mind, X is looking at the chips on the card, and what they are potentially capable of, not how the manufacturer put it all together). Different monitors will do different things when the timing is way off, some will attempt to display what they can, others will drop to power saving mode, some will make horrible noises, some will display useful messages on the screen. This monitor seems to do none of the above. A note is made to NOT use this monitor for initial X configuration in the future.

Looking through the generated xorg.conf.new file, we see this:

Section "Monitor" #DisplaySize 370 270 # mm Identifier "Monitor0" VendorName "SNY" ModelName "SONY CPD-G400" ### Comment all HorizSync and VertSync values to use DDC: HorizSync 30.0 - 107.0 VertRefresh 48.0 - 120.0 Option "DPMS" EndSection
As a test, let's try using DDC ("Data Display Channel", a way the monitor can tell the computer and video card what it is capable of), and see what happens. This time, we get the X mesh pattern and the moving cursor, which is all we expect when invoking X in this way (we terminate X using the CTRL-ALT-Backspace trick above). It is (again) a very low resolution, but it is working, so we can be pretty sure we have a timing and resolution problem. We'll restore the "HorizSync" and "VertRefresh" lines as they were, as we have verified this monitor's specs through a bit of Internet searching.

Let's try to force Xorg to a particular resolution, and see if we have any luck. In the Section "Screen" part of the xorg.conf file, we want to add a couple lines. The added lines are shown in bold:

Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultDepth 24 SubSection "Display" Viewport 0 0 Depth 1 EndSubSection SubSection "Display" Viewport 0 0 Depth 4 EndSubSection SubSection "Display" Viewport 0 0 Depth 8 EndSubSection SubSection "Display" Viewport 0 0 Depth 15 EndSubSection SubSection "Display" Viewport 0 0 Depth 16 EndSubSection SubSection "Display" Viewport 0 0 Depth 24 Modes "1280x1024" EndSubSection EndSection
These two changes tell X we want to use a 24 bit display depth, and for 24 bit depths, we want the resolution 1280x1024. As no other resolution is listed for "Depth 24", the system will be forced to that resolution.

We test as above, and... SUCCESS! We have what appears to be a very nice, high resolution display. Note that ALL that is expected is a mesh pattern (very good for seeing how good your monitor REALLY is and also great for calibrating LCD displays, called the "root weave") and a movable cursor. It is not intended to be functional at this point.

Now, we want to install this xorg.conf file so we can see how well we are really doing with usable running of X.

# cp xorg.conf.new /etc/X11/xorg.conf
We can now try X using the normal startx(1) command. It works!

It would probably be good to verify that we are at the resolution and color depth we desire, and also that we are running at a respectable refresh rate. We can do that with the xrandr(1) and xdpyinfo(1) commands. Among other things, xdpyinfo(1) tells us:

[...] screen #0: print screen: no dimensions: 1280x1024 pixels (433x347 millimeters) resolution: 75x75 dots per inch depths (7): 24, 1, 4, 8, 15, 16, 32 root window id: 0x44 depth of root window: 24 planes [...]
So, yes, we are running at 1280x1024 with a depth of 24 planes (bits).

xrandr(4) tells us:

SZ: Pixels Physical Refresh *0 1280 x 1024 ( 433mm x 347mm ) *85 75 60 1 1280 x 960 ( 433mm x 347mm ) 85 60 [...]
which tells us we are running with an 85Hz refresh rate, so this should be a very comfortable setting for most users.

11.3.3 - What if it isn't that "easy"?

Sometimes, things just don't go together. Here are some tips.

11.4 - Starting X

There are two common ways to run X:

11.4.1 - On Demand:

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

11.4.2 - Boot directly into X:

This is done using xdm(1), the X Display Manager. xdm(1) is started as root, normally by rc, 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 login 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).

[FAQ Index] [To Section 10 - System Management] [To Section 12 - Hardware and Platform-Specific Questions]

[back] www@openbsd.org
$OpenBSD: faq11.html,v 1.74 2007/12/27 01:42:47 nick Exp $