chiark / gitweb /
man: document $MAINPID
[elogind.git] / man / udev.xml
index 553bbfd..eab5d25 100644 (file)
@@ -30,7 +30,7 @@
 
   <refnamediv>
     <refname>udev</refname>
-    <refpurpose>Linux dynamic device management</refpurpose>
+    <refpurpose>Dynamic device management</refpurpose>
   </refnamediv>
 
   <refsect1><title>Description</title>
@@ -54,7 +54,7 @@
     sources is provided by the library libudev.</para>
   </refsect1>
 
-  <refsect1><title>Rules files</title>
+  <refsect1><title>Rules Files</title>
       <para>The udev rules are read from the files located in the
       system rules directory <filename>/usr/lib/udev/rules.d</filename>,
       the volatile runtime directory <filename>/run/udev/rules.d</filename>
       regardless of the directories in which they live. However, files with
       identical filenames replace each other. Files in <filename>/etc</filename>
       have the highest priority, files in <filename>/run</filename> take precedence
-      over files with the same name in <filename>/lib</filename>. This can be
+      over files with the same name in <filename>/usr/lib</filename>. This can be
       used to override a system-supplied rules file with a local 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>
+      <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>,
+      disables the rules file entirely. 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.
       Except for empty lines or lines beginning with <literal>#</literal>, which are ignored.
             <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 stdout
-            is available in the RESULT key.</para>
-            <para>This can only be used for very short-running foreground tasks. For details
+            executed program in the environment. The program's standard ouput
+            is available in the <varname>RESULT</varname> key.</para>
+            <para>This can only be used for very short-running foreground tasks. For details,
             see <varname>RUN</varname>.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><varname>RESULT</varname></term>
           <listitem>
-            <para>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.</para>
+            <para>Match the returned string of the last <varname>PROGRAM</varname> call.
+            This key can be used in the same or in any later rule after a
+            <varname>PROGRAM</varname> call.</para>
           </listitem>
         </varlistentry>
       </variablelist>
 
-      <para>Most of the fields support shell-style pattern matching. The following
+      <para>Most of the fields support shell glob pattern matching. The following
       pattern characters are supported:</para>
       <variablelist>
         <varlistentry>
             example, the pattern string <literal>tty[SR]</literal>
             would match either <literal>ttyS</literal> or <literal>ttyR</literal>.
             Ranges are also supported via the <literal>-</literal> character.
