Skip to content
Search

Xorg.conf

lastmod 2020-09-07created 2020-09-0534 edits

configuration files for Xorg X server

Categories

Introduction

Xorg supports several mechanisms for supplying/obtaining configuration and run-time parameters: command-line options, environment variables, the xorg.conf and xorg.conf.d configuration files, auto-detection, and fallback defaults. When the same information is supplied in more than one way, the highest-precedence mechanism is used. The list of mechanisms is ordered from highest precedence to lowest. Not all parameters can be supplied via all methods. The available command-line options and environment variables (and some defaults) are described in the Xserver(1) and Xorg(1) manual pages. Most configuration file parameters, with their defaults, are described below. Driver- and module-specific configuration parameters are described in the relevant driver or module manual pages.

Configuration files

Xorg uses a configuration file called xorg.conf and files ending in the suffix .conf from the xorg.conf.d directory for its initial setup. The xorg.conf configuration file is searched for in the following places when the server is started as a normal user.

  • /etc/X11/<cmdline>
  • /usr/etc/X11/<cmdline>
  • /etc/X11/$XORGCONFIG
  • /usr/etc/X11/$XORGCONFIG
  • /etc/X11/xorg.conf
  • /etc/xorg.conf
  • /usr/etc/X11/xorg.conf.<hostname>
  • /usr/etc/X11/xorg.conf
  • /usr/lib/X11/xorg.conf.<hostname>
  • /usr/lib/X11/xorg.conf

Here, <cmdline> is a relative path (with no .. components) specified with the -config command-line option, $XORGCONFIG is the relative path (with no .. components) specified by that environment variable, and <hostname> is the machine's hostname as reported by gethostname(3).

When the Xorg server is started by the "root" user, the configuration file search locations are as follows.

  • <cmdline>
  • /etc/X11/<cmdline>
  • /usr/etc/X11/<cmdline>
  • $XORGCONFIG
  • /etc/X11/$XORGCONFIG
  • /usr/etc/X11/$XORGCONFIG
  • /etc/X11/xorg.conf
  • /etc/xorg.conf
  • /usr/etc/X11/xorg.conf.<hostname>
  • /usr/etc/X11/xorg.conf
  • /usr/lib/X11/xorg.conf.<hostname>
  • /usr/lib/X11/xorg.conf

When the server is started as a normal user, additional configuration files are searched for in the following directories.

  • /etc/X11/<cmdline>
  • /etc/X11/<cmdline>
  • /etc/X11/xorg.conf.d
  • /etc/X11/xorg.conf.d

When the Xorg server is started by the "root" user, the config directory search locations are as follows.

  • <cmdline>
  • /etc/X11/<cmdline>
  • /etc/X11/<cmdline>
  • /etc/X11/xorg.conf.d
  • /etc/X11/xorg.conf.d

Finally, configuration files are also searched for in directories reserved for system use. This is to separate configuration files from vendors or third-party packages from those of local administration. These files are found in the following directories.

  • /usr/share/X11/xorg.conf.d

Sections

The xorg.conf and xorg.conf.d files are composed of a number of sections, which may be present in any order or omitted in order to use default configuration values.

Each section has the following form: 

Section "SectionName"
    SectionEntry
    ...
EndSection

The section names are:

  • Files: File pathnames
  • ServerFlags: Server flags
  • Module: Dynamic module loading
  • Extensions: Extension enabling
  • InputDevice: Input device description
  • InputClass: Input class description
  • OutputClass: Output class description
  • Device: Graphics device description
  • VideoAdaptor: Xv video adaptor description
  • Monitor: Monitor description
  • Modes: Video modes descriptions
  • Screen: Screen configuration
  • ServerLayout: Overall layout
  • DRI: DRI-specific configuration
  • Vendor: Vendor-specific configuration

The following obsolete section names are still recognized for compatibility purposes. In new configuration files, the InputDevice section should be used instead.

  • Keyboard: Keyboard configuration
  • Pointer: Pointer/mouse configuration

The old XInput section is no longer recognized.

  • The ServerLayout section is at the highest level.
  • It binds together the input and output devices that will be used in a session.
  • Input devices are described in InputDevice sections.
  • Output devices usually consist of multiple independent components (e.g., a graphics board and a monitor).
  • These multiple components are bound together in a Screen section, and it is this that is referenced by the ServerLayout section.
  • Each Screen section binds together a graphics board and a monitor.
  • Graphics boards are described in Device sections, and monitors are described in Monitor sections.

Configuration file keywords are case-insensitive, and _ characters are ignored. Most strings (including option names) are also case-insensitive and insensitive to white space and _ characters.

