Udev

Below is an example of a rule that creates a symlink /dev/video-cam when a webcamera is connected.

Let say this camera is currently connected and has loaded with the device name . The reason for writing this rule is that at the next boot, the device could show up under a different name, like .

To identify the webcamera, from the video4linux device we use and , then walking up two levels above, we match the webcamera using vendor and product ID's from the usb parent , and . Note that this matching is case sensitive, so can not be used to match the in this example.

We are now able to create a rule match for this device as follows:

Here we create a symlink using but we could easily set user or group using or set the permissions using .

If you intend to write a rule to do something when a device is being removed, be aware that device attributes may not be accessible. In this case, you will have to work with preset device environment variables. To monitor those environment variables, execute the following command while unplugging your device:

In this command's output, you will see value pairs such as and , which match the previously used attributes and . A rule that uses device environment variables instead of device attributes may look like this:

To get a list of all of the attributes of a device you can use to write rules, run this command:

Replace with the device present in the system, such as or .

If you do not know the device name you can also list all attributes of a specific system path:

To narrow down the search for a device, figure out the class and run:

You can use the symlink outright or what it points as the input to . For example:

To get the path of a bare USB device which does not populate any subordinate device you have to use the full USB device path. Start monitor mode and then plug in the USB device to get it:

You can just choose the deepest path and will show all parent's attributes anyway:

This will not perform all actions in your new rules but it will however process symlink rules on existing devices which might come in handy if you are unable to load them otherwise. You can also directly provide the path to the device you want to test the udev rule for:

udev automatically detects changes to rules files, so changes take effect immediately without requiring udev to be restarted. However, the rules are not re-triggered automatically on already existing devices. Hot-pluggable devices, such as USB devices, will probably have to be reconnected for the new rules to take effect, or at least unloading and reloading the ohci-hcd and ehci-hcd kernel modules and thereby reloading all USB drivers.

is used to only match against a device when something specific is happening, usually when it is appearing or disappearing. There are eight types of actions that can be raised for udev rules to match against:

The change action is somewhat special, because not all drivers use it the same way, if at all. A change event is only emitted as a result of the driver manually raising a userspace event (or uevent) of type . This normally signals that something has happened to that device, but it takes some additional information to determine what exactly.

Since that event is only raised under a limited number of situations, here is a (best-effort, non-exhaustive) list of subsystems that do raise change events, and under what conditions.

Device attributes, listed as (or for parent devices) in udev rules and , correspond to all the device information that is made available through sysfs, which exposes information from the "kobject" classes used by the kernel to keep track of device state. This means that there is no need for udev-specific tools to examine these, and that a simple or is all that is needed to explore device attributes, and some can even be changed with something like . It is, however, a lot more conveinient to use , which has the advantage of showing all matchable attributes for that device all at once in the same format that udev rules expect (as well as the attributes for any parent devices, also in their readily usable format).

Most of these attributes have well-documented meanings, behaviors and accepted values based on what kernel submodule is handling the device, such as sysfs-bus-usb for USB devices and sysfs-class-typec for USB type-C ports, for instance. Other attributes are present as subtrees, such as sysfs-devices-physical_location or sysfs-devices-power, which use slashes to separate levels, just like directories, giving .

The "environment" of an event is a set of device properties and event properties (and rarely global properties), both written as in udev rules and both reported as by and (without ). Despite being called "environment", they have nothing to do with environment variables (although they do get passed as environment variables to programs started by ). These contain context information added to an event by the kernel module or other udev rules to make that information available to downstream rules or components. The only difference between event properties and device properties is that devices properties are stored and can be examined with , whereas event properties are transient and can only be seen if the event is caught by . A lot of device properties are also available as device attributes with similar names.

