udev

Related articles
Kernel
Linux firmware
udisks
udev
(
user space
/dev
) is a user space system that enables the operating system administrator to register user space handlers for events. The events received by
udev
's daemon are mainly generated by the
Linux kernel
in response to physical events relating to peripheral devices.
As such,
udev
's main purpose is to act upon peripheral detection and hot-plugging, including actions that return control to the kernel, e.g. loading
kernel modules
or device
firmware
. Another component of this detection is adjusting the permissions of the device to be accessible to non-root users and groups.
udev
manages device nodes in the
/dev
directory by adding, symlinking and renaming them.
Note
The kernel module loading order is not preserved across boots
, because
udev
handles separate events concurrently (in parallel). For example, if a machine has multiple block devices, device nodes may change designations between reboots—i.e.
/dev/sda
may on next boot become
/dev/sdb
.
Tip
Rely on
…/by-id/…
,
…/by-path/…
,
…/by-uuid/…
and similar persistent identifiers.
Installation
udev
is part of
systemd
and thus installed by default. See
systemd-udevd.service(8)
for more information.
Introduction to udev rules
udev
rules written by the administrator go in
/etc/udev/rules.d/
, their file name has to end with
.rules
. The
udev
rules shipped with various packages are found in
/usr/lib/udev/rules.d/
. If there are two files by the same name under
/usr/lib
and
/etc
, the ones in
/etc
take precedence.
To learn about
udev
rules, refer to the
udev(7)
manual. Also see
Writing udev rules
and some practical examples are provided within the guide:
Writing udev rules - Examples
.
Example
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
/dev/video2
. The reason for writing this rule is that at the next boot, the device could show up under a different name, like
/dev/video0
.
$ udevadm info --attribute-walk --path=$(udevadm info --query=path --name=/dev/video2)
Udevadm info starts with the device specified by the devpath and then walks up the chain of parent devices.
It prints for every device found, all possible attributes in the udev rules key format.
A rule to match, can be composed by the attributes of the device and the attributes from one single parent device.

looking at device '/devices/pci0000:00/0000:00:04.1/usb3/3-2/3-2:1.0/video4linux/video2':
  KERNEL=="video2"
  SUBSYSTEM=="video4linux"
   ...
looking at parent device '/devices/pci0000:00/0000:00:04.1/usb3/3-2/3-2:1.0':
  KERNELS=="3-2:1.0"
  SUBSYSTEMS=="usb"
  ...
looking at parent device '/devices/pci0000:00/0000:00:04.1/usb3/3-2':
  KERNELS=="3-2"
  SUBSYSTEMS=="usb"
  ATTRS{idVendor}=="05a9"
  ATTRS{manufacturer}=="OmniVision Technologies, Inc."
  ATTRS{removable}=="unknown"
  ATTRS{idProduct}=="4519"
  ATTRS{bDeviceClass}=="00"
  ATTRS{product}=="USB Camera"
  ...
