udev
udev is a userspace system that enables the operating system administrator to register userspace 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.
As the successor of devfsd and hotplug, udev also manages device nodes in the /dev directory by adding, symlinking and renaming them. udev replaces the functionality of both hotplug and hwdetect.
udev handles separate events concurrently (in parallel), leading to a potential performance improvement over older systems. At the same time, this can complicate system administration, because, for example, the kernel module loading order is not preserved across boots. If the machine has multiple block devices, this may manifest itself in the form of device nodes changing designations after reboot. For example, if the machine has two hard drives, /dev/sda may on next boot become /dev/sdb. See below for more info on this.
Installation
udev is part of systemd and thus installed by default. See systemd-udevd.service(8) for information.
A standalone fork is available as eudevAUR and eudev-gitAUR.
About 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 . If there are two files by the same name under /usr/lib and , the ones in take precedence.
To learn about udev rules, refer to the manual. Also see Writing udev rules and some practical examples are provided within the guide: Writing udev rules - Examples.
udev rule 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 . The reason for writing this rule is that at the next boot, the device could show up under a different name, like .
$ 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 and , then walking up two levels above, we match the webcamera using vendor and product ID's from the usb parent , and .
We are now able to create a rule match for this device as follows:
Here we create a symlink using SYMLINK+="video-cam" 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:
$ udevadm monitor --environment --udev
In this command's output, you will see value pairs such as ID_VENDOR_ID and , which match the previously used attributes and . A rule that uses device environment variables instead of device attributes may look like this:
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 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 . 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:
You can just choose the deepest path and 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
udisks
See udisks.
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 with a separate "mount namespace" (see ), 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 and 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 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 is udev-media-automount. A variant of the same idea is explained in this blog post.
- Use
systemd-mountinstead ofmountin your Udev rule. This is recommended by systemd developers. For example this Udev rule should mount USB disks under :
Allowing regular users to use devices
When a kernel driver initializes a device, the default state of the device node is to be owned by , with permissions . This makes devices inaccessible to regular users unless the driver changes the default, or a udev rule in userspace changes the permissions.
The , , 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 group that devices are added to, but this practice is not only discouraged by the systemd developers, but considered a bug when shipped in udev rules on Arch (). 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 to let the group use the device, and then attach a named uaccess . This special tag makes udev apply a dynamic user ACL to the device node, which coordinates with to make the device usable to logged-in users. For an example of a udev rule implementing this:
Execute when HDMI cable is plugged in or unplugged
Create the rule with the following content:
ACTION=="change", SUBSYSTEM=="drm", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/username/.Xauthority", RUN+="/path/to/script.sh"
Execute on VGA cable plug in
Create the rule with the following content to launch 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 outside the user home directory. You will need to update the ENV{XAUTHORITY} accordingly. As an example GNOME Display Manager looks as follows:
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 > /sys/class/scsi_host/host*/scan
Or you could install (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.
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 randomly on boot. The recommended solution is to create symlinks using a udev rule as in the #udev rule example:
Printer
If you use multiple printers, devices will be assigned randomly on boot, which will break e.g. CUPS configuration.
You can create following rule, which will create symlinks under and /dev/lp/by-path, similar to Persistent block device naming scheme:
Identifying a disk by its serial
To perform some action on a specific disk device identified permanently by its unique serial as displayed with , 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.
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:
Triggering events
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 --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 .
Triggering desktop notifications from a udev rule
Invoking an external script containing calls to via udev can sometimes be challenging since the notification(s) never display on the Desktop. Here is an example of what commands and environmental variables need to be included in which files for to successfully be executed from a udev rule.
1) The following udev rule executes a script that plays a notification sound and sends a desktop notification when screen brightness is changed according to power state on a laptop. Create the file:
/etc/udev/rules.d/99-backlight_notification.rules
# Rule for when switching to battery
ACTION=="change", SUBSYSTEM=="power_supply", ATTR{type}=="Mains", ATTR{online}=="0", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/USERNAME/.Xauthority" RUN+="/usr/bin/su USERNAME_TO_RUN_SCRIPT_AS -c /usr/local/bin/brightness_notification.sh"
# Rule for when switching to AC
ACTION=="change", SUBSYSTEM=="power_supply", ATTR{type}=="Mains", ATTR{online}=="1", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/USERNAME/.Xauthority" RUN+="/usr/bin/su USERNAME_TO_RUN_SCRIPT_AS -c /usr/local/bin/brightness_notification.sh"
- and need to be changed to that of the shortname for the user of the graphical session where the notification will be displayed;
- the script needs to be executed with , which will place its ownership under the user of the graphical session (rather than root/the system) where the notification will be displayed.
2) Contents of the executable script to be run on trigger of the udev rule:
- ,
UID_OF_USER_TO_RUN_SCRIPT_ASand needs to be changed to that of the shortname for the user and user's UID of the graphical session where the notification will be displayed; - is needed when playing audio via pulseaudio;
- three environmental variables (i.e., , and ) for the user of the graphical session where the notification will be displayed need to be defined and exported.
3) Load/reload the new udev rule (see above) and test it by unplugging the power supply to the laptop.
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, you can use (e.g. your_command | at now, or ), or create a systemd unit which can be triggered directly from a udev rule.
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 . Alternatively you can set
This option can also be compiled into your initramfs by adding the config file to your array
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. 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 or (remember to change /dev/sdb if needed):
$ udevadm info /dev/sdb | grep ID_SERIAL
Then we set to mark the device for automounting and UDISKS_SYSTEM="0" to mark the device as "removable". See for details.
Remember to reload udev rules with . 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 . Try cleaning that file out and trying again.
IDE CD/DVD-drive support
Starting with version 170, udev does not support CD-ROM/DVD-ROM drives that are loaded as traditional IDE drives with the ide_cd_mod module and show up as . The drive remains usable for tools which access the hardware directly, like cdparanoia, but is invisible for higher userspace programs, like KDE.
A cause for the loading of the ide_cd_mod module prior to others, like sr_mod, could be e.g. that you have for some reason the module piix loaded with your initramfs. In that case you can just replace it with ata_piix in your .
Optical drives have group ID set to "disk"
If the group ID of your optical drive is set to and you want to have it set to , you have to create a custom udev rule:
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 error.