Input device configuration

Fedora 13

The following configuration guide applies to xorg-x11-server-Xorg >= 1.7.99.901-1. For earlier packages, please use the HAL configuration instructions.

Beginning with Fedora 13, the X server uses udev instead of HAL for input device detection and xorg.conf InputClass configuration. Thus, any HAL-specific configuration is deprecated and users with custom configurations in fdi files need to change these configurations to the new format. The basics of the new configuration mechanism in X is outlined below. Generally, users should not (need to) configure udev or add udev rules to enable device detection in X. While supported, users are discouraged of putting X.org-specific configuration into udev rules files.

xorg.conf.d

The X server now supports a configuration directory /etc/xorg.conf.d. Files with the suffix .conf in this directory are parsed by the X server on startup and treated like a part of the traditional xorg.conf configuration file. Files in this directory may contain one or more sections; for a description of the options in a section and the general layout please refer to xorg.conf(5). Files in the /etc/xorg.conf.d directory are parsed in-order before the xorg.conf has been parsed fully and precedence is given to the xorg.conf, then to the last configuration entry where applicable. The X server essentially treats the collection of configuration files as one big file with entries from xorg.conf at the end. Users are encouraged to put custom configuration into /etc/xorg.conf and leave the directory for configuration snippets provided by the distribution.

InputClasses

InputClasses are a new type of configuration section that does not apply to a single device but rather to a class of devices, including hotplugged devices. An InputClass section's scope is limited by the matches specified - to apply to an input device, all matches must apply to a device. An example InputClass section is provided below:

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

If this snippet is present in the xorg.conf or xorg.conf.d, any touchpad present in the system is assigned the synaptics driver. Note that due to precedence order (alphanumeric sorting of xorg.conf.d snippets) the Driver setting overwrites previously set driver options - the more generic the class, the earlier it should be listed. The default snippet shipped with the xorg-x11-drv-Xorg package is 00-evdev.conf and applies the evdev driver to all input devices.

The match options specify which devices a section may apply to. To match a device, all match lines must apply. The following match lines are supported (with examples):

• MatchIsPointer, MatchIsKeyboard, MatchIsTouchpad, MatchIsTouchscreen, MatchIsJoystick - boolean options to apply to a group of devices.
• MatchProduct "foo|bar": match any device with a product name containing either "foo" or "bar"
• MatchVendor "foo|bar|baz": match any device with a vendor string containing either "foo", "bar", or "baz"
• MatchDevicePath "/dev/input/event*": match any device with a device path matching the given patch (see fnmatch(3) for the allowed pattern)
• MatchTag "foo|bar": match any device with a tag of either "foo" or "bar". tags may be assigned by the config backend - udev in our case - to label devices that need quirks or special configuration.

An example section for user-specific configuration is:

Section "InputClass"
   Identifier     "lasermouse slowdown"
   MatchIsPointer "on"
   MatchProduct   "Lasermouse"
   MatchVendor    "LaserMouse Inc."
   Option         "ConstantDeceleration" 20
EndSection

This section would match a pointer device containing "Lasermouse" from "Lasermouse Inc." and apply a constant deceleration of 20 on this device - slowing it down by factor 20.

Some devices may get picked up by the X server when they really shouldn't be. These devices can be configured to be ignored:

Section "InputClass"
   Identifier     "no need for accelerometers in X"
   MatchProduct   "accelerometer"
   Option         "Ignore" "on"
EndSection

system-setup-keyboard

The system-setup-keyboard package (previously fedora-setup-keyboard) is a service running in runlevel 5 that watches for changes in /etc/sysconfig/keyboard. If a change occurs, it converts the information into an xorg.conf.d snippet that serves as default keyboard configuration (usually /etc/xorg.conf.d/00-system-setup-keyboard.conf). Do not edit the generated file as your changes will be overwritten whenever /etc/sysconfig/keyboard changes. If you want to change the default keyboard layout, simply rename the file and apply your custom options.

Example configurations

The following subsections describe example configurations for commonly used configuration options. Note that if you use a desktop environment such as GNOME or KDE, options you set in the xorg.conf may get overwritten with user-specific options upon login.

Example: Wheel Emulation (for a Trackpoint)

If you own a Computer with a Trackpoint (a Thinkpad for example) you can add the following to the xorg.conf to use the middle Button to emulate a mouse wheel:

Section "InputClass"
   Identifier     "Wheel Emulation"
   MatchIsPointer "on"
   MatchProduct   "TrackPoint"
   Option         "EmulateWheelButton" "2"
   Option "EmulateWheel" "on"
