Section 16.5. Configuring X.org

16.5. Configuring X.org

Setting up X.org 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 X.org can be somewhat time-consuming.

In this section, we describe how to create and edit the xorg.conf file, which configures the X.org server. This file is by default located in /etc/X11/, but is searched for in many other locations, so your distribution might elect to put it elsewhere. In any case, it is best to start out with a skeleton configuration file generated by any of the means described earlier. Then go for a low resolution: a good choice is 640 x 480, which should be supported on all video cards and monitor types. Once you have X.org 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 X.org 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 X.org for real use. With current hardware, you should easily be able to get up to 1280 x 1024 pixels (1024 x 768 on most laptops).

In addition to the information here, you should read the documentation at http://www.x.org/X11R6.8.2/doc/, in particular the README files for your particular graphics chipset.

The main configuration file you need to create is /etc/X11/xorg.conf. This file contains information on your mouse, video card parameters, and so on. The file /etc/X11/xorg.conf.install is provided with the X.org distribution as an example. Copy this file to xorg.conf and edit it as a starting point, if any of the other methods did not give you a skeleton configuration file.

The xorg.conf 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 xorg.conf file, piece by piece. This file may not look exactly like the sample file included in the X.org distribution, but the structure is the same. The xorg.conf file format may change with each version of X.org; this information is valid only for X.org Version 6.8.2.

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 xorg.conf file. The bottom line is this: make absolutely sure your xorg.conf 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 X.org 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 Xorg.conf file is surrounded by the pair of lines Section "section-name" and EndSection. The first part of the Xorg.conf file is Files, which looks like this:

 Section "Files"   FontPath     "/usr/X11R6/lib/X11/fonts/misc:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/local"   FontPath     "/usr/X11R6/lib/X11/fonts/75dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/100dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/Type1"   FontPath     "/usr/X11R6/lib/X11/fonts/URW"   FontPath     "/usr/X11R6/lib/X11/fonts/Speedo"   FontPath     "/usr/X11R6/lib/X11/fonts/PEX"   FontPath     "/usr/X11R6/lib/X11/fonts/cyrillic"   FontPath     "/usr/X11R6/lib/X11/fonts/latin2/misc:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/latin2/75dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/latin2/100dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/latin2/Type1"   FontPath     "/usr/X11R6/lib/X11/fonts/latin7/75dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/baekmuk:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/japanese:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/kwintv"   FontPath     "/usr/X11R6/lib/X11/fonts/truetype"   FontPath     "/usr/X11R6/lib/X11/fonts/uni:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/CID"   FontPath     "/usr/X11R6/lib/X11/fonts/ucs/misc:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/ucs/75dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/ucs/100dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/hellas/misc:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/hellas/75dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/hellas/100dpi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/hellas/Type1"   FontPath     "/usr/X11R6/lib/X11/fonts/misc/sgi:unscaled"   FontPath     "/usr/X11R6/lib/X11/fonts/xtest"   FontPath     "/opt/kde3/share/fonts"   InputDevices "/dev/ttyS0"   InputDevices "/dev/ttyS1"   InputDevices "/dev/ttyS2"   InputDevices "/dev/ttyS3"   InputDevices "/dev/ttyS4"   InputDevices "/dev/ttyS5"   InputDevices "/dev/ttyS6"   InputDevices "/dev/ttyS7"   InputDevices "/dev/ttyS8"   InputDevices "/dev/psaux"   InputDevices "/dev/logibm"   InputDevices "/dev/sunmouse"   InputDevices "/dev/atibm"   InputDevices "/dev/amigamouse"   InputDevices "/dev/atarimouse"   InputDevices "/dev/inportbm"   InputDevices "/dev/gpmdata"   InputDevices "/dev/mouse"   InputDevices "/dev/usbmouse"   InputDevices "/dev/adbmouse"   InputDevices "/dev/input/mice"   InputDevices "/dev/input/event0"   InputDevices "/dev/pointer0"   InputDevices "/dev/pointer1"   InputDevices "/dev/pointer2"   InputDevices "/dev/pointer3" EndSection

