]>
Commit | Line | Data |
---|---|---|
7b86ada7 KS |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
4 | ||
5 | <article> | |
6 | <articleinfo> | |
7 | <title>xmlto</title> | |
8 | <author> | |
9 | <firstname>Kay</firstname> | |
10 | <surname>Sievers</surname> | |
11 | <email>kay.sievers@vrfy.org</email> | |
12 | </author> | |
13 | <copyright> | |
c1979c82 | 14 | <year>2006</year> |
7b86ada7 KS |
15 | <holder>Kay Sievers</holder> |
16 | </copyright> | |
17 | </articleinfo> | |
18 | ||
19 | <section> | |
20 | <title>udev</title> | |
21 | <refentry> | |
22 | <refentryinfo> | |
23 | <title>udev</title> | |
24 | <date>August 2005</date> | |
25 | <productname>udev</productname> | |
26 | </refentryinfo> | |
27 | ||
28 | <refmeta> | |
29 | <refentrytitle>udev</refentrytitle> | |
2c769419 | 30 | <manvolnum>7</manvolnum> |
7b86ada7 KS |
31 | </refmeta> |
32 | ||
33 | <refnamediv> | |
34 | <refname>udev</refname> | |
35 | <refpurpose>dynamic device management</refpurpose> | |
36 | </refnamediv> | |
37 | ||
38 | <refsect1><title>DESCRIPTION</title> | |
39 | <para>udev provides a dynamic device directory containing only the files for | |
40 | actually present devices. It creates or removes device node files in the | |
41 | <filename>/dev</filename> directory, or it renames network interfaces.</para> | |
42 | ||
43 | <para>Usually udev runs as <citerefentry><refentrytitle>udevd</refentrytitle> | |
44 | <manvolnum>8</manvolnum></citerefentry> and receives uevents directly from the | |
c082b99a | 45 | kernel if a device is added or removed form the system.</para> |
7b86ada7 KS |
46 | |
47 | <para>If udev receives a device event, it matches its configured rules | |
48 | against the available device attributes provided in sysfs to identify the device. | |
49 | Rules that match, may provide additional device information or specify a device | |
50 | node name and multiple symlink names and instruct udev to run additional programs | |
51 | as part of the device event handling.</para> | |
52 | </refsect1> | |
53 | ||
54 | <refsect1><title>CONFIGURATION</title> | |
55 | <para>All udev configuration files are placed in <filename>/etc/udev/*</filename>. | |
309d6fd3 | 56 | Every file consists of a set of lines of text. All empty lines or lines beginning |
7b86ada7 KS |
57 | with '#' will be ignored.</para> |
58 | ||
59 | <refsect2><title>Configuration file</title> | |
60 | <para>udev expects its main configuration file at <filename>/etc/udev/udev.conf</filename>. | |
61 | It consists of a set of variables allowing the user to override default udev values. | |
62 | The following variables can be set:</para> | |
63 | <variablelist> | |
64 | <varlistentry> | |
65 | <term><option>udev_root</option></term> | |
66 | <listitem> | |
67 | <para>Specifies where to place the device nodes in the filesystem. | |
68 | The default value is <filename>/dev</filename>.</para> | |
69 | </listitem> | |
70 | </varlistentry> | |
71 | ||
7b86ada7 KS |
72 | <varlistentry> |
73 | <term><option>udev_rules</option></term> | |
74 | <listitem> | |
75 | <para>The name of the udev rules file or directory to look for files | |
76 | with the suffix <filename>.rules</filename>. Multiple rule files are | |
77 | read in lexical order. The default value is | |
78 | <filename>/etc/udev/rules.d</filename>.</para> | |
79 | </listitem> | |
80 | </varlistentry> | |
81 | ||
82 | <varlistentry> | |
83 | <term><option>udev_log</option></term> | |
84 | <listitem> | |
85 | <para>The logging priority. Valid values are the numerical syslog priorities | |
86 | or their textual representations: <option>err</option>, <option>info</option> | |
87 | and <option>debug</option>.</para> | |
88 | </listitem> | |
89 | </varlistentry> | |
90 | </variablelist> | |
91 | </refsect2> | |
92 | ||
93 | <refsect2><title>Rules files</title> | |
94 | <para>The udev rules are read from the files located in the | |
95 | <filename>/etc/udev/rules.d</filename> directory or at the location specified | |
96 | value in the configuraton file. Every line in the rules file contains at least | |
97 | one key value pair. There are two kind of keys, match and assignement keys. | |
98 | If all match keys are matching against its value, the rule gets applied and the | |
99 | assign keys get the specified value assigned. A matching rule may specify the | |
100 | name of the device node, add a symlink pointing to the node, or run a specified | |
101 | program as part of the event handling. If no matching rule is found, the default | |
102 | device node name is used.</para> | |
103 | ||
104 | <para>A rule may consists of a list of one or more key value pairs separated by | |
105 | a comma. Each key has a distinct operation, depending on the used operator. Valid | |
106 | operators are:</para> | |
107 | <variablelist> | |
108 | <varlistentry> | |
109 | <term><option>==</option></term> | |
110 | <listitem> | |
111 | <para>Compare for equality.</para> | |
112 | </listitem> | |
113 | </varlistentry> | |
114 | ||
115 | <varlistentry> | |
116 | <term><option>!=</option></term> | |
117 | <listitem> | |
118 | <para>Compare for non-equality.</para> | |
119 | </listitem> | |
120 | </varlistentry> | |
121 | ||
122 | <varlistentry> | |
123 | <term><option>=</option></term> | |
124 | <listitem> | |
125 | <para>Asign a value to a key. Keys that represent a list, are reset | |
126 | and only this single value is assigned.</para> | |
127 | </listitem> | |
128 | </varlistentry> | |
129 | ||
130 | <varlistentry> | |
131 | <term><option>+=</option></term> | |
132 | <listitem> | |
133 | <para>Add the value to a key that holds a list of entries.</para> | |
134 | </listitem> | |
135 | </varlistentry> | |
136 | ||
137 | <varlistentry> | |
138 | <term><option>:=</option></term> | |
139 | <listitem> | |
140 | <para>Assign a value to a key finally; disallow any later changes, | |
141 | which may be used to prevent changes by any later rules.</para> | |
142 | </listitem> | |
143 | </varlistentry> | |
144 | </variablelist> | |
145 | ||
146 | <para>The following key names can be used to match against device properties:</para> | |
147 | <variablelist> | |
148 | <varlistentry> | |
149 | <term><option>ACTION</option></term> | |
150 | <listitem> | |
03b24b71 | 151 | <para>Match the name of the event action.</para> |
7b86ada7 KS |
152 | </listitem> |
153 | </varlistentry> | |
154 | ||
155 | <varlistentry> | |
156 | <term><option>KERNEL</option></term> | |
157 | <listitem> | |
03b24b71 | 158 | <para>Match the name of the device.</para> |
7b86ada7 KS |
159 | </listitem> |
160 | </varlistentry> | |
161 | ||
162 | <varlistentry> | |
163 | <term><option>DEVPATH</option></term> | |
164 | <listitem> | |
03b24b71 | 165 | <para>Match the devpath of the device.</para> |
7b86ada7 KS |
166 | </listitem> |
167 | </varlistentry> | |
168 | ||
169 | <varlistentry> | |
170 | <term><option>SUBSYSTEM</option></term> | |
171 | <listitem> | |
03b24b71 | 172 | <para>Match the subsystem of the device.</para> |
7b86ada7 KS |
173 | </listitem> |
174 | </varlistentry> | |
175 | ||
176 | <varlistentry> | |
177 | <term><option>BUS</option></term> | |
178 | <listitem> | |
03b24b71 | 179 | <para>Search the devpath upwards for a matching device subsystem name.</para> |
7b86ada7 KS |
180 | </listitem> |
181 | </varlistentry> | |
182 | ||
183 | <varlistentry> | |
184 | <term><option>DRIVER</option></term> | |
185 | <listitem> | |
03b24b71 | 186 | <para>Search the devpath upwards for a matching device driver name.</para> |
7b86ada7 KS |
187 | </listitem> |
188 | </varlistentry> | |
189 | ||
190 | <varlistentry> | |
191 | <term><option>ID</option></term> | |
192 | <listitem> | |
03b24b71 | 193 | <para>Search the devpath upwards for a matching device name.</para> |
7b86ada7 KS |
194 | </listitem> |
195 | </varlistentry> | |
196 | ||
197 | <varlistentry> | |
03b24b71 | 198 | <term><option>SYSFS{<replaceable>filename</replaceable>}</option></term> |
7b86ada7 | 199 | <listitem> |
03b24b71 KS |
200 | <para>Search the devpath upwards for a device with matching sysfs attribute values. |
201 | Up to five <option>SYSFS</option> keys can be specified per rule. All attributes | |
202 | must match on the same device. Trailing whitespace in the attribute values is ignored, | |
203 | if the specified match value does not contain trailing whitespace itself.</para> | |
7b86ada7 KS |
204 | </listitem> |
205 | </varlistentry> | |
206 | ||
207 | <varlistentry> | |
03b24b71 | 208 | <term><option>ENV{<replaceable>key</replaceable>}</option></term> |
7b86ada7 | 209 | <listitem> |
03b24b71 KS |
210 | <para>Match against the value of an environment variable. Up to five <option>ENV</option> |
211 | keys can be specified per rule. This key can also be used to export a variable to | |
212 | the environment.</para> | |
7b86ada7 KS |
213 | </listitem> |
214 | </varlistentry> | |
215 | ||
216 | <varlistentry> | |
217 | <term><option>PROGRAM</option></term> | |
218 | <listitem> | |
219 | <para>Execute external program. The key is true, if the program returns | |
220 | without exit code zero. The whole event environment is available to the | |
221 | executed program. The program's output printed to stdout is available for | |
222 | the RESULT key.</para> | |
223 | </listitem> | |
224 | </varlistentry> | |
225 | ||
226 | <varlistentry> | |
227 | <term><option>RESULT</option></term> | |
228 | <listitem> | |
229 | <para>Match the returned string of the last PROGRAM call. This key can | |
230 | be used in the same or in any later rule after a PROGRAM call.</para> | |
231 | </listitem> | |
232 | </varlistentry> | |
233 | </variablelist> | |
234 | ||
235 | <para>Most of the fields support a shell style pattern matching. The following | |
236 | pattern characters are supported:</para> | |
237 | <variablelist> | |
238 | <varlistentry> | |
239 | <term><option>*</option></term> | |
240 | <listitem> | |
241 | <para>Matches zero, or any number of characters.</para> | |
242 | </listitem> | |
243 | </varlistentry> | |
244 | <varlistentry> | |
245 | <term><option>?</option></term> | |
246 | <listitem> | |
247 | <para>Matches any single character.</para> | |
248 | </listitem> | |
249 | </varlistentry> | |
250 | <varlistentry> | |
251 | <term><option>[]</option></term> | |
252 | <listitem> | |
253 | <para>Matches any single character specified within the brackets. | |
254 | example, the pattern string 'tty[SR]' would match either 'ttyS' or 'ttyR'. | |
255 | Ranges are also supported within this match with the '-' character. | |
256 | For example, to match on the range of all digits, the pattern [0-9] would | |
257 | be used. If the first character following the '[' is a '!', any characters | |
258 | not enclosed are matched.</para> | |
259 | </listitem> | |
260 | </varlistentry> | |
261 | </variablelist> | |
262 | ||
263 | <para>The following keys can get values assigned:</para> | |
264 | <variablelist> | |
265 | <varlistentry> | |
266 | <term><option>NAME</option></term> | |
267 | <listitem> | |
fabd8709 KS |
268 | <para>The name of the node to be created, or the name the network interface |
269 | should be renamed to. Only one rule can set the node name, all later rules with | |
7b86ada7 KS |
270 | a NAME key will be ignored.</para> |
271 | </listitem> | |
272 | </varlistentry> | |
273 | ||
274 | <varlistentry> | |
275 | <term><option>SYMLINK</option></term> | |
276 | <listitem> | |
277 | <para>The name of a symlink targeting the node. Every matching rule can add | |
278 | this value to the list of symlinks to be created along with the device node. | |
279 | Multiple symlinks may be specified by separating the names by the space | |
280 | character.</para> | |
281 | </listitem> | |
282 | </varlistentry> | |
283 | ||
284 | <varlistentry> | |
285 | <term><option>OWNER, GROUP, MODE</option></term> | |
286 | <listitem> | |
fabd8709 | 287 | <para>The permissions for the device node. Every specified value overwrites |
7b86ada7 KS |
288 | the compiled-in default value.</para> |
289 | </listitem> | |
290 | </varlistentry> | |
291 | ||
292 | <varlistentry> | |
293 | <term><option>ENV{<replaceable>key</replaceable>}</option></term> | |
294 | <listitem> | |
03b24b71 KS |
295 | <para>Export a variable to the environment. This key can also be used to match |
296 | against an environment variable.</para> | |
7b86ada7 KS |
297 | </listitem> |
298 | </varlistentry> | |
299 | ||
300 | <varlistentry> | |
301 | <term><option>RUN</option></term> | |
302 | <listitem> | |
303 | <para>Add a program to the list of programs to be executed for a specific | |
304 | device.</para> | |
305 | </listitem> | |
306 | </varlistentry> | |
307 | ||
308 | <varlistentry> | |
309 | <term><option>LABEL</option></term> | |
310 | <listitem> | |
311 | <para>Named label where a GOTO can jump to.</para> | |
312 | </listitem> | |
313 | </varlistentry> | |
314 | ||
315 | <varlistentry> | |
316 | <term><option>GOTO</option></term> | |
317 | <listitem> | |
a2a7f7d7 | 318 | <para>Jumps to the next LABEL with a matching name</para> |
7b86ada7 KS |
319 | </listitem> |
320 | </varlistentry> | |
321 | ||
322 | <varlistentry> | |
323 | <term><option>IMPORT{<replaceable>type</replaceable>}</option></term> | |
324 | <listitem> | |
03b24b71 | 325 | <para>Import the printed result or the value of a file in environment key |
7b86ada7 KS |
326 | format into the event environment. <option>program</option> will execute an |
327 | external program and read its output. <option>file</option> will inport a | |
328 | text file. If no option is given, udev will determine it from the executable | |
329 | bit of of the file permissions.</para> | |
330 | </listitem> | |
331 | </varlistentry> | |
332 | ||
333 | <varlistentry> | |
334 | <term><option>WAIT_FOR_SYSFS</option></term> | |
335 | <listitem> | |
03b24b71 KS |
336 | <para>Wait for the specified sysfs file of the device to be created. Can be used |
337 | to fight against kernel sysfs timing issues.</para> | |
7b86ada7 KS |
338 | </listitem> |
339 | </varlistentry> | |
340 | ||
341 | <varlistentry> | |
342 | <term><option>OPTIONS</option></term> | |
343 | <listitem> | |
344 | <para><option>last_rule</option> stops further rules application. No later rules | |
345 | will have any effect. | |
346 | <option>ignore_device</option> will ignore this event completely. | |
347 | <option>ignore_remove</option> will ignore any later remove event for this | |
348 | device. This may be useful as a workaround for broken device drivers. | |
349 | <option>all_partitions</option> will create device nodes for all available partitions of | |
350 | a block device. This may be useful for removable media.</para> | |
351 | </listitem> | |
352 | </varlistentry> | |
353 | </variablelist> | |
354 | ||
355 | <para>The <option>NAME</option>, <option>SYMLINK</option>, <option>PROGRAM</option>, | |
864412e0 AB |
356 | <option>OWNER</option>, <option>GROUP</option> and <option>RUN</option> |
357 | fields support simple printf-like string substitutions. The <option>RUN</option> | |
358 | format chars gets applied after all rules have been processed, right before the program | |
359 | is executed. It allows the use of the complete environment set by earlier matching | |
360 | rules. For all other fields, substitutions are applied while the individual rule is | |
361 | being processed. The available substitutions are:</para> | |
7b86ada7 KS |
362 | <variablelist> |
363 | <varlistentry> | |
03b24b71 | 364 | <term><option>$kernel</option>, <option>%k</option></term> |
7b86ada7 KS |
365 | <listitem> |
366 | <para>The kernel name for this device.</para> | |
367 | </listitem> | |
368 | </varlistentry> | |
369 | ||
7b86ada7 | 370 | <varlistentry> |
03b24b71 | 371 | <term><option>$number</option>, <option>%n</option></term> |
7b86ada7 KS |
372 | <listitem> |
373 | <para>The kernel number for this device. For example, 'sda3' has | |
374 | kernel number of '3'</para> | |
375 | </listitem> | |
376 | </varlistentry> | |
377 | ||
378 | <varlistentry> | |
03b24b71 | 379 | <term><option>$devpath</option>, <option>%p</option></term> |
7b86ada7 KS |
380 | <listitem> |
381 | <para>The devpath of the device.</para> | |
382 | </listitem> | |
383 | </varlistentry> | |
384 | ||
385 | <varlistentry> | |
03b24b71 KS |
386 | <term><option>$id</option>, <option>%b</option></term> |
387 | <listitem> | |
388 | <para>The name of the device matched while searching the devpath upwards for | |
389 | <option>BUS</option>, <option>ID</option> <option>DRIVER</option> and <option>SYSFS</option>. | |
390 | </para> | |
391 | </listitem> | |
392 | </varlistentry> | |
393 | ||
394 | <varlistentry> | |
395 | <term><option>$sysfs{<replaceable>file</replaceable>}</option>, <option>%s{<replaceable>file</replaceable>}</option></term> | |
7b86ada7 | 396 | <listitem> |
03b24b71 | 397 | <para>The value of a sysfs attribute found at the current or a parent device.</para> |
7b86ada7 KS |
398 | </listitem> |
399 | </varlistentry> | |
400 | ||
401 | <varlistentry> | |
03b24b71 | 402 | <term><option>$env{<replaceable>key</replaceable>}</option>, <option>%E{<replaceable>key</replaceable>}</option></term> |
7b86ada7 KS |
403 | <listitem> |
404 | <para>The value of an environment variable.</para> | |
405 | </listitem> | |
406 | </varlistentry> | |
407 | ||
408 | <varlistentry> | |
03b24b71 | 409 | <term><option>$major</option>, <option>%M</option></term> |
7b86ada7 KS |
410 | <listitem> |
411 | <para>The kernel major number for the device.</para> | |
412 | </listitem> | |
413 | </varlistentry> | |
414 | ||
415 | <varlistentry> | |
03b24b71 | 416 | <term><option>$minor</option> <option>%m</option></term> |
7b86ada7 KS |
417 | <listitem> |
418 | <para>The kernel minor number for the device.</para> | |
419 | </listitem> | |
420 | </varlistentry> | |
421 | ||
422 | <varlistentry> | |
03b24b71 | 423 | <term><option>$result</option>, <option>%c</option></term> |
7b86ada7 KS |
424 | <listitem> |
425 | <para>The string returned by the external program requested with PROGRAM. | |
426 | A single part of the string, separated by a space character may be selected | |
427 | by specifying the part number as an attribute: <option>%c{N}</option>. | |
428 | If the number is followed by the '+' char this part plus all remaining parts | |
429 | of the result string are substituted: <option>%c{N+}</option></para> | |
430 | </listitem> | |
431 | </varlistentry> | |
432 | ||
7b86ada7 | 433 | <varlistentry> |
03b24b71 | 434 | <term><option>$parent</option>, <option>%P</option></term> |
7b86ada7 KS |
435 | <listitem> |
436 | <para>The node name of the parent device.</para> | |
437 | </listitem> | |
438 | </varlistentry> | |
439 | ||
440 | <varlistentry> | |
03b24b71 | 441 | <term><option>$root</option>, <option>%r</option></term> |
7b86ada7 KS |
442 | <listitem> |
443 | <para>The udev_root value.</para> | |
444 | </listitem> | |
445 | </varlistentry> | |
446 | ||
447 | <varlistentry> | |
03b24b71 | 448 | <term><option>$tempnode</option>, <option>%N</option></term> |
7b86ada7 KS |
449 | <listitem> |
450 | <para>The name of a created temporary device node to provide access to | |
451 | the device from a external program before the real node is created.</para> | |
452 | </listitem> | |
453 | </varlistentry> | |
454 | ||
455 | <varlistentry> | |
456 | <term><option>%%</option></term> | |
457 | <listitem> | |
458 | <para>The '%' character itself.</para> | |
459 | </listitem> | |
460 | </varlistentry> | |
461 | ||
462 | <varlistentry> | |
463 | <term><option>$$</option></term> | |
464 | <listitem> | |
465 | <para>The '$' character itself.</para> | |
466 | </listitem> | |
467 | </varlistentry> | |
468 | </variablelist> | |
469 | <para>The count of characters to be substituted may be limited by specifying | |
470 | the format length value. For example, '%3s{file}' will only | |
471 | insert the first three characters of the sysfs attribute</para> | |
472 | </refsect2> | |
473 | </refsect1> | |
474 | ||
475 | <refsect1><title>ENVIRONMENT</title> | |
476 | <variablelist> | |
477 | <varlistentry> | |
478 | <term><option>ACTION</option></term> | |
479 | <listitem> | |
480 | <para><replaceable>add</replaceable> or <replaceable>remove</replaceable> signifies | |
481 | the addition or the removal of a device.</para> | |
482 | </listitem> | |
483 | </varlistentry> | |
484 | ||
485 | <varlistentry> | |
486 | <term><option>DEVPATH</option></term> | |
487 | <listitem> | |
488 | <para>The sysfs devpath without the mountpoint but a leading slash.</para> | |
489 | </listitem> | |
490 | </varlistentry> | |
491 | ||
492 | <varlistentry> | |
493 | <term><option>SUBSYSTEM</option></term> | |
494 | <listitem> | |
495 | <para>The kernel subsystem the device belongs to.</para> | |
496 | </listitem> | |
497 | </varlistentry> | |
498 | ||
499 | <varlistentry> | |
500 | <term><option>UDEV_LOG</option></term> | |
501 | <listitem> | |
502 | <para>Overrides the syslog priority specified in the config file.</para> | |
503 | </listitem> | |
504 | </varlistentry> | |
505 | </variablelist> | |
506 | </refsect1> | |
507 | ||
508 | <refsect1><title>AUTHOR</title> | |
509 | <para>Written by Greg Kroah-Hartman <email>greg@kroah.com</email> and | |
510 | Kay Sievers <email>kay.sievers@vrfy.org</email>. With much help from | |
511 | Dan Stekloff <email>dsteklof@us.ibm.com</email> and many others.</para> | |
512 | </refsect1> | |
513 | ||
514 | <refsect1> | |
515 | <title>SEE ALSO</title> | |
516 | <para><citerefentry> | |
2c769419 | 517 | <refentrytitle>udevd</refentrytitle><manvolnum>8</manvolnum> |
7b86ada7 KS |
518 | </citerefentry>, |
519 | <citerefentry> | |
520 | <refentrytitle>udevinfo</refentrytitle><manvolnum>8</manvolnum> | |
521 | </citerefentry>, | |
7b86ada7 KS |
522 | <citerefentry> |
523 | <refentrytitle>udevmonitor</refentrytitle><manvolnum>8</manvolnum> | |
524 | </citerefentry></para> | |
525 | </refsect1> | |
526 | </refentry> | |
527 | </section> | |
528 | </article> |