To identify the webcamera, from the
video4linux
device we use
KERNEL=="video2"
and
SUBSYSTEM=="video4linux"
, then walking up two levels above, we match the webcamera using vendor and product ID's from the usb parent
SUBSYSTEMS=="usb"
,
ATTRS{idVendor}=="05a9"
and
ATTRS{idProduct}=="4519"
. Note that this matching is case sensitive, so
"05A9"
can not be used to match the
idVendor
in this example.
We are now able to create a rule match for this device as follows:
/etc/udev/rules.d/83-webcam.rules
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="05a9", ATTRS{idProduct}=="4519", SYMLINK+="video-cam"
Here we create a symlink using
SYMLINK+="video-cam"
but we could easily set user
OWNER="john"
or group using
GROUP="video"
or set the permissions using
MODE="0660"
.
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:
$ udevadm monitor --property --udev
In this command's output, you will see value pairs such as
ID_VENDOR_ID
and
ID_MODEL_ID
, which match the previously used attributes
idVendor
and
idProduct
. A rule that uses device environment variables instead of device attributes may look like this:
/etc/udev/rules.d/83-webcam-removed.rules
ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="05a9", ENV{ID_MODEL_ID}=="4519", RUN+="
/path/to/your/script
"
List the attributes of a device
To get a list of all of the attributes of a device you can use to write rules, run this command:
$ udevadm info --attribute-walk --name=
device_name
Replace
device_name
with the device present in the system, such as
/dev/sda
or
/dev/ttyUSB0
.
If you do not know the device name you can also list all attributes of a specific system path:
$ udevadm info --attribute-walk --path=/sys/class/backlight/acpi_video0
To narrow down the search for a device, figure out the class and run:
$ ls /dev/
class
/by-id
You can use the symlink outright or what it points as the input to
--name
. For example:
$ udevadm info --attribute-walk --name=/dev/input/by-id/usb-foostan_Corne-event-kbd
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:
$ udevadm monitor
...
KERNEL[26652.638931] add      /devices/pci0000:00/0000:00:01.2/0000:02:00.0/0000:03:05.0/0000:05:00.0/usb1/1-3 (usb)
KERNEL[26652.639153] add      /devices/pci0000:00/0000:00:01.2/0000:02:00.0/0000:03:05.0/0000:05:00.0/usb1/1-3/1-3:1.0 (usb)
...
You can just choose the deepest path and
--attribute-walk
will show all parent's attributes anyway:
$ udevadm info --attribute-walk --path=
/devices/pci0000:00/0000:00:01.2/0000:02:00.0/0000:03:05.0/0000:05:00.0/usb1/1-3/1-3:1.0
Testing rules before loading
# udevadm test $(udevadm info --query=path --name=
device_name
) 2>&1
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:
# udevadm test /sys/class/backlight/acpi_video0/
Loading new rules
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.
If rules fail to reload automatically:
# udevadm control --reload
To manually force
udev
to trigger your rules:
# udevadm trigger
Components of udev rules
Action matching
ACTION==""
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:
add/remove
When device nodes (in
/dev/
) are created or removed.
bind/unbind
When a driver is attached or detached from a device.
change
Only raised manually by drivers on a "device state change", has no standard meaning; see
#The change action
.
offline
When a device (usually
memory
or
CPUs
) becomes locked for hot-unplugging.
online
When a previously offline device is unlocked.
move
When a device (usually a network interface) is renamed,
hopefully never
.
The change action
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
KOBJ_CHANGE
. 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.
SUBSYSTEM
Event trigger
Event-specific property
Documentation
typec
Change in alt-mode, USB-PD role or data role
None
usb_role
Role change (for a USB OTG or Type-C device)
USB_ROLE_SWITCH=
valued at
none
,
host
or
device
, based on the new role
block
Media changes for a disc drive or an SD card reader
DISK_MEDIA_CHANGE=1
for a new disc/card or
DISK_EJECT_REQUEST=1
when the media is being unloaded
drm
Device detected as "wedged" (hanged and cannot be recovered by the driver)
WEDGED=
with a list of available reset methods, like
rebind
or
bus-reset
Device wedging
drm
Monitor hot-plugged (plugged or unplugged)
HOTPLUG=1
, sometimes also
CONNECTOR=
with the internal ID of the connector
drm
Connector property change (such as HDCP status)
CONNECTOR=
and
PROPERTY=
with their respective internal IDs
backlight
Brightness changed
SOURCE=
valued at
sysfs
,
hotkey
or
unknown
based on what triggered the change.
power_supply
Power supply state changed (power supply plugged/unplugged, battery charging/discharging, etc.)
None
rfkill
Radio turned on or off by killswitch, button or menu
None
thunderbolt
Tunneling mode change
TUNNEL_EVENT=
with the state of the tunnel, possibly
TUNNEL_DETAILS=
as well
Thunderbolt tunneling events
Any device with a
power/
attribute group
Gaining or losing the ability to do remote wakeup
1
(i.e: when the entire
power/wakeup*
attribute set appears or disappears)
None
Device Power Management Basics
, though the uevent itself is not documented
Any (synthetic uevent)
Writing
change $(uuidgen) FOO=BAR HELLO=WORLD
to the uevent file of any sysfs device
2
SYNTH_UUID=
with the UUID written to the file, also
SYNTH_ARG_HELLO=WORLD
for any key-value pair after the UUID
sysfs-uevent
Gaining or losing the ability to do remote wakeup is interesting in cases such as USB, since unconfigured USB devices cannot issue wakeups in this state. See
#Force USB device features to be re-added after suspend
.
Both
udevadm trigger
and the
OPTIONS+="watch"
udev rule directive will cause synthetic change events to be raised through this mechanism, with
ENV{SYNTH_UUID}=="0"
in both cases.
Device attributes
Device attributes, listed as
ATTR{my_attr}=="..."
(or
ATTRS{my_attr}=="..."
for parent devices) in udev rules and
udevadm info --attribute-walk
, 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
ls /sys/class/thermal/thermal_zone0/
or
cat /sys/class/input/input0/name
is all that is needed to explore device attributes, and some can even be changed with something like
echo 1 > "/sys/class/leds/input2::capslock/brightness"
. It is, however, a lot more convenient to use
udevadm info --attribute-walk /sys/class/input/mouse0
, 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
ATTR{power/control}=="auto"
.
Event environment
The "environment" of an event is a set of device properties and event properties (and rarely global properties), both written as
ENV{MY_PROPERTY}=="..."
in udev rules and both reported as
E: MY_PROPERTY=...
by
udevadm monitor --property
and
udevadm info
(without
--attribute-walk
). Despite being called "environment", they have nothing to do with
environment variables
(although they do get passed as environment variables to programs started by
RUN+="..."
). 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
udevadm info
, whereas event properties are transient and can only be seen if the event is caught by
udevadm monitor --property
. 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
ENVS{...}==""
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
ENV{.PART_SUFFIX
}, which will be added to the
event properties
with the leading dot in the name and be usable by other rules, but not stored).
Useful device properties
There are a number of device properties that other programs listen to, and which can be used to affect how they recognize or handle a device that has them.
Property name
Usage
Software listening
Documentation
KEYBOARD_KEY_<hex scan code>
Can be used to remap any keyboard scancode to any logical key by name in
input-event-codes.h
(with the name in lowercase, only those that start with
KEY_
without the prefix or those with
BTN_
with the prefix
).
60-evdev.rules
and udev-builtin-keyboard
#Keyboard_devices
and
60-keyboard.hwdb
LIBINPUT_IGNORE_DEVICE
Input device is disregarded if property is non-zero.
libinput
Ignoring specific devices
Device tags
Tags (added using
TAG+="foo"
, removed with
TAG-="foo"
, matched with
TAG=="foo"
) are used by userspace software interacting with udev to list and identify all devices they should be acting upon. Those can also be arbitrary, but there are a few well-known ones.
Tag
Software listening
Meaning
Documentation
systemd
systemd
Systemd should create a device unit for this device
systemd.device(5)
seat
systemd-logind
Device is eligible to be assigned to a seat, and
ENV{ID_SEAT
} indicates which seat it is currently assigned to, if any
sd-login(3)
master-of-seat
systemd-logind
sd-login(3)
uaccess
70-uaccess.rules
and
73-seat-late.rules
Users should have read and write permissions granted on this device (via
Access Control Lists
) while it is assigned to their seat
see
#Allowing regular users to use devices
power-switch
systemd-logind
Device will be watched for lid and key events to trigger suspend, screen lock and other such things
logind.conf(5)
(HandlePowerKey)
Hardware database
udev's hardware database (
hwdb
) contains lists of
device properties
to be assigned to specific devices based solely on
modalias
patterns, similar to how kernel modules declare what devices they should be attached to. This is commonly used to configure keyboard scancodes, mice DPI, and USB classes/models, among other things. The database is compiled from files with
.hwdb
extension located in directories
/usr/lib/udev/hwdb.d/
,
/run/udev/hwdb.d/
and
/etc/udev/hwdb.d/
. See
hwdb(7)
for details.
Each
.hwdb
file can apply properties to one or more devices based on hardware ID glob patterns. You may obtain device identification info by running
evemu-describe(1)
as the root user. This command is provided by the
evemu
package.
Event devices (evdev)
Event devices
(evdev), which include input devices like keyboards, mice and gamepads (but also power buttons, laptop lid switches, remote controls, and anything that can raise "input" events) can be matched with the
evdev:
prefix in one of the following formats:
Using the kernel
modalias
:
evdev:input:b
<bus_id>
v
<vendor_id>
p
<product_id>
e
<version_id>
-
<input_modalias>
with the following 4-digit hex uppercase fields:
<vendor_id>
,
<product_id>
and
<version_id>
: vendor, product and version IDs matching the output of the
lsusb
command.
<bus_id>
is the 4-digit hex bus id and should be 0003 for usb devices. The possible
<bus_id>
values are defined in
/usr/include/linux/input.h
(you can run
awk '/BUS_/ {print $2, $3}' /usr/include/linux/input.h
to get a list).
<input_modalias>
is an arbitrary length input-modalias describing the device capabilities. The other fields are sufficient to uniquely identify the device, so you can use a glob here.
If you have the device currently plugged into your computer then you can get the whole modalias at once using sysfs, as demonstrated in
#Remap specific device
.
Input driver device name and DMI data match:
evdev:name:
<input device name>
:dmi:bvn*:bvr*:bd*:svn
<vendor>
:pn*
where
<input_device_name>
is the name device specified by the driver and
<vendor>
is the firmware-provided string exported by the kernel DMI modalias.
Keyboard devices
The
scancodes-to-keycodes
mapping for keyboards is defined in
/usr/lib/udev/hwdb.d/60-keyboard.hwdb
. The format of each line in the block body is
KEYBOARD_KEY_
<scancode>
=
<keycode>
, where:
The value of
<scancode>
is hexadecimal, but without the leading
0x
(i.e. specify
a0
instead of
0xa0
).
The value of
<keycode>
is the lower-case keycode name string as listed in
/usr/include/linux/input-event-codes.h
(see the
KEY_
<KEYCODE>
variables), with a sorted list is available at
[1]
. It is not possible to specify decimal value in
<keycode>
.
Examples
Remap specific device
Suppose you want to remap scancodes for a keyboard that you currently have plugged in. You should already have the evdev path (e.g.
/dev/input/event17
), and you can follow
Keyboard input#Identifying scancodes
to obtain the
scancode
(e.g.
70039
for caps lock). Now, using the event number, you can query
sysfs
for the modalias:
cat /sys/class/input/event17/device/modalias
input:b0003v32ACp0012e0111-e0,1,4,1...
This device could be matched with the following hwdb rule:
/etc/udev/hwdb.d/90-remap.hwdb
evdev:input:b0003v32ACp0012e0111*
 KEYBOARD_KEY_70039=rightctrl # This example maps the 70039 scancode to the "rightctrl" keycode.
