Configuring XFree86 (Running Linux, 4th Edition)

10.4. Configuring XFree86

Setting up XFree86 is not difficult in most cases. However, if you happen to be using hardware for which drivers are under development, or wish to obtain the best performance or resolution from an accelerated graphics card, configuring XFree86 can be somewhat time-consuming.

In this section, we describe how to create and edit the XF86Config file, which configures the XFree86 server. This file is located in /etc/X11/ in the current version of XFree86, but in /etc/ in the previous versions. Also, the file format has changed between Version 3 and Version 4; what we describe here applies to Version 4, the current version (to make things worse, some Red Hat versions call this file XF86Config-4). In many cases, it is best to start out with a "basic" XFree86 configuration — one that uses a low resolution. A good choice is 640x480, which should be supported on all video cards and monitor types. Once you have XFree86 working at a lower, standard resolution, you can tweak the configuration to exploit the capabilities of your video hardware. The idea is that you want to make sure XFree86 works at least minimally on your system and that something isn't wrong with your installation before attempting the sometimes difficult task of setting up XFree86 for real use. With current hardware, you should easily be able to get up to 1024x768 pixels.

But before you start to write an XF86Config file yourself, try one of the configuration programs that are available. In many cases, you can avoid going through the hassle that will be described on the next pages. Some programs that may help you are:

Distribution-specific configuration tools: Some distributions also have their own configuration tools. For example, SuSE has SaX2 and Red Hat has Xconfigurator. These tools are usually very convenient and should be your first try. But if these fail, it is good to know that you have other options at your disposal. Most installation programs start these programs automatically during the installation, but if you configure your X server after installation, you should be able to start them by invoking their name on the command line. When in doubt, consult the documentation of your distribution.
xf86cfg

If one of these tools is able to configure your X server for you, you should use it and save yourself a lot of trouble. However, if all the tools fail or if you want to fine-tune your X server, you will have to know how to edit the XF86Config file yourself.

In addition to the information here, you should read the following documentation:

The XFree86 documentation in /usr/X11R6/lib/X11/doc (contained within the Xdoc package).
The README file for your video chipset, if one exists, in the directory /usr/X11R6/lib/X11/doc. These README files have names, such as README.i740 and README.cyrix.
The manual page for XFree86.
The manual page for XF86Config.

The main configuration file you need to create is /etc/X11/XF86Config (/etc/XF86Config in older versions). This file contains information on your mouse, video card parameters, and so on. The file XF86Config.eg is provided with the XFree86 distribution as an example. Copy this file to XF86Config and edit it as a starting point.

The XF86Config manual page explains the format of this file in detail. Read this manual page now if you have not done so already.

We are going to present a sample XF86Config file, piece by piece. This file may not look exactly like the sample file included in the XFree86 distribution, but the structure is the same. The XF86Config file format may change with each version of XFree86; this information is valid only for XFree86 Version 4.2.0.

Whatever you do, you should not simply copy the configuration file listed here to your own system and attempt to use it. Attempting to use a configuration file that doesn't correspond to your hardware could drive the monitor at a frequency that is too high for it; there have been reports of monitors (especially fixed-frequency monitors) being damaged or destroyed by using an incorrectly configured XF86Config file. The bottom line is this: make absolutely sure your XF86Config file corresponds to your hardware before you attempt to use it.

Now that we have written this warning, we would also like to mention that configuring XFree86 is much less dangerous than it used to be a few years ago, since the X server has become very good at detecting unsuitable configurations.

Each section of the XF86Config file is surrounded by the pair of lines Section "section-name"...EndSection. The first part of the XF86Config file is Files, which looks like this:

Section "Files"
    FontPath    "/usr/X11R6/lib/X11/fonts/misc:unscaled"
    FontPath    "/usr/X11R6/lib/X11/fonts/Type"
    RgbPath     "/usr/X11R6/lib/X11/rgb"
