| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"><head><title>udev</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"/></head><body><div class="refentry" title="udev"><a id="udev"/><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>udev — Linux dynamic device management</p></div><div class="refsect1" title="Description"><a id="id278021"/><h2>Description</h2><p>udev supplies the system software with device events, manages permissions |
| of device nodes and may create additional symlinks in the <code class="filename">/dev</code> |
| 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.</p><p>The udev daemon <span class="citerefentry"><span class="refentrytitle">udevd</span>(8)</span> 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 information |
| to be used to create meaningful symlink names.</p><p>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 are provided by the library libudev.</p></div><div class="refsect1" title="Configuration"><a id="id310199"/><h2>Configuration</h2><p>udev configuration files are placed in <code class="filename">/etc/udev/</code> |
| and <code class="filename">/lib/udev/</code>. All empty lines, or lines beginning with |
| '#' will be ignored.</p><div class="refsect2" title="Configuration file"><a id="id310220"/><h3>Configuration file</h3><p>udev expects its main configuration file at <code class="filename">/etc/udev/udev.conf</code>. |
| It consists of a set of variables allowing the user to override default udev values. |
| The following variables can be set:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">udev_root</code></span></dt><dd><p>Specifies where to place the device nodes in the filesystem. |
| The default value is <code class="filename">/dev</code>.</p></dd><dt><span class="term"><code class="option">udev_log</code></span></dt><dd><p>The logging priority. Valid values are the numerical syslog priorities |
| or their textual representations: <code class="option">err</code>, <code class="option">info</code> |
| and <code class="option">debug</code>.</p></dd></dl></div></div><div class="refsect2" title="Rules files"><a id="id310294"/><h3>Rules files</h3><p>The udev rules are read from the files located in the |
| default rules directory <code class="filename">/lib/udev/rules.d/</code>, |
| the custom rules directory <code class="filename">/etc/udev/rules.d/</code> |
| and the temporary rules directory <code class="filename">/dev/.udev/rules.d/</code>. |
| All rule files are sorted and processed in lexical order, regardless |
| in which of these directories they live. Files in |
| <code class="filename">/etc/udev/rules.d/</code> have precedence over files with |
| the same name in <code class="filename">/lib/udev/rules.d/</code>. This can be |
| used to ignore a default rules file if needed.</p><p>Rule files must end in <code class="filename">.rules</code>, other extensions |
| are ignored.</p><p>Every line in the rules file contains at least one key value pair. |
| There are two kind of keys, match and assignment keys. |
| If all match keys are matching against its value, the rule gets applied and the |
| assign keys get the specified value assigned.</p><p>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.</p><p>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 |
| operators are:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">==</code></span></dt><dd><p>Compare for equality.</p></dd><dt><span class="term"><code class="option">!=</code></span></dt><dd><p>Compare for inequality.</p></dd><dt><span class="term"><code class="option">=</code></span></dt><dd><p>Assign a value to a key. Keys that represent a list, are reset |
| and only this single value is assigned.</p></dd><dt><span class="term"><code class="option">+=</code></span></dt><dd><p>Add the value to a key that holds a list of entries.</p></dd><dt><span class="term"><code class="option">:=</code></span></dt><dd><p>Assign a value to a key finally; disallow any later changes, |
| which may be used to prevent changes by any later rules.</p></dd></dl></div><p>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.</p><div class="variablelist"><dl><dt><span class="term"><code class="option">ACTION</code></span></dt><dd><p>Match the name of the event action.</p></dd><dt><span class="term"><code class="option">DEVPATH</code></span></dt><dd><p>Match the devpath of the event device.</p></dd><dt><span class="term"><code class="option">KERNEL</code></span></dt><dd><p>Match the name of the event device.</p></dd><dt><span class="term"><code class="option">NAME</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">SYMLINK</code></span></dt><dd><p>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. |
| </p></dd><dt><span class="term"><code class="option">SUBSYSTEM</code></span></dt><dd><p>Match the subsystem of the event device.</p></dd><dt><span class="term"><code class="option">DRIVER</code></span></dt><dd><p>Match the driver name of the event device. Only set for devices |
| which are bound to a driver at the time the event is generated.</p></dd><dt><span class="term"><code class="option">ATTR{<em class="replaceable"><code>filename</code></em>}</code></span></dt><dd><p>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. |
| </p></dd><dt><span class="term"><code class="option">KERNELS</code></span></dt><dd><p>Search the devpath upwards for a matching device name.</p></dd><dt><span class="term"><code class="option">SUBSYSTEMS</code></span></dt><dd><p>Search the devpath upwards for a matching device subsystem name.</p></dd><dt><span class="term"><code class="option">DRIVERS</code></span></dt><dd><p>Search the devpath upwards for a matching device driver name.</p></dd><dt><span class="term"><code class="option">ATTRS{<em class="replaceable"><code>filename</code></em>}</code></span></dt><dd><p>Search the devpath upwards for a device with matching sysfs attribute values. |
| If multiple <code class="option">ATTRS</code> 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.</p></dd><dt><span class="term"><code class="option">ENV{<em class="replaceable"><code>key</code></em>}</code></span></dt><dd><p>Match against a device property value.</p></dd><dt><span class="term"><code class="option">TAG</code></span></dt><dd><p>Match against a device tag.</p></dd><dt><span class="term"><code class="option">TEST{<em class="replaceable"><code>octal mode mask</code></em>}</code></span></dt><dd><p>Test the existence of a file. An octal mode mask can be specified |
| if needed.</p></dd><dt><span class="term"><code class="option">PROGRAM</code></span></dt><dd><p>Execute a program. 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.</p></dd><dt><span class="term"><code class="option">RESULT</code></span></dt><dd><p>Match the returned string of the last PROGRAM call. This key can |
| be used in the same or in any later rule after a PROGRAM call.</p></dd></dl></div><p>Most of the fields support a shell style pattern matching. The following |
| pattern characters are supported:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">*</code></span></dt><dd><p>Matches zero, or any number of characters.</p></dd><dt><span class="term"><code class="option">?</code></span></dt><dd><p>Matches any single character.</p></dd><dt><span class="term"><code class="option">[]</code></span></dt><dd><p>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 |
| be used. If the first character following the '[' is a '!', any characters |
| not enclosed are matched.</p></dd></dl></div><p>The following keys can get values assigned:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">NAME</code></span></dt><dd><p>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 will be 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 will result in unpredictable behavior.</p></dd><dt><span class="term"><code class="option">SYMLINK</code></span></dt><dd><p>The name of a symlink targeting the node. Every matching rule will add |
| this value to the list of symlinks to be created. Multiple symlinks may be |
| specified by separating the names by the space character. In case multiple |
| devices claim the same name, the link will always point to the device with |
| the highest link_priority. If the current device goes away, the links will |
| be re-evaluated and the device with the next highest link_priority will own |
| the link. If no link_priority is specified, the order of the devices, and |
| which one of them will own 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. |
| </p></dd><dt><span class="term"><code class="option">OWNER, GROUP, MODE</code></span></dt><dd><p>The permissions for the device node. Every specified value overwrites |
| the compiled-in default value.</p></dd><dt><span class="term"><code class="option">ATTR{<em class="replaceable"><code>key</code></em>}</code></span></dt><dd><p>The value that should be written to a sysfs attribute of the |
| event device.</p></dd><dt><span class="term"><code class="option">ENV{<em class="replaceable"><code>key</code></em>}</code></span></dt><dd><p>Set a device property value. Property names with a leading '.' |
| are not stored in the database or exported to external tool or events.</p></dd><dt><span class="term"><code class="option">TAG</code></span></dt><dd><p>Attach a tag to a device. This is used to filter events for users |
| of libudev's 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.</p></dd><dt><span class="term"><code class="option">RUN</code></span></dt><dd><p>Add a program to the list of programs to be executed for a specific |
| device. This can only be used for very short running tasks. Running an |
| event process for a long period of time may block all further events for |
| this or a dependent device. Long running tasks need to be immediately |
| detached from the event process itself. If the option |
| <code class="option">RUN{<em class="replaceable"><code>fail_event_on_error</code></em>}</code> is |
| specified, and the executed program returns non-zero, the event will be |
| marked as failed for a possible later handling.</p><p>If no absolute path is given, the program is expected to live in |
| <code class="filename">/lib/udev</code>, 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.</p></dd><dt><span class="term"><code class="option">LABEL</code></span></dt><dd><p>Named label where a GOTO can jump to.</p></dd><dt><span class="term"><code class="option">GOTO</code></span></dt><dd><p>Jumps to the next LABEL with a matching name</p></dd><dt><span class="term"><code class="option">IMPORT{<em class="replaceable"><code>type</code></em>}</code></span></dt><dd><p>Import a set of variables as device properties, |
| depending on <em class="replaceable"><code>type</code></em>:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">program</code></span></dt><dd><p>Execute an external program specified as the assigned value and |
| import its output, which must be in environment key |
| format. Path specification, command/argument separation, |
| and quoting work like in <code class="option">RUN</code>.</p></dd><dt><span class="term"><code class="option">file</code></span></dt><dd><p>Import a text file specified as the assigned value, which must be in |
| environment key format.</p></dd><dt><span class="term"><code class="option">db</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">cmdline</code></span></dt><dd><p>Import a single property from the kernel commandline. For simple flags |
| the value of the property will be set to '1'.</p></dd><dt><span class="term"><code class="option">parent</code></span></dt><dd><p>Import the stored keys from the parent device by reading |
| the database entry of the parent device. The value assigned to |
| <code class="option">IMPORT{parent}</code> is used as a filter of key names |
| to import (with the same shell-style pattern matching used for |
| comparisons).</p></dd></dl></div><p>If no option is given, udev will choose between <code class="option">program</code> |
| and <code class="option">file</code> based on the executable bit of the file |
| permissions.</p></dd><dt><span class="term"><code class="option">WAIT_FOR</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">OPTIONS</code></span></dt><dd><p>Rule and device options:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">link_priority=<em class="replaceable"><code>value</code></em></code></span></dt><dd><p>Specify the priority of the created symlinks. Devices with higher |
| priorities overwrite existing symlinks of other devices. The default is 0.</p></dd><dt><span class="term"><code class="option">event_timeout=</code></span></dt><dd><p>Number of seconds an event will wait for operations to finish, before it |
| will terminate itself.</p></dd><dt><span class="term"><code class="option">string_escape=<em class="replaceable"><code>none|replace</code></em></code></span></dt><dd><p>Usually control and other possibly unsafe characters are replaced |
| in strings used for device naming. The mode of replacement can be specified |
| with this option.</p></dd><dt><span class="term"><code class="option">static_node=</code></span></dt><dd><p>Apply the permissions specified in this rule to a static device node with |
| the specified name. Static device nodes might be provided by kernel modules, |
| or copied from <code class="filename">/lib/udev/devices</code>. These nodes might not have |
| a corresponding kernel device at the time udevd is started, and allow to trigger |
| automatic kernel module on-demand loading.</p></dd><dt><span class="term"><code class="option">watch</code></span></dt><dd><p>Watch the device node with inotify, when closed after being opened for |
| writing, a change uevent will be synthesised.</p></dd><dt><span class="term"><code class="option">nowatch</code></span></dt><dd><p>Disable the watching of a device node with inotify.</p></dd></dl></div></dd></dl></div><p>The <code class="option">NAME</code>, <code class="option">SYMLINK</code>, <code class="option">PROGRAM</code>, |
| <code class="option">OWNER</code>, <code class="option">GROUP</code>, <code class="option">MODE</code> and <code class="option">RUN</code> |
| fields support simple printf-like string substitutions. The <code class="option">RUN</code> |
| 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 |
| being processed. The available substitutions are:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">$kernel</code>, <code class="option">%k</code></span></dt><dd><p>The kernel name for this device.</p></dd><dt><span class="term"><code class="option">$number</code>, <code class="option">%n</code></span></dt><dd><p>The kernel number for this device. For example, 'sda3' has |
| kernel number of '3'</p></dd><dt><span class="term"><code class="option">$devpath</code>, <code class="option">%p</code></span></dt><dd><p>The devpath of the device.</p></dd><dt><span class="term"><code class="option">$id</code>, <code class="option">%b</code></span></dt><dd><p>The name of the device matched while searching the devpath upwards for |
| <code class="option">SUBSYSTEMS</code>, <code class="option">KERNELS</code>, <code class="option">DRIVERS</code> and <code class="option">ATTRS</code>. |
| </p></dd><dt><span class="term"><code class="option">$driver</code></span></dt><dd><p>The driver name of the device matched while searching the devpath upwards for |
| <code class="option">SUBSYSTEMS</code>, <code class="option">KERNELS</code>, <code class="option">DRIVERS</code> and <code class="option">ATTRS</code>. |
| </p></dd><dt><span class="term"><code class="option">$attr{<em class="replaceable"><code>file</code></em>}</code>, <code class="option">%s{<em class="replaceable"><code>file</code></em>}</code></span></dt><dd><p>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 |
| returned as the value.</p></dd><dt><span class="term"><code class="option">$env{<em class="replaceable"><code>key</code></em>}</code>, <code class="option">%E{<em class="replaceable"><code>key</code></em>}</code></span></dt><dd><p>A device property value.</p></dd><dt><span class="term"><code class="option">$major</code>, <code class="option">%M</code></span></dt><dd><p>The kernel major number for the device.</p></dd><dt><span class="term"><code class="option">$minor</code>, <code class="option">%m</code></span></dt><dd><p>The kernel minor number for the device.</p></dd><dt><span class="term"><code class="option">$result</code>, <code class="option">%c</code></span></dt><dd><p>The string returned by the external program requested with PROGRAM. |
| A single part of the string, separated by a space character may be selected |
| by specifying the part number as an attribute: <code class="option">%c{N}</code>. |
| If the number is followed by the '+' char this part plus all remaining parts |
| of the result string are substituted: <code class="option">%c{N+}</code></p></dd><dt><span class="term"><code class="option">$parent</code>, <code class="option">%P</code></span></dt><dd><p>The node name of the parent device.</p></dd><dt><span class="term"><code class="option">$name</code></span></dt><dd><p>The current name of the device node. If not changed by a rule, it is the |
| name of the kernel device.</p></dd><dt><span class="term"><code class="option">$links</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">$root</code>, <code class="option">%r</code></span></dt><dd><p>The udev_root value.</p></dd><dt><span class="term"><code class="option">$sys</code>, <code class="option">%S</code></span></dt><dd><p>The sysfs mount point.</p></dd><dt><span class="term"><code class="option">$tempnode</code>, <code class="option">%N</code></span></dt><dd><p>The name of a created temporary device node to provide access to |
| the device from a external program before the real node is created.</p></dd><dt><span class="term"><code class="option">%%</code></span></dt><dd><p>The '%' character itself.</p></dd><dt><span class="term"><code class="option">$$</code></span></dt><dd><p>The '$' character itself.</p></dd></dl></div></div></div><div class="refsect1" title="Author"><a id="id320469"/><h2>Author</h2><p>Written by Greg Kroah-Hartman <code class="email"><<a class="email" href="mailto:greg@kroah.com">greg@kroah.com</a>></code> and |
| Kay Sievers <code class="email"><<a class="email" href="mailto:kay.sievers@vrfy.org">kay.sievers@vrfy.org</a>></code>. With much help from |
| Dan Stekloff and many others.</p></div><div class="refsect1" title="See Also"><a id="id320486"/><h2>See Also</h2><p><span class="citerefentry"><span class="refentrytitle">udevd</span>(8)</span>, |
| <span class="citerefentry"><span class="refentrytitle">udevadm</span>(8)</span></p></div></div></body></html> |
