udev¶Contents
/dev Directoryuevents and udevudev Daemonudev Rulesudev
The kernel can add or remove almost any device in a running system.
Changes in the device state (whether a device is plugged in or removed)
need to be propagated to userspace. Devices need to be configured as soon
as they are plugged in and recognized. Users of a certain device need to
be informed about any changes in this device's recognized state.
udev provides the needed
infrastructure to dynamically maintain the device node files and symbolic
links in the /dev directory.
udev rules provide a way to plug
external tools into the kernel device event processing. This enables you
to customize udev device handling
by, for example, adding certain scripts to execute as part of kernel
device handling, or request and import additional data to evaluate during
device handling.
/dev Directory¶
The device nodes in the /dev directory provide
access to the corresponding kernel devices. With
udev, the
/dev directory reflects the current state of the
kernel. Every kernel device has one corresponding device file. If a
device is disconnected from the system, the device node is removed.
The content of the /dev directory is kept on a
temporary file system and all files are rendered at every system
start-up. Manually created or modified files do not, by design, survive a
reboot. Static files and directories that should always be present in the
/dev directory regardless of the state of the
corresponding kernel device can be placed in the
/lib/udev/devices directory. At system start-up, the
contents of that directory is copied to the /dev
directory with the same ownership and permissions as the files in
/lib/udev/devices.
uevents and udev¶
The required device information is exported by the
sysfs file system. For every
device the kernel has detected and initialized, a directory with the
device name is created. It contains attribute files with device-specific
properties.
Every time a device is added or removed, the kernel sends a uevent to
notify udev of the change. The
udev daemon reads and parses all
provided rules from the /etc/udev/rules.d/*.rules
files once at start-up and keeps them in memory. If rules files are
changed, added or removed, the daemon can reload the in-memory
representation of all rules with the command udevadm control
reload_rules. This is also done when running
/etc/init.d/boot.udev reload. For more details on
udev rules and their syntax,
refer to Section 20.6, “Influencing Kernel Device Event Handling with udev Rules”.
Every received event is matched against the set of provides rules. The
rules can add or change event environment keys, request a specific name
for the device node to create, add symlinks pointing to the node or add
programs to run after the device node is created. The driver core
uevents are received from a
kernel netlink socket.
The kernel bus drivers probe for devices. For every detected device, the
kernel creates an internal device structure while the driver core sends a
uevent to the udev daemon. Bus
devices identify themselves by a specially-formatted ID, which tells what
kind of device it is. Usually these IDs consist of vendor and product ID
and other subsystem-specific values. Every bus has its own scheme for
these IDs, called MODALIAS. The kernel takes the device
information, composes a MODALIAS ID string from it and
sends that string along with the event. For a USB mouse, it looks like
this:
MODALIAS=usb:v046DpC03Ed2000dc00dsc00dp00ic03isc01ip02
Every device driver carries a list of known aliases for devices it can
handle. The list is contained in the kernel module file itself. The
program depmod reads the ID lists and creates the file
modules.alias in the kernel's
/lib/modules directory for all currently available
modules. With this infrastructure, module loading is as easy as calling
modprobe for every event that carries a
MODALIAS key. If modprobe $MODALIAS
is called, it matches the device alias composed for the device with the
aliases provided by the modules. If a matching entry is found, that
module is loaded. All this is automatically triggered by
udev.
All device events happening during the boot process before the
udev daemon is running are lost,
because the infrastructure to handle these events resides on the root
file system and is not available at that time. To cover that loss, the
kernel provides a uevent file located in the device
directory of every device in the
sysfs file system. By writing
add to that file, the kernel resends the same event as
the one lost during boot. A simple loop over all
uevent files in /sys triggers
all events again to create the device nodes and perform device setup.
As an example, a USB mouse present during boot may not be initialized by
the early boot logic, because the driver is not available at that time.
The event for the device discovery was lost and failed to find a kernel
module for the device. Instead of manually searching for possibly
connected devices, udev just
requests all device events from the kernel after the root file system is
available, so the event for the USB mouse device just runs again. Now it
finds the kernel module on the mounted root file system and the USB mouse
can be initialized.
From userspace, there is no visible difference between a device coldplug sequence and a device discovery during runtime. In both cases, the same rules are used to match and the same configured programs are run.
udev Daemon¶
The program udevadm monitor can be used to visualize
the driver core events and the timing of the
udev event processes.
UEVENT[1185238505.276660] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1 (usb) UDEV [1185238505.279198] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1 (usb) UEVENT[1185238505.279527] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0 (usb) UDEV [1185238505.285573] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0 (usb) UEVENT[1185238505.298878] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10 (input) UDEV [1185238505.305026] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10 (input) UEVENT[1185238505.305442] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10/mouse2 (input) UEVENT[1185238505.306440] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10/event4 (input) UDEV [1185238505.325384] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10/event4 (input) UDEV [1185238505.342257] add /devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10/mouse2 (input)
The UEVENT lines show the events the kernel has sent
over netlink. The UDEV lines show the finished
udev event handlers. The timing
is printed in microseconds. The time between UEVENT
and UDEV is the time
udev took to process this event
or the udev daemon has delayed
its execution to synchronize this event with related and already running
events. For example, events for hard disk partitions always wait for the
main disk device event to finish, because the partition events may rely
on the data that the main disk event has queried from the hardware.
udevadm monitor --env shows the complete event environment:
ACTION=add DEVPATH=/devices/pci0000:00/0000:00:1d.2/usb3/3-1/3-1:1.0/input/input10 SUBSYSTEM=input SEQNUM=1181 NAME="Logitech USB-PS/2 Optical Mouse" PHYS="usb-0000:00:1d.2-1/input0" UNIQ="" EV=7 KEY=70000 0 0 0 0 REL=103 MODALIAS=input:b0003v046DpC03Ee0110-e0,1,2,k110,111,112,r0,1,8,amlsfw
udev also sends messages to
syslog. The default syslog priority that controls which messages are sent
to syslog is specified in the
udev configuration file
/etc/udev/udev.conf. The log priority of the running
daemon can be changed with udevadm control
log_priority=level/number.
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 20.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
considering. 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.
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.
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.
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.
udev Assign Keys¶
In contrast to the match keys described above, assign keys do not
describe conditions that must be met. They 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. Keep in 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.
The dynamic device directory and the
udev rules infrastructure make
it possible to provide stable names for all disk devices—regardless
of their order of recognition or the connection used for the device.
Every appropriate block device the kernel creates is examined by tools
with special knowledge about certain buses, drive types or file systems.
Along with the dynamic kernel-provided device node name,
udev maintains classes of
persistent symbolic links pointing to the device:
/dev/disk
|-- by-id
| |-- scsi-SATA_HTS726060M9AT00_MRH453M4HWHG7B -> ../../sda
| |-- scsi-SATA_HTS726060M9AT00_MRH453M4HWHG7B-part1 -> ../../sda1
| |-- scsi-SATA_HTS726060M9AT00_MRH453M4HWHG7B-part6 -> ../../sda6
| |-- scsi-SATA_HTS726060M9AT00_MRH453M4HWHG7B-part7 -> ../../sda7
| |-- usb-Generic_STORAGE_DEVICE_02773 -> ../../sdd
| `-- usb-Generic_STORAGE_DEVICE_02773-part1 -> ../../sdd1
|-- by-label
| |-- Photos -> ../../sdd1
| |-- SUSE10 -> ../../sda7
| `-- devel -> ../../sda6
|-- by-path
| |-- pci-0000:00:1f.2-scsi-0:0:0:0 -> ../../sda
| |-- pci-0000:00:1f.2-scsi-0:0:0:0-part1 -> ../../sda1
| |-- pci-0000:00:1f.2-scsi-0:0:0:0-part6 -> ../../sda6
| |-- pci-0000:00:1f.2-scsi-0:0:0:0-part7 -> ../../sda7
| |-- pci-0000:00:1f.2-scsi-1:0:0:0 -> ../../sr0
| |-- usb-02773:0:0:2 -> ../../sdd
| |-- usb-02773:0:0:2-part1 -> ../../sdd1
`-- by-uuid
|-- 159a47a4-e6e6-40be-a757-a629991479ae -> ../../sda7
|-- 3e999973-00c9-4917-9442-b7633bd95b9e -> ../../sda6
`-- 4210-8F8C -> ../../sdd1udev¶/sys/*
Virtual file system provided by the Linux kernel, exporting all
currently known devices. This information is used by
udev to create device nodes
in /dev
/dev/*
Dynamically created device nodes and static content copied at boot
time from /lib/udev/devices/*
The following files and directories contain the crucial elements of the
udev infrastructure:
/etc/udev/udev.conf
Main udev configuration file.
/etc/udev/rules.d/*
udev event matching rules.
/lib/udev/devices/*
Static /dev content.
/lib/udev/*
Helper programs called from
udev rules.
For more information about the
udev infrastructure, refer to
the following man pages:
udev
General information about
udev, keys, rules and other
important configuration issues.
udevadm can be used to control the runtime behavior
of udev, request kernel
events, manage the event queue and provide simple debugging
mechanisms.
udevd
Information about the udev
event managing daemon.