EndSection

There can be many more lines like these. The RgbPath line sets the path to the X11R6 RGB color database, and each FontPath line sets the path to a directory containing X11 fonts. In general, you shouldn't have to modify these lines; just be sure there is a FontPath entry for each font type you have installed (i.e., for each directory in /usr/X11R6/lib/X11/fonts). If you add the string :unscaled to a FontPath, the fonts from this directory will not be scaled. This is often an improvement because fonts that are greatly scaled look ugly. In addition to FontPath and RgbPath, you can also add a ModulePath to this section, to point to a directory with dynamically loaded modules. Those modules are currently used for some special input devices, as well as the PEX and XIE extensions.

The next section is ServerFlags, which specifies several global flags for the server. This section is often empty or very small:

Section "ServerFlags"
  Option       "AllowMouseOpenFail"
EndSection

Here, we say that we want the X server to start up even if it cannot find the mouse. For more options, please see the XF86Config(1) manual page. Often, options will be autodetected at server startup, so they don't need to be listed here.

The next section is the Module section, with which you can dynamically load additional X server modules, such as support for special hardware or graphics libraries like PEX. Unless you want to use special modules (which are likely to have their own documentation), you can leave this section out entirely.

The next sections are InputDevice. You usually have at least two, one for the keyboard and one for the mouse. If you have other input devices, such as a graphics tablet, these will go into additional sections:

Section "InputDevice"
        Identifier  "Keyboard1"
        Driver      "Keyboard"
        Option            "AutoRepeat" "250 30"
        Option            "XkbRules" "xfree86"
        Option            "XkbModel" "pc105"
        Option            "XkbLayout" "us"
EndSection

Section "InputDevice"
  Driver       "mouse"
  Identifier   "Mouse[1]"
  Option       "Device" "/dev/mouse"
  Option       "Emulate3Buttons" "on"
  Option       "Emulate3Timeout" "50"
  Option       "InputFashion" "Mouse"
  Option       "Name" "Autodetection"
  Option       "Protocol" "ps/2"
  Option       "Vendor" "Sysp"
EndSection

Again, other options are available as well. The keyboard configurations listed previously are for a U.S. keyboard; for other keyboards you will need to replace them with other lines suitable for your keyboard.

The mouse section tells the X server where the mouse is connected (/dev/mouse in this case, which is usually a link to the appropriate port, such as /dev/ttyS0), what kind of mouse it is (the "Protocol" option) and some other operational details. It is important for the protocol to be right, but the aforementioned configuration programs should usually find out the protocol automatically. You can find the list of supported protocols in /usr/X11R6/lib/X11/doc/README.mouse.

BusMouse should be used for the Logitech busmouse. Note that older Logitech mice that are not bus mice should use Logitech, but newer Logitech mice that are not bus mice use either the Microsoft or the Mouseman protocol. This is a case where the protocol doesn't necessarily have anything to do with the make of the mouse.

If you have a modern serial mouse, you could also try specifying Auto, which will try to autoselect a mouse driver.

It is easy to check whether you have selected the correct mouse driver once you have started up X; when you move your mouse, the mouse pointer on the screen should follow this movement. If it does this, your setup is very likely to be correct. If it doesn't, try another driver, and also check whether the device you specified is correct.

The next section of the XF86Config file is Device, which specifies parameters for your video card. If you have multiple video cards, there will also be multiple Device sections.

Section "Device"
  BoardName    "SiS630 GUI Accelerator+3D"
  BusID        "1:0:0"
  Driver       "sis"
  Identifier   "Device[0]"
  Screen       0
  VendorName   "SiS"
EndSection

The first entry here, BoardName, is simply a descriptive name that reminds you which graphics card you have configured here (important if you have more than one!). Similarly, VendorName is a free-form string that has purely descriptional purposes. Even the Identifier string can be picked freely, but needs to match the Device strings used in later sections of the configuration file. It is customary here to use the names Device"0", Device"1", and so on.

