Post

udev Rules: Persistent Device Naming and Custom Rules

udev Rules: Persistent Device Naming and Custom Rules

Device names like /dev/sdb are not stable. Add a disk, remove a USB drive, or reboot in a different order, and the name changes. udev is the userspace device manager that solves this, and its rules are how you give a device a name that never changes.

Inspecting Devices with udevadm

1
2
3
4
5
6
7
8
9
10
11
# Show all attributes of a device
udevadm info --query=all --name=/dev/sdb

# Show the attributes of the parent device
udevadm info --attribute-walk --name=/dev/sdb

# Show the device path
udevadm info --query=path --name=/dev/sdb

# Monitor udev events in real time
udevadm monitor

Tip: udevadm info --attribute-walk is the command you will use most. It prints every attribute you can match on, in the order udev evaluates them.

Finding Stable Identifiers

1
2
3
4
5
6
7
8
# UUID and label of a filesystem
sudo blkid /dev/sdb1

# Serial number of a disk
sudo udevadm info --query=property --name=/dev/sdb | grep -E "ID_SERIAL|ID_WWN"

# PCI address of a NIC
sudo udevadm info --query=property --name=eth0 | grep ID_NET_NAME

Tip: ID_SERIAL and ID_WWN are the most reliable identifiers for disks. They survive reordering, re-cabling, and moving the disk to another port.

Writing a udev Rule

1
2
3
4
5
6
7
8
9
10
# /etc/udev/rules.d/99-my-disk.rules

# Give a disk a stable symlink based on its serial
SUBSYSTEM=="block", ENV{ID_SERIAL}=="ABC123", SYMLINK+="disk/backup"

# Give a NIC a stable name based on its MAC address
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="00:11:22:33:44:55", NAME="eth-backup"

# Run a script when a USB device is plugged in
SUBSYSTEM=="usb", ACTION=="add", RUN+="/usr/local/bin/usb-inserted.sh"
1
2
3
4
5
# Reload the rules
sudo udevadm control --reload-rules

# Trigger the rules for existing devices
sudo udevadm trigger

Tip: SYMLINK+= is safer than NAME= for block devices. NAME= renames the kernel device, which can break other tools; SYMLINK+= adds an alias and leaves the original name intact.

Testing a Rule

1
2
3
4
5
# Test a rule against a device without applying it
sudo udevadm test /sys/class/block/sdb

# Check the udev log
sudo journalctl -u systemd-udevd -f

Tip: udevadm test shows exactly which rules match and what they do. It is the fastest way to debug a rule that is not firing.

Persistent Network Interface Names

1
2
# /etc/udev/rules.d/70-persistent-net.rules (legacy)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:11:22:33:44:55", NAME="eth0"

Tip: Modern systems use systemd-networkd’s .link files or net.ifnames=0 on the kernel command line instead of 70-persistent-net.rules. The udev rule still works, but it is no longer the recommended approach.

Common Use Cases

1
2
3
4
5
6
7
8
# Stable name for a USB serial adapter
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", SYMLINK+="ttyUSB-console"

# Stable name for a disk by serial
SUBSYSTEM=="block", ENV{ID_SERIAL}=="ABC123", SYMLINK+="disk/backup"

# Run a script when a specific USB device is inserted
SUBSYSTEM=="usb", ATTR{idVendor}=="1234", ATTR{idProduct}=="5678", ACTION=="add", RUN+="/usr/local/bin/on-insert.sh"

Tip: ATTRS{} (plural) matches the parent device, while ATTR{} matches the device itself. For USB serial adapters, you almost always want ATTRS{}.

udevadm test-builtin: Testing Built-in Commands

udevadm test-builtin runs a single built-in command against a device, which is the fastest way to debug a rule that uses one.

1
2
3
4
5
6
7
8
# Test the net_id built-in
sudo udevadm test-builtin net_id /sys/class/net/eth0

# Test the path_id built-in
sudo udevadm test-builtin path_id /sys/class/block/sdb

# Test the usb_id built-in
sudo udevadm test-builtin usb_id /sys/bus/usb/devices/1-1

Tip: udevadm test-builtin shows exactly what a built-in command produces, which is invaluable when a rule depends on its output.

udevadm trigger –action

1
2
3
4
5
6
7
8
9
10
11
# Trigger only add events
sudo udevadm trigger --action=add

# Trigger only change events
sudo udevadm trigger --action=change

# Trigger for a specific subsystem
sudo udevadm trigger --subsystem-match=block

# Trigger for a specific device
sudo udevadm trigger --sysname-match=sdb

Tip: udevadm trigger --action=change is the correct way to re-apply rules to existing devices without a reboot.

udevadm settle: Waiting for Events

1
2
3
4
5
6
7
8
# Wait for all pending udev events to finish
sudo udevadm settle

# Wait with a timeout
sudo udevadm settle --timeout=30

# Show the current event queue
sudo udevadm settle --seq-start=0 --seq-end=0

Tip: udevadm settle is essential in scripts that create devices and then immediately use them. Without it, the device may not exist yet when the script tries to access it.

systemd-udevd: The Daemon

1
2
3
4
5
6
7
8
9
10
11
# Is it running?
systemctl status systemd-udevd

# Show the daemon's configuration
udevadm info --version

# Reload the rules
sudo udevadm control --reload-rules

# Set the log level
sudo udevadm control --log-priority=debug

Tip: udevadm control --log-priority=debug is the fastest way to see why a rule is not firing. Set it back to info when you are done.

Quick Reference

1
2
3
4
5
6
7
8
9
10
11
12
# Inspect a device
udevadm info --attribute-walk --name=/dev/sdb

# Reload rules
sudo udevadm control --reload-rules
sudo udevadm trigger

# Test a rule
sudo udevadm test /sys/class/block/sdb

# Watch events
udevadm monitor

Tip: Work in order: inspect the device, find a stable identifier, write the rule, reload, then test. Most udev incidents are a rule that matches too broadly or a missing udevadm trigger.

This post is licensed under CC BY 4.0 by the author.