Built-in persistent naming schemes
udev provides persistent naming for some device types out of the box. This is a very useful feature, and in many circumstances means that your journey ends here: you do not have to write any rules.
udev provides out-of-the-box persistent naming for storage devices in the
/dev/disk directory. To view the persistent names which have been created for your storage hardware, you can use the following command:
# ls -lR /dev/disk
This works for all storage types. As an example, udev has created
/dev/disk/by-id/scsi-SATA_ST3120827AS_4MS1NDXZ-part3 which is a persistent-named symbolic link to my root partition. udev creates
/dev/disk/by-id/usb-Prolific_Technology_Inc._USB_Mass_Storage_Device-part1 when I plug my USB flash disk in, which is also a persistent name.
Rule writing
Rule files and semantics
When deciding how to name a device and which additional actions to perform, udev reads a series of rules files. These files are kept in the
/etc/udev/rules.d directory, and they all must have the
.rules suffix.
Default udev rules are stored in
/etc/udev/rules.d/50-udev.rules. You may find it interesting to look over this file - it includes a few examples, and then some default rules proving a devfs-style /dev layout. However, you should not write rules into this file directly.
Files in /etc/udev/rules.d/ are parsed in
lexical order, and in some circumstances, the order in which rules are parsed is important. In general, you want your own rules to be parsed before the defaults, so I suggest you create a file at
/etc/udev/rules.d/10-local.rules and write all your rules into this file.
In a rules file, lines starting with "#" are treated as comments. Every other non-blank line is a rule. Rules cannot span multiple lines.
One device can be matched by more than one rule. This has it's practical advantages, for example, we can write two rules which match the same device, where each one provides its own alternate name for the device. Both alternate names will be created, even if the rules are in separate files. It is important to understand that udev will
not stop processing when it finds a matching rule, it will continue searching and attempt to apply every rule that it knows about.
Rule syntax
Each rule is constructed from a series of key-value pairs, which are separated by commas.
match keys are conditions used to identify the device which the rule is acting upon. When
all match keys in a rule correspond to the device being handled, then the rule is applied and the actions of the
assignment keys are invoked. Every rule should consist of at least one match key and at least one assignment key.
Here is an example rule to illustrate the above:
KERNEL=="hdb", NAME="my_spare_disk"
The above rule includes one match key (
KERNEL) and one assignment key (
NAME). The semantics of these keys and their properties will be detailed later. It is important to note that the match key is related to its value through the
equality operator (==), whereas the assignment key is related to its value through the
assignment operator (=).
Be aware that udev does not support any form of line continuation. Do not insert any line breaks in your rules, as this will cause udev to see your one rule as multiple rules and will not work as expected.
Basic Rules
udev provides several different match keys which can be used to write rules which match devices very precisely. Some of the most common keys are introduced below, others will be introduced later in this document. For a complete list, see the udev man page.
- KERNEL - match against the kernel name for the device
- SUBSYSTEM - match against the subsystem of the device
- DRIVER - match against the name of the driver backing the device
After you have used a series of match keys to precisely match a device, udev gives you fine control over what happens next, through a range of assignment keys. For a complete list of possible assignment keys, see the udev man page. The most basic assignment keys are introduced below. Others will be introduced later in this document.
- NAME - the name that shall be used for the device node
- SYMLINK - a list of symbolic links which act as alternative names for the device node
As hinted above,
udev only creates one true device node for one device. If you wish to provide alternate names for this device node, you use the symbolic link functionality. With the
SYMLINK assignment, you are actually maintaining a
list of symbolic links, all of which will be pointed at the real device node. To manipulate these links, we introduce a new operator for appending to lists:
+=. You can append multiple symlinks to the list from any one rule by separating each one with a space.
KERNEL=="hdb", NAME="my_spare_disk"
The above rule says:
match a device which was named by the kernel as hdb, and instead of calling it hdb, name the device node as my_spare_disk. The device node appears at
/dev/my_spare_disk.
KERNEL=="hdb", DRIVER=="ide-disk", SYMLINK+="sparedisk"
The above rule says:
match a device which was named by the kernel as hdb AND where the driver is ide-disk. Name the device node with the default name and create a symbolic link to it named sparedisk. Note that we did not specify a device node name, so udev uses the default. In order to preserve the standard
/dev layout, your own rules will typically leave the NAME alone but create some SYMLINKs and/or perform other assignments.
KERNEL=="hdc", SYMLINK+="cdrom cdrom0"
The above rule is probably more typical of the types of rules you might be writing. It creates two symbolic links at
/dev/cdrom and
/dev/cdrom0, both of which point at
/dev/hdc. Again, no NAME assignment was specified, so the default kernel name (hdc) is used.
Matching sysfs attributes
The match keys introduced so far only provide limited matching capabilities. Realistically we require much finer control: we want to identify devices based on advanced properties such as vendor codes, exact product numbers, serial numbers, storage capacities, number of partitions, etc.
Many drivers export information like this into sysfs, and udev allows us to incorporate sysfs-matching into our rules, using the
ATTR key with a slightly different syntax.
Here is an example rule which matches a single attribute from sysfs. Further detail will be provided later in this document which will aid you in writing rules based on sysfs attributes.
SUBSYSTEM=="block", ATTR{size}=="234441648", SYMLINK+="my_disk"
Device hierarchy
The Linux kernel actually represents devices in a tree-like structure, and this information is exposed through sysfs and useful when writing rules. For example, the device representation of my hard disk device is a child of the SCSI disk device, which is in turn a child of the Serial ATA controller device, which is in turn a child of the PCI bus device. It is likely that you will find yourself needing to refer to information from a parent of the device in question, for example the serial number of my hard disk device is not exposed at the device level, it is exposed by its direct parent at the SCSI disk level.
The
four main match keys introduced so far (KERNEL/SUBSYSTEM/DRIVER/ATTR) only match against values corresponding to the device in question, and do not match values from parent devices. udev provides variants of the match keys that will search upwards through the tree:
- KERNELS - match against the kernel name for the device, or the kernel name for any of the parent devices
- SUBSYSTEMS - match against the subsystem of the device, or the subsystem of any of the parent devices
- DRIVERS - match against the name of the driver backing the device, or the name of the driver backing any of the parent devices
- ATTRS - match a sysfs attribute of the device, or a sysfs attribute of any of the parent devices
With hierarchy considerations in mind, you may feel that rule writing is becoming a little complicated. Rest assured that there are tools that help out here, which will be introduced later.