BusID identifies the actual graphics card in terms of the built-in hardware on the PCI bus. PCI:1:0:0, or the shorter 1:0:0, is usually the right choice if you have only one choice. If you are unsure about what to put in here, run the X server as follows:

XFree86 -scanpci

and check the output carefully. At least one graphics card should be contained in the output (probably among other hardware not relevant here). For example, a line like:

(1:0:0) Matrox unknown card (0x19d8) using a Matrox MGA G400 AGP

tells you that you have a Matrox MGA G400 card with an AGP connector installed. The first digits in parentheses are the PCI bus ID, as described earlier.

The Screen section is mandatory on multihead graphics cards, which have more than one monitor output. For single-head graphics cards, always put in 0 here.

Driver is very important, as it determines the actual graphics driver to be loaded by the X server. A good way to find the right driver name is either to use the configuration programs described earlier or to run the X server like this:

XFree86 -probeonly

This will output information the X server has collected about your hardware, including the driver it thinks it should use.

There are lots of other options you can specify in this file, including the chipset, the RAMDAC, and other hardware properties, but the X server is very good at finding these out all by itself, so you usually don't have to do that. If you still want to, check out the driver-specific README file, which lists the options and their possible values for that driver.

The next section is Monitor, which specifies the characteristics of your monitor. As with other sections in the XF86Config file, there may be more than one Monitor section. This is useful if you have multiple monitors connected to a system, or use the same XF86Config file under multiple hardware configurations. In general, though, you will need only a single Monitor section:

Section "Monitor"
  Option       "CalcAlgorithm" "CheckDesktopGeometry"
  HorizSync    31-65
  Identifier   "Monitor[0]"
  ModelName    "1024X768@70HZ"
  VendorName   "--> LCD"
  VertRefresh  58-78
  UseModes     "Modes[0]"
EndSection

The Identifier line is used to give an arbitrary name to the Monitor entry. This can be any string; you will use it to refer to the Monitor entry later in the XF86Config file.

HorizSync specifies the valid horizontal sync frequencies for your monitor in kHz. If you have a multisync monitor, this can be a range of values (or several comma-separated ranges), as seen in the Monitor section. If you have a fixed-frequency monitor, this will be a list of discrete values, such as:

    HorizSync    31.5, 35.2, 37.9, 35.5, 48.95

Your monitor manual should list these values in the technical specifications section. If you do not have this information, you should contact either the manufacturer or the vendor of your monitor to obtain it. There are other sources of information, as well; they are listed later.

You should be careful with those settings. While the settings VertRefresh and HorizSync (described next) help to make sure that your monitor will not be destroyed by wrong settings, you won't be very happy with your X setup if you get these values wrong. Unsteady pictures, flickering, or just plain snow can result.

VertRefresh specifies the valid vertical refresh rates (or vertical synchronization frequencies) for your monitor in Hz. Like HorizSync, this can be a range or a list of discrete values; your monitor manual should list them.

HorizSync and VertRefresh are used only to double-check that the monitor resolutions you specify are in valid ranges. This reduces the chance that you will damage your monitor by attempting to drive it at a frequency for which it wasn't designed.

You can use the ModeLine and Mode directive to specify resolution modes for your monitor. However, unlike earlier versions of XFree86, this is not strictly necessary any longer; the Monitor section shown earlier (which comes from a laptop) doesn't have one. Instead, this information is moved into the following section, Modes.

The Modes section, of which there should be one for every monitor you have configured, lists the various video modes that the X server should support. An example:

Section "Modes"
  Identifier   "Modes[0]"
  Modeline         "1024x768" 69.35 1024 1040 1216 1400 768 768 778 802
  Modeline         "1024x768" 79.55 1024 1040 1216 1400 768 768 778 802
  Modeline         "800x600" 42.43 800 816 928 1072 600 600 610 626
  Modeline         "800x600" 48.67 800 816 928 1072 600 600 610 626