Unlike with attributes, udev rules are allowed to set event properties arbitrarily, and there is also no concept of "parent properties" to inspect beyond the ones that are set on the event (which is why there is no directive). Note that setting a property with a udev rule sets a device property, which will be stored until the device is removed and will thus appear in every event raised by that device (unless the property's name starts with a period, like }, which will be added to the event properties with the leading dot in the name and be usable by other rules, but not stored).

This device could be matched with the following hwdb rule:

Suppose we want to remap a couple of common keys for all AT keyboards:

This creates , which takes precedence over the existing . Upon system upgrade, both files will be automatically kept up-to-date with the same contents:

You can check that your configuration was loaded either by pressing keys, or by running . For the USB keyboard in the above example, this outputs the mapping we configured as follows:

Programs started by udev will block further events from that device, and any tasks spawned from a udev rule will be killed after event handling is completed. If you need to spawn a long-running process with udev, the intended way is to have a systemd unit which handles running the actual command, and a udev rule that merely signals that this unit should run. However, using in a udev rule is discouraged, since it is meant for user interaction and may block, among other things.

The correct way of doing this is to have the rule tag the device as needing a systemd device unit (see systemd.device(5)) using and adding an device property of either for services that would run with or for services that should run with . For example:

is equivalent to the directive elsewhere in systemd, meaning the device will not be affected if the service fails, does not exists, or completes successfully at any point.

When a kernel driver initializes a device, the default state of the device node is to be owned by , with permissions . [2] This makes devices inaccessible to regular users unless the driver changes the default, or a udev rule in user space changes the permissions.

The , , and udev values can be used to provide access, though one encounters the issue of how to make a device usable to all users without an overly permissive mode. Ubuntu's approach is to create a group that devices are added to, but this practice is not only discouraged by the systemd developers, [3] but considered a bug when shipped in udev rules on Arch (FS#35602) and broken starting from systemd 258 [4][5]. Another approach historically employed, as described in Users and groups#Pre-systemd groups, is to have different groups corresponding to categories of devices.

If your eSATA drive is not detected when you plug it in, there are a few things you can try. You can reboot with the eSATA plugged in. Or you could try:

If you connected an eSATA bay or another eSATA adapter, the system will still recognize this disk as an internal SATA drive. GNOME and KDE will ask you for your root password all the time. The following rule will mark the specified SATA-Port as an external eSATA-Port. With that, a normal GNOME user can connect their eSATA drives to that port like a USB drive, without any root password and so on.

A udev rule can be useful to enable the wakeup triggers of a USB device, like a mouse or a keyboard, so that it can be used to wake the system from sleep.

First, identify the vendor and product identifiers of the USB device. They will be used to recognize it in the udev rule. For example:

Then, find where the device is connected to using:

Now create the rule to change the attribute of both the device and the USB controller it is connected to whenever it is added:

USB devices need to be reset after exiting a suspended state (whether from the system resuming from sleep or from a port being turned off when the device was idle for power saving), which the Linux kernel handles mostly transparently in a process called reset-resume, so that USB drives do not look like they have been disconnected and reconnected every time. This is mostly desirable, but some devices, like USB TTY interfaces, do need to be manually reconfigured after being power cycled, which is not signalled by any uevent from the relevent drivers.

The one uevent that does get raised, however, is the one from losing and regaining power/wakeup, since USB devices are unusable while unconfigured and would be unable to wake up the system from sleep in this state. These two events have no unique event properties, but the first one can still be easily identified because is set to zero (which is not a valid device number) immediately before the device is unconfigured and loses , raising the uevent. When that happens, one can simply touch the sysfs attribute to force the system to reconfigure the device non-transparently, as if it had been disconnected during sleep, which unbinds all drivers and removes all children devices before adding them back when the device is ready again.

It can be useful to trigger various udev events. For example, you might want to simulate a USB device disconnect on a remote machine. In such cases, use :

This command will trigger a USB remove event on all USB devices with vendor ID .

In rare cases, udev can make mistakes and load the wrong modules. To prevent it from doing this, you can blacklist modules. Once blacklisted, udev will never load that module - not at boot-time and not even later on when a hot-plug event is received (e.g., you plug in your USB flash drive).

After migrating to LDAP or updating an LDAP-backed system, udevd can hang at boot at the message "Starting UDev Daemon". This is usually caused by udevd trying to look up a name from LDAP but failing, because the network is not up yet. The solution is to ensure that all system group names are present locally.

When xrandr or another X-based program tries to connect to an X server, it falls back to a TCP connection on failure. However, due to in the systemd-udev service configuration, this hangs. Eventually the program will be killed and event processing will resume.

If the rule is for a drm device and the hang causes event processing to complete once the X server has started, this can cause 3D acceleration to stop working with a error.