1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
|
<html>
<head>
<title>Writing udev rules</title>
<META name="resource-type" content="document">
</head>
<body>
<h1>Writing udev rules</h1>
by Daniel Drake (dsd)<br />
Version 0.6<br /><br />
The most recent version of this document can always be found at: <br />
<a href="http://www.reactivated.net/udevrules.php">http://www.reactivated.net/udevrules.php</a>
<h2>Contents</h2>
<ol>
<li><a href="#about">About this document</a></li>
<li><a href="#history">History</a></li>
<li><a href="#versions">Software versions used at time of writing</a></li>
<li><a href="#terminology">Terminology: devfs, sysfs, nodes, etc.</a></li>
<li><a href="#why">Why? (The purpose of this document)</a></li>
<li><a href="#basics">The basics of writing rules</a></li>
<li><a href="#operators">Additional automated customisation for NAME and SYMLINK parameters</a></li>
<li><a href="#regexp">Using shell-style pattern matching in keys</a></li>
<li><a href="#keys">Key-writing basics</a></li>
<li><a href="#identify-keys">Identifying devices through basic keys</a></li>
<li><a href="#identify-sysfs">Identifying devices through SYSFS files</a></li>
<li><a href="#multiple-symlinks">Using multiple SYMLINK style rules</a></li>
<li><a href="#mode-owner-group">Controlling ownership and permissions</a></li>
<li><a href="#example-printer">Example: Writing a rule for my USB printer</a></li>
<li><a href="#example-camera">Example: Writing a rule for my USB-Storage digital camera</a></li>
<li><a href="#usbstorage-extra">Additional notes on writing rules for USB storage</a></li>
<li><a href="#example-cdrom">Example: Writing convenience rules for my CD drives</a></li>
<li><a href="#example-iface">Example: Writing a rule to name my network interface</a></li>
<li><a href="#tips">Tips for finding the appropriate places in SYSFS</a></li>
<li><a href="#debugging">Debugging your rules</a></li>
<li><a href="#author">Author and credits</a></li>
</ol>
<a name="about"></a>
<h2>About this document</h2>
udev is targetted 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.<br /><br />
udev is a well thought out solution, but I was initially very confused how I might customise it for my system. This document attempts to make the process of rule writing a little bit clearer.<br /><br />
I'm all open to feedback - please <a href="#author">contact me</a></b> with any comments, problems, and suggested improvements.<br /><br />
This document assumes that you have udev/hotplug installed and running OK with default configurations. If you do not yet have udev configured and running, I would suggest that you follow <a href="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html#UDEV">Decibels udev Primer</a> to get to this stage (contains some Gentoo Linux specifics, but should be useful for other distro's too).<br /><br />
<a name="history"></a>
<h2>History</h2>
May 9th 2005 v0.6: Misc updates, including information about udevinfo, groups and permissions, logging, and udevtest.<br /><br />
June 20th 2004 v0.55: Added info on multiple symlinks, and some minor changes/updates.<br /><br />
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.<br /><br />
April 15th 2004 v0.53: Minor corrections. Added info about NAME{all_partitions}. Added info about other udevinfo tricks.<br /><br />
April 14th 2004 v0.52: Reverted to suggesting using "udev.rules" until the udev defaults allow for other files. Minor work.<br /><br />
April 6th 2004 v0.51: I now write suggest users to use their own "local.rules" file rather than prepending "udev.rules".<br /><br />
April 3rd 2004 v0.5: Minor cleanups and preparations for possible inclusion in the udev distribution.<br /><br />
March 20th 2004 v0.4: General improvements, clarifications, and cleanups. Added more information about writing rules for usb-storage.<br /><br />
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.<br /><br />
February 18th 2004 v0.2: Fixed a small omission in an example. Updated section on identifying mass-storage devices. Updated section on nvidia.<br /><br />
February 15th 2004 v0.1: Initial publication.<br /><br />
<a name="versions"></a>
<h2>Software versions used at time of writing</h2>
Linux Kernel 2.6.11<br />
udev 056<br /><br />
<a name="terminology"></a>
<h2>Terminology: devfs, sysfs, nodes, etc.</h2>
<font size=2>A basic introduction only, might not be totally accurate.</font><br /><br />
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, XFree86 will "listen to" /dev/input/mice so that it can relate the users mouse movements to moving the visual mouse pointer.<br /><br />
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 managable approach (noticably, 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.<br /><br />
<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.<br /><br />
<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 browsable. 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.<br /><br /><br />
<a name="why"></a>
<h2>Why?</h2>
As stated above, writing rules for udev is an optional process. By default, you can plug a device in, and the a relevant node (e.g. <i>/dev/sda</i> for a mass-storage device) will be there, just like in previous <i>/dev</i> implementations.<br /><br />
However, udev allows you to customise the naming of device nodes. There are two reasons why you might want to do this: convenience, and persistent naming.<br /><br />
Take the example of using udev, so that when your printer is plugged in, it gets named as <i>/dev/printer</i> and also as the usual <i>/dev/lp0</i>. It's not only convenience (e.g. reading and interpreting "printer" as opposed to "lp0"), its a solution for non-persistent naming. Say that I have two printers - a HP laser printer and an Epson inkjet. When they are both plugged in and on, I have /dev/lp0 and /dev/lp1.<br />
How do I know which node refers to which printer? There is no easy way. The first printer that got connected was assigned name "lp0", and the second "lp1". Plugging in my printers in a different order would swap the names here, and that would mess up my scripts that always expect my HP laser printer to be lp1.<br /><br />
However, if my HP laser printer got named lp_hp (as well as lpX) and my other printer got named lp_epson (as well as lpY), then my scripts could just refer to those names. udev magic can control this and ensure that these <b>persistent names</b> always point to the device that I intended.<br /><br />
For external mass-storage devices (e.g. usb hard disks), persistent naming is very helpful in that it allows you to hardcode accurate device paths into your <i>/etc/fstab</i>.<br /><br />
It is important to understand that writing rules is simply a means of customizing udev behaviour. Writing rules is <b>not</b> a workaround for the problem where no device nodes for your particular device exist. If no matching rules exist, udev will create the node anyway, using the name that was supplied by the kernel.<br /><br />
<a name="basics"></a>
<h2>The basics of writing rules</h2>
When populating <i>/dev</i>, udev decides which nodes to include, and how to name them, by reading a series of rules files.<br /><br />
Default udev rules are stored in <i>/etc/udev/rules.d/50-udev.rules</i>. 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, to reduce hassle while updating your udev installation in the future.<br /><br />
Files in <i>/etc/udev/rules.d/</i> are parsed in <b>lexical</b> order. udev will stop processing rules as soon as it finds a matching rule in a file for the new item of hardware that has been detected. It is important that your own rules get processed before the udev defaults, otherwise your own naming schemes will not take effect! I suggest that you keep your own rules in a file at <i>/etc/udev/rules.d/10-local.rules</i> (this doesn't exist by default - create it). As 10 comes before 50, you know that your rules will be looked at first. It is important that the filenames of your rule files end with the <b>.rules</b> suffix, otherwise they will not be used.<br /><br />
As your own rules will effectively mask out the udev defaults which create the base /dev layout, it is recommended that you also specify devfs-style names/symlinks for the rules you write, so that you get the sensible defaults plus your own names.<br /><br />
In rule files, lines starting with a "#" are treated as comments. Every uncommented line in the file corresponds to a rule.<br /><br />
Rules are composed of keys. Keys are seperated by commas. Some keys are used for reading and matching information, others are used for assigning information and performing actions. Matches and assignments are carried out with the expected operators (= and ==).
<ol>
<li>At least one <i>identification key</i> should be provided, which will match the rule to any number of devices in the system. These are listed in the later section: <a href="#identify-keys">Identifying devices through basic keys</a>.</li>
<li>At least one <i>assignment key</i> should be provided, to control how the resultant device node is created. These include NAME, SYMLINK, OWNER, GROUP and MODE, all of which are described in this document.</li>
</ol>
Common rules will use basic identification keys to determine the device to name, and then have a <i>NAME</i> assignement key to define the device node name. udev will only create one node for one device, so if you want it to be accessible through multiple nodes, then you have to specify the other nodes in the <i>SYMLINK</i> assignment key.<br /><br />
I'll take a slightly modified udev example rule to illustrate this:
<blockquote><pre>BUS=="usb", SYSFS{serial}=="HXOLL0012202323480", NAME="lp_epson", SYMLINK="printers/epson_stylus"</pre></blockquote>
The identification keys here are <i>BUS</i> and <i>SYSFS{serial}</i>. The assignment keys here are <i>NAME</i> and <i>SYMLINK</i>. udev will match this rule against a device that is connected through the USB bus <u>and</u> with a serial number of HXOLL0012202323480. <b>Note that <u>all</u> (as opposed to any) specified keys must be matched for udev to use the rule to name a device.</b><br />
udev will name this node <i>lp_epson</i>, and it will be located at <i>/dev/lp_epson</i>.<br />
udev will also create a symlink to <i>/dev/lp_epson</i>, located at <i>/dev/printers/epson_stylus</i> (the printers directory will be automatically created). You can now print to your Epson printer by sending data to <i>/dev/printers/epson_stylus</i> or <i>/dev/lp_epson</i>.<br /><br />
Any rules that you have added or modified will <b>not</b> take effect until you notify udev of this. Make sure you remember to run the following every time you modify any rule files:
<blockquote><pre># udevstart</pre></blockquote>
<a name="operators"></a>
<h2>Additional automated customisation for NAME and SYMLINK parameters</h2>
In the NAME and SYMLINK parameters of your rules, you are able to use basic operators to assist the naming of devices. Hackers will know this sort of thing as <i>printf-like string substitution</i>.
There are a number of operators which can compose some or all of your NAME/SYMLINK parameters. These operators refer to kernel-data relating to the device. Take this example:
<blockquote><pre>BUS=="usb", SYSFS{vendor}=="FUJIFILM", SYSFS{model}=="M100", NAME="camera%n"</pre></blockquote>
The <i>%n</i> operator will be replaced with the "kernel number" for the camera device, to produce a NAME such as camera0, camera1, etc.<br /><br />
Another common operator is <i>%k</i>. This represents what the kernel would name the device, e.g. "hda1". You may often see rules which have NAME="%k" to produce the default names for the hardware. In these rules, customisation is usually done through the SYMLINK parameter.<br /><br />
<font size="2">A full list of operators, with explanations, can be found in the udev man page.</font><br /><br />
<a name="regexp"></a>
<h2>Using shell-style pattern matching in keys</h2>
You can use shell style pattern matching to provide even more flexibility when writing keys. Taking a default udev rule:
<blockquote><pre>KERNEL=="ts*", NAME="input/%k"</pre></blockquote>
The * operator is used here, which matches literally anything - zero, one, or more characters of any kind. The rule literally says:<br />
<blockquote>Match a device identified by a KERNEL name starting with the letters "ts" optionally followed by anything at all, and name it with the KERNEL name (%k) under the input directory.</blockquote>
The ? operator is similar, and matches any single character (but not zero characters).<br /><br />
You can also use square brackets [ ] to match any single character. Direct quote from udev man page:<br />
<blockquote>For example, the pattern string "tty[SR]" would match either "ttyS" or "ttyR".</blockquote>
You can also specify ranges that can be matched, e.g. [0-9] would match any single digit. Using an example rule from a default udev installation:
<blockquote><pre>KERNEL=="fd[0-9]*", NAME="floppy/%n"</pre></blockquote>
This rule says:<br />
<blockquote>Match a device identified by a KERNEL name starting with the letters "fd", followed by any single digit, optionally followed by anything at all. Name the device with the kernel number of the device (%n) under the floppy directory.</blockquote>
You can use these wildcards/pattern matches in any type of key, including both basic keys and sysfs-based identification (see below for explanations of these key types).<br /><br />
<font size="2">I have purposely left out some information on this topic (particularly the flexibility of using [ ] operators) that is out of the scope of basic rule-writing documentation. More information on this topic can be found in the udev man page.</font><br /><br />
<a name="keys"></a>
<h2>Key-writing basics</h2>
udev provides a few basic key matching methods, and also provides flexible ways of matching information in SYSFS. A typical rule will match both normal keys (e.g. BUS and KERNEL), as well as SYSFS keys to differentiate between different hardware plugged in throught the same port.<br /><br />
You may be wondering, "How do I find the serial number of my printer? What is the model of my camera?". Rule writing isn't as hard as it sounds. The trickiest bit is finding your device in /sys, and deciding which info to use.<br /><br />
<a name="identify-keys"></a>
<h2>Identifying devices through basic keys</h2>
<font size="2">See the udev man page for more info on these keys.</font><br /><br />
The valid keys are:
<ul><li>BUS - match the bus type of the device.</li>
<li>KERNEL - match the kernel device name.</li>
<li>DRIVER - match the name of the kernel driver.</li>
<li>SUBSYSTEM - match the kernel subsystem name.</li>
<li>ID - match the device number on the bus (e.g. PCI bus ID).</li>
<li>PLACE - match the physical position where the device is plugged into (useful for USB).</li>
</ul>
The ID and PLACE keys do have their uses, but they are not commonly used in rules. This document focuses on using BUS and KERNEL keys, as well as SYSFS{...} keys (detailed in the next section). I will show how to use these keys by example.<br /><br />
<font size="2">For extra flexibility, udev also provides keys to call external scripts and examine their result, and to examine environment variables. This is out of scope of this document. Look at the udev man page for more details.</font>
<a name="identify-sysfs"></a>
<h2>Identifying devices through SYSFS files</h2>
<font size="2">Background information: SYSFS stores many small files under a tree of directories which provide information about your hardware. One file typically contains just one "data item" - e.g. device name, manufacturer, or product ID.<br /><br />
Note that SYSFS{...} keys can be combined with the basic keys described in the previous section.</font><br /><br />
You can use keys in the format SYSFS{<i>filename</i>} to match specific info from SYSFS, where <i>filename</i> corresponds to a file in your SYSFS tree. For example, when my camera is connected, there is a file located at <i>/sys/block/sda/device/model</i> which contains "USB 2.0M DSC". To match this, I could use the following key: SYSFS{model} == "USB 2.0M DSC"<br /><br />
<b>Note that <u>any</u> file in sysfs can be matched in this manner, but if you match more than one file (through multiple keys), then you must only match files that exist in the same directory.</b> Typically, there will be several directories giving information about one device. You cannot mix and match (as shown by example below).<br /><br />
Luckily, the process of rule writing does not entail hunting through millions of files in SYSFS, the <i>udevinfo</i> utility does the hard work. This program is included in the udev distribution.</b><br /><br />
The first thing you need to do is find a directory somewhere in /sys that corresponds to your hardware, and includes a file named "<i>dev</i>", as udevinfo can only work on directories of this type. These directories are all found under either <i>/sys/block</i> or <i>/sys/class</i> - there is no point looking anywhere else! However, udevinfo will follow links through this directory and read info found from other sections of sysfs.<br /><br />
Once you have found a directory of this type, you can use the following command to assist you in the creation of writing keys for udev rules:
<blockquote><pre># udevinfo -a -p /sys/path/to/hardware/info</pre></blockquote>
You may find that finding the correct place in <i>/sys</i> to run udevinfo on is not obvious. Chances are the device you just plugged in has already careted a device node (e.g. <i>/dev/sda</i>), in which case, udevinfo can be helpful! Taking the example of my <i>/dev/sda</i> node, running the following command will point you to the appropriate area of sysfs:
<blockquote><pre>
# udevinfo -q path -n /dev/sda
/block/sda
</pre></blockquote>
The output of the command (shown above) is telling me that the sysfs path to start at is <i>/sys/block/sda</i>. I would now run "udevinfo -a -p /sys/block/sda". These two commands can be chained together, like so:
<blockquote><pre># udevinfo -a -p $(udevinfo -q path -n /dev/sda)</pre></blockquote>
<font size="2"><i>Sidenote: You may notice that we previously provided full paths (/sys/some/path) to udevinfo beforehand, but now we are providing sysfs-relative paths (/some/path) by chaining these commands. This does not matter - both types of path are accepted.</i></font><br /><br />
Moving on to rule-writing, some snipped output of the results of my "udevinfo -a -p /sys/block/sda" command is shown below, with colour added.<br />
<pre><font color="#003300">
follow the class device's "device"
looking at the device chain at '/sys/devices/pci0000:00/0000:00:02.1/usb3/3-3/3-3:1.0/host0/0:0:0:0':
BUS=="scsi"
ID=="0:0:0:0"
SYSFS{detach_state}=="0"
SYSFS{type}=="0"
SYSFS{max_sectors}=="240"
SYSFS{device_blocked}=="0"
SYSFS{queue_depth}=="1"
SYSFS{scsi_level}=="3"
SYSFS{vendor}==" "
SYSFS{model}=="USB 2.0M DSC "
SYSFS{rev}=="1.00"
SYSFS{online}=="1"</font>
<font color="#0000FF">
looking at the device chain at '/sys/devices/pci0000:00/0000:00:02.1/usb3/3-3':
BUS=="usb"
ID=="3-3"
SYSFS{detach_state}=="0"
SYSFS{bNumInterfaces}==" 1"
SYSFS{bConfigurationValue}=="1"
SYSFS{bmAttributes}=="c0"
SYSFS{bMaxPower}==" 0mA"
SYSFS{idVendor}=="052b"
SYSFS{idProduct}=="1514"
SYSFS{bcdDevice}=="0100"
SYSFS{bDeviceClass}=="00"
SYSFS{bDeviceSubClass}=="00"
SYSFS{bDeviceProtocol}=="00"
SYSFS{bNumConfigurations}=="1"
SYSFS{speed}=="12"
SYSFS{manufacturer}=="Tekom Technologies, Inc"
SYSFS{product}=="USB 2.0M DSC"</font>
</pre>
The <i>udevinfo</i> tool provides a lot of information which you can simply copy-paste as udev rules. The reason that I have colour coded the above output is to point out that <b>you generally cannot mix and match information from different parts of the udevinfo output</b>. In the above output, I could not combine information from the different coloured sections - this is because each section of output refers to a different directory in SYSFS. For example, the following rule would not work:
<blockquote><pre><font color="#003300">BUS=="scsi"</font>, <font color="#0000FF">SYSFS{manufacturer}=="Tekom Technologies, Inc"</font>, NAME="%k"</pre></blockquote>
This rule would not work because I am combining information found in the section beginning with BUS=="scsi" (green) with information only found in the blue section. The rule would work if I used BUS=="usb", sticking only to information found in the blue section above.<br /><br />
You will notice that a lot of information is not relevant for writing basic rules (there is so much of it!), you should generally be looking for information that you recognise and know will not change (e.g. model name).<br /><br />
<b>Note that if you write your own rule to identify a device, the default devfs-style rules will not take effect!</b> It is usually sensible to use NAME="%k" and specify your own extra names in the SYMLINK parameter so that you do not lose the default sensible names.<br /><br />
I will show three examples of this <i>rule writing based on udevinfo output</i> process below. I will then attempt to list some device-dependant tips and tricks for locating the correct info.<br /><br />
<font size=2>A reader wrote to me and informed me that he found KDE's control centre useful for writing rules. Apparently, information about USB devices (and others) can be found in the "Info Centre" section of the KDE Control Centre. This interface shows information such as serial number, vendor ID, etc. If you prefer a GUI-like approach, you might want to investigate this.<br /><br />
The current releases of gnome-volume-manager are unable to treat symlink-nodes as real devices. Conversely as described above, you may wish to specify your own naming in the <i>NAME</i> parameter and specify %k in the <i>SYMLINK</i> parameter.<br /><br />
The behaviour of your own rules masking the defaults can be overcome if you write <a href="#multiple-symlinks">multiple-SYMLINK style rules</a>.
</font>
<a name="multiple-symlinks"></a>
<h2>Using multiple SYMLINK style rules</h2>
Another recent feature is the ability to write rules that do not specify a <i>NAME</i>, but instead they simply specify <i>SYMLINK</i> keys. This allows you to avoid the issue where your own rules effectively mask the udev defaults.<br /><br />
Take the rule:<br />
<blockquote><pre>KERNEL=="hdc", SYMLINK="dvd"</pre></blockquote>
When udev finds this rule, it will take a mental note of it. Upon finding another rule matching the same device which also includes a <i>NAME</i> parameter, udev will create the node as specified by the <i>NAME</i> parameter, plus symbolic links as specified by the <i>SYMLINK</i> parameters of both rules.<br />
To put it into practical terms, when udev is naming nodes for my <i>hdc</i> device, it will use the default rules for block devices as usual, with the addition of my personal symlink "dvd".<br /><br />
Similarly to normal rules, rules of this type will only take effect if udev is able to find them <i>before</i> it finds a rule specifying a <i>NAME</i> parameter.<br /><br />
<a name="mode-owner-group"></a>
<h2>Controlling ownership and permissions</h2>
As well as controlling the naming of the device nodes which are created, udev rules also allow you to control ownership and permission attributes on that device node.<br /><br />
The <i>GROUP</i> key allows you to define which unix group should own the device node. Here's an example from the udev defaults, which defines that the <i>video</i> group will own framebuffer (fb) devices:
<blockquote><pre>KERNEL=="fb[0-9]*", NAME="fb/%n", SYMLINK="%k", GROUP="video"</pre></blockquote>
The <i>OWNER</i> key, perhaps less useful, allows you to define which unix user should own the device node. Assuming the slightly odd situation where you would want "john" to own your floppy devices, you could use:
<blockquote><pre>KERNEL=="fd[0-9]*", OWNER="john"</pre></blockquote>
You'll notice in the above rule that we didn't specify any <i>NAME</i> or <i>SYMLINK</i> keys. This is similar to the <a href="#multiple-symlink">multiple symlink style</a> where udev will take a mental note that we want john to own floppy nodes, and will apply that ownership once it finds a rule which defines a <i>NAME</i> for the floppy device nodes.<br /><br />
Building on the style mentioned above, you can do even more flashy things. The udev defaults use the following rule to define that all the sound device nodes shall be owned by the "audio" group:
<blockquote><pre>SUBSYSTEM=="sound", GROUP="audio"</pre></blockquote>
This prevents the need to excessively provide a <i>GROUP=="audio"</i> key on every following rule which names sound devices.<br /><br />
udev defaults to creating nodes with unix permissions of 0660 (read/write to owner and group). There may be some situations where you do not want to use the default permissions on your device node. Fortunately, you can easily override the permissions in your rules using the <i>MODE</i> assignment key. As an example, the following rule defines that the inotify node shall be readable and writable to everyone:
<blockquote><pre>KERNEL=="inotify", NAME="misc/%k", SYMLINK="%k", MODE="0666"</pre></blockquote>
<a name="example-printer"></a>
<h2>Example: Writing a rule for my USB printer</h2>
After plugging in my printer, I started looking around some /sys directories for a relevant place to start. I didn't get anywhere, but I noticed that my printer had been given device node <i>/dev/lp0</i>. udevinfo was able to provide me with a useful path:
<blockquote><pre>
# udevinfo -q path -n /dev/lp0
/class/usb/lp0
</pre></blockquote>
Running "udevinfo -a -p /sys/class/usb/lp0" provided me with a heap of info, as usual. I picked out the relevant bits for unique device identification:
<blockquote><pre>
looking at the device chain at '/sys/devices/pci0000:00/0000:00:02.1/usb3/3-3':
BUS=="usb"
SYSFS{manufacturer}=="EPSON"
SYSFS{product}=="USB Printer"
SYSFS{serial}=="L72010011070626380"
</pre></blockquote>
My udev rule becomes:
<blockquote><pre>BUS=="usb", SYSFS{serial}=="L72010011070626380", NAME="%k", SYMLINK="epson_680"</pre></blockquote>
And my printer nodes exist at <i>/dev/lp0</i> (or <i>/dev/lp1</i> if another printer was plugged in beforehand) and <i>/dev/epson_680</i> <b>always</b> points at the device node for that particular printer.<br /><br />
<a name="example-camera"></a>
<h2>Example: Writing a rule for my USB-Storage digital camera</h2>
<font size="2">Quick Intro: My camera identifies itself as an external SCSI hard disk (it uses the usb-storage driver which is also used by devices such as USB hard disks and flash-card readers). I can then mount the partition on that disk and copy images over. Not all cameras work like this - many require external software (e.g. gphoto2) to be able to access photos.</font><br /><br />
This one is a bit tricky. Several nodes are created by default when my camera is connected : <i>/dev/sda</i> and <i>/dev/sda1</i>, and possibly even <i>/dev/sg1</i>. <b>This is an example where specifity is important - if your rule is not specific enough, it could match any of the above 3 nodes.</b><br /><br />
sda1 is the node that I would like as my <i>/dev/camera</i>, as that is what gets mounted. udevinfo did not point out any useful differences between sda, sda1, and sg1. I decided that a reliable way to differentiate between these 3 nodes would be to look at the <i>KERNEL</i> name.<br /><br />
A key such as <i>KERNEL=="sd?1"</i> would match KERNEL names such as "sda1", "sdb1", "sdc1", and equally importantly, it will <b>not</b> match KERNEL names such as sda, sdb, or sg1. The purpose of this key is to ignore the <i>/dev/sda</i> and <i>/dev/sg1</i> nodes. The device is a digital camera - I would not dream of fdisking it or anything like that, so these 2 nodes are pretty useless to me. The key attempts to capture the <i>/dev/sda1</i> node, which is mountable and therefore useful!<br /><br />
As this node (sda1) is treated as a block device, looking in <i>/sys/block</i> would be a good place to start.<br /><br />
In my <i>/sys/block</i>, I have a directory named <i>sda</i>. In my <i>/sys/block/sda</i>, I have a directory named <i>sda1</i>. Both of these directories have <i>dev</i> files in, so they are OK to run <i>udevinfo</i> on. Running the following dumps a lot of information about my camera and the USB port it is connected through.
<blockquote><pre># udevinfo -a -p /sys/block/sda/sda1</pre></blockquote>
In the udevinfo output, I also noticed this bit of useful and understandable information:
<blockquote><pre>SYSFS{product}=="USB 2.0M DSC"</pre></blockquote>
So that gives me my rule. For completeness, I also include a BUS key (this was also found in the udevinfo output).
<blockquote><pre>BUS=="usb", SYSFS{product}=="USB 2.0M DSC", KERNEL=="sd?1", NAME="%k", SYMLINK="camera"</pre></blockquote>
Now, when my camera is plugged in, it will be named <i>/dev/sda1</i> (or, if sda1 isnt available, it might be called <i>/dev/sdb1</i>) and will <b>always</b> be correctly linked to from <i>/dev/camera</i>. The /dev/sda (or sdb) node still appears as normal, but the important thing is that my custom persistent "camera" symlink points to the mountable partition.<br /><br />
<a name="usbstorage-extra"></a>
<h2>Additional notes on writing rules for USB storage</h2>
<i>Carl Streeter</i>, the owner of a large USB hard disk, wrote to me and explained that unlike in my digital camera example, the <i>/dev/sda</i> node is useful to him. He pointed out that he does occasionally need to use tools such as <i>fdisk</i> and <i>hdparm</i> on that node.<br /><br />
Carl's rule is:
<blockquote><pre>BUS=="usb", KERNEL=="sd*", SYSFS{product}=="USB 2.0 Storage Device", NAME="%k", SYMLINK="usbhd%n"</pre></blockquote>
This rule creates symlinks such as:
<ul>
<li><i>/dev/usbhd</i> - The fdiskable node</li>
<li><i>/dev/usbhd1</i> - The first partition (mountable)</li>
<li><i>/dev/usbhd2</i> - The second partition (mountable)</li>
</ul>
We agreed that depending on the situation and device in question, there are reasons for both wanting and not wanting the non-mountable <i>/dev/sda</i> node. Use whichever setup suits you best.<br /><br />
Another difficult situation is having a multiple-slot USB-storage card reader. These types of device generally do not inform the host when new cards are plugged in or out, so plugging a card into an unused slot while the reader is plugged in will not create the extra device node needed for mounting!<br />
This problem also applies to other USB disks - e.g. if you create a new partition, the new partition node will not appear until you re-plug the device.<br /><br />
udev provides a solution here - it is able to create nodes for all partitions of a block device. For every rule that you specify, the block device will have all 16 partition nodes created. To achieve this, you can simply modify the NAME key, as shown below:<br />
<blockquote><pre>BUS=="usb", SYSFS{product}=="USB 2.0 Storage Device", NAME{all_partitions}="usbhd"</pre></blockquote>
You will now have nodes named: usbhd, usbhd1, usbhd2, usbhd3, ..., usbhd15.<br /><br />
<a name="example-cdrom"></a>
<h2>Example: Writing convenience rules for my CD drives</h2>
I have two CD drives in my PC - a DVD reader, and a CD rewriter. My DVD is hdc and my CDRW is hdd. I would not expect this to change, unless I manually changed the cabling of my system.<br /><br />
Still, some people (myself included) like to have nodes such as <i>/dev/dvd</i> and <i>/dev/cdrw</i> for convenience. Since we know the "hdX" values for these drives, writing rules is simple. The examples below should be self explanatory.
<blockquote><pre>
BUS=="ide", KERNEL=="hdc", NAME="%k", SYMLINK="dvd cdroms/cdrom%n"
BUS=="ide", KERNEL=="hdd", NAME="%k", SYMLINK="cdrw cdroms/cdrom%n"
</pre></blockquote>
<font size="2">You may have noticed that the default 50-udev.rules file contains a rule which runs a script to produces names for block devices. Do not be confused by this - as usual, because your own rules are located in a file which is processed <b>before</b> the default rules, the defaults will not be used when naming the hardware you have written rules for.</font><br /><br />
<a href="example-pilot"></a>
<h2>Example: Writing a rule for your USB Visor Palm Pilot</h2>
These devices work as USB-serial devices, so by default, you only get the <i>ttyUSB1</i> node. The user-space palm utilities rely on <i>/dev/pilot</i>, so you need to use a rule to create this. The following rule will do the job:<br /><br />
<blockquote><pre>BUS=="usb", SYSFS{product}=="Palm Handheld", KERNEL=="ttyUSB*", SYMLINK="pilot"</pre></blockquote>
This was adapted from <a href="http://www.clasohm.com/blog/one-entry?entry%5fid=12096">Carsten Clasohm's blog entry</a>, which includes a useful discussion of the situation. You may also wish to add <a href="#mode-owner-group">ownership and permission keys</a> to the rule to suit your setup.<br /><br />
<a name="example-iface"></a>
<h2>Example: Writing a rule to name my network interface</h2>
An interesting new feature in recent udev versions is the ability to rename your network interfaces, like the <i>nameif</i> utility does. Network interfaces do not show up in <i>/dev</i>, but they are generally referenced by names (e.g. with <i>ifconfig</i>). Despite the differences, the rule writing process is almost identical.<br /><br />
As usual, udevinfo comes to our aid in rule-writing. In my example, I wish to rename my "eth0" network device (the following output is snipped):
<blockquote><pre>
# udevinfo -a -p /sys/class/net/eth0/
looking at class device '/sys/class/net/eth0':
SYSFS{address}=="00:52:8b:d5:04:48"
</pre></blockquote>
Every network adapter has its own unique MAC-address, so I chose to use this when writing my rule. This will not change, unless you change your network card. There is one caveat here: make sure you use the MAC address you obtain from udevinfo (as above), because it is case sensitive. Be careful when using utilities such as <i>ifconfig</i> as they will capitalize the letters.<br /><br />
An example rule is shown below:
<blockquote><pre>KERNEL=="eth*", SYSFS{address}=="00:52:8b:d5:04:48", NAME="lan"</pre></blockquote>
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.<br />
After that, you should be able to use "lan" instead of "eth0" in any calls to <i>ifconfig</i> or similar utilities.<br /><br />
<a name="tips"></a>
<h2>Tips for finding the appropriate places in SYSFS</h2>
<font size=2>I'm looking for some more device specific tips here. Please <a href="#author">contact me</a> with any you can provide.</font>
<ul>
<li>If the device you are looking to write rules for has created a device node under /dev, then you are in luck! Run the following command to get an appropriate /sys path: <i>udevinfo -q path -n /dev/yournode</i></li>
<li>Always use udevinfo to assist the rule-writing process. Always use udevinfo to look under /sys/block or /sys/class (it will not start reading a chain from anywhere else).</li>
<li>If you get totally stuck, use the following command to find all "dev" files under /sys (udevinfo can work on directories containing this file): find /sys -iname dev</li>
<li>If your device is a flash-card reader, usb flash-drive, or digital camera that acts as usb-storage, that is created as /dev/sdX, then start looking in /sys/block/sdX.</li>
<li>If applicable, make sure you identify the difference between sdX and sdX1 in the above situation. This can be done with the key <i>KERNEL="sd?1"</i> to match sdX1, or <i>KERNEL=="sd?"</i> to match sdX.</li>
<li>For USB printers that are created as /dev/lpX, then you should start looking in /sys/class/usb/lpX.</li>
<li>The usb scanner driver has recently been removed from the kernel and re-implemented in userspace (as part of the SANE package). You do not (and can not) write rules for this hardware as it does not rely on specific kernel drivers.</li>
<li>Remember that unfortunately, the kernel does not export information for all devices into sysfs, meaning that you simply can't write rules for some devices yet. On 20/02/04, the udev author stated that there are 162 drivers left to convert to sysfs.</li>
</ul>
<a name="debugging"></a>
<h2>Debugging your rules</h2>
If you have written rules and remembered to run <b>udevstart</b> but they do not appear to be taking effect, there are a couple of ways you can debug them.<br /><br />
The file <i>/etc/udev/udev.conf</i> contains a <b>udev_log</b> option. Setting this option to <i>yes</i> will cause udev to log some useful information about which rules are being applied to which nodes into the system logger. The logs will be included in /var/log/messages for most users.<br /><br />
Additionally, if you know the path in <i>sysfs</i> for the node you want to create, you can use <b>udevtest</b> to see a rundown on what udev would do with the node. For example:
<blockquote><pre># udevtest /sys/class/sound/dsp/
version 056
looking at '/class/sound/dsp/'
opened class_dev->name='dsp'
configured rule in '/etc/udev/rules.d/50-udev.rules[132]' applied, added symlink '%k'
configured rule in '/etc/udev/rules.d/50-udev.rules[132]' applied, 'dsp' becomes 'sound/%k'
creating device node '/dev/sound/dsp', major = '14', minor = '3', mode = '0660', uid = '0', gid = '18'</blockquote></pre>
<b>udevtest</b> is only a debugging/testing tool - it does not actually create the device node, even though it says it doing so!<br /><br />
<a name="author"></a>
<h2>Author and Credits</h2>
This document is written by Daniel Drake <<a href="mailto:dan@reactivated.net">dan@reactivated.net</a>><br />
Please do not hesitate to send feedback!<br /><br />
Copyright (C) 2003-2005 Daniel Drake<br />
This document is licensed under the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public License, Version 2</a>.
</body>
</html>
|
