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 conform to the new format. The basics of the new configuration mechanism in X are 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 from putting X.org-specific configuration content into udev rules files.

xorg.conf.d

The X server now supports the configuration directories /etc/X11/xorg.conf.d and /usr/share/X11/xorg.conf.d. The former is for user-specific configuration and the latter provides configurations by the distribution vendors. Changes to files in the latter directory may be overwritten. The following focuses on the user-specific configuration directory.

Files with the suffix .conf in this directory are parsed by the X server upon startup and treated like 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/X11/xorg.conf.d directory are parsed in-order before the xorg.conf has been parsed fully with 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 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 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.

Blacklisting a device

Some devices may get picked up by the X server when they 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

The information required for MatchIsPointer and other match keywords comes from /lib/udev/input-id. [1] It checks the capabilities of the device and assigns a number of variables, the server will then check those variables to determine a match. Check the output of "udevadm info --export-db | grep ID_INPUT" for the variables assigned to your input devices.

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 the default keyboard configuration (usually /etc/X11/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 be 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

Example: Tap-to-click

Tap-to-click can be enabled in the mouse configuration dialog (in the touchpad tab) but if you need tapping enabled at gdm, the following snippet will enable it for you:

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

Example: Axis inversion

Some devices, notably built-in touch tablets have their touch frame mounted in a rotated or inverted manner. For these devices, add the following snippet, adjusted to your device name (obtain this via xinput --list). Uncomment whichever is not approriate

Section "InputClass"
       Identifier "axis inversion"
       MatchProduct "device name substring"
       # swap x/y axes on the device. i.e. rotate by 90 degrees
       Option "SwapAxes" "on"
       # Invert the respective axis.
       Option "InvertX" "on"
       Option "InvertY" "on"
EndSection

The right combination of the settings can be run-time tested with the xinput command.

 # toggle axis swap
 $> xinput --set-prop "<device name>" "Evdev Axes Swap" 1
 # invert X, not Y
 $> xinput --set-prop "<device name>" "Evdev Axis Inversion" 1 0
 # invert Y, not X
 $> xinput --set-prop "<device name>" "Evdev Axis Inversion" 0 1

gdm and GNOME

GNOME keyboard configuration will overwrite the keyboard configuration set in the xorg.conf - once the login process completes. Thus, once a keyboard configuration is set in the GNOME session, changing the xorg.conf will have little effect on the keyboard layout.

On the other hand, a layout manually chosen in gdm will be transferred into the session as an additional keyboard layout. Thus, if you select "us" in gdm to log in and then "de" in the GNOME session, the effective keyboard layout for future sessions is "de,us". To avoid this, chose your default keyboard layout in gdm as well (see Bug 602145).

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 their 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 the device. Because of this notification system, some devices configured in 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 /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.

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 stated 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 important to review changes to the fdi files 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 by 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.