`xorg.conf`

While there is rarely a need to manually edit the /etc/X11/xorg.conf file, it is useful to understand the various sections and optional parameters available, especially when troubleshooting.

The Structure

The /etc/X11/xorg.conf file is comprised of many different sections which address specific aspects of the system hardware.

Each section begins with a Article "<section-name>" line (where <section-name> is the title for the section) and ends with an EndArticle line. Each section contains lines that include option names and one or more option values. These are sometimes enclosed in double quotes (").

Lines beginning with a hash mark (#) are not read by the X server and are used for human-readable comments.

Some options within the /etc/X11/xorg.conf file accept a boolean switch which turns the feature on or off. Acceptable boolean values are:

1, on, true, or yes - Turns the option on.

0, off, false, or no - Turns the option off.

The following are some of the more important sections in the order in which they appear in a typical /etc/X11/xorg.conf file. More detailed information about the X server configuration file can be found in the xorg.conf man page.

`ServerFlags`

The optional ServerFlags section contains miscellaneous global X server settings. Any settings in this section may be overridden by options placed in the ServerLayout section (refer to "ServerLayout" for details).

Each entry within the ServerFlags section is on its own line and begins with the term Option followed by an option enclosed in double quotation marks (").

The following is a sample ServerFlags section:

Article "ServerFlags"
 Option "DontZap" "true"
EndArticle

The following lists some of the most useful options:

"DontZap" "<boolean>" - When the value of <boolean> is set to true, this setting prevents the use of the Ctrl+Alt+Backspace key combination to immediately terminate the X server.

"DontZoom" "<boolean>" - When the value of <boolean> is set to true, this setting prevents cycling through configured video resolutions using the Ctrl+Alt+Keypad-Plus and Ctrl+Alt+Keypad-Minus key combinations.

`ServerLayout`

The ServerLayout section binds together the input and output devices controlled by the X server. At a minimum, this section must specify one output device and one input device. By default, a monitor (output device) and keyboard (input device) are specified.

The following example illustrates a typical ServerLayout section:

Article  "ServerLayout"
 Identifier     "Default Layout"
 Screen      0  "Screen0" 0 0
 InputDevice    "Mouse0" "CorePointer"
 InputDevice    "Keyboard0" "CoreKeyboard"
EndArticle

The following entries are commonly used in the ServerLayout section:

Identifier - Specifies a unique name for this ServerLayout section.

Screen - Specifies the name of a Screen section to be used with the X server. More than one Screen option may be present.
The following is an example of a typical Screen entry:
```
Screen      0  "Screen0" 0 0
```
The first number in this example Screen entry (0) indicates that the first monitor connector or head on the video card uses the configuration specified in the Screen section with the identifier "Screen0".
An example of a Screen section with the identifier "Screen0" can be found in "Screen".
If the video card has more than one head, another Screen entry with a different number and a different Screen section identifier is necessary .
The numbers to the right of "Screen0" give the absolute X and Y coordinates for the upper-left corner of the screen (0 0 by default).
InputDevice - Specifies the name of an InputDevice section to be used with the X server.
It is advisable that there be at least two InputDevice entries: one for the default mouse and one for the default keyboard. The options CorePointer and CoreKeyboard indicate that these are the primary mouse and keyboard.
Option "<option-name>" - An optional entry which specifies extra parameters for the section. Any options listed here override those listed in the ServerFlags section.
Replace <option-name> with a valid option listed for this section in the xorg.conf man page.

It is possible to put more than one ServerLayout section in the /etc/X11/xorg.conf file. By default, the server only reads the first one it encounters, however.

If there is an alternative ServerLayout section, it can be specified as a command line argument when starting an X session.

`Files`

The Files section sets paths for services vital to the X server, such as the font path. This is an optional section, these paths are normally detected automatically. This section may be used to override any automatically detected defaults.

The following example illustrates a typical Files section:

Article "Files"
 RgbPath      "/usr/share/X11/rgb.txt"
 FontPath     "unix/:7100"
EndArticle

The following entries are commonly used in the Files section:

RgbPath - Specifies the location of the RGB color database. This database defines all valid color names in X and ties them to specific RGB values.

FontPath - Specifies where the X server must connect to obtain fonts from the xfs font server.
By default, the FontPath is unix/:7100. This tells the X server to obtain font information using UNIX-domain sockets for inter-process communication (IPC) on port 7100.
Refer to "Fonts" for more information concerning X and fonts.
ModulePath - An optional parameter which specifies alternate directories which store X server modules.

`Module`

By default, the X server automatically loads the following modules from the /usr/lib/xorg/modules/ directory:

extmod

dbe

glx
freetype
type1
record
dri

The default directory for loading these modules can be changed by specifying a different directory with the optional ModulePath parameter in the Files section. Refer to "Files" for more information on this section.

Adding a Module section to /etc/X11/xorg.conf instructs the X server to load the modules listed in this section instead of the default modules.

For example, the following typical Module section:

Article "Module"
 Load  "fbdevhw"
EndArticle

instructs the X server to load the fbdevhw instead of the default modules.

As such, if you add a Module section to /etc/X11/xorg.conf, you will need to specify any default modules you want to load as well as any extra modules.

`InputDevice`

Each InputDevice section configures one input device for the X server. Systems typically have at least one InputDevice section for the keyboard. It is perfectly normal to have no entry for a mouse, as most mouse settings are automatically detected.

The following example illustrates a typical InputDevice section for a keyboard:

Article "InputDevice"
        Identifier  "Keyboard0"
        Driver      "kbd"
        Option      "XkbModel" "pc105"
        Option      "XkbLayout" "us"
EndArticle

The following entries are commonly used in the InputDevice section:

Identifier - Specifies a unique name for this InputDevice section. This is a required entry.

Driver - Specifies the name of the device driver X must load for the device.
Option - Specifies necessary options pertaining to the device.
A mouse may also be specified to override any autodetected defaults for the device. The following options are typically included when adding a mouse in the xorg.conf:
- Protocol - Specifies the protocol used by the mouse, such as IMPS/2.
Device - Specifies the location of the physical device.
Emulate3Buttons - Specifies whether to allow a two-button mouse to act like a three-button mouse when both mouse buttons are pressed simultaneously.

Consult the xorg.conf man page for a list of valid options for this section.

`Monitor`

Each Monitor section configures one type of monitor used by the system. This is an optional entry as well, as most monitors are now automatically detected.

The easiest way to configure a monitor is to configure X during the installation process or by using the X Configuration Tool. For more information about using the X Configuration Tool, refer to X Window System Configuration.

This example illustrates a typical Monitor section for a monitor:

Article "Monitor"
 Identifier   "Monitor0"
 VendorName   "Monitor Vendor"
 ModelName    "DDC Probed Monitor - ViewSonic G773-2"
 DisplaySize  320 240
 HorizSync    30.0 - 70.0
 VertRefresh  50.0 - 180.0
EndArticle

Be careful when manually editing values in the Monitor section of /etc/X11/xorg.conf. Inappropriate values can damage or destroy a monitor. Consult the monitor's documentation for a listing of safe operating parameters.

The following are commonly entries used in the Monitor section:

Identifier - Specifies a unique name for this Monitor section. This is a required entry.

VendorName - An optional parameter which specifies the vendor of the monitor.
ModelName - An optional parameter which specifies the monitor's model name.
DisplaySize - An optional parameter which specifies, in millimeters, the physical size of the monitor's picture area.
HorizSync - Specifies the range of horizontal sync frequencies compatible with the monitor in kHz. These values help the X server determine the validity of built-in or specified Modeline entries for the monitor.
VertRefresh - Specifies the range of vertical refresh frequencies supported by the monitor, in kHz. These values help the X server determine the validity of built in or specified Modeline entries for the monitor.
Modeline - An optional parameter which specifies additional video modes for the monitor at particular resolutions, with certain horizontal sync and vertical refresh resolutions. Refer to the xorg.conf man page for a more detailed explanation of Modeline entries.
Option "<option-name>" - An optional entry which specifies extra parameters for the section. Replace <option-name> with a valid option listed for this section in the xorg.conf man page.

`Device`

Each Device section configures one video card on the system. While one Device section is the minimum, additional instances may occur for each video card installed on the machine.

The best way to configure a video card is to configure X during the installation process or by using the X Configuration Tool. For more about using the X Configuration Tool, refer to X Window System Configuration.

The following example illustrates a typical Device section for a video card:

Article "Device"
 Identifier  "Videocard0"
 Driver      "mga"
 VendorName  "Videocard vendor"
 BoardName   "Matrox Millennium G200"
 VideoRam    8192
 Option      "dpms"
EndArticle

The following entries are commonly used in the Device section:

Identifier - Specifies a unique name for this Device section. This is a required entry.

Driver - Specifies which driver the X server must load to utilize the video card. A list of drivers can be found in /usr/share/hwdata/videodrivers, which is installed with the hwdata package.
VendorName - An optional parameter which specifies the vendor of the video card.
BoardName - An optional parameter which specifies the name of the video card.
VideoRam - An optional parameter which specifies the amount of RAM available on the video card in kilobytes. This setting is only necessary for video cards the X server cannot probe to detect the amount of video RAM.
BusID - An entry which specifies the bus location of the video card. On systems with only one video card a BusID entry is optional and may not even be present in the default /etc/X11/xorg.conf file. On systems with more than one video card, however, a BusID entry must be present.
Screen - An optional entry which specifies which monitor connector or head on the video card the Device section configures. This option is only useful for video cards with multiple heads.
If multiple monitors are connected to different heads on the same video card, separate Device sections must exist and each of these sections must have a different Screen value.
Values for the Screen entry must be an integer. The first head on the video card has a value of 0. The value for each additional head increments this value by one.
Option "<option-name>" - An optional entry which specifies extra parameters for the section. Replace <option-name> with a valid option listed for this section in the xorg.conf man page.
One of the more common options is "dpms" (for Display Power Management Signaling, a VESA standard), which activates the Service Star energy compliance setting for the monitor.

`Screen`

Each Screen section binds one video card (or video card head) to one monitor by referencing the Device section and the Monitor section for each. While one Screen section is the minimum, additional instances may occur for each video card and monitor combination present on the machine.

The following example illustrates a typical Screen section:

Article "Screen"
 Identifier "Screen0"
 Device     "Videocard0"
 Monitor    "Monitor0"
 DefaultDepth     16
 SubArticle "Display"
  Depth     24
  Modes    "1280x1024" "1280x960" "1152x864" "1024x768" "800x600" "640x480"
 EndSubArticle
 SubArticle "Display"
  Depth     16
  Modes    "1152x864" "1024x768" "800x600" "640x480"
 EndSubArticle
EndArticle

The following entries are commonly used in the Screen section:

Identifier - Specifies a unique name for this Screen section. This is a required entry.

Device - Specifies the unique name of a Device section. This is a required entry.
Monitor - Specifies the unique name of a Monitor section. This is only required if a specific Monitor section is defined in the xorg.conf file. Normally, monitors are automatically detected.
DefaultDepth - Specifies the default color depth in bits. In the previous example, 16 (which provides thousands of colors) is the default. Only one DefaultDepth is permitted, although this can be overridden with the Xorg command line option -depth <n>,where <n> is any additional depth specified.
SubArticle "Display" - Specifies the screen modes available at a particular color depth. The Screen section can have multiple Display subsections, which are entirely optional since screen modes are automatically detected.
This subsection is normally used to override autodetected modes.
Option "<option-name>" - An optional entry which specifies extra parameters for the section. Replace <option-name> with a valid option listed for this section in the xorg.conf man page.

`DRI`

The optional DRI section specifies parameters for the Direct Rendering Infrastructure (DRI). DRI is an interface which allows 3D software applications to take advantage of 3D hardware acceleration capabilities built into most modern video hardware. In addition, DRI can improve 2D performance via hardware acceleration, if supported by the video card driver.

This section rarely appears, as the DRI Group and Mode are automatically initialized to default values. If a different Group or Mode is desired, then adding this section to the xorg.conf file will override those defaults.

The following example illustrates a typical DRI section:

Article "DRI"
 Group        0
 Mode         0666
EndArticle

Since different video cards use DRI in different ways, do not add to this section without first referring to http://dri.sourceforge.net/.