C.3.3. The xorg.conf File

C.3.3. The `xorg.conf` File

In previous releases of the X Window System, /etc/X11/xorg.conf file was used to store initial setup for X. When a change occurred with the monitor, video card or other device managed by the X server, the file needed to be edited manually. In Fedora, there is rarely a need to manually create and edit the /etc/X11/xorg.conf file. Nevertheless, it is still useful to understand various sections and optional parameters available, especially when troubleshooting or setting up unusual hardware configuration.

In the following, some important sections are described 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(5) man page. This section is mostly intended for advanced users as most configuration options described below are not needed in typical configuration scenarios.

C.3.3.1. The `InputClass` section

InputClass is a new type of configuration section that does not apply to a single device but rather to a class of devices, including hot-plugged devices. An InputClass section's scope is limited by the matches specified; in order to apply to an input device, all matches must apply to the device as seen in the example below:

Section "InputClass"
   Identifier      "touchpad catchall"
   MatchIsTouchpad "on"
   Driver           "synaptics"
EndSection

If this snippet is present in an xorg.conf file or an xorg.conf.d directory, any touchpad present in the system is assigned the synaptics driver.

Alphanumeric sorting in `xorg.conf.d`

Note that due to alphanumeric sorting of configuration files in the xorg.conf.d directory, the Driver setting in the example above overwrites previously set driver options. The more generic the class, the earlier it should be listed.

The match options specify which devices a section may apply to. To match a device, all match options must correspond. The following options are commonly used in the InputClass section:

MatchIsPointer, MatchIsKeyboard, MatchIsTouchpad, MatchIsTouchscreen, MatchIsJoystick — boolean options to specify a type of a device.
MatchProduct "product_name" — this option matches if the product_name substring occurs in the product name of the device.
MatchVendor "vendor_name" — this option matches if the vendor_name substring occurs in the vendor name of the device.
MatchDevicePath "/path/to/device" — this option matches any device if its device path corresponds to the patterns given in the "/path/to/device" template, for example /dev/input/event*. Refer to the fnmatch(3) man page for further details.
MatchTag "tag_pattern" — this option matches if at least one tag assigned by the HAL configuration back end matches the tag_pattern pattern.

A configuration file may have multiple InputClass sections. These sections are optional and are used to configure a class of input devices as they are automatically added. An input device can match more than one InputClass section. When arranging these sections, it is recommended to put generic matches above specific ones because each input class can override settings from a previous one if an overlap occurs.

C.3.3.2. The `InputDevice` section

Each InputDevice section configures one input device for the X server. Previously, systems typically had at least one InputDevice section for the keyboard, and most mouse settings were automatically detected.

With Fedora 16, no InputDevice configuration is needed for most setups, and the xorg-x11-drv-* input driver packages provide the automatic configuration through HAL. The default driver for both keyboards and mice is evdev.

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

Section "InputDevice"
  Identifier "Keyboard0"
  Driver "kbd"
  Option "XkbModel" "pc105"
  Option "XkbLayout" "us"
EndSection

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. If the AutoAddDevices option is enabled (which is the default setting), any input device section with Driver "mouse" or Driver "kbd" will be ignored. This is necessary due to conflicts between the legacy mouse and keyboard drivers and the new evdev generic driver. Instead, the server will use the information from the back end for any input devices. Any custom input device configuration in the xorg.conf should be moved to the back end. In most cases, the back end will be HAL and the configuration location will be the /etc/X11/xorg.conf.d directory.
Option — Specifies necessary options pertaining to the device.
A mouse may also be specified to override any auto-detected values for the device. The following options are typically included when adding a mouse in the xorg.conf file:
- 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(5) man page for a complete list of valid options for this section.

C.3.3.3. The `ServerFlags` section

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 Section C.3.3.4, “ServerLayout” for details).

Each entry within the ServerFlags section occupies a single line and begins with the term Option followed by an option enclosed in double quotation marks (").

The following is a sample ServerFlags section:

Section "ServerFlags"
  Option "DontZap" "true"
EndSection

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.
X keyboard extension
Even if this option is enabled, the key combination still must be configured in the X Keyboard Extension (XKB) map before it can be used. One way how to add the key combination to the map is to run the following command:
```
setxkbmap -option "terminate:ctrl_alt_bksp"
```
"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.
"AutoAddDevices" "boolean" — When the value of <boolean> is set to false, the server will not hot plug input devices and instead rely solely on devices configured in the xorg.conf file. Refer to Section C.3.3.2, “The InputDevice section” for more information concerning input devices. This option is enabled by default and HAL (hardware abstraction layer) is used as a back end for device discovery.

C.3.3.4. `ServerLayout`

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

The following example shows a typical ServerLayout section:

Section "ServerLayout"
  Identifier "Default Layout"
  Screen 0 "Screen0" 0 0
  InputDevice "Mouse0" "CorePointer"
  InputDevice "Keyboard0" "CoreKeyboard"
EndSection

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 Section C.3.3.8, “The Screen section”.
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. If the AutoAddDevices option is enabled, this entry needs not to be specified in the ServerLayout section. If the AutoAddDevices option is disabled, both mouse and keyboard are auto-detected with the default values.
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(5) 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; as in the Xorg -layout <layoutname> command.

C.3.3.5. The `Files` section

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

The following example shows a typical Files section:

Section "Files"
  RgbPath "/usr/share/X11/rgb.txt"
  FontPath "unix/:7100"
EndSection

The following entries are commonly used in the Files section:

ModulePath — An optional parameter which specifies alternate directories which store X server modules.

C.3.3.6. The `Monitor` section

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

This example shows a typical Monitor section for a monitor:

Section "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
EndSection

The following entries are commonly 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(5) 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(5) man page.

C.3.3.7. The `Device` section

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 following example shows a typical Device section for a video card:

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

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 is required.
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(5) 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.

C.3.3.8. The `Screen` section

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 shows a typical Screen section:

Section "Screen"
  Identifier "Screen0"
  Device "Videocard0"
  Monitor "Monitor0"
  DefaultDepth 16

  SubSection "Display"
    Depth 24
    Modes "1280x1024" "1280x960" "1152x864" "1024x768" "800x600" "640x480"
  EndSubSection

  SubSection "Display"
    Depth 16
    Modes "1152x864" "1024x768" "800x600" "640x480"
  EndSubSection
EndSection

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 detected automatically.
DefaultDepth — Specifies the default color depth in bits. In the previous example, 16 (which provides thousands of colors) is the default. Only one DefaultDepth entry is permitted, although this can be overridden with the Xorg command line option -depth <n>, where <n> is any additional depth specified.
SubSection "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 detected automatically.
This subsection is normally used to override auto-detected 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(5) man page.

C.3.3.9. The `DRI` section

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 is rarely used, as the DRI Group and Mode are automatically initialized to default values. If a different Group or Mode is needed, then adding this section to the xorg.conf file will override the default values.

The following example shows a typical DRI section:

Section "DRI"
  Group 0
  Mode 0666
EndSection

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