path: root/upstream/fedora-rawhide/man7/udev.7

'\" t
.TH "UDEV" "7" "" "systemd 255" "udev"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
udev \- Dynamic device management
.SH "DESCRIPTION"
.PP
udev supplies the system software with device events, manages permissions of device nodes and may create additional symlinks in the
/dev/
directory, or renames network interfaces\&. The kernel usually just assigns unpredictable device names based on the order of discovery\&. Meaningful symlinks or network device names provide a way to reliably identify devices based on their properties or current configuration\&.
.PP
The udev daemon,
\fBsystemd-udevd.service\fR(8), receives device uevents directly from the kernel whenever a device is added or removed from the system, or it changes its state\&. When udev receives a device event, it matches its configured set of rules against various device attributes to identify the device\&. Rules that match may provide additional device information to be stored in the udev database or to be used to create meaningful symlink names\&.
.PP
All device information udev processes is stored in the udev database and sent out to possible event subscribers\&. Access to all stored data and the event sources is provided by the library libudev\&.
.SH "RULES FILES"
.PP
The udev rules are read from the files located in the system rules directories
/usr/lib/udev/rules\&.d
and
/usr/local/lib/udev/rules\&.d, the volatile runtime directory
/run/udev/rules\&.d
and the local administration directory
/etc/udev/rules\&.d\&. All rules files are collectively sorted and processed in lexical order, regardless of the directories in which they live\&. However, files with identical filenames replace each other\&. Files in
/etc/
have the highest priority, files in
/run/
take precedence over files with the same name under
/usr/\&. This can be used to override a system\-supplied rules file with a local file if needed; a symlink in
/etc/
with the same name as a rules file in
/usr/lib/, pointing to
/dev/null, disables the rules file entirely\&. Rule files must have the extension
\&.rules; other extensions are ignored\&.
.PP
Every line in the rules file contains at least one key\-value pair\&. Except for empty lines or lines beginning with
"#", which are ignored\&. There are two kinds of keys: match and assignment\&. If all match keys match against their values, the rule gets applied and the assignment keys get the specified values assigned\&.
.PP
A matching rule may rename a network interface, add symlinks pointing to the device node, or run a specified program as part of the event handling\&.
.PP
A rule consists of a comma\-separated list of one or more key\-operator\-value expressions\&. Each expression has a distinct effect, depending on the key and operator used\&.
.SS "Operators"
.PP
"=="
.RS 4
Compare for equality\&. (The specified key has the specified value\&.)
.RE
.PP
"!="
.RS 4
Compare for inequality\&. (The specified key doesn\*(Aqt have the specified value, or the specified key is not present at all\&.)
.RE
.PP
"="
.RS 4
Assign a value to a key\&. Keys that represent a list are reset and only this single value is assigned\&.
.RE
.PP
"+="
.RS 4
Add the value to a key that holds a list of entries\&.
.RE
.PP
"\-="
.RS 4
Remove the value from a key that holds a list of entries\&.
.sp
Added in version 217\&.
.RE
.PP
":="
.RS 4
Assign a value to a key finally; disallow any later changes\&.
.sp
Added in version 247\&.
.RE
.SS "Values"
.PP
Values are written as double quoted strings, such as ("string")\&. To include a quotation mark (") in the value, precede it by a backslash (\e")\&. Any other occurrences of a backslash followed by a character are not unescaped\&. That is, "\et\en" is treated as four characters: backslash, lowercase t, backslash, lowercase n\&.
.PP
The string can be prefixed with a lowercase e (e"string\en") to mark the string as C\-style escaped, see
\m[blue]\fBEscape sequences in C\fR\m[]\&\s-2\u[1]\d\s+2\&. For example, e"string\en" is parsed as 7 characters: 6 lowercase letters and a newline\&. This can be useful for writing special characters when a kernel driver requires them\&.
.PP
Please note that
\fBNUL\fR
is not allowed in either string variant\&.
.SS "Keys"
.PP
The following key names can be used to match against device properties\&. Some of the keys also match against properties of the parent devices in sysfs, not only the device that has generated the event\&. If multiple keys that match a parent device are specified in a single rule, all these keys must match at one and the same parent device\&.
.PP
\fIACTION\fR
.RS 4
Match the name of the event action\&.
.RE
.PP
\fIDEVPATH\fR
.RS 4
Match the devpath of the event device\&.
.RE
.PP
\fIKERNEL\fR
.RS 4
Match the name of the event device\&.
.RE
.PP
\fIKERNELS\fR
.RS 4
Search the devpath upwards for a matching device name\&.
.RE
.PP
\fINAME\fR
.RS 4
Match the name of a network interface\&. It can be used once the NAME key has been set in one of the preceding rules\&.
.RE
.PP
\fISYMLINK\fR
.RS 4
Match the name of a symlink targeting the node\&. It can be used once a SYMLINK key has been set in one of the preceding rules\&. There may be multiple symlinks; only one needs to match\&. If the operator is
"!=", the token returns true only if there is no symlink matched\&.
.RE
.PP
\fISUBSYSTEM\fR
.RS 4
Match the subsystem of the event device\&.
.RE
.PP
\fISUBSYSTEMS\fR
.RS 4
Search the devpath upwards for a matching device subsystem name\&.
.RE
.PP
\fIDRIVER\fR
.RS 4
Match the driver name of the event device\&. Only set this key for devices which are bound to a driver at the time the event is generated\&.
.RE
.PP
\fIDRIVERS\fR
.RS 4
Search the devpath upwards for a matching device driver name\&.
.RE
.PP
\fIATTR{\fR\fI\fIfilename\fR\fR\fI}\fR
.RS 4
Match sysfs attribute value of the event device\&.
.sp
Trailing whitespace in the attribute values is ignored unless the specified match value itself contains trailing whitespace\&.
.RE
.PP
\fIATTRS{\fR\fI\fIfilename\fR\fR\fI}\fR
.RS 4
Search the devpath upwards for a device with matching sysfs attribute values\&. If multiple
\fIATTRS\fR
matches are specified, all of them must match on the same device\&.
.sp
Trailing whitespace in the attribute values is ignored unless the specified match value itself contains trailing whitespace\&.
.RE
.PP
\fISYSCTL{\fR\fI\fIkernel parameter\fR\fR\fI}\fR
.RS 4
Match a kernel parameter value\&.
.sp
Added in version 240\&.
.RE
.PP
\fIENV{\fR\fI\fIkey\fR\fR\fI}\fR
.RS 4
Match against a device property value\&.
.RE
.PP
\fICONST{\fR\fI\fIkey\fR\fR\fI}\fR
.RS 4
Match against a system\-wide constant\&. Supported keys are:
.PP
"arch"
.RS 4
System\*(Aqs architecture\&. See
\fBConditionArchitecture=\fR
in
\fBsystemd.unit\fR(5)
for possible values\&.
.sp
Added in version 244\&.
.RE
.PP
"virt"
.RS 4
System\*(Aqs virtualization environment\&. See
\fBsystemd-detect-virt\fR(1)
for possible values\&.
.sp
Added in version 244\&.
.RE
.PP
"cvm"
.RS 4
System\*(Aqs confidential virtualization technology\&. See
\fBsystemd-detect-virt\fR(1)
for possible values\&.
.sp
Added in version 254\&.
.RE
.sp
Unknown keys will never match\&.
.sp
Added in version 244\&.
.RE
.PP
\fITAG\fR
.RS 4
Match against one of device tags\&. It can be used once a TAG key has been set in one of the preceding rules\&. There may be multiple tags; only one needs to match\&. If the operator is
"!=", the token returns true only if there is no tag matched\&.
.RE
.PP
\fITAGS\fR
.RS 4
Search the devpath upwards for a device with matching tag\&. If the operator is
"!=", the token returns true only if there is no tag matched\&.
.RE
.PP
\fITEST{\fR\fI\fIoctal mode mask\fR\fR\fI}\fR
.RS 4
Test the existence of a file\&. An octal mode mask can be specified if needed\&.
.RE
.PP
\fIPROGRAM\fR
.RS 4
Execute a program to determine whether there is a match; the key is true if the program returns successfully\&. The device properties are made available to the executed program in the environment\&. The program\*(Aqs standard output is available in the
\fIRESULT\fR
key\&.
.sp
This can only be used for very short\-running foreground tasks\&. For details, see
\fIRUN\fR\&.
.sp
Note that multiple
\fIPROGRAM\fR
keys may be specified in one rule, and
"=",
":=", and
"+="
have the same effect as
"=="\&.
.RE
.PP
\fIRESULT\fR
.RS 4
Match the returned string of the last
\fIPROGRAM\fR
call\&. This key can be used in the same or in any later rule after a
\fIPROGRAM\fR
call\&.
.RE
.PP
Most of the fields support shell glob pattern matching and alternate patterns\&. The following special characters are supported:
.PP
"*"
.RS 4
Matches zero or more characters\&.
.RE
.PP
"?"
.RS 4
Matches any single character\&.
.RE
.PP
"[]"
.RS 4
Matches any single character specified within the brackets\&. For example, the pattern string
"tty[SR]"
would match either
"ttyS"
or
"ttyR"\&. Ranges are also supported via the
"\-"
character\&. For example, to match on the range of all digits, the pattern
"[0\-9]"
could be used\&. If the first character following the
"["
is a
"!", any characters not enclosed are matched\&.
.RE
.PP
"|"
.RS 4
Separates alternative patterns\&. For example, the pattern string
"abc|x*"
would match either
"abc"
or
"x*"\&.
.sp
Added in version 217\&.
.RE
.PP
The following keys can get values assigned:
.PP
\fINAME\fR
.RS 4
The name to use for a network interface\&. See
\fBsystemd.link\fR(5)
for a higher\-level mechanism for setting the interface name\&. The name of a device node cannot be changed by udev, only additional symlinks can be created\&.
.RE
.PP
\fISYMLINK\fR
.RS 4
The name of a symlink targeting the node\&. Every matching rule adds this value to the list of symlinks to be created\&.
.sp
The set of characters to name a symlink is limited\&. Allowed characters are
"0\-9A\-Za\-z#+\-\&.:=@_/", valid UTF\-8 character sequences, and
"\ex00"
hex encoding\&. All other characters are replaced by a
"_"
character\&.
.sp
Multiple symlinks may be specified by separating the names by the space character\&. In case multiple devices claim the same name, the link always points to the device with the highest link_priority\&. If the current device goes away, the links are re\-evaluated and the device with the next highest link_priority becomes the owner of the link\&. If no link_priority is specified, the order of the devices (and which one of them owns the link) is undefined\&.
.sp
Symlink names must never conflict with the kernel\*(Aqs default device node names, as that would result in unpredictable behavior\&.
.RE
.PP
\fIOWNER\fR, \fIGROUP\fR, \fIMODE\fR
.RS 4
The permissions for the device node\&. Every specified value overrides the compiled\-in default value\&.
.RE
.PP
\fISECLABEL{\fR\fI\fImodule\fR\fR\fI}\fR
.RS 4
Applies the specified Linux Security Module label to the device node\&.
.sp
Added in version 209\&.
.RE
.PP
\fIATTR{\fR\fI\fIkey\fR\fR\fI}\fR
.RS 4
The value that should be written to a sysfs attribute of the event device\&.
.RE
.PP
\fISYSCTL{\fR\fI\fIkernel parameter\fR\fR\fI}\fR
.RS 4
The value that should be written to kernel parameter\&.
.sp
Added in version 220\&.
.RE
.PP
\fIENV{\fR\fI\fIkey\fR\fR\fI}\fR
.RS 4
Set a device property value\&. Property names with a leading
"\&."
are neither stored in the database nor exported to events or external tools (run by, for example, the
\fIPROGRAM\fR
match key)\&.
.RE
.PP
\fITAG\fR
.RS 4
Attach a tag to a device\&. This is used to filter events for users of libudev\*(Aqs monitor functionality, or to enumerate a group of tagged devices\&. The implementation can only work efficiently if only a few tags are attached to a device\&. It is only meant to be used in contexts with specific device filter requirements, and not as a general\-purpose flag\&. Excessive use might result in inefficient event handling\&.
.RE
.PP
\fIRUN{\fR\fI\fItype\fR\fR\fI}\fR
.RS 4
Specify a program to be executed after processing of all the rules for the event\&. With
"+=", this invocation is added to the list, and with
"="
or
":=", it replaces any previous contents of the list\&. Please note that both
"program"
and
"builtin"
types described below share a common list, so clearing the list with
":="
and
"="
affects both types\&.
.sp
\fItype\fR
may be:
.PP
"program"
.RS 4
Execute an external program specified as the assigned value\&. If no absolute path is given, the program is expected to live in
/usr/lib/udev; otherwise, the absolute path must be specified\&.
.sp
This is the default if no
\fItype\fR
is specified\&.
.RE
.PP
"builtin"
.RS 4
As
\fIprogram\fR, but use one of the built\-in programs rather than an external one\&.
.sp
Added in version 199\&.
.RE
.sp
The program name and following arguments are separated by spaces\&. Single quotes can be used to specify arguments with spaces\&.
.sp
This can only be used for very short\-running foreground tasks\&. Running an event process for a long period of time may block all further events for this or a dependent device\&.
.sp
Note that running programs that access the network or mount/unmount filesystems is not allowed inside of udev rules, due to the default sandbox that is enforced on
systemd\-udevd\&.service\&.
.sp
Starting daemons or other long\-running processes is not allowed; the forked processes, detached or not, will be unconditionally killed after the event handling has finished\&. In order to activate long\-running processes from udev rules, provide a service unit and pull it in from a udev device using the
\fISYSTEMD_WANTS\fR
device property\&. See
\fBsystemd.device\fR(5)
for details\&.
.RE
.PP
\fILABEL\fR
.RS 4
A named label to which a
\fIGOTO\fR
may jump\&.
.RE
.PP
\fIGOTO\fR
.RS 4
Jumps to the next
\fILABEL\fR
with a matching name\&.
.RE
.PP
\fIIMPORT{\fR\fI\fItype\fR\fR\fI}\fR
.RS 4
Import a set of variables as device properties, depending on
\fItype\fR:
.PP
"program"
.RS 4
Execute an external program specified as the assigned value and, if it returns successfully, import its output, which must be in environment key format\&. Path specification, command/argument separation, and quoting work like in
\fIRUN\fR\&.
.sp
Added in version 199\&.
.RE
.PP
"builtin"
.RS 4
Similar to
"program", but use one of the built\-in programs rather than an external one\&.
.sp
Added in version 199\&.
.RE
.PP
"file"
.RS 4
Import a text file specified as the assigned value, the content of which must be in environment key format\&.
.RE
.PP
"db"
.RS 4
Import a single property specified as the assigned value from the current device database\&. This works only if the database is already populated by an earlier event\&.
.RE
.PP
"cmdline"
.RS 4
Import a single property from the kernel command line\&. For simple flags the value of the property is set to
"1"\&.
.RE
.PP
"parent"
.RS 4
Import the stored keys from the parent device by reading the database entry of the parent device\&. The value assigned to
\fBIMPORT{parent}\fR
is used as a filter of key names to import (with the same shell glob pattern matching used for comparisons)\&.
.RE
.sp
This can only be used for very short\-running foreground tasks\&. For details see
\fBRUN\fR\&.
.sp
Note that multiple
\fIIMPORT{}\fR
keys may be specified in one rule, and
"=",
":=", and
"+="
have the same effect as
"=="\&. The key is true if the import is successful, unless
"!="
is used as the operator which causes the key to be true if the import failed\&.
.RE
.PP
\fIOPTIONS\fR
.RS 4
Rule and device options:
.PP
\fBlink_priority=\fR\fB\fIvalue\fR\fR
.RS 4
Specify the priority of the created symlinks\&. Devices with higher priorities overwrite existing symlinks of other devices\&. The default is 0\&.
.RE
.PP
\fBstring_escape=\fR\fB\fInone|replace\fR\fR
.RS 4
When
"replace", possibly unsafe characters in strings assigned to
\fINAME\fR,
\fISYMLINK\fR, and
\fIENV{\fR\fI\fIkey\fR\fR\fI}\fR
are replaced\&. When
"none", no replacement is performed\&. When unset, the replacement is performed for
\fINAME\fR,
\fISYMLINK\fR, but not for
\fIENV{\fR\fI\fIkey\fR\fR\fI}\fR\&. Defaults to unset\&.
.RE
.PP
\fBstatic_node=\fR
.RS 4
Apply the permissions specified in this rule to the static device node with the specified name\&. Also, for every tag specified in this rule, create a symlink in the directory
/run/udev/static_node\-tags/\fItag\fR
pointing at the static device node with the specified name\&. Static device node creation is performed by systemd\-tmpfiles before systemd\-udevd is started\&. The static nodes might not have a corresponding kernel device; they are used to trigger automatic kernel module loading when they are accessed\&.
.RE
.PP
\fBwatch\fR
.RS 4
Watch the device node with inotify; when the node is closed after being opened for writing, a change uevent is synthesized\&.
.RE
.PP
\fBnowatch\fR
.RS 4
Disable the watching of a device node with inotify\&.
.RE
.PP
\fBdb_persist\fR
.RS 4
Set the flag (sticky bit) on the udev database entry of the event device\&. Device properties are then kept in the database even when
\fBudevadm info \-\-cleanup\-db\fR
is called\&. This option can be useful in certain cases (e\&.g\&. Device Mapper devices) for persisting device state on the transition from initrd\&.
.sp
Added in version 241\&.
.RE
.PP
\fBlog_level=\fR\fB\fIlevel\fR\fR
.RS 4
Takes a log level name like
"debug"
or
"info", or a special value
"reset"\&. When a log level name is specified, the maximum log level is changed to that level\&. When
"reset"
is set, then the previously specified log level is revoked\&. Defaults to the log level of the main process of
\fBsystemd\-udevd\fR\&.
.sp
This may be useful when debugging events for certain devices\&. Note that the log level is applied when the line including this rule is processed\&. So, for debugging, it is recommended that this is specified at earlier place, e\&.g\&., the first line of
00\-debug\&.rules\&.
.sp
Example for debugging uevent processing for network interfaces:
.sp
.if n \{\
.RS 4
.\}
.nf
# /etc/udev/rules\&.d/00\-debug\-net\&.rules
SUBSYSTEM=="net", OPTIONS="log_level=debug"
.fi
.if n \{\
.RE
.\}
.sp
Added in version 248\&.
.RE
.RE
.PP
The
\fINAME\fR,
\fISYMLINK\fR,
\fIPROGRAM\fR,
\fIOWNER\fR,
\fIGROUP\fR,
\fIMODE\fR,
\fISECLABEL\fR, and
\fIRUN\fR
fields support simple string substitutions\&. The
\fIRUN\fR
substitutions are performed after all rules have been processed, right before the program is executed, allowing for the use of device properties set by earlier matching rules\&. For all other fields, substitutions are performed while the individual rule is being processed\&. The available substitutions are:
.PP
\fB$kernel\fR, \fB%k\fR
.RS 4
The kernel name for this device\&.
.RE
.PP
\fB$number\fR, \fB%n\fR
.RS 4
The kernel number for this device\&. For example,
"sda3"
has kernel number 3\&.
.RE
.PP
\fB$devpath\fR, \fB%p\fR
.RS 4
The devpath of the device\&.
.RE
.PP
\fB$id\fR, \fB%b\fR
.RS 4
The name of the device matched while searching the devpath upwards for
\fBSUBSYSTEMS\fR,
\fBKERNELS\fR,
\fBDRIVERS\fR, and
\fBATTRS\fR\&.
.RE
.PP
\fB$driver\fR
.RS 4
The driver name of the device matched while searching the devpath upwards for
\fBSUBSYSTEMS\fR,
\fBKERNELS\fR,
\fBDRIVERS\fR, and
\fBATTRS\fR\&.
.RE
.PP
\fB$attr{\fR\fB\fIfile\fR\fR\fB}\fR, \fB%s{\fR\fB\fIfile\fR\fR\fB}\fR
.RS 4
The value of a sysfs attribute found at the device where all keys of the rule have matched\&. If the matching device does not have such an attribute, and a previous
\fBKERNELS\fR,
\fBSUBSYSTEMS\fR,
\fBDRIVERS\fR, or
\fBATTRS\fR
test selected a parent device, then the attribute from that parent device is used\&.
.sp
If the attribute is a symlink, the last element of the symlink target is returned as the value\&.
.RE
.PP
\fB$env{\fR\fB\fIkey\fR\fR\fB}\fR, \fB%E{\fR\fB\fIkey\fR\fR\fB}\fR
.RS 4
A device property value\&.
.RE
.PP
\fB$major\fR, \fB%M\fR
.RS 4
The kernel major number for the device\&.
.RE
.PP
\fB$minor\fR, \fB%m\fR
.RS 4
The kernel minor number for the device\&.
.RE
.PP
\fB$result\fR, \fB%c\fR
.RS 4
The string returned by the external program requested with
\fIPROGRAM\fR\&. A single part of the string, separated by a space character, may be selected by specifying the part number as an attribute:
"%c{N}"\&. If the number is followed by the
"+"
character, this part plus all remaining parts of the result string are substituted:
"%c{N+}"\&.
.RE
.PP
\fB$parent\fR, \fB%P\fR
.RS 4
The node name of the parent device\&.
.RE
.PP
\fB$name\fR
.RS 4
The current name of the device\&. If not changed by a rule, it is the name of the kernel device\&.
.RE
.PP
\fB$links\fR
.RS 4
A space\-separated list of the current symlinks\&. The value is only set during a remove event or if an earlier rule assigned a value\&.
.RE
.PP
\fB$root\fR, \fB%r\fR
.RS 4
The udev_root value\&.
.RE
.PP
\fB$sys\fR, \fB%S\fR
.RS 4
The sysfs mount point\&.
.RE
.PP
\fB$devnode\fR, \fB%N\fR
.RS 4
The name of the device node\&.
.RE
.PP
\fB%%\fR
.RS 4
The
"%"
character itself\&.
.RE
.PP
\fB$$\fR
.RS 4
The
"$"
character itself\&.
.RE
.SH "SEE ALSO"
.PP
\fBsystemd-udevd.service\fR(8),
\fBudevadm\fR(8),
\fBsystemd.link\fR(5)
.SH "NOTES"
.IP " 1." 4
Escape sequences in C
.RS 4
\%https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences
.RE