EndSection

The Identifier line refers to a name specified in the Monitor section. The following Modeline lines each specify a video mode. The format of Modeline is:

Modeline name dot-clock horiz-values vert-values

name is an arbitrary string, which you will use to refer to the resolution mode later in the file. dot-clock is the driving clock frequency or dot clock associated with the resolution mode. A dot clock is usually specified in MHz and is the rate at which the video card must send pixels to the monitor at this resolution. horiz-values and vert-values are four numbers each; they specify when the electron gun of the monitor should fire and when the horizontal and vertical sync pulses fire during a sweep across the screen.

How can you determine the Modeline values for your monitor? That's difficult, especially since a lot of the documentation files that used to be shipped with XFree86 are no longer included, probably because they became outdated and haven't been updated yet. Your best bet is probably to use one of the configuration file generators mentioned in the previous section to get a set of start values and then tweaking these until you reach a satisfactory setting. For example, if while running XFree86 the image on the monitor shifts slightly or seems to flicker, tweak the values little by little to try to fix the image. Exactly what you need to adjust is difficult to say because it depends a lot on your actual graphics hardware, but with some experimenting, you usually get good results. Also, be sure to check the knobs and controls on the monitor itself! In many cases it is necessary to change the horizontal or vertical size of the display after starting up XFree86 in order for the image to be centered and of the appropriate size. Another option is to use the program xvidtune (see the manual page for how to use it), which can help you to get all the numbers for the modeline, lets you try your changes, and even allows you to undo them if you did something wrong.

Also, XFree86 has the so-called VESA monitor timings built in, so you might get along without a Modes section altogether. The VESA timings are standard values for the Modeline that work on most display hardware, at the expense of not using the individual hardware to its fullest potential.

Note that the name argument to Modeline (in this case "640x480") is an arbitrary string; the convention is to name the mode after the resolution, but name can be anything that describes the mode to you.

For each Modeline used, the server checks that the specifications for the mode fall within the range of values specified with HorizSync and VertRefresh. If they do not, the server will complain when you attempt to start up X (more on this later).

You shouldn't insert monitor timing values or Modeline values for monitors other than the model you own. If you attempt to drive the monitor at a frequency for which it was not designed, you can damage or even destroy it.

The next section is Screen, which specifies the monitor/video card combination to use for a particular server:

Section "Screen"
  DefaultDepth 16
  SubSection "Display"
    Depth      15
    Modes      "800x600" 
  EndSubSection
  SubSection "Display"
    Depth      16
    Modes      "1024x768" 
  EndSubSection
  SubSection "Display"
    Depth      24
    Modes      "800x600" 
  EndSubSection
  SubSection "Display"
    Depth      32
    Modes      "800x600" 
  EndSubSection
  SubSection "Display"
    Depth      8
    Modes      "800x600" 
  EndSubSection
  Device       "Device[0]"
  Identifier   "Screen[0]"
  Monitor      "Monitor[0]"
EndSection
 EndSection

This section ties together device, screen, and monitor definitions and lists the color depths to use with the video modes.

Finally, the section ServerLayout wraps things up by defining one actual configuration that consists of one or more Screen sections and one or more InputDevice sections. If you have a so-called multihead system (a system with more than one graphics board and one monitor attached to each, or one of those fancy multihead graphics boards to which you can connect multiple monitors), this section also specifies their relative layout. Here is an example:

Section "ServerLayout"
  Identifier   "Layout[all]"
  InputDevice  "Keyboard[0]" "CoreKeyboard"
  InputDevice  "Mouse[1]" "CorePointer"
  Option       "Clone" "off"
  Option       "Xinerama" "off"
  Screen       "Screen[0]"
EndSection

There are also other sections, but these are entirely optional and not needed in order to get your X server up and running.