There can be many more lines like these. 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, you can also set a RgbPath for finding the RGB color database (unlikely to be necessary), and a ModulePath, 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 documentation at http://www.x.org. 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 such as PEX. It is also used for loading the freetype support library and the video and 3D support. Here is a sample Module section:

 Section "Module"   Load         "v4l"   Load         "extmod"   Load         "type1"   Load         "freetype"   Load         "dbe"   Load         "dri"   Load         "speedo"   Load         "glx" EndSection

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"   Driver       "kbd"   Identifier   "Keyboard[0]"   Option       "Protocol" "Standard"   Option       "XkbLayout" "us"   Option       "XkbModel" "pc105"   Option       "XkbRules" "xfree86" EndSection Section "InputDevice"   Driver       "mouse"   Identifier   "Mouse[1]"   Option       "ButtonNumber" "7"   Option       "Device" "/dev/mouse"   Option       "Name" "Autodetection"   Option       "Protocol" "ExplorerPS/2"   Option       "Vendor" "Sysp"   Option       "ZAxisMapping" "4 5" 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 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.

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 xorg.conf 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    "Radeon LW"   BusID        "1:0:0"   Driver       "radeon"   Identifier   "Device[0]"   Screen       0   Option       "Rotate" "off"   VendorName   "ATI" 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:

 X.org -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, because 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:

 Xorg -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 xorg.conf file, there may be more than one Monitor section. This is useful if you have multiple monitors connected to a system, or if you use the same xorg.conf file under multiple hardware configurations. In general, though, you will need only a single Monitor section:

 Section "Monitor"   Option       "CalcAlgorithm" "CheckDesktopGeometry"   DisplaySize  320 240   HorizSync    28-60   Identifier   "Monitor[0]"   ModelName    "THINKPAD 1400X1050 LCD PANEL"   Option       "DPMS"   VendorName   "IBM"   VertRefresh  50-60   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 xorg.conf file.

HorizSync specifies the valid horizontal synchronization 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 the following:

 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 these settings. Although 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 X.org, 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         "800x600" 36.88 800 832 912 1024 600 601 604 621   Modeline         "800x600" 40.00 800 840 968 1056 600 601 605 628 +HSync +VSync   Modeline         "1400x1050" 109.01 1400 1480 1632 1864 1050 1051 1054 1083   Modeline         "1280x1024" 98.60 1280 1352 1488 1696 1024 1025 1028 1057   Modeline         "1280x960" 97.68 1280 1352 1488 1696 960 961 964 993   Modeline         "1152x864" 78.82 1152 1216 1336 1520 864 865 868 894   Modeline         "1024x768" 61.89 1024 1080 1184 1344 768 769 772 794   Modeline         "800x600" 36.88 800 832 912 1024 600 601 604 621   Modeline         "800x600" 40.00 800 840 968 1056 600 601 605 628 +HSync +VSync   Modeline         "640x480" 23.06 640 656 720 800 480 481 484 497   Modeline         "1400x1050" 109.01 1400 1480 1632 1864 1050 1051 1054 1083 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 X.org 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 X 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 X 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, X.org 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 "800x 600") 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 24   SubSection "Display"     Depth      15     Modes      "800 x 600"   EndSubSection   SubSection "Display"     Depth      16     Modes      "1400 x 1050"   EndSubSection   SubSection "Display"     Depth      24     Modes      "1400 x 1050" "1280 x 1024" "1280 x 960" "1152 x 864" "1024 x 768"                "800 x 600" "640 x 480"   EndSubSection   SubSection "Display"     Depth      32     Modes      "800 x 600"   EndSubSection   SubSection "Display"     Depth      8     Modes      "800 x 600"   EndSubSection   Device       "Device[0]"   Identifier   "Screen[0]"   Monitor      "Monitor[0]" EndSection

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

Finally, the ServerLayout section 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"   InputDevice  "Mouse[3]" "SendCoreEvents"   Option       "Clone" "off"   Option       "Xinerama" "off"   Screen       "Screen[0]" EndSection

Other sections also exist, but these are entirely optional and are not needed to get your X server up and running .