</refsect1>
<refsect1><title>Configuration</title>
- <para>udev configuration files are placed in <filename>/etc/udev/</filename>
- and <filename>/lib/udev/</filename>. All empty lines or lines beginning with
+ <para>udev configuration files are placed in <filename>/etc/udev</filename>
+ and <filename>/usr/lib/udev</filename>. All empty lines or lines beginning with
'#' are ignored.</para>
<refsect2><title>Configuration file</title>
<refsect2><title>Rules files</title>
<para>The udev rules are read from the files located in the
- default rules directory <filename>/lib/udev/rules.d/</filename>,
- the custom rules directory <filename>/etc/udev/rules.d/</filename>
- and the temporary rules directory <filename>/run/udev/rules.d/</filename>.
- All rule files are collectively sorted and processed in lexical order,
- regardless of the directories in which they live. However, files in
- <filename>/etc/udev/rules.d/</filename> take precedence over files with
- the same name in <filename>/lib/udev/rules.d/</filename>; this can be
- used to ignore a default rules file if needed.</para>
+ system rules directory <filename>/usr/lib/udev/rules.d</filename>,
+ the local administration directory <filename>/etc/udev/rules.d</filename>
+ and the volatile runtime directory <filename>/run/udev/rules.d</filename>.
+ All rules files are collectively sorted and processed in lexical order,
+ regardless of the directories in which they live. However, files with
+ identical file names replace each other. Files in <filename>/run</filename>
+ have the highest priority, files in <filename>/etc</filename> take precedence
+ over files with the same name in <filename>/lib</filename>. This can be
+ used to overwrite a system rules file if needed; a symlink in
+ <filename>/etc</filename> with the same name as a rules file in
+ <filename>/lib</filename>, pointing to <filename>/dev/null</filename>,
+ disables the rules file entirely.</para>
<para>Rule files must have the extension <filename>.rules</filename>; other
extensions are ignored.</para>
<para>Every line in the rules file contains at least one key-value pair.
There are two kind of keys: match and assignment.
If all match keys are matching against its value, the rule gets applied and the
- assign keys get the specified value assigned.</para>
+ assignment keys get the specified value assigned.</para>
<para>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.</para>
- <para>A rule consists of a list of one or more key-value pairs separated by
- a comma. Each key has a distinct operation, depending on the used operator. Valid
+ <para>A rule consists of a comma-separated list of one or more key-value pairs.
+ Each key has a distinct operation, depending on the used operator. Valid
operators are:</para>
<variablelist>
<varlistentry>
<varlistentry>
<term><option>:=</option></term>
<listitem>
- <para>Assign a value to a key finally; disallow any later changes,
- which may be used to prevent changes by any later rules.</para>
+ <para>Assign a value to a key finally; disallow any later changes.</para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term><option>NAME</option></term>
<listitem>
- <para>Match the name of the node or network interface. It can
- be used once the NAME key has been set in one of the preceding
- rules.</para>
+ <para>Match the name of a network interface. It can be used once the
+ NAME key has been set in one of the preceding rules.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>DRIVER</option></term>
<listitem>
- <para>Match the driver name of the event device. Only set for devices
+ <para>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.</para>
</listitem>
</varlistentry>
<term><option>ATTR{<replaceable>filename</replaceable>}</option></term>
<listitem>
<para>Match sysfs attribute values of the event device. Trailing
- whitespace in the attribute values is ignored, if the specified match
- value does not contain trailing whitespace itself.
+ whitespace in the attribute values is ignored unless the specified match
+ value itself contains trailing whitespace.
</para>
</listitem>
</varlistentry>
<listitem>
<para>Search the devpath upwards for a device with matching sysfs attribute values.
If multiple <option>ATTRS</option> matches are specified, all of them
- must match on the same device. Trailing whitespace in the attribute values is ignored,
- if the specified match value does not contain trailing whitespace itself.</para>
+ must match on the same device. Trailing whitespace in the attribute values is ignored
+ unless the specified match value itself contains trailing whitespace.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>TAGS</option></term>
+ <listitem>
+ <para>Search the devpath upwards for a device with matching tag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>PROGRAM</option></term>
<listitem>
- <para>Execute a program. The key is true, if the program returns
+ <para>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's output printed to
- stdout, is available in the RESULT key.</para>
+ executed program in the environment. The program's stdout
+ is available in the RESULT key.</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
- <para>Most of the fields support a shell style pattern matching. The following
+ <para>Most of the fields support shell-style pattern matching. The following
pattern characters are supported:</para>
<variablelist>
<varlistentry>
<term><option>*</option></term>
<listitem>
- <para>Matches zero, or any number of characters.</para>
+ <para>Matches zero or more characters.</para>
</listitem>
</varlistentry>
<varlistentry>
<listitem>
<para>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 within this match with the '-' character.
- For example, to match on the range of all digits, the pattern [0-9] would
+ 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.</para>
</listitem>
<varlistentry>
<term><option>NAME</option></term>
<listitem>
- <para>The name, a network interface should be renamed to. Or as
- a temporary workaround, the name a device node should be named.
- Usually the kernel provides the defined node name, or even creates
- and removes the node before udev even receives any event. Changing
- the node name from the kernel's default creates inconsistencies
- and is not supported. If the kernel and NAME specify different names,
- an error is logged. Udev is only expected to handle device node
- permissions and to create additional symlinks, not to change
- kernel-provided device node names. Instead of renaming a device node,
- SYMLINK should be used. Symlink names must never conflict with
- device node names, it results in unpredictable behavior.</para>
+ <para>The name to use for a network interface. The name of a device node
+ can not be changed by udev, only additional symlinks can be created.</para>
</listitem>
</varlistentry>
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. Claiming the same name for
- a symlink, which is or might be used for a device node, may result in
- unexpected behavior and is not supported.
+ the link. If no link_priority is specified, the order of the devices (and
+ which one of them owns the link) is undefined. Also, symlink names must
+ never conflict with the kernel's default device node names, as that would
+ result in unpredictable behavior.
</para>
</listitem>
</varlistentry>
<term><option>ENV{<replaceable>key</replaceable>}</option></term>
<listitem>
<para>Set a device property value. Property names with a leading '.'
- are not stored in the database or exported to external tool or events.</para>
+ are neither stored in the database nor exported to events or
+ external tools (run by, say, the PROGRAM match key).</para>
</listitem>
</varlistentry>
this or a dependent device. Long running tasks need to be immediately
detached from the event process itself.</para>
<para>If no absolute path is given, the program is expected to live in
- <filename>/lib/udev</filename>, otherwise the absolute path must be
- specified. Program name and arguments are separated by spaces. Single quotes
- can be used to specify arguments with spaces.</para>
+ the directory provided at compile-time to configure via --libexecdir
+ (this is usually <filename>/usr/lib/udev</filename>), otherwise the absolute
+ path must be specified. The program name and following arguments are
+ separated by spaces. Single quotes can be used to specify arguments with
+ spaces.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>LABEL</option></term>
<listitem>
- <para>Named label where a GOTO can jump to.</para>
+ <para>A named label to which a GOTO may jump.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>GOTO</option></term>
<listitem>
- <para>Jumps to the next LABEL with a matching name</para>
+ <para>Jumps to the next LABEL with a matching name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>file</option></term>
<listitem>
- <para>Import a text file specified as the assigned value, which must be in
- environment key format.</para>
+ <para>Import a text file specified as the assigned value, the content
+ of which must be in environment key format.</para>
</listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>cmdline</option></term>
<listitem>
- <para>Import a single property from the kernel commandline. For simple flags
+ <para>Import a single property from the kernel command line. For simple flags
the value of the property is set to '1'.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
</variablelist>
- <para>If no option is given, udev chooses between <option>program</option>
- and <option>file</option> based on the executable bit of the file
- permissions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>WAIT_FOR</option></term>
<listitem>
- <para>Wait for a file to become available or until a 10
- seconds timeout expires. The path is relative to the sysfs device,
- i. e. if no path is specified this waits for an attribute to appear.</para>
+ <para>Wait for a file to become available or until a timeout of
+ 10 seconds expires. The path is relative to the sysfs device;
+ if no path is specified, this waits for an attribute to appear.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>static_node=</option></term>
<listitem>
- <para>Apply the permissions specified in this rule to a static device node with
+ <para>Apply the permissions specified in this rule to the static device node with
the specified name. Static device nodes might be provided by kernel modules
- or copied from <filename>/lib/udev/devices</filename>. These nodes might not have
+ or copied from <filename>/usr/lib/udev/devices</filename>. These nodes might not have
a corresponding kernel device at the time udevd is started; they can trigger
automatic kernel module loading.</para>
</listitem>
<varlistentry>
<term><option>watch</option></term>
<listitem>
- <para>Watch the device node with inotify; when closed after being opened for
- writing, a change uevent is synthesised.</para>
+ <para>Watch the device node with inotify; when the node is closed after being opened for
+ writing, a change uevent is synthesized.</para>
</listitem>
</varlistentry>
<varlistentry>
<para>The <option>NAME</option>, <option>SYMLINK</option>, <option>PROGRAM</option>,
<option>OWNER</option>, <option>GROUP</option>, <option>MODE</option> and <option>RUN</option>
- fields support simple printf-like string substitutions. The <option>RUN</option>
- format chars gets applied after all rules have been processed, right before the program
- is executed. It allows the use of device properties set by earlier matching
- rules. For all other fields, substitutions are applied while the individual rule is
+ fields support simple string substitutions. The <option>RUN</option>
+ 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:</para>
<variablelist>
<varlistentry>
<para>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 KERNELS, SUBSYSTEMS, DRIVERS, or
- ATTRS test selected a parent device, use the attribute from that
- parent device.
- If the attribute is a symlink, the last element of the symlink target is
+ ATTRS test selected a parent device, then the attribute from that
+ parent device is used.</para>
+ <para>If the attribute is a symlink, the last element of the symlink target is
returned as the value.</para>
</listitem>
</varlistentry>
<term><option>$result</option>, <option>%c</option></term>
<listitem>
<para>The string returned by the external program requested with PROGRAM.
- A single part of the string, separated by a space character may be selected
+ A single part of the string, separated by a space character, may be selected
by specifying the part number as an attribute: <option>%c{N}</option>.
- If the number is followed by the '+' char this part plus all remaining parts
+ If the number is followed by the '+' character, this part plus all remaining parts
of the result string are substituted: <option>%c{N+}</option></para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$name</option></term>
<listitem>
- <para>The current name of the device node. If not changed by a rule, it is the
+ <para>The current name of the device. If not changed by a rule, it is the
name of the kernel device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>$links</option></term>
<listitem>
- <para>The current list of symlinks, separated by a space character. The value is
- only set if an earlier rule assigned a value, or during a remove events.</para>
+ <para>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.</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term><option>$tempnode</option>, <option>%N</option></term>
+ <term><option>$devnode</option>, <option>%N</option></term>
<listitem>
- <para>The name of a created temporary device node to provide access to
- the device from a external program before the real node is created.</para>
+ <para>The name of the device node.</para>
</listitem>
</varlistentry>
~ianmdlvl / elogind.git / blobdiff