Each configuration file entry usually takes up a single line in the file. A keyword may be followed by one or more arguments, with the number and types of the arguments depending on the keyword. The argument types are:

  • Integer: an integer number in decimal, hex or octal
  • Real: a floating point number
  • String: a string enclosed in double quote marks (")

Note: Hexadecimal integer values must be prefixed with ``0x``, and octal values with ``0``.

A special keyword called Option may be used to provide free-form data to various components of the server. The Option keyword takes either one or two string arguments. The first is the option name, and the optional second argument is the option value. Some commonly used option value types are:

  • Integer: an integer number in decimal, hex or octal
  • Real: a floating point number
  • String: a sequence of characters
  • Boolean: a boolean value (see below)
  • Frequency: a frequency value (see below)

All option values, not just strings, must be enclosed in quotes.

Boolean options may optionally have a value specified. When no value is specified, the option's value is TRUE. The following boolean option values are recognized as TRUE.

  • 1, on, true, yes

The following boolean option values are recognized as FALSE:

  • 0, off, false, no

If an option name is prefixed with No, the option value is negated.

For example, the following option entries are equivalent:

  • Option "Accel" "Off"
  • Option "NoAccel"
  • Option "NoAccel" "On"
  • Option "Accel" "false"
  • Option "Accel" "no"

Frequency option values consist of a real number that is optionally followed by one of the following frequency units.

  • Hz, k, kHz, M, MHz

When the unit name is omitted, the correct units will be determined from the value and the expectations of the appropriate range of the value. It is recommended that the units always be specified when using frequency option values to avoid any errors in determining the value.

Files

The Files section is used to specify some path names required by the server. Some of these paths can also be set from the command line (see Xserver(1) and Xorg(1)). The command-line settings override the values specified in the configuration file. The Files section is optional, as are all of the entries that may appear in it.

FontPath "path"
Sets the search path for fonts. This path is a comma-separated list of font path elements which the Xorg server searches for font databases.
  • Catalogue directories: <identifier>:[attribute]:pri=<priority>
    • Here, <identifier> is an alphanumeric identifier,
    • [attribute] is an attribute which will be passed to the underlying FPE, and
    • <priority> is a number used to order the font file FPEs.
  • Font server identifiers: <trans>/<hostname>:<port-number>
    • Here, <trans> is the transport type to use to connect to the font server
    • e.g.: unix for UNIX-domain sockets, tcp for a TCP / IP connection
    • <hostname> is the hostname of the machine running the font server.
    • <port-number> is the port number that the font server is listening on (usually 7100).
ModulePath "path"
Sets the search path for loadable Xorg server modules.
XkbDir "path"
Sets the base directory for keyboard layout files. This can be overridden with the -xkbdir command-line option.

ServerFlags

In addition to the options specific to this section (described below), the ServerFlags section is used to specify some global Xorg server options. All of the entries in this section are Options, although for compatibility purposes some of the old style entries are still recognized. Those old style entries are not documented here, and using them is discouraged. The ServerFlags section is optional, as are the entries that may be specified in it.

Options specified in this section (with the exception of the DefaultServerLayout option) may be overridden by options specified in the active ServerLayout section. Options with command-line equivalents are overridden when their command-line equivalent is used. The options recognized by this section are:

Module

The Module section is used to specify which Xorg server modules should be loaded. This section is ignored when the Xorg server is built in static form. The types of modules normally loaded in this section are Xorg server extension modules. Most other module types are loaded automatically when they are needed via other mechanisms. The Module section is optional, as are all of the entries that may be specified in it.

Entries in this section may be in two forms. The first and most commonly used form is an entry that uses the Load keyword, as described here.

Extensions

The Extensions section is used to specify which X11 protocol extensions should be enabled or disabled. The Extensions section is optional, as are all of the entries that may be specified in it.

Entries in this section are listed as Option statements with the name of the extension as the first argument and a boolean value as the second. The extension name is case-sensitive and matches the form shown in the output of Xorg -extension ?.

e.g.: The MIT-SHM extension can be disabled with the following entry. 

Section "Extensions"
    Option "MIT-SHM" "Disable"
EndSection

InputDevice

The config file may have multiple InputDevice sections. Recent X servers employ HAL or udev backends for input device enumeration and input hotplugging. When hotplugging is in use (i.e., AutoAddDevices is enabled), it is usually not necessary to provide InputDevice sections in xorg.conf. If hotplugging is enabled, InputDevice sections using the mouse, kbd, and vmmouse drivers are ignored.

InputClass

The config file may have multiple InputClass sections. These sections are optional and are used to provide configuration for a class of input devices as they are automatically added. An input device can match more than one InputClass section. Each class can override settings from a previous class, so it is best to arrange the sections with the most generic matches first.

OutputClass

The config file may have multiple OutputClass sections. These sections are optional and are used to provide configuration for a class of output devices as they are automatically added. An output device can match more than one OutputClass section. Each class can override settings from a previous class, so it is best to arrange the sections with the most generic matches first.

Device

The config file may have multiple Device Sections. There must be at least one, for the video card being used.

The format is: 

Section "Device"
    Identifier "name"
    Driver     "driver"
    entries
    ...
EndSection

The Identifier and Driver entries are required in all Device Sections. All other entries are optional.

  • Identifier: Specifies a unique name for this graphics device.
  • Driver: Specifies the name of the driver to use for this graphics device.

When using a loadable server, the driver module "driver" will be loaded for each active Device section. A Device Section is considered active if it is referenced by an active Screen section.

Device sections recognize some driver-independent entries and options, which are described here. Not all drivers make use of these driver-independent entries, and many of those that do don't require them to be specified because the information is auto-detected. See the individual graphics driver manual pages for further information about this, and for a description of the device-specific options. Most of the options listed here (but not the other entries) may be specified in the Screen Section instead of here in the Device Section.

  • BusID "bus-id"
  • Screen number
  • Chipset "chipset"
  • Ramdac "ramdac-type"
  • DacSpeed speed
  • DacSpeed speed-8 speed-16 speed-24 speed-32
  • Clocks clock ...
  • ClockChip "clockchip-type"
  • VideoRam mem
  • MemBase baseaddress
  • IOBase baseaddress
  • ChipID id
  • ChipRev rev
  • MatchSeat seat-id
  • Option "ModeDebug" "boolean"
  • Option "PreferCloneMode" "boolean"
  • Options

Monitor

The config file may have multiple Monitor sections. There should normally be at least one, for the monitor being used, but a default configuration will be created when one isn't specified.

Modes

The config file may have multiple Modes sections, or none. These sections provide a way of defining sets of video modes independently of the Monitor sections. Monitor sections may include the definitions provided in these sections by using the UseModes keyword. In most cases the Modes sections are not necessary because the built-in set of VESA standard modes will be sufficient.

Screen

The config file may have multiple Screen sections. There must be at least one, for the "screen" being used. A "screen" represents the binding of a graphics device (Device section) and a monitor (Monitor section). A Screen section is considered "active" if it is referenced by an active ServerLayout section or by the -screen command-line option. If neither of those is present, the first Screen section found in the config file is considered the active one.

SubSection "Display"

Each Screen section may have multiple Display subsections. The "active" Display subsection is the first that matches the depth and/or fbbpp values being used, or failing that, the first that has neither a depth nor an fbbpp value specified. The Display subsections are optional. When there isn't one that matches the depth and/or fbbpp values being used, all the parameters that can be specified here fall back to their defaults.

Display subsections have the following format: 

SubSection "Display"
    Depth  depth
    entries
    ...
EndSubSection

ServerLayout

The config file may have multiple ServerLayout sections. A "server layout" represents the binding of one or more screens (Screen sections) and one or more input devices (InputDevice sections) to form a complete configuration. In multi-head configurations, it also specifies the relative layout of the heads. A ServerLayout section is considered "active" if it is referenced by the -layout command-line option or by an Option "DefaultServerLayout" entry in the ServerFlags section (the former takes precedence over the latter). If those options are not used, the first ServerLayout section found in the config file is considered the active one. If no ServerLayout sections are present, the single active screen and two active (core) input devices are selected as described in the relevant sections above.

DRI

This optional section is used to provide some information for the Direct Rendering Infrastructure. Details about the format of this section can be found online at http://dri.freedesktop.org/.

Default config file

Example of automatically generating the X.org configuration file: 

$ Xorg -configure

A new file is created with the filename xorg.conf.new.

Simple tutorials

A simple configuration is set up as follows. 

Section "ServerLayout"
    Identifier "single head configuration"
    Screen 0 "Screen0" 0 0
    InputDevice "Mouse0" "CorePointer"
    InputDevice "Keyboard0" "CoreKeyboard"
EndSection

The ServerLayout section configures how input devices such as the keyboard and mouse are assigned to a single screen. The Identifier option sets the name of the ServerLayout. Screen sets the name of the Screen section configured in the xorg.conf file: Screen0 is the Screen section name, the number 0 on the left means that the video card head (monitor connector) uses the Screen0 identifier specified in the Screen section, and the two 0s on the right indicate the monitor position. InputDevice specifies the names used in the InputDevice sections; the mouse and keyboard input device names follow it respectively, and after each input device the CorePointer option is used for the mouse and the CoroeKeyboard option for the keyboard. 

Section "MOdule"
    Load "dbe"
    Load "extmod"
    Load "glx"
    Load "dri"
    Load "v41"
EndSection

Just add the settings for the relevant modules. Also, if a module is supported by the X server but does not work because it is missing from this section, just add it to this section. 

Section "InputDevice"
    Identifier "Mouse0"
    Driver "mouse"
    Option "Protocol" "IMPS/2"
    Option "Device" "/dev/input/mice"
    Option "ZAxisMapping" "4 5"
    Option "Emulate3Buttons" "no"
EndSection

The InputDevice section configures input devices such as the mouse and keyboard. Identifier is the name of the input device and is used the same way in ServerLayout. Driver sets the device driver name for that input device. For a keyboard the "Keyboard" driver name is used, and for a mouse the "mouse" driver name is used. Option sets additional options needed by the input device. For a mouse, the protocol is usually PS/2, but to use wheel mouse functionality you must add the "IMPS/2" option value and the ZAxisMapping option value.

Device refers to the device name used by that input device. For a mouse, the /dev/input/mice and /dev/psaux devices can be used. Among the mouse options, Emulate3Buttons is used when you want to get the effect of the middle button of a 3-button mouse on a 2-button mouse by pressing both buttons at the same time. Since the X server works on the basis of a 3-button mouse, this is a useful option for 2-button mice.

For a 105-key keyboard, use the usual InputDevice section settings. 

Section "InputDevice"
    Identifier "keyboard0"
    Driver "kbd"
    Option "XkbRules" "xfree86"
    Option "XkbModel" "pc105"
    Option "xkbLayout" "us"
EndSection

Section "Monitor"
    Identifier "Monitor0"
    VendorName "Generic"
    ModelName "Flat Panel 1920x1080"
    HorizSync 31.5~67.0
    VertRefresh 56.0~65.0
EndSection

The Monitor section sets the monitor specifications and is the most important part of the X server configuration. If the frequencies are set incorrectly, X may fail to start with an out-of-range frequency message, and settings far beyond the frequency range can even damage the monitor, so be careful. In this case, it is best to configure it by referring to the monitor manual. Identifier takes the monitor's identifying name, and VendorName sets the manufacturer name. ModelName takes the monitor's model name. For HorizSync and VertRefresh, enter the exact horizontal and vertical frequency ranges of the monitor. 

Section "Device"
    Identifier "Videocard0"
    Driver "nvidia"
    Option "dpms"
EndSection

The Device section sets the video card driver. Identifier takes an identifying name for the video card, and Driver sets the driver name for that video card. Please refer to the site to see which driver your video card uses.

See xorg.drivers.

Option takes the options supported for the monitor. dpms (Display Power Management Signaling) is an option for the monitor's advanced power-saving feature; since today's monitors support this feature, it is a good idea to add the option. 

Section "Screen"
    Identiifier "Screen0"
    Device "Videocard0"
    Monitor "Monitor0"
    DefaultDepth 24
    Subsection "Display"
    Depth 24
    modes "1280x1024" "1024x768" "800x600"
    EndSubsection
EndSection

The Screen section sets the resolution the X server will use, through the identifiers of the Device and Monitor sections covered so far. Identifier specifies a name that identifies the screen, and the Device and Monitor settings are set to the same values as the identifiers of the Device section and Monitor section. DefaultDepths sets the default color bit depth to use. This is the color bit depth the X server uses when it starts, out of the several bit depths set in the Subsection. In the Subsection, you can set resolutions to match several color bit depths. The subsection value used here is 'Display'. With color bit depths set to 24-bit and 16-bit, setting DefaultDepth to the desired color bit depth lets X run with that color bit depth when it starts, and lets it run at the resolution set first for that bit depth. Among the resolutions set with Modes, the first one is used at startup, and while X is running you can cycle through the resolutions using [Ctrl]+[Alt] and the + key to use X at the resolution you want.

Dummy video

Example

Resolution settings 

Section "Device"
  Identifier  "RadeonHD 4550"
  Option      "Monitor-DVI-0" "DVI screen"
EndSection
Section "Monitor"
  Identifier  "DVI screen"
  Option      "PreferredMode" "1440x900"
EndSection

Multiple monitors 

Section "Device"
  Identifier "RadeonHD 4550"
  Option     "Monitor-DVI-0" "DVI screen"
  Option     "Monitor-VGA-0" "VGA screen"
EndSection
Section "Monitor"
  Identifier "DVI screen"
EndSection
Section "Monitor"
  Identifier "VGA screen"
  Option     "RightOf" "DVI screen"
EndSection

Keyboard settings 

Section "InputClass"
        Identifier "keyboard-all"
        Driver "evdev"
        Option "XkbLayout" "us,cz"
        Option "XkbModel" "logitech_g15"
        Option "XkbRules" "xorg"
        Option "XkbOptions" "grp:alt_shift_toggle,grp:switch,grp_led:scroll,compose:rwin,terminate:ctrl_alt_bksp"
        Option "XkbVariant" ",qwerty"
        MatchIsKeyboard "on"
EndSection

See also

Favorite site

References

  1. Xorg_-ArchWiki-_20200806.pdf ↩

author Zer0 sitemap