/[gentoo]/xml/htdocs/doc/en/udev-guide.xml
Gentoo

Contents of /xml/htdocs/doc/en/udev-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.50 - (show annotations) (download) (as text)
Wed Aug 5 15:44:08 2009 UTC (8 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.49: +5 -5 lines
File MIME type: application/xml
Updated the rest of our guides for the modules.d-modprobe.d switch, bug 223885

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.49 2009/01/26 09:28:37 nightmorph Exp $ -->
4
5 <guide link="/doc/en/udev-guide.xml">
6 <title>Gentoo udev Guide</title>
7
8 <author title="Author">
9 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
10 </author>
11 <author title="Contributor">
12 <mail link="greg_g@gentoo.org">Gregorio Guidi</mail>
13 </author>
14 <author title="Editor">
15 <mail link="nightmorph"/>
16 </author>
17
18 <abstract>
19 This document explains what udev is and how you can use udev to fit your needs.
20 </abstract>
21
22 <!-- The content of this document is licensed under the CC-BY-SA license -->
23 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
24 <license/>
25
26 <version>5</version>
27 <date>2009-08-05</date>
28
29 <chapter>
30 <title>What is udev?</title>
31 <section>
32 <title>The /dev Directory</title>
33 <body>
34
35 <p>
36 When Linux-users talk about the hardware on their system in the vicinity of
37 people who believe Linux is some sort of virus or brand of coffee, the use of
38 "slash dev slash foo" will return a strange look for sure. But for the fortunate
39 user (and that includes you) using <path>/dev/hda1</path> is just a fast way of
40 explaining that we are talking about the primary master IDE, first partition. Or
41 aren't we?
42 </p>
43
44 <p>
45 We all know what a device file is. Some even know why device files have special
46 numbers when we take a closer look at them when we issue <c>ls -l</c> in
47 <path>/dev</path>. But what we always take for granted is that the primary
48 master IDE disk is referred to as <path>/dev/hda</path>. You might not see it
49 this way, but this is a flaw by design.
50 </p>
51
52 <p>
53 Think about hotpluggable devices like USB, IEEE1394, hot-swappable PCI, ... What
54 is the first device? And for how long? What will the other devices be named when
55 the first one disappears? How will that affect ongoing transactions? Wouldn't it
56 be fun that a printing job is suddenly moved from your supernew laserprinter to
57 your almost-dead matrix printer because your mom decided to pull the plug of the
58 laserprinter which happened to be the first printer?
59 </p>
60
61 <p>
62 Enter <e>udev</e>. The goals of the udev project are both interesting and
63 needed:
64 </p>
65
66 <ul>
67 <li>Runs in userspace</li>
68 <li>Dynamically creates/removes device files</li>
69 <li>Provides consistent naming</li>
70 <li>Provides a user-space API</li>
71 </ul>
72
73 <p>
74 To provide these features, udev is developed in three separate projects:
75 <e>namedev</e>, <e>libsysfs</e> and, of course, <e>udev</e>.
76 </p>
77
78 </body>
79 </section>
80 <section>
81 <title>namedev</title>
82 <body>
83
84 <p>
85 Namedev allows you to define the device naming separately from the udev program.
86 This allows for flexible naming policies and naming schemes developed by
87 separate entities. This device naming subsystem provides a standard interface
88 that udev can use.
89 </p>
90
91 <p>
92 Currently only a single naming scheme is provided by namedev; the one provided
93 by LANANA, used by the majority of Linux systems currently and therefore very
94 suitable for the majority of Linux users.
95 </p>
96
97 <p>
98 Namedev uses a 5-step procedure to find out the name of a given device. If the
99 device name is found in one of the given steps, that name is used. The steps
100 are:
101 </p>
102
103 <ul>
104 <li>label or serial number</li>
105 <li>bus device number</li>
106 <li>bus topology</li>
107 <li>statically given name</li>
108 <li>kernel provided name</li>
109 </ul>
110
111 <p>
112 The <e>label or serial number</e> step checks if the device has a unique
113 identifier. For instance USB devices have a unique USB serial number; SCSI
114 devices have a unique UUID. If namedev finds a match between this unique number
115 and a given configuration file, the name provided in the configuration file is
116 used.
117 </p>
118
119 <p>
120 The <e>bus device number</e> step checks the device bus number. For
121 non-hot-swappable environments this procedure is sufficient to
122 identify a hardware device. For instance PCI bus numbers rarely change in the
123 lifetime of a system. Again, if namedev finds a match between this position and
124 a given configuration file, the name provided in that configuration file is
125 used.
126 </p>
127
128 <p>
129 Likewise the <e>bus topology</e> is a rather static way of defining devices as
130 long as the user doesn't switch devices. When the position of the device matches
131 a given setting provided by the user, the accompanying name is used.
132 </p>
133
134 <p>
135 The fourth step, <e>statically given name</e>, is a simple string replacement.
136 When the kernel name (the default name) matches a given replacement string, the
137 substitute name will be used.
138 </p>
139
140 <p>
141 The final step (<e>kernel provided name</e>) is a catch-all: this one takes
142 the default name provided by the kernel. In the majority of cases this is
143 sufficient as it matches the device naming used on current Linux systems.
144 </p>
145
146 </body>
147 </section>
148 <section>
149 <title>libsysfs</title>
150 <body>
151
152 <p>
153 udev interacts with the kernel through the sysfs pseudo filesystem. The libsysfs
154 project provides a common API to access the information given by the sysfs
155 filesystem in a generic way. This allows for querying all kinds of hardware
156 without having to make assumptions on the kind of hardware.
157 </p>
158
159 </body>
160 </section>
161 <section>
162 <title>udev</title>
163 <body>
164
165 <p>
166 Every time the kernel gets an event in the device structure, it asks udev to
167 take a look. udev follows the rules in the <path>/etc/udev/rules.d/</path>
168 directory. udev then uses the information given by the kernel to perform the
169 necessary actions on the <path>/dev</path> structure (creating or deleting
170 device files).
171 </p>
172
173 </body>
174 </section>
175 </chapter>
176
177 <chapter>
178 <title>Using udev on Gentoo</title>
179 <section>
180 <title>Requirements</title>
181 <body>
182
183 <p>
184 udev is meant to be used in combination with a 2.6 kernel (like
185 <c>gentoo-sources</c> with the default 2007.0 profile). If you're using such a
186 kernel then you just have to make sure that you have a recent
187 <c>sys-apps/baselayout</c> version. That's all you need.
188 </p>
189
190 <pre caption="Installing udev">
191 # <i>emerge udev</i>
192 </pre>
193
194 <p>
195 Kernelwise, be sure to activate the following options:
196 </p>
197
198 <pre caption="Required kernel options">
199 General setup ---&gt;
200 [*] Support for hot-pluggable devices
201
202 File systems ---&gt;
203 [*] Inotify file change notification support
204 [*] Inotify support for userspace
205 Pseudo filesystems ---&gt;
206 [*] /proc file system support
207 [*] Virtual memory file system support (former shm fs)
208 </pre>
209
210 <p>
211 If you use <c>genkernel</c>, you don't need to do anything special. Genkernel
212 sets up udev by default.
213 </p>
214
215 </body>
216 </section>
217 <section>
218 <title>Configuration</title>
219 <body>
220
221 <p>
222 If you want to use the udev settings Gentoo provides to make your life
223 comfortable, then read no more. Gentoo will use udev but keep a static
224 <path>/dev</path> so that you will never have any missing device nodes.
225 The Gentoo init scripts won't run the devfsd daemon and will deactivate devfs
226 when you boot up.
227 </p>
228
229 <p>
230 But if you are a die-hard and want to run a udev-only, unmodified system as is
231 intended by the udev development (including the difficulties of missing device
232 nodes because udev doesn't support them yet), by all means, read on :)
233 </p>
234
235 <p>
236 We'll deactivate the rules that save the device file nodes: edit the
237 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
238 <c>no</c>:
239 </p>
240
241 <pre caption="/etc/conf.d/rc">
242 RC_DEVICE_TARBALL="no"
243 </pre>
244
245 <p>
246 If you have included devfs support in your kernel, you can deactivate it in
247 the bootloader configuration: add <c>gentoo=nodevfs</c> as a kernel parameter.
248 If you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
249 parameter.
250 </p>
251
252 </body>
253 </section>
254 </chapter>
255
256 <chapter>
257 <title>Known Issues</title>
258 <section>
259 <title>Missing device node files at boot</title>
260 <body>
261
262 <p>
263 If you can't boot successfully because you get an error about
264 <path>/dev/null</path> not found, or because the initial console is missing, the
265 problem is that you lack some device files that must be available <e>before</e>
266 <path>/dev</path> is mounted and handled by udev. This is common on Gentoo
267 machines installed from old media.
268 </p>
269
270 <p>
271 If you run <c>sys-apps/baselayout-1.8.12</c> or later, this problem is
272 alleviated since the boot process should still manage to complete. However, to
273 get rid of those annoying warnings, you should create the missing device nodes
274 as described below.
275 </p>
276
277 <p>
278 To see which devices nodes are present before the <path>/dev</path> filesystem
279 is mounted, run the following commands:
280 </p>
281
282 <pre caption="Listing device nodes available at boot">
283 # <i>mkdir test</i>
284 # <i>mount --bind / test</i>
285 # <i>cd test/dev</i>
286 # <i>ls</i>
287 </pre>
288
289 <p>
290 The devices needed for a successful boot are <path>/dev/null</path> and
291 <path>/dev/console</path>. If they didn't show up in the previous test, you have
292 to create them manually. Issue the following commands in the
293 <path>test/dev/</path> directory:
294 </p>
295
296 <pre caption="Creating necessary device node files">
297 # <i>mknod -m 660 console c 5 1</i>
298 # <i>mknod -m 660 null c 1 3</i>
299 </pre>
300
301 <p>
302 When you're finished, don't forget to unmount the <path>test/</path> directory:
303 </p>
304
305 <pre caption="Unmounting the test/ directory">
306 # <i>cd ../..</i>
307 # <i>umount test</i>
308 # <i>rmdir test</i>
309 </pre>
310
311 </body>
312 </section>
313 <section>
314 <title>udev and nvidia</title>
315 <body>
316
317 <p>
318 If you use the proprietary driver from nVidia and the X server fails to start on
319 a udev-only system, then make sure you have:
320 </p>
321
322 <ul>
323 <li>
324 the <c>nvidia</c> module listed in
325 <path>/etc/modules.autoload.d/kernel-2.6</path>
326 </li>
327 <li>
328 a version of baselayout equal to or greater than
329 <c>sys-apps/baselayout-1.8.12</c>
330 </li>
331 </ul>
332
333 </body>
334 </section>
335 <section>
336 <title>No Consistent Naming between DevFS and udev</title>
337 <body>
338
339 <p>
340 Even though our intention is to have a consistent naming scheme between both
341 dynamical device management solutions, sometimes naming differences do occur.
342 </p>
343
344 <p>
345 One reported clash is with a HP Smart Array 5i RAID controller (more precisely
346 the <c>cciss</c> kernel module). With udev, the devices are named
347 <path>/dev/cciss/cXdYpZ</path> with X, Y and Z regular numbers. With devfs, the
348 devices are <path>/dev/hostX/targetY/partZ</path> or symlinked from
349 <path>/dev/cciss/cXdY</path>.
350 </p>
351
352 <p>
353 If this is the case, don't forget to update your <path>/etc/fstab</path> and
354 bootloader configuration files accordingly.
355 </p>
356
357 <p>
358 The same happens with all-round symlinks that used to exist in
359 <path>/dev</path>, such as <path>/dev/mouse</path>, which <c>udev</c> doesn't
360 create anymore. Be certain to check your X configuration file and see if the
361 Device rule for your mouse points to an existing device file.
362 </p>
363
364 <p>
365 Another issue is the difference in naming of terminals between devfs and udev.
366 While devfs calls its terminals <c>tty</c>, udev calls them <c>vc</c> and
367 <c>tty</c>. This could lead to a problem in case you are restricting root
368 logins from consoles using <path>/etc/securetty</path>. You will need to make
369 sure that both <c>tty1</c> and <c>vc/1</c> are listed in
370 <path>/etc/securetty</path> to ensure that root can login using the console.
371 </p>
372
373 </body>
374 </section>
375 <section>
376 <title>Block device renaming</title>
377 <body>
378
379 <p>
380 Recent versions of udev (104 and up) along with newer kernel versions (2.6.19
381 and up) may change your disc device names, due to a change in the kernel's
382 libata implementation. A CD-RW device at <path>/dev/hdc</path> may be changed to
383 <path>/dev/sr0</path>. While this is not normally a problem, it may cause issues
384 for some applications that are hardcoded to look for devices at other locations.
385 For example, <c>media-sound/rip</c> expects to find discs at
386 <path>/dev/cdrom</path>, which becomes a problem if you use a newer kernel and
387 udev renames your device to <path>/dev/cdrom1</path>.
388 </p>
389
390 <p>
391 To work around these issues, you must edit
392 <path>/etc/udev/rules.d/70-persistent-cd.rules</path> and assign the correct
393 name to the device.
394 </p>
395
396 <p>
397 For more information on writing udev rules, be sure to read Daniel Drake's <uri
398 link="http://www.reactivated.net/udevrules.php">guide</uri>.
399 </p>
400
401 </body>
402 </section>
403 <section>
404 <title>Network device renaming</title>
405 <body>
406
407 <p>
408 Sometimes unplugging and replugging a network device (like a USB WiFi card) can
409 rename your net device each time, incrementing the number by one.
410 </p>
411
412 <p>
413 When this happens, you'll see it become <c>wlan0</c>, <c>wlan1</c>,
414 <c>wlan2</c>, etc. This is because udev is adding additional rules to its rules
415 file, instead of reloading the existing rules. Since udev watches its rules
416 directory via inotify, you need inotify support in your kernel config:
417 </p>
418
419 <pre caption="Enabling inotify support in the kernel">
420 File systems ---&gt;
421 [*] Inotify file change notification support
422 [*] Inotify support for userspace
423 </pre>
424
425 <p>
426 Now udev will retain proper names for your network devices.
427 </p>
428
429 </body>
430 </section>
431 <section>
432 <title>udev loads modules in an unpredictable order</title>
433 <body>
434
435 <p>
436 Sometimes udev loads modules in an undesired, unpredictable, or seemingly random
437 order. This is especially common for systems that have multiple devices of the
438 same type, as well as multimedia devices. This can affect the assigned numbers
439 of devices; for example, sound cards may sometimes swap numbers.
440 </p>
441
442 <p>
443 There are a few solutions to fix device numbers and/or module load order.
444 Ideally, you can just use module parameters to specify your desired device
445 number. Some modules, such as ALSA, include the "index" parameter. Modules that
446 use the index parameter can be adjusted as shown. This example is for a system
447 with two sound cards. The card with an index of 0 is designated as the first
448 card. Once the parameters are changed, the module config files must be updated.
449 </p>
450
451 <pre caption="Specifying module parameters">
452 # <i>echo "option snd-ice1724 index=0" >> /etc/modprobe.d/alsa.conf</i>
453 # <i>echo "option snd-ymfpci index=1" >> /etc/modprobe.d/alsa.conf</i>
454 # <i>update-modules</i>
455 </pre>
456
457 <p>
458 The above example is the preferred solution, but not all modules support
459 parameters such as index. For these modules, you'll have to force the correct
460 module load order. First, you must stop udev from autoloading the modules by
461 blacklisting them. Be sure to use the exact name of the module being loaded.
462 For PCI devices, you'll need to use the module names obtained from the output of
463 <c>pcimodules</c>, available in the <c>pciutils</c> package. The following
464 example uses DVB modules.
465 </p>
466
467 <pre caption="Blacklisting modules">
468 # <i>echo "blacklist b2c2-flexcop-pci" >> /etc/modprobe.d/dvb</i>
469 # <i>echo "blacklist budget" >> /etc/modprobe.d/dvb</i>
470 # <i>update-modules</i>
471 </pre>
472
473 <p>
474 Next, load the modules in the correct order. Add them to
475 <path>/etc/modules.autoload.d/kernel-2.6</path> <e>in the exact order you want
476 them loaded</e>.
477 </p>
478
479 <pre caption="Loading modules in the correct order">
480 # <i>echo "budget" >> /etc/modules.autoload.d/kernel-2.6</i>
481 # <i>echo "b2c2-flexcop-pci" >> /etc/modules.autoload.d/kernel-2.6</i>
482 </pre>
483
484 </body>
485 </section>
486 <section>
487 <title>Other issues</title>
488 <body>
489
490 <p>
491 If device nodes are not created when a module is loaded from
492 <path>/etc/modules.autoload.d/kernel-2.6</path> but they appear when you load
493 the module manually with modprobe then you should try upgrading to
494 <c>sys-apps/baselayout-1.8.12</c> or later.
495 </p>
496
497 <p>
498 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
499 kernel starting from version 2.6.6-rc2.
500 </p>
501
502 <p>
503 For kernels older than 2.6.4 you have to explicitly include support for the
504 <path>/dev/pts</path> filesystem.
505 </p>
506
507 <pre caption="Enabling the /dev/pts filesystem">
508 File systems ---&gt;
509 Pseudo filesystems ---&gt;
510 [*] /dev/pts file system for Unix98 PTYs
511 </pre>
512
513 </body>
514 </section>
515 </chapter>
516
517 <chapter>
518 <title>Resources &amp; Acknowledgements</title>
519 <section>
520 <body>
521
522 <p>
523 The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
524 Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
525 application.
526 </p>
527
528 <p>
529 <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
530 UDEV Primer</uri> is an in-depth document about udev and Gentoo.
531 </p>
532
533 <p>
534 <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
535 fellow Gentoo developer Daniel Drake is an excellent document to learn how to
536 customize your udev installation.
537 </p>
538
539 </body>
540 </section>
541 </chapter>
542 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20