-            For example, to match on the range of all digits, the pattern [0-9] could
-            be used. If the first character following the <literal>[</literal> is a
-            <literal>!</literal>, any characters not enclosed are matched.</para>
+            For example, to match on the range of all digits, the pattern
+            <literal>[0-9]</literal> could be used. If the first character
+            following the <literal>[</literal> is a <literal>!</literal>,
+            any characters not enclosed are matched.</para>
           </listitem>
         </varlistentry>
       </variablelist>
         </varlistentry>
 
         <varlistentry>
+          <term><varname>SECLABEL{<replaceable>module</replaceable>}</varname></term>
+          <listitem>
+            <para>Applies the specified Linux Security Module label to the device node.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
           <term><varname>ATTR{<replaceable>key</replaceable>}</varname></term>
           <listitem>
             <para>The value that should be written to a sysfs attribute of the
           <listitem>
             <para>Set a device property value. Property names with a leading <literal>.</literal>
             are neither stored in the database nor exported to events or
-            external tools (run by, say, the PROGRAM match key).</para>
+            external tools (run by, for example, the <varname>PROGRAM</varname>
+            match key).</para>
           </listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>RUN{<replaceable>type</replaceable>}</varname></term>
           <listitem>
-            <para>Add a program to the list of programs to be executed after processing all the
-            rules for a specific event, depending on <literal>type</literal>:</para>
+            <para>Add a program to the list of programs to be executed after
+            processing all the rules for a specific event, depending on
+            <literal>type</literal>:</para>
             <variablelist>
               <varlistentry>
                 <term><literal>program</literal></term>
                 <listitem>
                   <para>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.</para>
-                  <para>This is the default if no <replaceable>type</replaceable> is
-                  specified.</para>
+                  value. If no absolute path is given, the program is expected
+                  to live in <filename>/usr/lib/udev</filename>; otherwise, the
+                  absolute path must be specified.</para>
+                  <para>This is the default if no <replaceable>type</replaceable>
+                  is specified.</para>
                 </listitem>
               </varlistentry>
               <varlistentry>
                 <term><literal>builtin</literal></term>
                 <listitem>
-                  <para>As <varname>program</varname>, but use one of the built-in programs rather
-                  than an external one.</para>
+                  <para>As <varname>program</varname>, but use one of the
+                  built-in programs rather than an external one.</para>
                 </listitem>
               </varlistentry>
             </variablelist>
             <para>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.</para>
-            <para>Starting daemons or other long running processes is not appropriate
+            <para>Starting daemons or other long-running processes is not appropriate
             for udev; the forked processes, detached or not, will be unconditionally
             killed after the event handling has finished.</para>
           </listitem>
         <varlistentry>
           <term><varname>LABEL</varname></term>
           <listitem>
-            <para>A named label to which a GOTO may jump.</para>
+            <para>A named label to which a <varname>GOTO</varname> may jump.</para>
           </listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>GOTO</varname></term>
           <listitem>
-            <para>Jumps to the next LABEL with a matching name.</para>
+            <para>Jumps to the next <varname>LABEL</varname> with a matching name.</para>
           </listitem>
         </varlistentry>
 
                   <para>Import the stored keys from the parent device by reading
                   the database entry of the parent device. The value assigned to
                   <option>IMPORT{parent}</option> is used as a filter of key names
-                  to import (with the same shell-style pattern matching used for
+                  to import (with the same shell glob pattern matching used for
                   comparisons).</para>
                 </listitem>
               </varlistentry>
               <varlistentry>
                 <term><option>static_node=</option></term>
                 <listitem>
-                  <para>Apply the permissions specified in this rule to the static device node with
-                  the specified name. Static device node creation can be requested by kernel modules.
-                  These nodes might not have a corresponding kernel device at the time systemd-udevd is
-                  started; they can trigger automatic kernel module loading.</para>
+                  <para>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
+                  <filename>/run/udev/static_node-tags/<replaceable>tag</replaceable></filename>
+                  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.</para>
                 </listitem>
               </varlistentry>
               <varlistentry>
                 <term><option>watch</option></term>
                 <listitem>
-                  <para>Watch the device node with inotify; when the node is closed after being opened for
-                  writing, a change uevent is synthesized.</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>
         </varlistentry>
       </variablelist>
 
-      <para>The <varname>NAME</varname>, <varname>SYMLINK</varname>, <varname>PROGRAM</varname>,
-      <varname>OWNER</varname>, <varname>GROUP</varname>, <varname>MODE</varname>  and  <varname>RUN</varname>
-      fields support simple string substitutions. The <varname>RUN</varname>
-      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>
+      <para>The <varname>NAME</varname>, <varname>SYMLINK</varname>,
+      <varname>PROGRAM</varname>, <varname>OWNER</varname>,
+      <varname>GROUP</varname>, <varname>MODE</varname>, and
+      <varname>RUN</varname> fields support simple string substitutions.
+      The <varname>RUN</varname> 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 class='udev-directives'>
         <varlistentry>
           <term><option>$kernel</option>, <option>%k</option></term>
           <term><option>$number</option>, <option>%n</option></term>
           <listitem>
             <para>The kernel number for this device. For example,
-            <literal>sda3</literal> has kernel number <literal>3</literal>.</para>
+              <literal>sda3</literal> has kernel number <literal>3</literal>.
+            </para>
           </listitem>
         </varlistentry>
 
         <varlistentry>
           <term><option>$id</option>, <option>%b</option></term>
           <listitem>
-            <para>The name of the device matched while searching the devpath upwards for
-              <option>SUBSYSTEMS</option>, <option>KERNELS</option>, <option>DRIVERS</option> and <option>ATTRS</option>.
+            <para>The name of the device matched while searching the devpath
+              upwards for <option>SUBSYSTEMS</option>, <option>KERNELS</option>,
+              <option>DRIVERS</option>, and <option>ATTRS</option>.
             </para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><option>$driver</option></term>
           <listitem>
-            <para>The driver name of the device matched while searching the devpath upwards for
-              <option>SUBSYSTEMS</option>, <option>KERNELS</option>, <option>DRIVERS</option> and <option>ATTRS</option>.
+            <para>The driver name of the device matched while searching the
+              devpath upwards for <option>SUBSYSTEMS</option>,
+              <option>KERNELS</option>, <option>DRIVERS</option>, and
+              <option>ATTRS</option>.
             </para>
           </listitem>
         </varlistentry>
           <term><option>$attr{<replaceable>file</replaceable>}</option>, <option>%s{<replaceable>file</replaceable>}</option></term>
           <listitem>
             <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, 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>
+              all keys of the rule have matched. If the matching device does not
+              have such an attribute, and a previous <option>KERNELS</option>,
+              <option>SUBSYSTEMS</option>, <option>DRIVERS</option>, or
+              <option>ATTRS</option> 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>
 
         <varlistentry>
           <term><option>$result</option>, <option>%c</option></term>
           <listitem>
-            <para>The string returned by the external program requested with PROGRAM.
+            <para>The string returned by the external program requested with
+            <varname>PROGRAM</varname>.
             A single part of the string, separated by a space character, may be selected
             by specifying the part number as an attribute: <literal>%c{N}</literal>.
             If the number is followed by the <literal>+</literal> character, this part plus all remaining parts
       </variablelist>
   </refsect1>
 
+  <refsect1><title>Hardware Database Files</title>
+      <para>The hwdb files are read from the files located in the
+      system hwdb directory <filename>/usr/lib/udev/hwdb.d</filename>,
+      the volatile runtime directory <filename>/run/udev/hwdb.d</filename>
+      and the local administration directory <filename>/etc/udev/hwdb.d</filename>.
+      All hwdb 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 <filename>/etc</filename>
+      have the highest priority, files in <filename>/run</filename> take precedence
+      over files with the same name in <filename>/usr/lib</filename>. This can be
+      used to override a system-supplied hwdb file with a local file if needed;
+      a symlink in <filename>/etc</filename> with the same name as a hwdb file in
+      <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>,
+      disables the hwdb file entirely. hwdb files must have the extension
+      <filename>.hwdb</filename>; other extensions are ignored.</para>
+
+      <para>The hwdb file contains data records consisting of matches and
+      associated key-value pairs. Every record in the hwdb starts with one or
+      more match string, specifying a shell glob to compare the database
+      lookup string against. Multiple match lines are specified in additional
+      consecutive lines. Every match line is compared indivdually, they are
+      combined by OR. Every match line must start at the first character of
+      the line.</para>
+
+      <para>The match lines are followed by one or more key-value pair lines, which
+      are recognized by a leading space character. The key name and value are separated
+      by <literal>=</literal>. An empty line signifies the end
+      of a record. Lines beginning with <literal>#</literal> are ignored.</para>
+
+      <para>The content of all hwdb files is read by
+      <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      and compiled to a binary database located at <filename>/etc/udev/hwdb.bin</filename>.
+      During runtime only the binary database is used.</para>
+  </refsect1>
+
+  <refsect1><title>Network Link Configuration</title>
+      <para>Network link configuration is performed by the <literal>net_setup_link</literal>
+      udev builtin.</para>
+
+      <para>The link files are read from the files located in the
+      system network directory <filename>/usr/lib/systemd/network</filename>,
+      the volatile runtime network directory <filename>/run/systemd/network</filename>
+      and the local administration network directory <filename>/etc/systemd/network</filename>.
+      Link files must have the extension <filename>.link</filename>; other extensions are ignored.
+      All link 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 <filename>/etc</filename>
+      have the highest priority, files in <filename>/run</filename> take precedence
+      over files with the same name in <filename>/usr/lib</filename>. This can be
+      used to override a system-supplied link file with a local file if needed;
+      a symlink in <filename>/etc</filename> with the same name as a link file in
+      <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>,
+      disables the link file entirely.</para>
+
+      <para>The link file contains a <literal>[Match]</literal> section, which
+      determines if a given link file may be applied to a given device; and a
+      <literal>[Link]</literal> section specifying how the device should be
+      configured. The first (in lexical order) of the link files that matches
+      a given device is applied.</para>
+
+      <para>A link file is said to match a device if each of the entries in the
+      <literal>[Match]</literal> section matches, or if the section is empty.
+      The following keys are accepted:</para>
+
+      <variablelist class='network-directives'>
+        <varlistentry>
+          <term><varname>MACAddress</varname></term>
+          <listitem>
+            <para>The hardware address.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>Path</varname></term>
+          <listitem>
+            <para>The persistent path, as exposed by the udev property <literal>ID_PATH</literal>.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>Driver</varname></term>
+          <listitem>
+            <para>The driver currently bound to the device, as exposed by the
+            udev property <literal>DRIVER</literal> of its parent device.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>Type</varname></term>
+          <listitem>
+            <para>The device type, as exposed by the udev property <literal>DEVTYPE</literal>.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+      <para>The <literal>[Link]</literal> section accepts the following keys:</para>
+
+      <variablelist class='network-directives'>
+        <varlistentry>
+          <term><varname>Description</varname></term>
+          <listitem>
+            <para>A description of the device.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>Alias</varname></term>
+          <listitem>
+            <para>The <literal>ifalias</literal> is set to this value.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>MACAddressPolicy</varname></term>
+          <listitem>
+            <para>The policy by which the MAC address should be set. The
+              available policies are:
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term><literal>persistent</literal></term>
+                <listitem>
+                  <para>If the hardware has a persistent MAC address, as most
+                    hardware should, and this is used by the kernel, nothing is
+                    done. Otherwise, a new MAC address is generated which is
+                    guaranteed to be the same on every boot for the given
+                    machine and the given device, but which is otherwise random.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><literal>random</literal></term>
+                <listitem>
+                  <para>If the kernel is using a random MAC address, nothing is
+                    done. Otherwise, a new address is randomly generated each
+                    time the device appears, typically at boot.
+                  </para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>MACAddress</varname></term>
+          <listitem>
+            <para>The MAC address to use, if no <literal>MACAddressPolicy</literal>
+              is specified.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>NamePolicy</varname></term>
+          <listitem>
+            <para>An ordered, space-separated list of policies by which the
+              interface name should be set. <literal>NamePolicy</literal> may
+              be disabled by specifying <literal>net.ifnames=0</literal> on the
+              kernel commandline. Each of the policies may fail, and the first
+              successful one is used. The name is not set directly, but
+              is exported to udev as the property <literal>ID_NET_NAME</literal>,
+              which is, by default, used by a udev rule to set
+              <literal>NAME</literal>. The available policies are:
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term><literal>onboard</literal></term>
+                <listitem>
+                  <para>The name is set based on information given by the
+                    firmware for on-board devices, as exported by the udev
+                    property <literal>ID_NET_NAME_ONBOARD</literal>.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><literal>slot</literal></term>
+                <listitem>
+                  <para>The name is set based on information given by the
+                    firmware for hot-plug devices, as exported by the udev
+                    property <literal>ID_NET_NAME_SLOT</literal>.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><literal>path</literal></term>
+                <listitem>
+                  <para>The name is set based on the device's physical location,
+                    as exported by the udev property
+                    <literal>ID_NET_NAME_PATH</literal>.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><literal>mac</literal></term>
+                <listitem>
+                  <para>The name is set based on the device's persistent MAC
+                    address, as exported by the udev property
+                    <literal>ID_NET_NAME_MAC</literal>.
+                  </para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>Name</varname></term>
+          <listitem>
+            <para>The interface name to use in case all the policies specified
+              in <literal>NamePolicy</literal> fail, or in case
+              <literal>NamePolicy</literal> is missing or disabled.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>MTU</varname></term>
+          <listitem>
+            <para>The MTU to set for the device.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>SpeedMBytes</varname></term>
+          <listitem>
+            <para>The speed to set for the device.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>Duplex</varname></term>
+          <listitem>
+            <para>The duplex mode to set for the device. The accepted values
+              are <literal>half</literal> and <literal>full</literal>.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>WakeOnLan</varname></term>
+          <listitem>
+            <para>The Wake-on-LAN policy to set for the device. The supported
+              values are:
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term><literal>phy</literal></term>
+                <listitem>
+                  <para>Wake on PHY activity.</para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><literal>magic</literal></term>
+                <listitem>
+                  <para>Wake on receipt of a magic packet.</para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><literal>off</literal></term>
+                <listitem>
+                  <para>Never wake.</para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
-    <para><citerefentry>
+    <para>
+      <citerefentry>
         <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>,
       <citerefentry>
         <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum>
-    </citerefentry></para>
+      </citerefentry>
+    </para>
   </refsect1>
 </refentry>