chiark / gitweb /
doc: writing_udev_rules updated for the new command names
[elogind.git] / docs / writing_udev_rules / index.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6 <style type="text/css">
7 <!--
8         .green { color: #003300; }
9         .blue  { color: #0000CC; }
10         .maroon { color: maroon; }
11 //-->
12 </style>
13 <title>Writing udev rules</title>
14 </head>
15
16 <body>
17
18 <h1>Writing udev rules</h1>
19 by Daniel Drake (dsd)<br />
20 Version 0.74<br /><br />
21
22 The most recent version of this document can always be found at: <br />
23
24 <a href="http://www.reactivated.net/writing_udev_rules.html">http://www.reactivated.net/writing_udev_rules.html</a>
25
26 <h2>Contents</h2>
27 <ul>
28 <li>Introduction
29         <ul>
30         <li><a href="#about">About this document</a></li>
31         <li><a href="#history">History</a></li>
32         </ul>
33 </li>
34 <li>The concepts
35         <ul>
36         <li><a href="#terminology">Terminology: devfs, sysfs, nodes, etc.</a></li>
37         <li><a href="#why">Why?</a></li>
38         <li><a href="#builtin">Built-in persistent naming schemes</a></li>
39         </ul>
40 </li>
41 <li>Rule writing
42         <ul>
43         <li><a href="#syntax">Rule files and semantics</a></li>
44         <li><a href="#syntax">Rule syntax</a></li>
45         <li><a href="#basic">Basic rules</a></li>
46         <li><a href="#sysfsmatch">Matching sysfs attributes</a></li>
47         <li><a href="#hierarchy">Device hierarchy</a></li>
48         <li><a href="#strsubst">String substitutions</a></li>
49         <li><a href="#strmatch">String matching</a></li>
50         </ul>
51 </li>
52 <li>Finding suitable information from sysfs
53         <ul>
54         <li><a href="#sysfstree">The sysfs tree</a></li>
55         <li><a href="#udevadm">udevadm info</a></li>
56         <li><a href="#sysfsalt">Alternative methods</a></li>
57         </ul>
58 </li>
59 <li>Advanced topics
60         <ul>
61         <li><a href="#ownership">Controlling permissions and ownership</a></li>
62         <li><a href="#external-naming">Using external programs to name devices</a></li>
63         <li><a href="#external-run">Running external programs on certain events</a></li>
64         <li><a href="#env">Environment interaction</a></li>
65         <li><a href="options">Additional options</a></li>
66         </ul>
67 </li>
68 <li>Examples
69         <ul>
70         <li><a href="#example-printer">USB Printer</a></li>
71         <li><a href="#example-camera">USB Camera</a></li>
72         <li><a href="#example-usbhdd">USB Hard Disk</a></li>
73         <li><a href="#example-usbcardreader">USB Card Reader</a></li>
74         <li><a href="#example-pilot">USB Palm Pilot</a></li>
75         <li><a href="#example-cdrom">CD/DVD drives</a></li>
76         <li><a href="#example-netif">Network interfaces</a></li>
77         </ul>
78 </li>
79 <li>Testing and debugging
80         <ul>
81         <li><a href="#testing">Putting your rules into action</a></li>
82         <li><a href="#udevtest">udevadm test</a></li>
83         </ul>
84 </li>
85 <li><a href="#author">Author and contact</a></li>
86 </ul>
87
88 <h2>Introduction</h2>
89
90 <a name="about"></a>
91 <h3>About this document</h3>
92
93 <p>
94 udev is targeted at Linux kernels 2.6 and beyond to provide a userspace solution for a dynamic /dev directory, with persistent device naming. The previous /dev implementation, <i>devfs</i>, is now deprecated, and udev is seen as the successor. udev vs devfs is a sensitive area of conversation - you should read <a href="http://kernel.org/pub/linux/utils/kernel/hotplug/udev_vs_devfs">this document</a> before making comparisons.
95 </p>
96
97 <p>
98 Over the years, the things that you might use udev rules for has changed, as well as the flexibility of rules themselves. On a modern system, udev provides persistent naming for some device types out-of-the-box, eliminating the need for custom rules for those devices. However, some users will still require the extra level of customisation.
99 </p>
100
101 <p>
102 This document assumes that you have udev installed and running OK with default configurations. This is usually handled by your Linux distribution.
103 </p>
104
105 <p>
106 This document does not cover every single detail of rule writing, but does aim to introduce all of the main concepts. The finer details can be found in the udev man page.
107 </p>
108
109 <p>
110 This document uses various examples (many of which are entirely fictional) to illustrate ideas and concepts. Not all syntax is explicitly described in the accompanying text, be sure to look at the example rules to get a complete understanding.
111 </p>
112
113 <a name="history"></a>
114 <h3>History</h3>
115
116 <ul>
117 <li>April 5th 2008 v0.74: Typo fixes.</li>
118 <li>December 3rd 2007 v0.73: Update for new udev versions, and some miscellaneous improvements.</li>
119 <li>October 2nd 2006 v0.72: Fixed a typo in one of the example rules.</li>
120 <li>June 10th 2006 v0.71: Misc changes based on recent feedback - thanks!</li>
121 <li>June 3rd 2006 v0.7: Complete rework, to be more suited for the modern-day udev.</li>
122 <li>May 9th 2005 v0.6: Misc updates, including information about udevinfo, groups and permissions, logging, and udevtest.</li>
123 <li>June 20th 2004 v0.55: Added info on multiple symlinks, and some minor changes/updates.</li>
124 <li>April 26th 2004 v0.54: Added some Debian info. Minor corrections. Re-reverted information about what to call your rule file. Added info about naming network interfaces.</li>
125 <li>April 15th 2004 v0.53: Minor corrections. Added info about NAME{all_partitions}. Added info about other udevinfo tricks.</li>
126 <li>April 14th 2004 v0.52: Reverted to suggesting using "udev.rules" until the udev defaults allow for other files. Minor work.</li>
127 <li>April 6th 2004 v0.51: I now write suggest users to use their own "local.rules" file rather than prepending "udev.rules".</li>
128 <li>April 3rd 2004 v0.5: Minor cleanups and preparations for possible inclusion in the udev distribution.</li>
129 <li>March 20th 2004 v0.4: General improvements, clarifications, and cleanups. Added more information about writing rules for usb-storage.</li>
130 <li>February 23rd 2004 v0.3: Rewrote some parts to emphasise how sysfs naming works, and how it can be matched. Updated rule-writing parts to represent udev 018s new SYSFS{filename} naming scheme. Improved sectioning, and clarified many points. Added info about KDE.</li>
131 <li>February 18th 2004 v0.2: Fixed a small omission in an example. Updated section on identifying mass-storage devices. Updated section on nvidia.</li>
132 <li>February 15th 2004 v0.1: Initial publication.</li>
133 </ul>
134
135 <h2>The concepts</h2>
136
137 <a name="terminology"></a>
138 <h3>Terminology: devfs, sysfs, nodes, etc.</h3>
139
140 <p>
141 A basic introduction only, might not be totally accurate.
142 </p>
143
144 <p>
145 On typical Linux-based systems, the <i>/dev</i> directory is used to store file-like device <b>nodes</b> which refer to certain devices in the system. Each node points to a part of the system (a device), which might or might not exist. Userspace applications can use these device nodes to interface with the systems hardware, for example, the X server will "listen to" /dev/input/mice so that it can relate the user's mouse movements to moving the visual mouse pointer.
146 </p>
147
148 <p>
149 The original <i>/dev</i> directories were just populated with every device that might possibly appear in the system. /dev directories were typically very large because of this. <b>devfs</b> came along to provide a more manageable approach (noticeably, it only populated /dev with hardware that is plugged into the system), as well as some other functionality, but the system proved to have problems which could not be easily fixed.
150 </p>
151
152 <p>
153 <b>udev</b> is the "new" way of managing <i>/dev</i> directories, designed to clear up some issues with previous <i>/dev</i> implementations, and provide a robust path forward. In order to create and name <i>/dev</i> device nodes corresponding to devices that are present in the system, udev relies on matching information provided by <i>sysfs</i> with <i>rules</i> provided by the user. This documentation aims to detail the process of rule-writing, one of the only udev-related tasks that must (optionally) be performed by the user.
154 </p>
155
156 <p>
157 <b>sysfs</b> is a new filesystem to the 2.6 kernels. It is managed by the kernel, and exports basic information about the devices currently plugged into your system. udev can use this information to create device nodes corresponding to your hardware. sysfs is mounted at <i>/sys</i> and is browseable. You may wish to investigate some of the files stored there before getting to grips with udev. Throughout this document, I will use the terms <i>/sys</i> and <i>sysfs</i> interchangeably.
158 </p>
159
160 <a name="why"></a>
161 <h3>Why?</h3>
162
163 <p>
164 udev rules are flexible and very powerful. Here are some of the things you can use rules to achieve:
165 </p>
166
167 <ul>
168 <li>Rename a device node from the default name to something else</li>
169 <li>Provide an alternative/persistent name for a device node by creating a symbolic link to the default device node</li>
170 <li>Name a device node based on the output of a program</li>
171 <li>Change permissions and ownership of a device node</li>
172 <li>Launch a script when a device node is created or deleted (typically when a device is attached or unplugged)</li>
173 <li>Rename network interfaces</li>
174 </ul>
175
176 <p>
177 Writing rules is <u>not</u> a workaround for the problem where no device nodes for your particular device exist. Even if there are no matching rules, udev will create the device node with the default name supplied by the kernel.
178 </p>
179
180 <p>
181 Having persistently named device nodes has several advantages. Assume you own two USB storage devices: a digital camera and a USB flash disk. These devices are typically assigned device nodes <em>/dev/sda</em> and <em>/dev/sdb</em> but the exact assignment depends on the order which they were originally connected. This may cause problems to some users, who would benefit greatly if each device could be named persistently every time, e.g. <em>/dev/camera</em> and <em>/dev/flashdisk</em>.
182 </p>
183
184 <a name="builtin"></a>
185 <h3>Built-in persistent naming schemes</h3>
186
187 <p>
188 udev provides persistent naming for some device types out of the box. This is a very useful feature, and in many circumstances means that your journey ends here: you do not have to write any rules.
189 </p>
190
191 <p>
192 udev provides out-of-the-box persistent naming for storage devices in the <em>/dev/disk</em> directory. To view the persistent names which have been created for your storage hardware, you can use the following command:
193 </p>
194
195 <blockquote><pre># ls -lR /dev/disk</pre></blockquote>
196
197 <p>
198 This works for all storage types. As an example, udev has created <em>/dev/disk/by-id/scsi-SATA_ST3120827AS_4MS1NDXZ-part3</em> which is a persistent-named symbolic link to my root partition. udev creates <em>/dev/disk/by-id/usb-Prolific_Technology_Inc._USB_Mass_Storage_Device-part1</em> when I plug my USB flash disk in, which is also a persistent name.
199 </p>
200
201 <!-- FIXME: document CDROM persistent naming when things settle down -->
202
203 <h2>Rule writing</h2>
204
205 <a name="files"></a>
206 <h3>Rule files and semantics</h3>
207
208 <p>
209 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.
210 </p>
211
212 <p>
213 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.
214 </p>
215
216 <p>
217 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.
218 </p>
219
220 <p>
221 In a rules file, lines starting with "#" are treated as comments. Every other non-blank line is a rule. Rules cannot span multiple lines.
222 </p>
223
224 <p>
225 One device can be matched by more than one rule. This has it's practical advantages, for example, we can write two rules which match the same device, where each one provides its own alternate name for the device. Both alternate names will be created, even if the rules are in separate files. It is important to understand that udev will <em>not</em> stop processing when it finds a matching rule, it will continue searching and attempt to apply every rule that it knows about.
226 </p>
227
228 <a name="syntax"></a>
229 <h3>Rule syntax</h3>
230
231 <p>
232 Each rule is constructed from a series of key-value pairs, which are separated by commas. <b>match</b> keys are conditions used to identify the device which the rule is acting upon. When <u>all</u> match keys in a rule correspond to the device being handled, then the rule is applied and the actions of the <b>assignment</b> keys are invoked. Every rule should consist of at least one match key and at least one assignment key.
233 </p>
234
235 <p>
236 Here is an example rule to illustrate the above:
237 </p>
238
239 <blockquote><pre>KERNEL=="hdb", NAME="my_spare_disk"</pre></blockquote>
240
241 <p>
242 The above rule includes one match key (<em>KERNEL</em>) and one assignment key (<em>NAME</em>). The semantics of these keys and their properties will be detailed later. It is important to note that the match key is related to its value through the equality operator (==), whereas the assignment key is related to its value through the assignment operator (=).
243 </p>
244
245 <p>
246 Be aware that udev does not support any form of line continuation. Do not insert any line breaks in your rules, as this will cause udev to see your one rule as multiple rules and will not work as expected.
247 </p>
248
249 <a name="basic"></a>
250 <h3>Basic Rules</h3>
251
252 <p>
253 udev provides several different match keys which can be used to write rules which match devices very precisely. Some of the most common keys are introduced below, others will be introduced later in this document. For a complete list, see the udev man page.
254 </p>
255
256 <ul>
257 <li><b>KERNEL</b> - match against the kernel name for the device</li>
258 <li><b>SUBSYSTEM</b> - match against the subsystem of the device</li>
259 <li><b>DRIVER</b> - match against the name of the driver backing the device</li>
260 </ul>
261
262 <p>
263 After you have used a series of match keys to precisely match a device, udev gives you fine control over what happens next, through a range of assignment keys. For a complete list of possible assignment keys, see the udev man page. The most basic assignment keys are introduced below. Others will be introduced later in this document.
264 </p>
265
266 <ul>
267 <li><b>NAME</b> - the name that shall be used for the device node</li>
268 <li><b>SYMLINK</b> - a <b>list</b> of symbolic links which act as alternative names for the device node</li>
269 </ul>
270
271 <p>
272 As hinted above, udev only creates one true device node for one device. If you wish to provide alternate names for this device node, you use the symbolic link functionality. With the <em>SYMLINK</em> assignment, you are actually maintaining a <em>list</em> of symbolic links, all of which will be pointed at the real device node. To manipulate these links, we introduce a new operator for appending to lists: <b>+=</b>. You can append multiple symlinks to the list from any one rule by separating each one with a space.
273 </p>
274
275 <blockquote><pre>KERNEL=="hdb", NAME="my_spare_disk"</pre></blockquote>
276
277 <p>
278 The above rule says: <em>match a device which was named by the kernel as hdb, and instead of calling it hdb, name the device node as my_spare_disk</em>. The device node appears at <em>/dev/my_spare_disk</em>.
279 </p>
280
281 <blockquote><pre>KERNEL=="hdb", DRIVER=="ide-disk", SYMLINK+="sparedisk"</pre></blockquote>
282
283 <p>
284 The above rule says: <em>match a device which was named by the kernel as hdb AND where the driver is ide-disk. Name the device node with the default name and create a symbolic link to it named sparedisk</em>. Note that we did not specify a device node name, so udev uses the default. In order to preserve the standard <em>/dev</em> layout, your own rules will typically leave the NAME alone but create some SYMLINKs and/or perform other assignments.
285 </p>
286
287 <blockquote><pre>KERNEL=="hdc", SYMLINK+="cdrom cdrom0"</pre></blockquote>
288
289 <p>
290 The above rule is probably more typical of the types of rules you might be writing. It creates two symbolic links at <em>/dev/cdrom</em> and <em>/dev/cdrom0</em>, both of which point at <em>/dev/hdc</em>. Again, no NAME assignment was specified, so the default kernel name (hdc) is used.
291 </p>
292
293 <a name="sysfsmatch"></a>
294 <h3>Matching sysfs attributes</h3>
295
296 <p>
297 The match keys introduced so far only provide limited matching capabilities. Realistically we require much finer control: we want to identify devices based on advanced properties such as vendor codes, exact product numbers, serial numbers, storage capacities, number of partitions, etc.
298 </p>
299
300 <p>
301 Many drivers export information like this into sysfs, and udev allows us to incorporate sysfs-matching into our rules, using the <em>ATTR</em> key with a slightly different syntax.
302 </p>
303
304 <p>
305 Here is an example rule which matches a single attribute from sysfs. Further detail will be provided later in this document which will aid you in writing rules based on sysfs attributes.
306 </p>
307
308 <blockquote><pre>
309 SUBSYSTEM=="block", ATTR{size}=="234441648", SYMLINK+="my_disk"
310 </pre></blockquote>
311
312 <a name="hierarchy"></a>
313 <h3>Device hierarchy</h3>
314
315 <p>
316 The Linux kernel actually represents devices in a tree-like structure, and this information is exposed through sysfs and useful when writing rules. For example, the device representation of my hard disk device is a child of the SCSI disk device, which is in turn a child of the Serial ATA controller device, which is in turn a child of the PCI bus device. It is likely that you will find yourself needing to refer to information from a parent of the device in question, for example the serial number of my hard disk device is not exposed at the device level, it is exposed by its direct parent at the SCSI disk level.
317 </p>
318
319 <p>
320 The four main match keys introduced so far (KERNEL/SUBSYSTEM/DRIVER/ATTR) only match against values corresponding to the device in question, and do not match values from parent devices. udev provides variants of the match keys that will search upwards through the tree:
321 </p>
322
323 <ul>
324 <li><b>KERNELS</b> - match against the kernel name for the device, or the kernel name for any of the parent devices</li>
325 <li><b>SUBSYSTEMS</b> - match against the subsystem of the device, or the subsystem of any of the parent devices</li>
326 <li><b>DRIVERS</b> - match against the name of the driver backing the device, or the name of the driver backing any of the parent devices</li>
327 <li><b>ATTRS</b> - match a sysfs attribute of the device, or a sysfs attribute of any of the parent devices</li>
328 </ul>
329
330 <p>
331 With hierarchy considerations in mind, you may feel that rule writing is becoming a little complicated. Rest assured that there are tools that help out here, which will be introduced later.
332 </p>
333
334 <a name="strsubst"></a>
335 <h3>String substitutions</h3>
336
337 <p>
338 When writing rules which will potentially handle multiple similar devices, udev's <em>printf-like string substitution operators</em> are very useful. You can simply include these operators in any assignments your rule makes, and udev will evaluate them when they are executed.
339 </p>
340
341 <p>
342 The most common operators are <b>%k</b> and <b>%n</b>. %k evaluates to the kernel name for the device, e.g. "sda3" for a device that would (by default) appear at <em>/dev/sda3</em>. <b>%n</b> evaluates to the kernel number for the device (the partition number for storage devices), e.g. "3" for <em>/dev/sda3</em>.
343 </p>
344
345 <p>
346 udev also provides several other substitution operators for more advanced functionality. Consult the udev man page after reading the rest of this document. There is also an alternative syntax for these operators - <b>$kernel</b> and <b>$number</b> for the examples above. For this reason, if you wish to match a literal % in a rule then you must write <b>%%</b>, and if you wish to match a literal $ then you must write <b>$$</b>.
347 </p>
348
349 <p>
350 To illustrate the concept of string substitution, some example rules are shown below.
351 </p>
352
353 <blockquote><pre>
354 KERNEL=="mice", NAME="input/%k"
355 KERNEL=="loop0", NAME="loop/%n", SYMLINK+="%k"
356 </pre></blockquote>
357
358 <p>
359 The first rule ensures that the mice device node appears exclusively in the <em>/dev/input</em> directory (by default it would be at <em>/dev/mice</em>). The second rule ensures that the device node named loop0 is created at <em>/dev/loop/0</em> but also creates a symbolic link at <em>/dev/loop0</em> as usual.
360 </p>
361
362 <p>
363 The use of the above rules is questionable, as they all could be rewritten without using any substitution operators. The true power of these substitutions will become apparent in the next section.
364 </p>
365
366 <a name="strmatch"></a>
367 <h3>String matching</h3>
368
369 <p>
370 As well as matching strings exactly, udev allows you to use shell-style pattern matching. There are 3 patterns supported:
371 </p>
372
373 <ul>
374 <li><b>*</b> - match any character, zero or more times</li>
375 <li><b>?</b> - match any character exactly once</li>
376 <li><b>[]</b> - match any single character specified in the brackets, ranges are also permitted</li>
377 </ul>
378
379 <p>
380 Here are some examples which incorporate the above patterns. Note the use of the string substitution operators.
381 </p>
382
383 <blockquote><pre>
384 KERNEL=="fd[0-9]*", NAME="floppy/%n", SYMLINK+="%k"
385 KERNEL=="hiddev*", NAME="usb/%k"
386 </pre></blockquote>
387
388 <p>
389 The first rule matches all floppy disk drives, and ensures that the device nodes are placed in the <em>/dev/floppy</em> directory, as well as creating a symbolic link from the default name. The second rule ensures that hiddev devices are only present in the <em>/dev/usb</em> directory.
390 </p>
391
392 <h2>Finding information from sysfs</h2>
393
394 <a name="sysfstree"></a>
395 <h3>The sysfs tree</h3>
396
397 <p>
398 The concept of using interesting information from sysfs was briefly touched upon above. In order to write rules based on this information, you first need to know the names of the attributes and their current values.
399 </p>
400
401 <p>
402 sysfs is actually a very simple structure. It is logically divided into directories. Each directory contains a number of files (<em>attributes</em>) which typically contain just one value. Some symbolic links are present, which link devices to their parents. The hierarchical structure was touched upon above.
403 </p>
404
405 <p>
406 Some directories are referred to as <em>top-level device paths</em>. These directories represent actual devices that have corresponding device nodes. Top-level device paths can be classified as sysfs directories which contain a <em>dev</em> file, the following command will list these for you:
407 </p>
408
409 <blockquote><pre># find /sys -name dev</pre></blockquote>
410
411 <p>
412 For example, on my system, the <em>/sys/block/sda</em> directory is the device path for my hard disk. It is linked to it's parent, the SCSI disk device, through the <em>/sys/block/sda/device</em> symbolic link.
413 </p>
414
415 <p>
416 When you write rules based on sysfs information, you are simply matching attribute contents of some files in one part of the chain. For example, I can read the size of my hard disk as follows:
417 </p>
418
419 <blockquote><pre>
420 # cat /sys/block/sda/size
421 234441648
422 </pre></blockquote>
423
424 <p>
425 In a udev rule, I could use ATTR{size}=="234441648" to identify this disk. As udev iterates through the entire device chain, I could alternatively opt to match attributes in another part of the chain (e.g. attributes in <em>/sys/class/block/sda/device/</em>) using <em>ATTRS</em>, however there are some caveats when dealing with different parts of the chain which are described later.
426 </p>
427
428 <p>
429 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.
430 </p>
431
432 <a name="udevadm"></a>
433 <h3>udevadm info</h3>
434
435 <p>
436 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:
437 </p>
438
439 <blockquote><pre>
440 # udevadm info -a -p /sys/block/sda
441
442 <span class="green">  looking at device '/block/sda':
443     KERNEL=="sda"
444     SUBSYSTEM=="block"
445     ATTR{stat}=="  128535     2246  2788977   766188    73998   317300  3132216  5735004        0   516516  6503316"
446     ATTR{size}=="234441648"
447     ATTR{removable}=="0"
448     ATTR{range}=="16"
449     ATTR{dev}=="8:0"</span>
450
451 <span class="blue">  looking at parent device '/devices/pci0000:00/0000:00:07.0/host0/target0:0:0/0:0:0:0':
452     KERNELS=="0:0:0:0"
453     SUBSYSTEMS=="scsi"
454     DRIVERS=="sd"
455     ATTRS{ioerr_cnt}=="0x0"
456     ATTRS{iodone_cnt}=="0x31737"
457     ATTRS{iorequest_cnt}=="0x31737"
458     ATTRS{iocounterbits}=="32"
459     ATTRS{timeout}=="30"
460     ATTRS{state}=="running"
461     ATTRS{rev}=="3.42"
462     ATTRS{model}=="ST3120827AS     "
463     ATTRS{vendor}=="ATA     "
464     ATTRS{scsi_level}=="6"
465     ATTRS{type}=="0"
466     ATTRS{queue_type}=="none"
467     ATTRS{queue_depth}=="1"
468     ATTRS{device_blocked}=="0"</span>
469
470 <span class="maroon">  looking at parent device '/devices/pci0000:00/0000:00:07.0':
471     KERNELS=="0000:00:07.0"
472     SUBSYSTEMS=="pci"
473     DRIVERS=="sata_nv"
474     ATTRS{vendor}=="0x10de"
475     ATTRS{device}=="0x037f"</span>
476 </pre></blockquote>
477
478 <p>
479 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:
480 </p>
481
482 <blockquote><pre>
483 <span class="green">SUBSYSTEM=="block"</span>, <span class="green">ATTR{size}=="234441648",</span> NAME="my_hard_disk"
484 <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>
485
486 <p>
487 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:
488 </p>
489
490 <blockquote><pre>
491 <span class="green">SUBSYSTEM=="block"</span>, <span class="blue">ATTRS{model}=="ST3120827AS"</span>, <span class="maroon">DRIVERS=="sata_nv"</span>, NAME="my_hard_disk"</pre></blockquote>
492
493 <p>
494 You are usually provided with a large number of attributes, and you must pick a number of them to construct your rule. In general, you want to choose attributes which identify your device in a persistent and human-recognisable way. In the examples above, I chose the size of my disk and its model number. I did not use meaningless numbers such as ATTRS{iodone_cnt}=="0x31737".
495 </p>
496
497 <p>
498 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.
499 </p>
500
501 <p>
502 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.
503 </p>
504
505 <p>
506 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:
507 </p>
508
509 <blockquote><pre># udevadm info -a -p $(udevadm info -q path -n /dev/sda)</pre></blockquote>
510
511 <a name="sysfsalt"></a>
512 <h3>Alternative methods</h3>
513
514 <p>
515 Although udevadm 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.
516 </p>
517
518 <h2>Advanced topics</h2>
519
520 <a name="ownership"></a>
521 <h3>Controlling permissions and ownership</h3>
522
523 <p>
524 udev allows you to use additional assignments in rules to control ownership and permission attributes on each device.
525 </p>
526
527 <p>
528 The <em>GROUP</em> assignment allows you to define which Unix group should own the device node. Here is an example rule which defines that the <em>video</em> group will own the framebuffer devices:
529 </p>
530
531 <blockquote><pre>KERNEL=="fb[0-9]*", NAME="fb/%n", SYMLINK+="%k", GROUP="video"</pre></blockquote>
532
533 <p>
534 The <em>OWNER</em> key, perhaps less useful, allows you to define which Unix user should have ownership permissions on the device node. Assuming the slightly odd situation where you would want <em>john</em> to own your floppy devices, you could use:
535 </p>
536
537 <blockquote><pre>KERNEL=="fd[0-9]*", OWNER="john"</pre></blockquote>
538
539 <p>
540 udev defaults to creating nodes with Unix permissions of 0660 (read/write to owner and group). If you need to, you can override these defaults on certain devices using rules including the <em>MODE</em> assignment. As an example, the following rule defines that the inotify node shall be readable and writable to everyone:
541 </p>
542
543 <blockquote><pre>KERNEL=="inotify", NAME="misc/%k", SYMLINK+="%k", MODE="0666"</pre></blockquote>
544
545 <a name="external-naming"></a>
546 <h3>Using external programs to name devices</h3>
547
548 <p>
549 Under some circumstances, you may require more flexibility than standard udev rules can provide. In this case, you can ask udev to run a program and use the standard output from that program to provide device naming.
550 </p>
551
552 <p>
553 To use this functionality, you simply specify the absolute path of the program to run (and any parameters) in the <em>PROGRAM</em> assignment, and you then use some variant of the <em>%c</em> substitution in the NAME/SYMLINK assignments.
554 </p>
555
556 <p>
557 The following examples refer to a fictional program found at <em>/bin/device_namer</em>. device_namer takes one command line argument which is the kernel name for the device. Based upon this kernel name, device_namer does its magic and produces some output to the usual <em>stdout</em> pipe, split into several parts. Each part is just a single word, and parts are separated by a single space.
558 </p>
559
560 <p>
561 In our first example, we assume that device_namer outputs a number of parts, each one to form a symbolic link (alternative name) for the device in question.
562 </p>
563
564 <blockquote><pre>KERNEL=="hda", PROGRAM="/bin/device_namer %k", SYMLINK+="%c"</pre></blockquote>
565
566 <p>
567 The next example assumes that device_namer outputs two parts, the first being the device name, and the second being the name for an additional symbolic link. We now introduce the <em>%c{N}</em> substitution, which refers to part N of the output:
568 </p>
569
570 <blockquote><pre>KERNEL=="hda", PROGRAM="/bin/device_namer %k", NAME="%c{1}", SYMLINK+="%c{2}"</pre></blockquote>
571
572 <p>
573 The next example assumes that device_namer outputs one part for the device name, followed by any number of parts which will form additional symbolic links. We now introduce the <em>%c{N+}</em> substitution, which evaluates to part N, N+1, N+2, ... until the end of the output.
574 </p>
575
576 <blockquote><pre>KERNEL=="hda", PROGRAM="/bin/device_namer %k", NAME="%c{1}", SYMLINK+="%c{2+}"</pre></blockquote>
577
578 <p>
579 Output parts can be used in any assignment key, not only NAME and SYMLINK. The example below uses a fictional program to determine the Unix group which should own the device:
580 </p>
581
582 <blockquote><pre>KERNEL=="hda", PROGRAM="/bin/who_owns_device %k", GROUP="%c"</pre></blockquote>
583
584 <a name="external-run"></a>
585 <h3>Running external programs upon certain events</h3>
586
587 <p>
588 Yet another reason for writing udev rules is to run a particular program when a device is connected or disconnected. For example, you might want to execute a script to automatically download all of your photos from your digital camera when it is connected.
589 </p>
590
591 <p>
592 Do not confuse this with the <em>PROGRAM</em> functionality described above. <em>PROGRAM</em> is used for running programs which produce device names (and they shouldn't do anything other than that). When those programs are being executed, the device node has not yet been created, so acting upon the device in any way is not possible.
593 </p>
594
595 <p>
596 The functionality introduced here allows you to run a program after the device node is put in place. This program can act on the device, however it must not run for any extended period of time, because udev is effectively paused while these programs are running. One workaround for this limitation is to make sure your program immediately detaches itself.
597 </p>
598
599 <p>
600 Here is an example rule which demonstrates the use of the <em>RUN</em> list assignment:
601 </p>
602
603 <blockquote><pre>KERNEL=="sdb", RUN+="/usr/bin/my_program"</pre></blockquote>
604
605 <p>
606 When <em>/usr/bin/my_program</em> is executed, various parts of the udev environment are available as environment variables, including key values such as <em>SUBSYSTEM</em>. You can also use the <em>ACTION</em> environment variable to detect whether the device is being connected or disconnected - ACTION will be either "add" or "remove" respectively.
607 </p>
608
609 <p>
610 udev does not run these programs on any active terminal, and it does not execute them under the context of a shell. Be sure to ensure your program is marked executable, if it is a shell script ensure it starts with an appropriate <a href="http://en.wikipedia.org/wiki/Shebang_(Unix)">shebang</a> (e.g. <code>#!/bin/sh</code>), and do not expect any standard output to appear on your terminal.
611 </p>
612
613 <a name="env"></a>
614 <h3>Environment interaction</h3>
615
616 <p>
617 udev provides an <em>ENV</em> key for environment variables which can be used for both matching and assignment.
618 </p>
619
620 <p>
621 In the assignment case, you can set environment variables which you can then match against later. You can also set environment variables which can be used by any external programs invoked using the techniques mentioned above. A fictional example rule which sets an environment variable is shown below.
622 </p>
623
624 <blockquote><pre>KERNEL=="fd0", SYMLINK+="floppy", ENV{some_var}="value"</pre></blockquote>
625
626 <p>
627 In the matching case, you can ensure that rules only run depending on the value of an environment variable. Note that the environment that udev sees will not be the same user environment as you get on the console. A fictional rule involving an environment match is shown below.
628 </p>
629
630 <blockquote><pre>KERNEL=="fd0", ENV{an_env_var}=="yes", SYMLINK+="floppy"</pre></blockquote>
631
632 <p>
633 The above rule only creates the <em>/dev/floppy</em> link if $an_env_var is set to "yes" in udev's environment.
634 </p>
635
636 <a name="options"></a>
637 <h3>Additional options</h3>
638
639 <p>
640 Another assignment which can prove useful is the <em>OPTIONS</em> list. A few options are available:
641 </p>
642
643 <ul>
644 <li><b>all_partitions</b> - create all possible partitions for a block device, rather than only those that were initially detected</li>
645 <li><b>ignore_device</b> - ignore the event completely</li>
646 <li><b>last_rule</b> - ensure that no later rules have any effect</li>
647 </ul>
648
649 <p>
650 For example, the rule below sets the group ownership on my hard disk node, and ensures that no later rule can have any effect:
651 </p>
652
653 <blockquote><pre>KERNEL=="sda", GROUP="disk", OPTIONS+="last_rule"</pre></blockquote>
654
655
656 <h2>Examples</h2>
657
658 <a name="example-printer"></a>
659 <h3>USB Printer</h3>
660
661 <p>
662 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:
663 </p>
664
665 <blockquote><pre>
666 # udevadm info -a -p $(udevadm info -q path -n /dev/lp0)
667   looking at device '/class/usb/lp0':
668     KERNEL=="lp0"
669     SUBSYSTEM=="usb"
670     DRIVER==""
671     ATTR{dev}=="180:0"
672
673   looking at parent device '/devices/pci0000:00/0000:00:1d.0/usb1/1-1':
674     SUBSYSTEMS=="usb"
675     ATTRS{manufacturer}=="EPSON"
676     ATTRS{product}=="USB Printer"
677     ATTRS{serial}=="L72010011070626380"
678 </pre></blockquote>
679
680 <p>
681 My rule becomes:
682 </p>
683
684 <blockquote><pre>SUBSYSTEM=="usb", ATTRS{serial}=="L72010011070626380", SYMLINK+="epson_680"</pre></blockquote>
685
686 <a name="example-camera"></a>
687 <h3>USB Camera</h3>
688
689 <p>
690 Like most, my camera identifies itself as an external hard disk connected over the USB bus, using the SCSI transport. To access my photos, I mount the drive and copy the image files onto my hard disk.
691 </p>
692
693 <p>
694 Not all cameras work in this way: some of them use a non-storage protocol such as cameras supported by <a href="http://www.gphoto.org/">gphoto2</a>. In the gphoto case, you do not want to be writing rules for your device, as is it controlled purely through userspace (rather than a specific kernel driver).
695 </p>
696
697 <p>
698 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>.
699 </p>
700
701 <p>
702 To get around this, you simply need to think about what differs between sdb and sdb1. It is surprisingly simple: the name itself differs, so we can use a simple pattern match on the NAME field.
703 </p>
704
705 <blockquote><pre>
706 # udevadm info -a -p $(udevadm info -q path -n /dev/sdb1)
707   looking at device '/block/sdb/sdb1':
708     KERNEL=="sdb1"
709     SUBSYSTEM=="block"
710
711   looking at parent device '/devices/pci0000:00/0000:00:02.1/usb1/1-1/1-1:1.0/host6/target6:0:0/6:0:0:0':
712     KERNELS=="6:0:0:0"
713     SUBSYSTEMS=="scsi"
714     DRIVERS=="sd"
715     ATTRS{rev}=="1.00"
716     ATTRS{model}=="X250,D560Z,C350Z"
717     ATTRS{vendor}=="OLYMPUS "
718     ATTRS{scsi_level}=="3"
719     ATTRS{type}=="0"
720 </pre></blockquote>
721
722 <p>
723 My rule:
724 </p>
725
726 <blockquote><pre>KERNEL=="sd?1", SUBSYSTEMS=="scsi", ATTRS{model}=="X250,D560Z,C350Z", SYMLINK+="camera"</pre></blockquote>
727
728 <a name="example-usbhdd"></a>
729 <h3>USB Hard Disk</h3>
730
731 <p>
732 A USB hard disk is comparable to the USB camera I described above, however typical usage patterns are different. In the camera example, I explained that I am not interested in the sdb node - it's only real use is for partitioning (e.g. with fdisk), but why would I want to partition my camera!?
733 </p>
734
735 <p>
736 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:
737 </p>
738
739 <blockquote><pre>KERNEL=="sd*", SUBSYSTEMS=="scsi", ATTRS{model}=="USB 2.0 Storage Device", SYMLINK+="usbhd%n"</pre></blockquote>
740
741 <p>
742 This rule creates symlinks such as:
743 </p>
744
745 <ul>
746 <li><em>/dev/usbhd</em> - The fdiskable node</li>
747 <li><em>/dev/usbhd1</em> - The first partition (mountable)</li>
748 <li><em>/dev/usbhd2</em> - The second partition (mountable)</li>
749 </ul>
750
751 <a name="example-usbcardreader"></a>
752 <h3>USB Card Reader</h3>
753
754 <p>
755 USB card readers (CompactFlash, SmartMedia, etc) are yet another range of USB storage devices which have different usage requirements.
756 </p>
757
758 <p>
759 These devices typically do not inform the host computer upon media change. So, if you plug in the device with no media, and then insert a card, the computer does not realise, and you do not have your mountable sdb1 partition node for the media.
760 </p>
761
762 <p>
763 One possible solution is to take advantage of the <em>all_partitions</em> option, which will create 16 partition nodes for every block device that the rule matches:
764 </p>
765
766 <blockquote><pre>KERNEL="sd*", SUBSYSTEMS=="scsi", ATTRS{model}=="USB 2.0 CompactFlash Reader", SYMLINK+="cfrdr%n", OPTIONS+="all_partitions"</pre></blockquote>
767
768 You will now have nodes named: cfrdr, cfrdr1, cfrdr2, cfrdr3, ..., cfrdr15.
769
770 <a name="example-pilot"></a>
771 <h3>USB Palm Pilot</h3>
772
773 <p>
774 These devices work as USB-serial devices, so by default, you only get the <em>ttyUSB1</em> device node. The palm utilities rely on <em>/dev/pilot</em>, so many users will want to use a rule to provide this.
775 </p>
776
777 <p>
778 <a href="http://www.clasohm.com/blog/one-entry?entry%5fid=12096">Carsten Clasohm's blog post</a> appears to be the definitive source for this. Carsten's rule is shown below:
779 </p>
780
781 <blockquote><pre>SUBSYSTEMS=="usb", ATTRS{product}=="Palm Handheld", KERNEL=="ttyUSB*", SYMLINK+="pilot"</pre></blockquote>
782
783 <p>
784 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.
785 </p>
786
787 <a name="example-cdrom"></a>
788 <h3>CD/DVD drives</h3>
789
790 <p>
791 I have two optical drives in this computer: a DVD reader (hdc), and a DVD rewriter (hdd). I do not expect these device nodes to change, unless I physically rewire my system. However, many users like to have device nodes such as <em>/dev/dvd</em> for convenience.
792 </p>
793
794 <p>
795 As we know the KERNEL names for these devices, rule writing is simple. Here are some examples for my system:
796 </p>
797
798 <blockquote><pre>
799 SUBSYSTEM=="block", KERNEL=="hdc", SYMLINK+="dvd", GROUP="cdrom"
800 SUBSYSTEM=="block", KERNEL=="hdd", SYMLINK+="dvdrw", GROUP="cdrom"
801 </pre></blockquote>
802
803 <a name="example-netif"></a>
804 <h3>Network interfaces</h3>
805
806 <p>
807 Even though they are referenced by names, network interfaces typically do not have device nodes associated with them. Despite that, the rule writing process is almost identical.
808 </p>
809
810 <p>
811 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.
812 </p>
813
814 <blockquote><pre>
815 # udevadm info -a -p /sys/class/net/eth0
816   looking at class device '/sys/class/net/eth0':
817     KERNEL=="eth0"
818     ATTR{address}=="00:52:8b:d5:04:48"
819 </pre></blockquote>
820
821 <p>
822 Here is my rule:
823 </p>
824
825 <blockquote><pre>KERNEL=="eth*", ATTR{address}=="00:52:8b:d5:04:48", NAME="lan"</pre></blockquote>
826
827 <p>
828 You will need to reload the net driver for this rule to take effect. You can either unload and reload the module, or simply reboot the system. You will also need to reconfigure your system to use "lan" rather than "eth0". I had some troubles getting this going (the interface wasn't being renamed) until I had completely dropped all references to eth0.
829 After that, you should be able to use "lan" instead of "eth0" in any calls to ifconfig or similar utilities.
830 </p>
831
832 <h2>Testing and debugging</h2>
833
834 <a name="testing"></a>
835 <h3>Putting your rules into action</h3>
836
837 <p>
838 Assuming you are on a recent kernel with <em>inotify</em> support, udev will automatically monitor your rules directory and automatically pick up any modifications you make to the rule files.
839 </p>
840
841 <p>
842 Despite this, udev will not automatically reprocess all devices and attempt to apply the new rule(s). For example, if you write a rule to add an extra symbolic link for your camera while your camera is plugged in, you cannot expect the extra symbolic link to show up right away.
843 </p>
844
845 <p>
846 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>.
847 </p>
848
849 <a name="udevtest"></a>
850 <h3>udevadm test</h3>
851
852 <p>
853 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>:
854 </p>
855
856 <blockquote><pre>
857 # udevadm test /class/sound/dsp
858 main: looking at device '/class/sound/dsp' from subsystem 'sound'
859 udev_rules_get_name: add symlink 'dsp'
860 udev_rules_get_name: rule applied, 'dsp' becomes 'sound/dsp'
861 udev_device_event: device '/class/sound/dsp' already known, remove possible symlinks
862 udev_node_add: creating device node '/dev/sound/dsp', major = '14', minor = '3', mode = '0660', uid = '0', gid = '18'
863 udev_node_add: creating symlink '/dev/dsp' to 'sound/dsp'
864 </pre></blockquote>
865
866 <p>
867 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. Also note that udevadm test is purely a testing/debugging tool, it does not create any device nodes, despite what the output suggests!
868 </p>
869
870 <a name="author"></a>
871 <h2>Author and contact</h2>
872
873 <p>
874 This document is written by Daniel Drake &lt;<a href="mailto:dan@reactivated.net">dan@reactivated.net</a>&gt;. Feedback is appreciated.
875 </p>
876
877 <p>
878 For support, you should mail the linux-hotplug mailing list: <a href="mailto:linux-hotplug-devel@lists.sourceforge.net">linux-hotplug-devel@lists.sourceforge.net</a>.
879 </p>
880
881 <p>
882 Copyright (C) 2003-2006 Daniel Drake.<br />
883 This document is licensed under the <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General Public License, Version 2</a>.
884 </p>
885
886 </body>
887 </html>
888