/[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.51 - (hide annotations) (download) (as text)
Fri May 14 22:37:43 2010 UTC (7 years, 5 months ago) by nightmorph
Branch: MAIN
Changes since 1.50: +4 -7 lines
File MIME type: application/xml
Remove unnecessary bit about enabling hot-pluggable device support. This is already enabled by default in modern kernels, since the option 'configure standard kernel features for small systems' is deselected by default, meaning everything under it is already activated. This includes hot-pluggable device support. bug 308453

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 nightmorph 1.51 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.50 2009/08/05 15:44:08 nightmorph Exp $ -->
4 neysx 1.4
5 nightmorph 1.51 <guide>
6 swift 1.1 <title>Gentoo udev Guide</title>
7    
8     <author title="Author">
9 nightmorph 1.34 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
10 swift 1.8 </author>
11     <author title="Contributor">
12 neysx 1.24 <mail link="greg_g@gentoo.org">Gregorio Guidi</mail>
13 swift 1.1 </author>
14 nightmorph 1.44 <author title="Editor">
15     <mail link="nightmorph"/>
16     </author>
17 swift 1.1
18     <abstract>
19     This document explains what udev is and how you can use udev to fit your needs.
20     </abstract>
21    
22 nightmorph 1.43 <!-- The content of this document is licensed under the CC-BY-SA license -->
23     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
24 swift 1.1 <license/>
25    
26 nightmorph 1.51 <version>6</version>
27     <date>2010-05-14</date>
28 swift 1.1
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 swift 1.3 people who believe Linux is some sort of virus or brand of coffee, the use of
38 swift 1.1 "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 swift 1.3 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 swift 1.1 the first one disappears? How will that affect ongoing transactions? Wouldn't it
56 swift 1.45 be fun that a printing job is suddenly moved from your supernew laserprinter to
57 swift 1.1 your almost-dead matrix printer because your mom decided to pull the plug of the
58 swift 1.20 laserprinter which happened to be the first printer?
59 swift 1.1 </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 swift 1.3 <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 swift 1.1 </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 swift 1.3 by LANANA, used by the majority of Linux systems currently and therefore very
94 swift 1.1 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 swift 1.45 The <e>bus device number</e> step checks the device bus number. For
121 swift 1.1 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 swift 1.3 a given setting provided by the user, the accompanying name is used.
132 swift 1.1 </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 swift 1.45 substitute name will be used.
138 swift 1.1 </p>
139    
140     <p>
141 swift 1.45 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 swift 1.1 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 nightmorph 1.39 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 swift 1.1 </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 swift 1.8 udev is meant to be used in combination with a 2.6 kernel (like
185 nightmorph 1.39 <c>gentoo-sources</c> with the default 2007.0 profile). If you're using such a
186 nightmorph 1.37 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 swift 1.1 </p>
189    
190 swift 1.8 <pre caption="Installing udev">
191     # <i>emerge udev</i>
192 swift 1.1 </pre>
193    
194     <p>
195 swift 1.21 Kernelwise, be sure to activate the following options:
196 swift 1.1 </p>
197    
198     <pre caption="Required kernel options">
199     File systems ---&gt;
200 nightmorph 1.49 [*] Inotify file change notification support
201     [*] Inotify support for userspace
202 swift 1.1 Pseudo filesystems ---&gt;
203     [*] /proc file system support
204     [*] Virtual memory file system support (former shm fs)
205     </pre>
206    
207     <p>
208 nightmorph 1.48 If you use <c>genkernel</c>, you don't need to do anything special. Genkernel
209     sets up udev by default.
210 swift 1.21 </p>
211    
212 swift 1.1 </body>
213     </section>
214     <section>
215     <title>Configuration</title>
216     <body>
217    
218     <p>
219 swift 1.47 If you want to use the udev settings Gentoo provides to make your life
220 swift 1.15 comfortable, then read no more. Gentoo will use udev but keep a static
221     <path>/dev</path> so that you will never have any missing device nodes.
222 swift 1.45 The Gentoo init scripts won't run the devfsd daemon and will deactivate devfs
223     when you boot up.
224 swift 1.1 </p>
225    
226     <p>
227 swift 1.47 But if you are a die-hard and want to run a udev-only, unmodified system as is
228 swift 1.2 intended by the udev development (including the difficulties of missing device
229     nodes because udev doesn't support them yet), by all means, read on :)
230 swift 1.1 </p>
231    
232     <p>
233 swift 1.45 We'll deactivate the rules that save the device file nodes: edit the
234 swift 1.2 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
235     <c>no</c>:
236     </p>
237 swift 1.1
238 swift 1.2 <pre caption="/etc/conf.d/rc">
239     RC_DEVICE_TARBALL="no"
240 swift 1.1 </pre>
241    
242     <p>
243 swift 1.8 If you have included devfs support in your kernel, you can deactivate it in
244 swift 1.45 the bootloader configuration: add <c>gentoo=nodevfs</c> as a kernel parameter.
245 swift 1.14 If you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
246 swift 1.8 parameter.
247     </p>
248    
249     </body>
250     </section>
251     </chapter>
252    
253     <chapter>
254     <title>Known Issues</title>
255     <section>
256     <title>Missing device node files at boot</title>
257     <body>
258    
259     <p>
260 neysx 1.9 If you can't boot successfully because you get an error about
261 swift 1.8 <path>/dev/null</path> not found, or because the initial console is missing, the
262     problem is that you lack some device files that must be available <e>before</e>
263     <path>/dev</path> is mounted and handled by udev. This is common on Gentoo
264     machines installed from old media.
265     </p>
266    
267     <p>
268     If you run <c>sys-apps/baselayout-1.8.12</c> or later, this problem is
269     alleviated since the boot process should still manage to complete. However, to
270 swift 1.10 get rid of those annoying warnings, you should create the missing device nodes
271 swift 1.8 as described below.
272     </p>
273    
274     <p>
275     To see which devices nodes are present before the <path>/dev</path> filesystem
276     is mounted, run the following commands:
277     </p>
278    
279     <pre caption="Listing device nodes available at boot">
280     # <i>mkdir test</i>
281     # <i>mount --bind / test</i>
282     # <i>cd test/dev</i>
283     # <i>ls</i>
284     </pre>
285    
286     <p>
287 neysx 1.9 The devices needed for a successful boot are <path>/dev/null</path> and
288 swift 1.8 <path>/dev/console</path>. If they didn't show up in the previous test, you have
289 cam 1.12 to create them manually. Issue the following commands in the
290     <path>test/dev/</path> directory:
291 swift 1.1 </p>
292    
293     <pre caption="Creating necessary device node files">
294 cam 1.11 # <i>mknod -m 660 console c 5 1</i>
295     # <i>mknod -m 660 null c 1 3</i>
296 swift 1.1 </pre>
297    
298     <p>
299 swift 1.8 When you're finished, don't forget to unmount the <path>test/</path> directory:
300 swift 1.1 </p>
301    
302 swift 1.8 <pre caption="Unmounting the test/ directory">
303 cam 1.11 # <i>cd ../..</i>
304 swift 1.8 # <i>umount test</i>
305 cam 1.11 # <i>rmdir test</i>
306 swift 1.8 </pre>
307    
308     </body>
309     </section>
310     <section>
311     <title>udev and nvidia</title>
312     <body>
313    
314 swift 1.1 <p>
315 swift 1.8 If you use the proprietary driver from nVidia and the X server fails to start on
316     a udev-only system, then make sure you have:
317 swift 1.1 </p>
318    
319 swift 1.8 <ul>
320     <li>
321     the <c>nvidia</c> module listed in
322     <path>/etc/modules.autoload.d/kernel-2.6</path>
323     </li>
324     <li>
325     a version of baselayout equal to or greater than
326     <c>sys-apps/baselayout-1.8.12</c>
327     </li>
328     </ul>
329    
330 swift 1.1 </body>
331     </section>
332     <section>
333 swift 1.18 <title>No Consistent Naming between DevFS and udev</title>
334     <body>
335    
336     <p>
337 swift 1.45 Even though our intention is to have a consistent naming scheme between both
338 swift 1.18 dynamical device management solutions, sometimes naming differences do occur.
339 swift 1.22 </p>
340    
341     <p>
342 swift 1.18 One reported clash is with a HP Smart Array 5i RAID controller (more precisely
343     the <c>cciss</c> kernel module). With udev, the devices are named
344     <path>/dev/cciss/cXdYpZ</path> with X, Y and Z regular numbers. With devfs, the
345     devices are <path>/dev/hostX/targetY/partZ</path> or symlinked from
346     <path>/dev/cciss/cXdY</path>.
347     </p>
348    
349     <p>
350     If this is the case, don't forget to update your <path>/etc/fstab</path> and
351     bootloader configuration files accordingly.
352     </p>
353    
354 swift 1.22 <p>
355     The same happens with all-round symlinks that used to exist in
356     <path>/dev</path>, such as <path>/dev/mouse</path>, which <c>udev</c> doesn't
357     create anymore. Be certain to check your X configuration file and see if the
358 swift 1.23 Device rule for your mouse points to an existing device file.
359 swift 1.22 </p>
360    
361 fox2mike 1.29 <p>
362     Another issue is the difference in naming of terminals between devfs and udev.
363 nightmorph 1.31 While devfs calls its terminals <c>tty</c>, udev calls them <c>vc</c> and
364     <c>tty</c>. This could lead to a problem in case you are restricting root
365     logins from consoles using <path>/etc/securetty</path>. You will need to make
366     sure that both <c>tty1</c> and <c>vc/1</c> are listed in
367     <path>/etc/securetty</path> to ensure that root can login using the console.
368 fox2mike 1.29 </p>
369    
370 swift 1.18 </body>
371     </section>
372     <section>
373 nightmorph 1.49 <title>Block device renaming</title>
374 nightmorph 1.41 <body>
375    
376     <p>
377     Recent versions of udev (104 and up) along with newer kernel versions (2.6.19
378     and up) may change your disc device names, due to a change in the kernel's
379     libata implementation. A CD-RW device at <path>/dev/hdc</path> may be changed to
380     <path>/dev/sr0</path>. While this is not normally a problem, it may cause issues
381     for some applications that are hardcoded to look for devices at other locations.
382     For example, <c>media-sound/rip</c> expects to find discs at
383     <path>/dev/cdrom</path>, which becomes a problem if you use a newer kernel and
384     udev renames your device to <path>/dev/cdrom1</path>.
385     </p>
386    
387     <p>
388     To work around these issues, you must edit
389     <path>/etc/udev/rules.d/70-persistent-cd.rules</path> and assign the correct
390     name to the device.
391     </p>
392    
393     <p>
394     For more information on writing udev rules, be sure to read Daniel Drake's <uri
395     link="http://www.reactivated.net/udevrules.php">guide</uri>.
396     </p>
397    
398     </body>
399     </section>
400     <section>
401 nightmorph 1.49 <title>Network device renaming</title>
402     <body>
403    
404     <p>
405     Sometimes unplugging and replugging a network device (like a USB WiFi card) can
406     rename your net device each time, incrementing the number by one.
407     </p>
408    
409     <p>
410     When this happens, you'll see it become <c>wlan0</c>, <c>wlan1</c>,
411     <c>wlan2</c>, etc. This is because udev is adding additional rules to its rules
412     file, instead of reloading the existing rules. Since udev watches its rules
413     directory via inotify, you need inotify support in your kernel config:
414     </p>
415    
416     <pre caption="Enabling inotify support in the kernel">
417     File systems ---&gt;
418     [*] Inotify file change notification support
419     [*] Inotify support for userspace
420     </pre>
421    
422     <p>
423     Now udev will retain proper names for your network devices.
424     </p>
425    
426     </body>
427     </section>
428     <section>
429 nightmorph 1.44 <title>udev loads modules in an unpredictable order</title>
430     <body>
431    
432     <p>
433     Sometimes udev loads modules in an undesired, unpredictable, or seemingly random
434     order. This is especially common for systems that have multiple devices of the
435     same type, as well as multimedia devices. This can affect the assigned numbers
436     of devices; for example, sound cards may sometimes swap numbers.
437     </p>
438    
439     <p>
440     There are a few solutions to fix device numbers and/or module load order.
441     Ideally, you can just use module parameters to specify your desired device
442     number. Some modules, such as ALSA, include the "index" parameter. Modules that
443     use the index parameter can be adjusted as shown. This example is for a system
444     with two sound cards. The card with an index of 0 is designated as the first
445     card. Once the parameters are changed, the module config files must be updated.
446     </p>
447    
448     <pre caption="Specifying module parameters">
449 nightmorph 1.50 # <i>echo "option snd-ice1724 index=0" >> /etc/modprobe.d/alsa.conf</i>
450     # <i>echo "option snd-ymfpci index=1" >> /etc/modprobe.d/alsa.conf</i>
451 nightmorph 1.44 # <i>update-modules</i>
452     </pre>
453    
454     <p>
455     The above example is the preferred solution, but not all modules support
456     parameters such as index. For these modules, you'll have to force the correct
457     module load order. First, you must stop udev from autoloading the modules by
458     blacklisting them. Be sure to use the exact name of the module being loaded.
459     For PCI devices, you'll need to use the module names obtained from the output of
460     <c>pcimodules</c>, available in the <c>pciutils</c> package. The following
461     example uses DVB modules.
462     </p>
463    
464     <pre caption="Blacklisting modules">
465 nightmorph 1.46 # <i>echo "blacklist b2c2-flexcop-pci" >> /etc/modprobe.d/dvb</i>
466     # <i>echo "blacklist budget" >> /etc/modprobe.d/dvb</i>
467 nightmorph 1.44 # <i>update-modules</i>
468     </pre>
469    
470     <p>
471     Next, load the modules in the correct order. Add them to
472     <path>/etc/modules.autoload.d/kernel-2.6</path> <e>in the exact order you want
473     them loaded</e>.
474     </p>
475    
476     <pre caption="Loading modules in the correct order">
477     # <i>echo "budget" >> /etc/modules.autoload.d/kernel-2.6</i>
478     # <i>echo "b2c2-flexcop-pci" >> /etc/modules.autoload.d/kernel-2.6</i>
479     </pre>
480    
481     </body>
482     </section>
483     <section>
484 swift 1.8 <title>Other issues</title>
485 swift 1.1 <body>
486    
487 swift 1.8 <p>
488     If device nodes are not created when a module is loaded from
489     <path>/etc/modules.autoload.d/kernel-2.6</path> but they appear when you load
490     the module manually with modprobe then you should try upgrading to
491     <c>sys-apps/baselayout-1.8.12</c> or later.
492     </p>
493 swift 1.7
494     <p>
495 swift 1.8 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
496     kernel starting from version 2.6.6-rc2.
497 swift 1.7 </p>
498    
499     <p>
500 swift 1.8 For kernels older than 2.6.4 you have to explicitly include support for the
501     <path>/dev/pts</path> filesystem.
502 swift 1.1 </p>
503    
504 swift 1.8 <pre caption="Enabling the /dev/pts filesystem">
505     File systems ---&gt;
506     Pseudo filesystems ---&gt;
507     [*] /dev/pts file system for Unix98 PTYs
508     </pre>
509    
510 swift 1.1 </body>
511     </section>
512     </chapter>
513    
514     <chapter>
515     <title>Resources &amp; Acknowledgements</title>
516     <section>
517     <body>
518    
519     <p>
520     The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
521     Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
522     application.
523     </p>
524    
525     <p>
526 swift 1.45 <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
527 swift 1.1 UDEV Primer</uri> is an in-depth document about udev and Gentoo.
528     </p>
529    
530 swift 1.8 <p>
531     <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
532     fellow Gentoo developer Daniel Drake is an excellent document to learn how to
533     customize your udev installation.
534     </p>
535    
536 swift 1.1 </body>
537     </section>
538     </chapter>
539     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20