A udev rule can match any property the kernel adds to the event itself
or any information that the kernel exports to sysfs
.
The rule can also request additional information from external programs.
Every event is matched against all provided rules. All rules are located in
the /etc/udev/rules.d
directory.
Every line in the rules file contains at least one key value pair. There
are two kinds of keys, match and assignment keys. If all match keys match
their values, the rule is applied and the assignment keys are assigned the
specified value. A matching rule may specify the name of the device node,
add symlinks pointing to the node, or run a specified program as part of
the event handling. If no matching rule is found, the default device node
name is used to create the device node. Detailed information about the rule
syntax and the provided keys to match or import data are described in the
udev man page. The following example rules provide a basic introduction to
udev rule syntax. The example rules are all taken from the udev default
rule set that is located under
/etc/udev/rules.d/50-udev-default.rules
.
Example 11.1. Example udev Rules
# console KERNEL=="console", MODE="0600", OPTIONS="last_rule" # serial devices KERNEL=="ttyUSB*", ATTRS{product}=="[Pp]alm*Handheld*", SYMLINK+="pilot" # printer SUBSYSTEM=="usb", KERNEL=="lp*", NAME="usb/%k", SYMLINK+="usb%k", GROUP="lp" # kernel firmware loader SUBSYSTEM=="firmware", ACTION=="add", RUN+="firmware.sh"
The console
rule consist of three keys. One
match key (KERNEL
), and two assign keys
(MODE
, OPTIONS
). The
KERNEL
match rule searches the device list for any items
of the type console
. Only exact matches are valid and
trigger this rule to be executed. The MODE
key assigns
special permissions to the device node, in this case, read and write
permissions to the owner of this device and none else. The
OPTIONS
key makes this rule the last rule to be applied
to any device of this type. Any later rule matching this particular device
type does not have any effect.
The serial devices
rule is not available
in 50-udev-default.rules anymore, but it is still worth a look. It
consists of two match
keys (KERNEL
and ATTRS
) and one
assign key (SYMLINK
). The KERNEL
key
searches for all devices of the ttyUSB
type. Using the
*
wild card, this key matches several of these devices.
The second match key, ATTRS
, checks whether the
product
attribute file in sysfs
for
any ttyUSB
device contains a certain string. The assign
key (SYMLINK
) triggers the addition of a symbolic link
to this device under /dev/pilot
. The operator used in
this key (+=
) tells udev to additionally perform this
action, even if previous or later rules add other symbolic links. As this
rule contains two match keys, it is only applied if both conditions are
met.
The printer
rule deals with USB printers and
contains two match keys which must both apply to get the entire rule
applied (SUBSYSTEM
and KERNEL
). Three
assign keys deal with the naming for this device type
(NAME
), the creation of symbolic device links
(SYMLINK
), and the group membership for this device type
(GROUP
). Using the *
wild card in the
KERNEL
key makes it match several lp
printer devices. Substitutions are used in both the NAME
and the SYMLINK
keys to extend these strings by the
internal device name. For example, the symlink to the first
lp
USB printer would read
/dev/usblp0
.
The kernel firmware loader
rule makes udev load
additional firmware by an external helper script during runtime. The
SUBSYSTEM
match key searches for the
firmware
subsystem. The ACTION
key
checks whether any device belonging to the firmware
subsystem has been added. The RUN+=
key triggers the
execution of the firmware.sh
script to locate the
firmware that is to be loaded.
Some general characteristics are common to all rules:
Each rule consists of one or more key value pairs separated by a comma.
A key's operation is determined by the operator. udev rules support several different operators.
Each given value must be enclosed by quotation marks.
Each line of the rules file represents one rule. If a rule is longer
than just one line, use \
to join the different lines
just as you would do in shell syntax.
udev rules support a shell-style pattern matching for the
*
, ?
, and []
patterns.
udev rules support substitutions.
Creating keys you can choose from several different operators, depending on the type of key you want to create. Match keys will normally just be used to find a value that either matches or explicitly mismatches the search value. Match keys contain either of the following operators:
==
Compare for equality. If the key contains a search pattern, then all results matching this pattern are valid.
!=
Compare for non-equality. If the key contains a search pattern, then all results matching this pattern are valid.
Any of the following operators can be used with assign keys:
=
Assign a value to a key. If the key previously consisted of a list of values, the key resets and only the single value is assigned.
+=
Add a value to a key that contains a list of entries.
:=
Assign a final value. Disallow any later change (by later rules).
udev rules support the use of placeholders and substitutions. Use them in a similar fashion as you would do in any other scripts. The following substitutions can be used with udev rules:
%r
, $root
The device directory, /dev
by default
%p
, $devpath
The value of DEVPATH
%k
, $kernel
The value of KERNEL
or the internal device
name
%n
, $number
The device number
%N
, $tempnode
The temporary name of the device file
%M
, $major
The major number of the device
%m
, $minor
The minor number of the device
%s{attribute
}
,
$attr{attribute
}
The value of a sysfs
attribute (specified by
attribute
)
%E{variable
}
,
$attr{variable
}
The value of an environment variable (specified by
variable
)
%c
, $result
The output of PROGRAM
%%
The %
character
$$
The $
character
Match keys describe conditions that must be met before a udev rule can be applied. The following match keys are available:
ACTION
The name of the event action, e.g. add
or
remove
for a device add or remove action.
DEVPATH
The device path of the event device, e.g.
DEVPATH=/bus/pci/drivers/ipw3945
to search for all
events related to the ipw3945 driver.
KERNEL
The internal (kernel) name of the event device.
SUBSYSTEM
The subsystem of the event device, e.g.
SUBSYSTEM=usb
for all events related to USB
devices.
ATTR{filename
}
sysfs attributes of the event device. To match a string contained
in the vendor
attribute file name, you could use
ATTR{vendor}=="On[sS]tream"
, for example.
KERNELS
Let udev search the device path upwards for a matching device name.
SUBSYSTEMS
Let udev search the device path upwards for a matching device subsystem name.
DRIVERS
Let udev search the device path upwards for a matching device driver name.
ATTRS{filename
}
Let udev search the device path upwards for a device with matching sysfs attribute values.
ENV{key
}
The value of an environment variable, e.g.
ENV{ID_BUS}="ieee1394
to search for all events
related to the FireWire bus ID.
PROGRAM
Let udev execute an external program. For this key to be true, the
program must return without exit code zero. The program's output is
printed to stdout and available to the RESULT
key.
RESULT
Match the return value/string of the last
PROGRAM
call. Either include this key in the same
rule as the PROGRAM
key or in a later one.
In contrast to the match keys described above, assign keys do not describe conditions that must be met, but assign values, names and actions to the device nodes maintained by udev.
NAME
The name of the device node to be created. Once a rule has set a
node name, all other rules with a NAME
key for this
node are ignored.
SYMLINK
The name of a symlink related to the node to be created. Multiple matching rules can add symlinks to be created with the device node. You can also specify multiple symlinks for one node in one rule using the space character to separate the symlink names.
OWNER, GROUP, MODE
The permissions for the new device node. Values specified here overwrite anything that has been compiled in.
ATTR{key
}
Specify a value to be written to a sysfs attribute of the event
device. If the ==
operator is used, this key is also
used to match against the value of a sysfs attribute.
ENV{key
}
Tell udev to export a variable to the environment. If the
==
operator is used, this key is also used to match
against an environment variable.
RUN
Tell udev to add a program to the list of programs to be executed for this device. Mind to restrict this to very short tasks to avoid blocking further events for this device.
LABEL
Add a label where a GOTO
can jump to.
GOTO
Tell udev to skip a number of rules and continue with the one that
carries the label referenced by the GOTO
key.
IMPORT{type
}
Load variables into the event environment such as the output of an external program. udev imports variables of several different types. If no type is specified, udev tries to determine the type itself based on the executable bit of the file permissions.
program
tells udev to execute an external
program and import its output.
file
tells udev to import a text file.
parent
tells udev to import the stored keys
from the parent device.
WAIT_FOR_SYSFS
Tells udev to wait for the specified sysfs file to be created for a
certain device, e.g. WAIT_FOR_SYSFS="ioerr_cnt"
informs udev to wait until the ioerr_cnt
file has
been created.
OPTIONS
There are several possible values to the OPTION
key:
last_rule
tells udev to ignore all later
rules.
ignore_device
tells udev to ignore this event
completely.
ignore_remove
tells udev to ignore all later
remove event the device.
all_partitions
tells udev to create device
nodes for all available partitions on a block device.