<h1>Writing udev rules</h1>
by Daniel Drake (dsd)<br />
-Version 0.73<br /><br />
+Version 0.74<br /><br />
The most recent version of this document can always be found at: <br />
<li>Finding suitable information from sysfs
<ul>
<li><a href="#sysfstree">The sysfs tree</a></li>
- <li><a href="#udevinfo">udevinfo</a></li>
+ <li><a href="#udevadm">udevadm info</a></li>
<li><a href="#sysfsalt">Alternative methods</a></li>
</ul>
</li>
<li>Testing and debugging
<ul>
<li><a href="#testing">Putting your rules into action</a></li>
- <li><a href="#udevtest">udevtest</a></li>
+ <li><a href="#udevtest">udevadm test</a></li>
</ul>
</li>
<li><a href="#author">Author and contact</a></li>
<h3>History</h3>
<ul>
+<li>April 5th 2008 v0.74: Typo fixes.</li>
<li>December 3rd 2007 v0.73: Update for new udev versions, and some miscellaneous improvements.</li>
<li>October 2nd 2006 v0.72: Fixed a typo in one of the example rules.</li>
<li>June 10th 2006 v0.71: Misc changes based on recent feedback - thanks!</li>
<h3>Rule files and semantics</h3>
<p>
-When deciding how to name a device and which additional actions to perform, udev reads a series of rules files. These files are kept in the <em>/etc/udev/rules.d</em> directory, and they all must have the <em>.rules</em> suffix.
+When deciding how to name a device and which additional actions to perform, udev reads a series of rules files. These files are kept in the <em>/etc/udev/rules.d</em> and <em>/lib/udev/rules.d</em> directories, and they all must have the <em>.rules</em> suffix. If two files with the same name exist in both directories then only the one in <em>/etc</em> is used.
</p>
<p>
-Default udev rules are stored in <em>/etc/udev/rules.d/50-udev.rules</em>. You may find it interesting to look over this file - it includes a few examples, and then some default rules proving a devfs-style /dev layout. However, you should not write rules into this file directly.
-</p>
-
-<p>
-Files in /etc/udev/rules.d/ are parsed in <b>lexical</b> order, and in some circumstances, the order in which rules are parsed is important. In general, you want your own rules to be parsed before the defaults, so I suggest you create a file at <em>/etc/udev/rules.d/10-local.rules</em> and write all your rules into this file.
+Files in the <em>rules.d</em> directories are parsed in <b>lexical</b> order, and in some circumstances, the order in which rules are parsed is important. In general, you want your own rules to be parsed before the defaults, so I suggest you create a file at <em>/etc/udev/rules.d/10-local.rules</em> and write all your rules into this file.
</p>
<p>
Although this serves as a useful introduction as to the structure of sysfs and exactly how udev matches values, manually trawling through sysfs is both time consuming and unnecessary.
</p>
-<a name="udevinfo"></a>
-<h3>udevinfo</h3>
+<a name="udevadm"></a>
+<h3>udevadm info</h3>
<p>
-Enter <em>udevinfo</em>, which is probably the most straightforward tool you can use to construct rules. All you need to know is the sysfs device path of the device in question. A trimmed example is shown below:
+Enter <em>udevadm info</em>, which is probably the most straightforward tool you can use to construct rules. All you need to know is the sysfs device path of the device in question. A trimmed example is shown below:
</p>
<blockquote><pre>
-# udevinfo -a -p /sys/block/sda
+# udevadm info -a -p /sys/block/sda
<span class="green"> looking at device '/block/sda':
KERNEL=="sda"
</pre></blockquote>
<p>
-As you can see, udevinfo simply produces a list of attributes you can use as-is as match keys in your udev rules. From the above example, I could produce (e.g.) either of the following two rules for this device:
+As you can see, udevadm info simply produces a list of attributes you can use as-is as match keys in your udev rules. From the above example, I could produce (e.g.) either of the following two rules for this device:
</p>
<blockquote><pre>
<span class="green">SUBSYSTEM=="block"</span>, <span class="green">ATTR{size}=="234441648",</span> NAME="my_hard_disk"
-<span class="green">SUBSYSTEM="block"</span>, <span class="blue">SUBSYSTEMS=="scsi"</span>, <span class="blue">ATTRS{model}=="ST3120827AS",</span> NAME="my_hard_disk"</pre></blockquote>
+<span class="green">SUBSYSTEM=="block"</span>, <span class="blue">SUBSYSTEMS=="scsi"</span>, <span class="blue">ATTRS{model}=="ST3120827AS",</span> NAME="my_hard_disk"</pre></blockquote>
<p>
You may have noted the use of colour in the above examples. This is to demonstrate that while it is legal to combine the attributes from the device in question and a <em>single</em> parent device, you cannot mix-and-match attributes from multiple parent devices - your rule will not work. For example, the following rule is <em>invalid</em> as it attempts to match attributes from two parent devices:
</p>
<p>
-Observe the effects of hierarchy in the udevinfo output. The <span class="green">green</span> section corresponding to the device in question uses the standard match keys such as KERNEL and ATTR. The <span class="blue">blue</span> and <span class="maroon">maroon</span> sections corresponding to parent devices use the parent-traversing variants such as SUBSYSTEMS and ATTRS. This is why the complexity introduced by the hierarchical structure is actually quite easy to deal with, just be sure to use the exact values that udevinfo suggests.
+Observe the effects of hierarchy in the udevadm info output. The <span class="green">green</span> section corresponding to the device in question uses the standard match keys such as KERNEL and ATTR. The <span class="blue">blue</span> and <span class="maroon">maroon</span> sections corresponding to parent devices use the parent-traversing variants such as SUBSYSTEMS and ATTRS. This is why the complexity introduced by the hierarchical structure is actually quite easy to deal with, just be sure to use the exact values that udevadm info suggests.
</p>
<p>
-Another point to note is that it is common for text attributes to appear in the udevinfo output to be padded with spaces (e.g. see ST3120827AS above). In your rules, you can either specify the extra spaces, or you can cut them off as I have done.
+Another point to note is that it is common for text attributes to appear in the udevadm info output to be padded with spaces (e.g. see ST3120827AS above). In your rules, you can either specify the extra spaces, or you can cut them off as I have done.
</p>
<p>
-The only complication with using udevinfo is that you are required to know the top-level device path (/sys/block/sda in the example above). This is not always obvious. However, as you are generally writing rules for device nodes which already exist, you can use udevinfo to look up the device path for you:
+The only complication with using udevadm info is that you are required to know the top-level device path (/sys/block/sda in the example above). This is not always obvious. However, as you are generally writing rules for device nodes which already exist, you can use udevadm info to look up the device path for you:
</p>
-<blockquote><pre># udevinfo -a -p $(udevinfo -q path -n /dev/sda)</pre></blockquote>
+<blockquote><pre># udevadm info -a -p $(udevadm info -q path -n /dev/sda)</pre></blockquote>
<a name="sysfsalt"></a>
<h3>Alternative methods</h3>
<p>
-Although udevinfo is almost certainly the most straightforward way of listing the exact attributes you can build rules from, some users are happier with other tools. Utilities such as <a href="http://www.kroah.com/linux/usb/">usbview</a> display a similar set of information, most of which can be used in rules.
+Although udev
adm info is almost certainly the most straightforward way of listing the exact attributes you can build rules from, some users are happier with other tools. Utilities such as <a href="http://www.kroah.com/linux/usb/">usbview</a> display a similar set of information, most of which can be used in rules.
</p>
<h2>Advanced topics</h2>
<h3>USB Printer</h3>
<p>
-I power on my printer, and it is assigned device node <em>/dev/lp0</em>. Not satisfied with such a bland name, I decide to use udevinfo to aid me in writing a rule which will provide an alternative name:
+I power on my printer, and it is assigned device node <em>/dev/lp0</em>. Not satisfied with such a bland name, I decide to use udevadm info to aid me in writing a rule which will provide an alternative name:
</p>
<blockquote><pre>
-# udevinfo -a -p $(udevinfo -q path -n /dev/lp0)
+# udevadm info -a -p $(udevadm info -q path -n /dev/lp0)
looking at device '/class/usb/lp0':
KERNEL=="lp0"
SUBSYSTEM=="usb"
</p>
<p>
-A common complication with USB camera devices is that they usually identify themselves as a disk with a single partition, in this case <em>/dev/sdb</em> with <em>/dev/sdb1</em>. The sdb node is useless to me, but sdb1 is interesting - this is the one I want to mount. There is a problem here that because sysfs is chained, the useful attributes which udevinfo produces for /dev/sdb1 are identical to the ones for /dev/sdb. This results in your rule potentially matching <u>both</u> the raw disk and the partition, which is not what you want, your rule should be <b>specific</b>.
+A common complication with USB camera devices is that they usually identify themselves as a disk with a single partition, in this case <em>/dev/sdb</em> with <em>/dev/sdb1</em>. The sdb node is useless to me, but sdb1 is interesting - this is the one I want to mount. There is a problem here that because sysfs is chained, the useful attributes which udevadm info produces for /dev/sdb1 are identical to the ones for /dev/sdb. This results in your rule potentially matching <u>both</u> the raw disk and the partition, which is not what you want, your rule should be <b>specific</b>.
</p>
<p>
</p>
<blockquote><pre>
-# udevinfo -a -p $(udevinfo -q path -n /dev/sdb1)
+# udevadm info -a -p $(udevadm info -q path -n /dev/sdb1)
looking at device '/block/sdb/sdb1':
KERNEL=="sdb1"
SUBSYSTEM=="block"
Of course, if you have a 100GB USB hard disk, it is perfectly understandable that you might want to partition it, in which case we can take advantage of udev's string substitutions:
</p>
-<blockquote><pre>KERNEL=="sd*", SUBSYSTEMS="scsi", ATTRS{model}=="USB 2.0 Storage Device", SYMLINK+="usbhd%n"</pre></blockquote>
+<blockquote><pre>KERNEL=="sd*", SUBSYSTEMS=="scsi", ATTRS{model}=="USB 2.0 Storage Device", SYMLINK+="usbhd%n"</pre></blockquote>
<p>
This rule creates symlinks such as:
<blockquote><pre>SUBSYSTEMS=="usb", ATTRS{product}=="Palm Handheld", KERNEL=="ttyUSB*", SYMLINK+="pilot"</pre></blockquote>
<p>
-Note that the product string seems to vary from product to product, so make sure that you check (using udevinfo) which one applies to you.
+Note that the product string seems to vary from product to product, so make sure that you check (using udevadm info) which one applies to you.
</p>
<a name="example-cdrom"></a>
</p>
<p>
-It makes sense to simply match the MAC address of your interface in the rule, as this is unique. However, make sure that you use the <em>exact</em> MAC address as shown as udevinfo, because if you do not match the case exactly, your rule will not work.
+It makes sense to simply match the MAC address of your interface in the rule, as this is unique. However, make sure that you use the <em>exact</em> MAC address as shown as udevadm info, because if you do not match the case exactly, your rule will not work.
</p>
<blockquote><pre>
-# udevinfo -a -p /sys/class/net/eth0
+# udevadm info -a -p /sys/class/net/eth0
looking at class device '/sys/class/net/eth0':
KERNEL=="eth0"
ATTR{address}=="00:52:8b:d5:04:48"
</p>
<p>
-To make the symbolic link show up, you can either disconnect and reconnect your camera, or alternatively in the case of non-removable devices, you can run <b>udevtrigger</b>.
-</p>
-
-<p>
-If your kernel does not have inotify support, new rules will not be detected automatically. In this situation, you must run <b>udevcontrol reload_rules</b> after making any rule file modifications for those modifications to take effect.
+To make the symbolic link show up, you can either disconnect and reconnect your camera, or alternatively in the case of non-removable devices, you can run <b>udevadm trigger</b>.
</p>
<a name="udevtest"></a>
-<h3>udevtest</h3>
+<h3>udevadm test</h3>
<p>
-If you know the top-level device path in sysfs, you can use <b>udevtest</b> to show the actions which udev would take. This may help you debug your rules. For example, assuming you want to debug a rule which acts on <em>/sys/class/sound/dsp</em>:
+If you know the top-level device path in sysfs, you can use <b>udevadm test</b> to show the actions which udev would take. This may help you debug your rules. For example, assuming you want to debug a rule which acts on <em>/sys/class/sound/dsp</em>:
</p>
<blockquote><pre>
-# udevtest /class/sound/dsp
+# udevadm test /class/sound/dsp
main: looking at device '/class/sound/dsp' from subsystem 'sound'
udev_rules_get_name: add symlink 'dsp'
udev_rules_get_name: rule applied, 'dsp' becomes 'sound/dsp'
</pre></blockquote>
<p>
-Note the <em>/sys</em> prefix was removed from the udevtest command line argument, this is because udevtest operates on device paths. Also note that udevtest is purely a testing/debugging tool, it does not create any device nodes, despite what the output suggests!
+Note the <em>/sys</em> prefix was removed from the udevadm test test command line argument, this is because udevadm test operates on device paths.
</p>
<a name="author"></a>
~ianmdlvl / elogind.git / blobdiff