EndSection

Fedora 12 and earlier

The X servers provided in Fedora 9 and later use HAL to retrieve the list of input devices. Whenever the X server is started, it asks HAL for the list of input devices and adds each of them with the respective driver. Whenever a new input device is plugged in or an existing input device is removed, HAL notifies the X server about the presence or removal of this device. Because of this notification system, some devices configured in the xorg.conf are ignored by the X server (all devices using the 'mouse', 'kbd' or 'vmmouse' driver).

In addition to signaling the presence of the new device, HAL also provides the X server with a number of options for each device. Most notably, this includes the driver the server should load and the device file to open. It also allows for additional, user-specific configuration options.

Device configuration

Fedora provides a list of default configurations in /usr/share/hal/fdi/policies/10osvendor/10-x11-input.fdi and some driver-specific configurations in e.g. /usr/share/hal/fdi/policies/20thirdparty/10-synaptics.fdi. Do not edit these files directly, as they will be overwritten in the next update. Instead, copy the file into /etc/hal/fdi/policy first and then edit as appropriate. For example, the fdi for a synaptics touchpad may look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<deviceinfo version="0.2">
  <device>
    <match key="info.capabilities" contains="input.touchpad">
        <merge key="input.x11_driver" type="string">synaptics</merge>
        <merge key="input.x11_options.TapButton1" type="string">1</merge>
    </match>
  </device>
</deviceinfo>

The above XML file defines the following: If the device is a touchpad (HAL assigns this capability automatically), then load the synaptics X11 driver for this device. The key input.x11_driver is interpreted by the server. The second merge command states that the option TapButton1 with a value of '1' should be passed to the driver. Any input.x11_options key is interpreted by the driver and is equivalent to the traditional form of Option "Option name" "Option value" in the xorg.conf. The man page of the respective driver lists the available options. Note that any input.x11_options key must have the type 'string' even if it denotes a number. Other types will be ignored by the server.

The above HAL configuration to enable 'tap-to-click' can be migrated to the new Xorg configuration as follows:

Section "InputClass"
       Identifier "tap-by-default"
       MatchIsTouchpad "on"
       Option "TapButton1" "1"
EndSection

Merge commands are additive. For example, the fdi file provided by the xorg-x11-drv-synaptics package supplies the input.x11_driver key. User-specific configuration does not need to specify this key again and instead should only provide local configuration options (such as the TapButton1 setting above).

To remove an existing key, the following syntax may be used:

<?xml version="1.0" encoding="ISO-8859-1"?>
  <deviceinfo version="0.2">
    <device>
      <match key="input.product" contains="Random String">
         <remove key="input.x11_driver"></remove>
      </match>
     </device>
  </deviceinfo>

This snipped removes the input.x11_driver key from all devices that include the string "Random String". As said above, input.x11_driver is a special key and removing it prevents the X server from adding this device. The same syntax may be used to remove other options.

Reviewing configuration changes

In the extreme case, a misconfiguration of input drivers may result in an X server with no input devices. It is advisable that changes to the fdi files are reviewed before restarting the server to ensure that at least some devices are available.

After editing the fdi files, the HAL daemon can be restarted with service haldaemon restart. Once the restart is successful, lshal may be used to list all devices and their configurations. As a general rule, at least one keyboard device should have input.x11_driver set to 'evdev' to allow keyboard input if all other configurations fail.

Disabling the use of HAL

Some users wish to disable the use of HAL. The X server provides two options to achieve this:

• Option "AutoAddDevices" "false"

If this option is disabled, then no devices will be added from HAL events. Note that if this option is disabled, AllowEmptyInput is automatically disabled too unless explicitly enabled the user.

• Option "AllowEmptyInput" "false"

If AllowEmptyInput is false, the server checks the xorg.conf for core devices (Option "CorePointer" and Option "CoreKeyboard"). If none are present and referenced in the ServerLayout section, the server automatically adds the first mouse and keyboard device in the xorg.conf or (if neither are present) the hard-coded default input devices. Disabling AllowEmptyInput also forces the server to honor devices using the 'mouse', 'kbd' and 'vmmouse' drivers (these devices are ignored by default).

In most cases, simply disabling AutoAddDevices is the correct way to disable the use of HAL. Note that if AllowEmptyInput is off and AutoAddDevices is on, then devices may be added multiple times (once as specified in the xorg.conf, and once as listed by HAL). This leads to duplicate button presses and triplicate key presses.