Remap all devices
Suppose we want to remap a couple of common keys for all AT keyboards:
/etc/udev/hwdb.d/90-custom-keyboard.hwdb
evdev:atkbd:*
 KEYBOARD_KEY_10=suspend
 KEYBOARD_KEY_a0=search
Disable key
To block the
Sleep
key, bind it to the "reserved" keyword. Alternatively, you can use "unknown" to map it to the
NoSymbol
key. For example:
/etc/udev/hwdb.d/90-block-sleep.hwdb
evdev:input:b0003v03F0p020C* # hp 5308 keyboard controller
 KEYBOARD_KEY_10082=reserved
Updating the Hardware Database Index
After changing the configuration files, the hardware database index,
hwdb.bin
needs to be rebuilt by running:
# systemd-hwdb update
This creates
/etc/udev/hwdb.bin
, which takes precedence over the existing
/usr/lib/udev/hwdb.bin
. Upon system upgrade, both files will be automatically kept up-to-date with the same contents:
/usr/lib/udev/hwdb.bin
is rebuilt by the
30-systemd-hwdb.hook
pacman hook
on each
systemd
upgrade, and immediately effected by
30-systemd-udev-reload.hook
.
/etc/udev/hwdb.bin
is rebuilt by
systemd-hwdb-update.service
on the next boot after the upgrade (see
systemd-update-done.service(8)
), since it detects we have manually generated it.
Reloading the Hardware Database Index
The kernel loads
hwdb.bin
as part of the boot process, rebooting the system will load the updated
hwdb.bin
.
It is possible to load new properties from the updated
hwdb.bin
by running:
# udevadm trigger
Be aware that only added or changed properties are loaded so if we delete a property from the configuration file, the deleted property is still kept by the kernel until a reboot.
Querying the database
You can check that your configuration was loaded either by pressing keys, or by running
udevadm info
. For the USB keyboard in the above example, this outputs the mapping we configured as follows:
# udevadm info /dev/input/by-path/*-usb-*-kbd | grep KEYBOARD_KEY
E: KEYBOARD_KEY_70039=leftalt
E: KEYBOARD_KEY_700e2=leftctrl
Tips and tricks
Mounting drives in rules
To mount removable drives, do not call
mount
from
udev
rules. This is ill-advised for two reasons:
systemd by default runs
systemd-udevd.service
with a separate "mount namespace" (see
namespaces(7)
), which means that mounts will not be visible to the rest of the system.
Even if you change the service parameters to fix this (commenting out the
PrivateMounts
and
MountFlags
lines), there is another problem which is that processes started from Udev are killed after a few seconds. In case of FUSE filesystems, such as
NTFS-3G
,
mount
starts a user-space process to handle the filesystem internals; when this is killed you will get
Transport endpoint not connected
errors if you try to access the filesystem.
There are some options that work:
Start a custom systemd service from the Udev rule; the systemd service can invoke a script which can start any number of long-running processes (like FUSE). A concise example which automatically mounts USB disks under
/media
is
udev-media-automount
. A variant of the same idea is explained in
this blog post
.
Use
systemd-mount
instead of
mount
in your Udev rule. This is
recommended by systemd developers
. For example this Udev rule should mount USB disks under
/media
:
ACTION=="add", SUBSYSTEMS=="usb", SUBSYSTEM=="block", ENV{ID_FS_USAGE}=="filesystem", RUN{program}+="/usr/bin/systemd-mount --no-block --automount=yes --collect $devnode /media"
Use a package like
udisks
or
udiskie
. These are very powerful, but difficult to set up. Also, they are meant to be used in single user sessions, since they make some filesystems available under the ownership of the unprivileged user whose session is currently active.
Spawning long-running processes
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
systemctl
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
TAG+="systemd"
and adding a device property of either
ENV{SYSTEMD_WANTS}+=
for services that would run with
systemctl --system
or
ENV{SYSTEMD_USER_WANTS}+=
for services that should run with
systemctl --user
. For example:
SUBSYSTEM=="tty", ACTION=="add", ATTRS{manufacturer}=="Pulse-Eight", ATTRS{product}=="CEC Adapter", TAG+="systemd", ENV{SYSTEMD_WANTS}+="inputattach-cec@$devnode.service"
/etc/systemd/system/inputattach-cec@.service
[Unit]
Description=Configure USB serial device at %I

