|
 |
|
| |
17.6 Influencing Kernel Device Event Handling with udev Rules
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 17-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 consists 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 only. 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 that matches the
*, ?, and []
patterns.
-
udev rules support substitutions.
17.6.1 Using Operators in udev Rules
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, all
results matching this pattern are valid.
- !=
-
Compare for non-equality. If the key contains a search pattern, 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.
17.6.2 Using Substitutions in udev 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.
17.6.3 Using udev Match Keys
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, for example, add or
remove when adding or removing a device.
- DEVPATH
-
The device path of the event device, for example,
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, for example,
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, for example,
ENV{ID_BUS}="ieee1394 to search for all events
related to the FireWire bus ID.
- PROGRAM
-
Let udev execute an external program. To be successful, the program
must return with exit code zero. The program's output, printed to
stdout, is available to the RESULT key.
- RESULT
-
Match the output string of the last PROGRAM call.
Either include this key in the same rule as the
PROGRAM key or in a later one.
17.6.4 Using udev Assign Keys
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, for example,
WAIT_FOR_SYSFS="ioerr_cnt" informs udev to wait
until the ioerr_cnt file has been created.
- OPTIONS
-
The OPTION key may have several possible values:
-
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 events for the device.
-
all_partitions tells udev to create device nodes
for all available partitions on a block device.
|
|
|
