Input device configuration

Generally, users are encouraged to use the desktop-specific configuration tools (e.g. gnome-control-center). For options that are not exposed by the desktop environment, an xorg.conf.d InputClass config snippet is the best approach.

xorg.conf.d

The X server 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/X11/xorg.conf and leave the directory for configuration snippets provided by the distribution.

InputClasses

InputClasses apply 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           "libinput"
EndSection

If this snippet is present, any touchpad is assigned the libinput 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. 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.

Wacom devices special requirements

Devices handled by xorg-x11-drv-wacom have some special requirements to configuration. This driver will create multiple X devices from a single kernel device. All devices are configurable, but the driver adjusts the name to reflect the tool. For example, a "Wacom Intuos4 6x9" (kernel name) will show up as "Wacom Intuos4 6x9 stylus", "Wacom Intuos4 6x9 eraser", etc. For xorg.conf.d snippets, the "stylus" can not be matched, it is applied after the server sees the device. You may match on "eraser" and other tools.

If you have a specific configuration that should only apply to the stylus but not other devices, you must configure several configuration snippets, one matching on "Wacom Intuos4 6x9" to apply the stylus setting and others that unset that setting for the other devices.

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

systemd-localed

In F18 and later systemd-localed is in charge of setting keyboard layouts. The main file is /etc/vconsole.conf and any changes to this file will be reflected in /etc/X11/xorg.conf.d/00-keyboard.conf. Note that changes to the system-wide layout will not apply until X is restarted. Use localectl to change the keyboard settings. For example, to change the default layout to us with the terminate server option, use:

 localectl set-x11-keymap "us" "" "" "terminate:ctrl_alt_bksp"

The arguments are layout, model, variant, options and any empty argument is simply ignored (in this case model and variant).

You can check if systemd-localed is running with the command

 systemctl status systemd-localed.service

system-setup-keyboard

For Fedora 18 and later, see #systemd-localed.

Until Fedora 17, 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. Note that the configuration files are driver-specific.

Example: Wheel Emulation (for a Trackpoint)

This option applies to xorg-x11-drv-evdev only. Wheel emulation is available by default with xorg-x11-drv-libinput.

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:

# For xorg-x11-drv-libinput
Section "InputClass"
       Identifier "tap-by-default"
       MatchIsTouchpad "on"
       MatchDriver "libinput"
       Option "Tapping" "on"
EndSection

# For xorg-x11-drv-synaptics
Section "InputClass"
       Identifier "tap-by-default"
       MatchIsTouchpad "on"
       MatchDriver "synaptics"
       Option "TapButton1" "1"
EndSection

Example: ClickPad enablement

This option applies to xorg-x11-drv-synaptics only. It is not needed under xorg-x11-drv-libinput which auto-detects clickpads.

Many newer laptops have so-called ClickPads, touchpads without physical buttons. Instead, the whole touchpad works as a button. Examples for such touchpads are found on the Lenovo x220 series and Apple laptops. ClickPads are only supported on Fedora 17 and later [2] ClickPad devices are detected automatically but in case your device isn't, the snippet below enables it.

Section "InputClass"
       Identifier "force clickpad"
       MatchProduct "device name substring"
       Option "ClickPad" "on"
       # Enable bottom right half as right button
       Option "SoftButtonAreas" "50% 0 82% 0 0 0 0 0"
EndSection

Example: Axis inversion

This option applies to xorg-x11-drv-evdev only.

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).

Solution for the gdm overruling Xorg settings has been developed with Custom input device configuration in GNOME. One can then set the dconf setting org.gnome.settings-daemon.peripherals.input-devices hotplug-command to the full pathname of the custom script which is run on every input device event. Example how to make Yubikey always with "us" layout (even though the rest of the system is non-US) has been presented at this blogpost.

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.