It’s easy to understand users’ caution. Not only does xorg.conf contain a lot that can go wrong, but it is only fitfully documented in man and Web pages. Moreover, because the file’s settings are specific to each system, borrowing an example of the file off the Internet is unlikely to give you more than basic ideas of how to get its settings correct. However, so long as you remember to make a backup copy of the file and keep within the settings defined by the documentation that comes with the hardware, the danger is actually minimal.
The xorg.conf file is divided into a minimum of eight sections. The start of each section is marked by the word Section followed by the section’s name, and its end by EndSection. Sections can be placed in any order, and you can have more than one section that cover a certain purpose — for example, if you are using multiple monitors. As in most configuration files, you may also see lines that start with a number sign (#) that provide comments for human readers. These lines are ignored by the operating system, and you can add more for your own purposes.
Within each section, you can quickly observe the structure that additional entries should follow. For instance, most sections indent once for a field and again for its value, which is placed in double quotation marks. Similarly, hardware has an Identifier field, which can be anything so long as it is unique. The indentations are not needed by your computer, but they do ensure that the file is kept in human-readable form. Once you understand this basic structure, you are ready to edit xorg.conf.
Setting resources and improving font display
Resources for the X server are listed in the Files section. Some distributions include the path to the database used for the RGB color palettes used for the display (/usr/share/X11/rgb), as well as the path to the server modules (/usr/lib/xorg/modules or /usr/lib/modules), but these paths should be unnecessary unless your system has resources stored in unusual places. Recent versions of Debian, for instance, omit these entries entirely.
Most of the system resources are devoted to the paths used for fonts. Users must add all new fonts via a font server, the easiest one to use being the one built into the KDE Control Center, which stores fonts in /usr/local/share/fonts (nothing comparable exists for GNOME). Fonts that were added during system installation are usually stored in /usr/share/fonts/ or /usr/share/fonts/X11, which has subdirectories for TrueType, Type 1 or PostScript, and bitmapped fonts. You can add new font paths by following the format of existing entries:
t
FontPatht””
t
If an application needs to display a particular font, then the X server uses the first instance of the font located. For this reason, you can sometimes improve font display on the system by changing the order in which fontpaths are listed. The “XFree86 Font Deuglification Mini HOWTO,” an old but still useful source, suggests that you place any directory for 100dpi bitmap fonts before those for 75dpi bitmap fonts, and add :unscaled to the end of all the paths for bitmapped fonts. These changes help to ensure that a higher quality font will be the one used by the X server.
t
Editing X server modules
xorg.conf’s Modules and DRI sections refer to modules loaded by the X server for such purposes as 3-D acceleration (glx, dri) and font support (freetype, type1, speedo). For the most part, you should not edit these sections. They are dependent on resources compiled in the kernel and supplied by various libraries added during installation, so simply editing xorg.conf may not have any effect on your system. Unfortunately, too, they are by far the least documented sections of the file, so if you’re not an expert, leave them alone.
However, if you are having display problems, as a last resort, you can try the hacker’s solution of commenting out all of the modules and adding them back one by one with each reboot. In particular, if you’re using the freetype module, other font modules may be redundant, such as type1, as well as the xtt module, which provides TrueType support conflicts with freetype according to some reports.
Defining the keyboard
The keyboard is defined in a separate Input Device section in xorg.conf that starts with an Identifier. The Identifier is followed by a Driver — usually just kbd in a 2.6 kernel — and, for the main keyboard in a configuration, the CoreKeyboard option.
Most users will also want to use the XkbRules options to define the general behavior of the keyboard, since the alternative is to define all aspects of the keyboard layout separately. This option should usually be defined as xorg, which indicates that the X server should use the standard settings for xorg.
However, even with the shortcut provided by XkbRules, you still need to define the XkbModel for the keyboard, using one of the options listed in /usr/share/X11/xkb/rules/base.lst, or else a generic one such as pc104 or pc102. You also need the XkbLayout option, which takes one of the standard two-digit locale codes that are also listed in base.lst in order to define the symbols associated with other keys.
If you want to use multiple layouts you can use XkbLayout to list multiple keyboard layouts in a comma-separated list, and use XkbOption to define a key or key combination that cycles through each layout. For example, to use Alt-Shift to move through the defined layouts, you would enter the line Option “XkbOptions” “grp:Alt_shift_toggle”.
Similarly, if you want to define a Compose and an AltGraph key — two keys that are used to enable the typing of international characters, such as accents or currency symbols — you can use XkbOptions to define them. For instance, defining them as “compose:rwin, grp:lwin” would give those useless right and left Windows key a purpose at last.
Configuring the pointing device
A mouse or other pointing device is defined in a separate Input Device section. After the Identifier, the next three lines in the section will generally be:
Drivert"mouse"
Optiont"CorePointer"
Optiont"Device" "/dev/input/mice"
As you can probably guess, the CorePointer option defines the primary input device, and the Device gives the path to the device.
After that, an entry for a pointer device will have an option defining the Protocol, which describes the manufacturer and model of the device. The Auto option for the protocol is reported as broken in recent versions of xorg, so you should specify the exact protocol, such as Microsoft or Logitech, or the general type of mouse, such as ImPS/2 or USB.
If you have a two-button mouse, you should add the “Emulate 2 buttons” option. For devices that have more than three buttons, you can use the “Buttons” option to specify the exact number if you have more than three. More esoterically, you can use the “XAxisMapping” and “YAxisMapping” options to give a space-separated list of buttons to use when a scroll wheel is emulated, or “ZAxisMapping” to map the scroll wheel motion to another axis or button, either because you are using a device that lacks a scroll wheel but has extra buttons, or for simple convenience.
Configuring the graphics card
xorg.conf’s Device section controls the graphics card configuration. This name is obscure, but understandable when you consider that the graphics card drives the entire display. The basic configuration consists of the Identifier, followed by the Driver field. If you are having trouble with the display, you can try one of the drivers in the /usr/lib/xorg/modules/drivers directory, using the first element of the file name before the underscore as the entry for the driver in xorg.conf. For example, if the s3virge_drv.so file is in the directory, you would enter the driver name as “s3virge”. If all else fails you can get basic video support by entering “vesa” or “vga” for the driver. Most of these drivers have a man page that you can consult for more information.
Increasingly, the BusID field, which defines the slot the video card is placed in, is also being used in this section. Usually, the first video card’s bus ID will be PCI:1:0:0, but you can find it for sure by running the lspci command and looking for the video card in the results. Depending on the card in your system, you may also need to add the VendorName and BoardName fields, using information that came with your video card.
Defining the monitor
At a minimum, the modern Monitor section of xorg.conf consists of a unique Identifier and the option DPMS, which enables Display Power Management Signaling in order to conserve the power used by the monitor. However, you can also set the horizontal and vertical refresh rates in the HorizSync and VertRefresh fields, or the monitor’s Gamma setting, using information supplied with the monitor.
Another option is DisplaySize, which is measured in millimeters and specifies the dots per inch to use at a particular resolution. To get the resolution in millimeters, multiply both the height and the width by 25.4, and divide each result by the desired DPI. For example, if your resolution is 1024 x768, the results rounded down would be 270 and 203, and the entire entry for the option would read:Optiont”DisplaySize” “270 203 # 96 DPI @ 1024×768”.Alternatively, with some Nvidia cards, you may need to suppress the automatic setting of the DPI by including the option “USEdidDPI” set to “false” and following by the option “DPI” with a value for the desired DPI, such as “96 x 96”.
Setting resolution and color depth
The Screen section begins with a unique identifier, followed by a summary of the display options, listing the video card (“Device”) and monitor by the Identifiers they were given in early sections of the file, followed by the default color depth (“DefaultDepth”).
The rest of the section is devoted to the Display subsection. For each color depth (“Depth”), the subsection lists each resolution (“Mode”) that the system supports. When the X Window System starts, it will try to use the default color depth at the maximum resolution listed for it. However, if X is unable to do so for any reason, then it will try each resolution for the default color depth, then repeat the process for the next highest color depth until it manages to load.
You can use this behavior to force your display to use a particular color depth and resolution, either because your system refuses to use the settings you want — possibly due to a flaw in the driver — or because you want settings lower than the maximum. All you need to do is change the default color depth, then, under the listing of resolutions for that depth, place your preferred resolution first.
You may also choose to delete the resolution listings for other color depths, as well as other resolutions. As long as you have a backup of the original xorg.conf file, the worst this practice can do is force you to restore the backup and reboot.
Final steps and final words
If you have added hardware to your system, your last step in editing xorg.conf must be to make sure that the xorg.conf references it. That means adding the Identifier for a new monitor or video card to the Screen section, and the Identifier for a new pointing device or keyboard to the ServerLayout section. When you have done that, either reboot your system or restart X using Ctrl-Alt-Backspace to test the new configuration. Should X fail to start, you can still edit xorg.conf from the command line, or, when either all options or all patience is exhausted, restore your system using the backup copy you made of xorg.conf. You can find log files for Xorg in /var/log, although, since the problem is bound to be in your recent changes, you may not need the log to figure out what is wrong.
These are only the most basic options for editing xorg.conf. Depending on which manufacturer you buy your hardware from and whether you are using multiple pieces of the same type of hardware, you can significantly complicate the contents of the file. However, the information here is enough for a basic orientation. You may never have to edit xorg.conf manually, but if you do, knowing what to expect can only help.