[Service]
Type=simple
ExecStart=/usr/bin/inputattach --pulse8-cec %I
SYSTEMD_WANTS
is equivalent to the
Wants=
directive elsewhere in systemd, meaning the device will not be affected if the service fails, does not exist, or completes successfully at any point.
Allowing regular users to use devices
Warning
Do not set the
uaccess
tag on input or block devices; those have their own access control mechanisms and unprivileged users should not have raw access to those. For instance, unprivileged raw keyboard access would make keylogging trivial, and unprivileged raw disk access would completely negate filesystem security.
When a
kernel
driver initializes a device, the default state of the device node is to be owned by
root:root
, with permissions
600
.
[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
OWNER
,
GROUP
, and
MODE
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
plugdev
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.
The modern recommended approach for systemd systems is to use a
MODE
of
660
to let the group use the device, and then attach a
TAG
named
uaccess
[6]
. This special tag makes udev apply a
dynamic user ACL
to the device node, which coordinates with
systemd-logind(8)
to make the device usable to logged-in users. For an example of a udev rule implementing this:
/etc/udev/rules.d/71-device-name.rules
ACTION!="remove", SUBSYSTEMS=="usb", ATTRS{idVendor}=="
vendor_id
", ATTRS{idProduct}=="
product_id
", MODE="0660", TAG+="uaccess"
Note
For any rule adding the
uaccess
tag to be effective, the name of the file it is defined in
has to lexically precede
/usr/lib/udev/rules.d/73-seat-late.rules
.
Execute when HDMI cable is plugged in or unplugged
Create the rule
/etc/udev/rules.d/95-hdmi-plug.rules
with the following content:
ACTION=="change", SUBSYSTEM=="drm", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/
username
/.Xauthority", RUN+="
/path/to/script.sh
"
Note
If the rule triggers before the X server starts, it may not work as intended. See
#X programs in RUN rules hang when no X server is present
.
Execute on VGA cable plug in
Create the rule
/etc/udev/rules.d/95-monitor-hotplug.rules
with the following content to launch
arandr
on plug in of a VGA monitor cable:
KERNEL=="card0", SUBSYSTEM=="drm", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/
username
/.Xauthority", RUN+="/usr/bin/arandr"
Some display managers store the
.Xauthority
outside the user home directory. You will need to update the
ENV{XAUTHORITY}
accordingly. As an example
GNOME Display Manager
looks as follows:
$ printenv XAUTHORITY
/run/user/1000/gdm/Xauthority
Note
If the rule triggers before the X server starts, it may not work as intended. See
#X programs in RUN rules hang when no X server is present
.
Detect new eSATA drives
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:
# echo 0 0 0 | tee /sys/class/scsi_host/host*/scan
Or you could install
scsiadd
AUR
(from the AUR) and try:
# scsiadd -s
Hopefully, your drive is now in
/dev
. If it is not, you could try the above commands while running:
# udevadm monitor
to see if anything is actually happening.
Mark internal SATA ports as eSATA
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.
/etc/udev/rules.d/10-esata.rules
DEVPATH=="/devices/pci0000:00/0000:00:1f.2/host4/*", ENV{UDISKS_SYSTEM}="0"
Note
The
DEVPATH
can be found after connection the eSATA drive with the following commands (replace
sdb
accordingly):
$ udevadm info --query=path /dev/sdb
/devices/pci0000:00/0000:00:1f.2/host4/target4:0:0/4:0:0:0/block/sdb
$ find /sys/devices/ -name sdb
/sys/devices/pci0000:00/0000:00:1f.2/host4/target4:0:0/4:0:0:0/block/sdb
Setting static device names
Because
udev
loads all modules asynchronously, they are initialized in a different order. This can result in devices randomly switching names. A
udev
rule can be added to use static device names.
See also
Persistent block device naming
for block devices and
Network configuration#Change interface name
for network devices.
Video device
For setting up the webcam in the first place, refer to
Webcam setup
.
Using multiple webcams will assign video devices as
/dev/video*
randomly on boot. The recommended solution is to create symlinks using a
udev
rule as in the
#Example
:
/etc/udev/rules.d/83-webcam.rules
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="05a9", ATTRS{idProduct}=="4519", SYMLINK+="video-cam1"
KERNEL=="video[0-9]*", SUBSYSTEM=="video4linux", SUBSYSTEMS=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="08f6", SYMLINK+="video-cam2"
Note
Using names other than
/dev/video*
will break preloading of
v4l1compat.so
and perhaps
v4l2convert.so
Printer
If you use multiple printers,
/dev/lp[0-9]
devices will be assigned randomly on boot, which will break e.g.
CUPS
configuration.
You can create the following rule, which will create symlinks under
/dev/lp/by-id
and
/dev/lp/by-path
, similar to
Persistent block device naming
scheme:
/etc/udev/rules.d/60-persistent-printer.rules
ACTION=="remove", GOTO="persistent_printer_end"
# This should not be necessary
#KERNEL!="lp*", GOTO="persistent_printer_end"

SUBSYSTEMS=="usb", IMPORT{builtin}="usb_id"
ENV{ID_TYPE}!="printer", GOTO="persistent_printer_end"

ENV{ID_SERIAL}=="?*", SYMLINK+="lp/by-id/$env{ID_BUS}-$env{ID_SERIAL}"

IMPORT{builtin}="path_id"
ENV{ID_PATH}=="?*", SYMLINK+="lp/by-path/$env{ID_PATH}"

LABEL="persistent_printer_end"
Identifying a disk by its serial
To perform some action on a specific disk device
/dev/sd
X
identified permanently by its unique serial
ID_SERIAL_SHORT
as displayed with
udevadm info /dev/sd
X
, one can use the below rule. It is passing as a parameter the device name found if any to illustrate:
/etc/udev/rules.d/69-disk.rules
ACTION=="add", KERNEL=="sd[a-z]", ENV{ID_SERIAL_SHORT}=="
X5ER1ALX
", RUN+="/path/to/script /dev/%k"
Waking from suspend with USB device
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.
Note
By default, the USB host controllers are all enabled for wakeup. The status can be checked using
cat /proc/acpi/wakeup
. The rule below is in this case not necessary but can be used as a template to perform other actions, like disabling the wakeup functionality for example.
First, identify the vendor and product identifiers of the USB device. They will be used to recognize it in the udev rule. For example:
$ lsusb | grep Logitech
Bus 007 Device 002: ID
046d
:
c52b
Logitech, Inc. Unifying Receiver
Then, find where the device is connected to using:
$ grep
c52b
/sys/bus/usb/devices/*/idProduct
/sys/bus/usb/devices/
1-1.1.1.4/
idProduct:c52b
Now create the rule to change the
power/wakeup
attribute of both the device and the USB controller it is connected to whenever it is added:
/etc/udev/rules.d/50-wake-on-device.rules
ACTION=="add", SUBSYSTEM=="usb", DRIVERS=="usb", ATTRS{idVendor}=="
046d
", ATTRS{idProduct}=="
c52b
", ATTR{power/wakeup}="enabled", ATTR{driver/
1-1.1.1.4
/power/wakeup}="enabled"
Force USB device features to be re-added after suspend
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 they are unconfigured, so they cannot issue
wakeup triggers
while in this state. That uevent has no distinctive properties and is issued once for losing
power/wakeup
(when the device state becomes
default
), and then a second time when regaining it (as the device state reaches
addressed
). The first event can still be easily identified because
DEVNUM
is set to zero (which is not a valid device number)
immediately before
the device is unconfigured and loses
power/wakeup
. When that happens, one can simply touch the
bConfigurationValue
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.
Note
DEVNUM
will not be set to zero if the attribute
power/persist
(which controls the
USB-persist feature
) is set to
1
. USB-persist is enabled by default on the default kernel of several Linux distributions (
including
Arch's
linux
kernel) using the
CONFIG_USB_DEFAULT_PERSIST
option at compilation. If so, the USB-persist feature needs to be disabled on that device in order to work properly.
# Make sure that power/persist is and stays off,
# in case CONFIG_USB_DEFAULT_PERSIST enables it by default
SUBSYSTEM=="usb" ATTR{manufacturer}=="Foo" ATTR{product}=="Bar" ATTR{power/persist}="0"

# The actual rule to be run
ACTION=="add" SUBSYSTEM=="tty" SUBSYSTEMS=="usb" ATTRS{manufacturer}=="Foo" ATTRS{product}=="Bar" TAG+="systemd" ENV{SYSTEMD_WANTS}="setup-usb-tty@$devnode.service"

# The rule that will get the above rule to re-run when the computer comes out of sleep
# Can't use $attr{bConfigurationValue} in ATTR{}, so make sure to replace
# both "1" by whatever configuration value is being used when
# the device is functional.
ACTION=="change" SUBSYSTEM=="usb" ENV{DEVNUM}=="000" ATTR{manufacturer}=="Foo" ATTR{product}=="Bar" ATTR{bConfigurationValue}=="1" ATTR{bConfigurationValue}="1"
Triggering events
This article or section is a candidate for merging with
#Testing rules before loading
.
Notes:
similar trick (Discuss in
Talk:Udev
)
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
udevadm trigger
:
# udevadm trigger --verbose --type=subsystems --action=remove --subsystem-match=usb --attr-match="idVendor=abcd"
This command will trigger a USB remove event on all USB devices with vendor ID
abcd
.
Triggering desktop notifications from a udev rule
To trigger a desktop notification from a
udev
rule, use
systemd-run(1)
as explained in
Desktop notifications#Send notifications to another user
:
Create the file:
/etc/udev/rules.d/99-powersupply_notification.rules
# Rule for when switching to battery
ACTION=="change", SUBSYSTEM=="power_supply", ATTRS{type}=="Mains", ATTRS{online}=="0", RUN+="/usr/bin/systemd-run --machine=
target_user
@.host --user notify-send 'Changing Power States' 'Using battery power'"
# Rule for when switching to AC
ACTION=="change", SUBSYSTEM=="power_supply", ATTRS{type}=="Mains", ATTRS{online}=="1", RUN+="/usr/bin/systemd-run --machine=
target_user
@.host --user notify-send 'Changing Power States' 'Using AC power'"
To launch multiple or long commands, an
executable
script can be given to
systemd-run
:
/usr/local/bin/from_battery.sh
#!/bin/sh

paplay /usr/share/sounds/freedesktop/stereo/power-unplug.oga
notify-send --icon=/usr/share/icons/Adwaita/symbolic/legacy/battery-good-symbolic.svg 'Changing Power States' 'Using battery power' --expire-time=4000
Note
If the rule triggers before the X server starts, it may not work as intended. See
#X programs in RUN rules hang when no X server is present
.
Troubleshooting
Blacklisting modules
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).
Debug output
To get hardware
debug
info, use the
kernel parameter
udev.log-priority=debug
. Alternatively you can set
/etc/udev/udev.conf
udev_log=debug
This option can also be compiled into your initramfs by adding the configuration file to your
FILES
array:
/etc/mkinitcpio.conf
FILES=(... /etc/udev/udev.conf)
and then
regenerate the initramfs
.
udevd hangs at boot
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.
Extract the group names referenced in
udev
rules and the group names actually present on the system:
# grep -Fr GROUP /etc/udev/rules.d/ /usr/lib/udev/rules.d/ | sed 's:.*GROUP="\([-a-z_]\{1,\}\)".*:\1:' | sort -u >udev_groups
# cut -d: -f1 /etc/gshadow /etc/group | sort -u >present_groups
To see the differences, do a side-by-side diff:
# diff -y present_groups udev_groups
...
network							      <
nobody							      <
ntp							      <
optical								optical
power							      |	pcscd
rfkill							      <
root								root
scanner								scanner
smmsp							      <
storage								storage
...
In this case, the
pcscd
group is for some reason not present in the system.
Add the missing groups
. Also, make sure that local resources are looked up before resorting to LDAP.
/etc/nsswitch.conf
should contain the following line:
group: files ldap
Some devices, that should be treated as removable, are not
You need to create a custom
udev
rule for that particular device. To get definitive information of the device you can use either
ID_SERIAL
or
ID_SERIAL_SHORT
(remember to change
/dev/sdb
if needed):
$ udevadm info --query=property --property=ID_SERIAL,ID_SERIAL_SHORT --name=/dev/sdb
Then we set
UDISKS_AUTO="1"
to mark the device for automounting and
UDISKS_SYSTEM="0"
to mark the device as "removable". See
udisks(8)
for details.
/etc/udev/rules.d/99-removable.rules
ENV{ID_SERIAL_SHORT}=="
serial_number
", ENV{UDISKS_AUTO}="1", ENV{UDISKS_SYSTEM}="0"
Remember to reload
udev
rules with
udevadm control --reload
. Next time you plug your device in, it will be treated as an external drive.
Sound problems with some modules not loaded automatically
Some users have traced this problem to old entries in
/etc/modprobe.d/sound.conf
. Try cleaning that file out and trying again.
The
OSS emulation
modules
snd_pcm_oss
and
snd_seq_oss
are not automatically loaded by default.
Optical drives have group ID set to "disk"
If the group ID of your optical drive is set to
disk
and you want to have it set to
optical
, you have to create a custom
udev
rule:
/etc/udev/rules.d
# permissions for SCSI CD devices
SUBSYSTEMS=="scsi", KERNEL=="s[rg][0-9]*", ATTRS{type}=="5", GROUP="optical"
X programs in RUN rules hang when no X server is present
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
IPAddressDeny
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
failed to authenticate magic
error.
See also
udev(7)
An Introduction to udev
udev mailing list information
Scripting with udev
Writing udev rules
Device and Module Handling on an LFS System
Running GUI or accessing display variables from udev rules
openSUSE udev documentation