diff options
Diffstat (limited to 'upstream/fedora-rawhide/man7/udev.7')
| -rw-r--r-- | upstream/fedora-rawhide/man7/udev.7 | 717 |
1 files changed, 717 insertions, 0 deletions
diff --git a/upstream/fedora-rawhide/man7/udev.7 b/upstream/fedora-rawhide/man7/udev.7 new file mode 100644 index 00000000..4703ad59 --- /dev/null +++ b/upstream/fedora-rawhide/man7/udev.7 @@ -0,0 +1,717 @@ +'\" 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 |