/[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.29 - (hide annotations) (download) (as text)
Sat Mar 25 07:19:00 2006 UTC (12 years ago) by fox2mike
Branch: MAIN
Changes since 1.28: +12 -3 lines
File MIME type: application/xml
Fixes to close bug #105729

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 neysx 1.4
4 fox2mike 1.29 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.28 2006/01/05 20:08:16 swift Exp $ -->
5 neysx 1.4
6 swift 1.1 <guide link="/doc/en/udev-guide.xml">
7     <title>Gentoo udev Guide</title>
8    
9     <author title="Author">
10 swift 1.8 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
11     </author>
12     <author title="Contributor">
13 neysx 1.24 <mail link="greg_g@gentoo.org">Gregorio Guidi</mail>
14 swift 1.1 </author>
15    
16     <abstract>
17     This document explains what udev is and how you can use udev to fit your needs.
18     </abstract>
19    
20     <license/>
21    
22 fox2mike 1.29 <version>0.23</version>
23     <date>2006-03-25</date>
24 swift 1.1
25     <chapter>
26     <title>What is udev?</title>
27     <section>
28     <title>The /dev Directory</title>
29     <body>
30    
31     <p>
32     When Linux-users talk about the hardware on their system in the vicinity of
33 swift 1.3 people who believe Linux is some sort of virus or brand of coffee, the use of
34 swift 1.1 "slash dev slash foo" will return a strange look for sure. But for the fortunate
35     user (and that includes you) using <path>/dev/hda1</path> is just a fast way of
36     explaining that we are talking about the primary master IDE, first partition. Or
37     aren't we?
38     </p>
39    
40     <p>
41     We all know what a device file is. Some even know why device files have special
42     numbers when we take a closer look at them when we issue <c>ls -l</c> in
43     <path>/dev</path>. But what we always take for granted is that the primary
44     master IDE disk is referred to as <path>/dev/hda</path>. You might not see it
45     this way, but this is a flaw by design.
46     </p>
47    
48     <p>
49 swift 1.3 Think about hotpluggable devices like USB, IEEE1394, hot-swappable PCI, ... What
50     is the first device? And for how long? What will the other devices be named when
51 swift 1.1 the first one disappears? How will that affect ongoing transactions? Wouldn't it
52 swift 1.3 be fun that a printing job is suddenly moved from your supernew laserprinter to
53 swift 1.1 your almost-dead matrix printer because your mom decided to pull the plug of the
54 swift 1.20 laserprinter which happened to be the first printer?
55 swift 1.1 </p>
56    
57     <p>
58     Enter <e>udev</e>. The goals of the udev project are both interesting and
59     needed:
60     </p>
61    
62     <ul>
63 swift 1.3 <li>Runs in userspace</li>
64     <li>Dynamically creates/removes device files</li>
65     <li>Provides consistent naming</li>
66     <li>Provides a user-space API</li>
67 swift 1.1 </ul>
68    
69     <p>
70     To provide these features, udev is developed in three separate projects:
71     <e>namedev</e>, <e>libsysfs</e> and, of course, <e>udev</e>.
72     </p>
73    
74     </body>
75     </section>
76     <section>
77     <title>namedev</title>
78     <body>
79    
80     <p>
81     Namedev allows you to define the device naming separately from the udev program.
82     This allows for flexible naming policies and naming schemes developed by
83     separate entities. This device naming subsystem provides a standard interface
84     that udev can use.
85     </p>
86    
87     <p>
88     Currently only a single naming scheme is provided by namedev; the one provided
89 swift 1.3 by LANANA, used by the majority of Linux systems currently and therefore very
90 swift 1.1 suitable for the majority of Linux users.
91     </p>
92    
93     <p>
94     Namedev uses a 5-step procedure to find out the name of a given device. If the
95     device name is found in one of the given steps, that name is used. The steps
96     are:
97     </p>
98    
99     <ul>
100     <li>label or serial number</li>
101     <li>bus device number</li>
102     <li>bus topology</li>
103     <li>statically given name</li>
104     <li>kernel provided name</li>
105     </ul>
106    
107     <p>
108     The <e>label or serial number</e> step checks if the device has a unique
109     identifier. For instance USB devices have a unique USB serial number; SCSI
110     devices have a unique UUID. If namedev finds a match between this unique number
111     and a given configuration file, the name provided in the configuration file is
112     used.
113     </p>
114    
115     <p>
116     The <e>bus device number</e> step checks the device bus number. For
117     non-hot-swappable environments this procedure is sufficient to
118     identify a hardware device. For instance PCI bus numbers rarely change in the
119     lifetime of a system. Again, if namedev finds a match between this position and
120     a given configuration file, the name provided in that configuration file is
121     used.
122     </p>
123    
124     <p>
125     Likewise the <e>bus topology</e> is a rather static way of defining devices as
126     long as the user doesn't switch devices. When the position of the device matches
127 swift 1.3 a given setting provided by the user, the accompanying name is used.
128 swift 1.1 </p>
129    
130     <p>
131     The fourth step, <e>statically given name</e>, is a simple string replacement.
132     When the kernel name (the default name) matches a given replacement string, the
133     substitute name will be used.
134     </p>
135    
136     <p>
137     The final step (<e>kernel provided name</e>) is a catch-all: this one takes
138     the default name provided by the kernel. In the majority of cases this is
139     sufficient as it matches the device naming used on current Linux systems.
140     </p>
141    
142     </body>
143     </section>
144     <section>
145     <title>libsysfs</title>
146     <body>
147    
148     <p>
149     udev interacts with the kernel through the sysfs pseudo filesystem. The libsysfs
150     project provides a common API to access the information given by the sysfs
151     filesystem in a generic way. This allows for querying all kinds of hardware
152     without having to make assumptions on the kind of hardware.
153     </p>
154    
155     </body>
156     </section>
157     <section>
158     <title>udev</title>
159     <body>
160    
161     <p>
162     Every time the kernel notices an update in the device structure, it calls the
163     <path>/sbin/hotplug</path> program. Hotplug runs the applications linked in the
164     <path>/etc/hotplug.d/default</path> directory where you will also find a symlink
165     to the udev application. Hotplug directs the information given by the kernel to
166     the udev application which performs the necessary actions on the
167     <path>/dev</path> structure (creating or deleting device files).
168     </p>
169    
170     </body>
171     </section>
172     </chapter>
173    
174     <chapter>
175     <title>Using udev on Gentoo</title>
176     <section>
177     <title>Requirements</title>
178     <body>
179    
180     <p>
181 swift 1.8 udev is meant to be used in combination with a 2.6 kernel (like
182 swift 1.25 <c>vanilla-sources</c> or <c>gentoo-sources</c> with the default 2005.0
183     profile). If you're using such a kernel then you just have to make sure that
184     you have a recent <c>sys-apps/baselayout</c> version. That's all you need.
185 swift 1.1 </p>
186    
187 swift 1.8 <pre caption="Installing udev">
188     # <i>emerge udev</i>
189 swift 1.1 </pre>
190    
191     <p>
192 swift 1.19 udev will install <c>hotplug-base</c> as one of it's dependencies.
193     You do not need to install <c>hotplug</c> unless you want your modules
194     automatically loaded when you plug devices in. <c>hotplug</c> also handles the
195     automated bringup of network devices and firmware downloading.
196 swift 1.1 </p>
197    
198 swift 1.8 <pre caption="Installing optional hotplug scripts">
199     # <i>emerge hotplug</i>
200 swift 1.1 </pre>
201    
202     <p>
203 swift 1.19 If you want modules loaded for devices that have been plugged in before you
204     boot, use the coldplug package:
205     </p>
206    
207     <pre caption="Installing the coldplug package">
208     # <i>emerge coldplug</i>
209     </pre>
210    
211     <p>
212 swift 1.26 Don't forget to add <c>coldplug</c> to the boot runlevel:
213     </p>
214    
215     <pre caption="Adding coldplug to the boot runlevel">
216     # <i>rc-update add coldplug boot</i>
217     </pre>
218    
219     <p>
220 swift 1.21 Kernelwise, be sure to activate the following options:
221 swift 1.1 </p>
222    
223     <pre caption="Required kernel options">
224 swift 1.6 General setup ---&gt;
225 swift 1.1 [*] Support for hot-pluggable devices
226    
227     File systems ---&gt;
228     Pseudo filesystems ---&gt;
229     [*] /proc file system support
230     [*] Virtual memory file system support (former shm fs)
231     </pre>
232    
233     <p>
234     You can leave the <c>/dev file system support (OBSOLETE)</c> active if you
235 swift 1.16 wish but you have to make sure that "Automatically mount at boot" is disabled:
236 swift 1.1 </p>
237    
238 swift 1.16 <pre caption="Don't automatically mount devfsd">
239     File systems ---&gt;
240     Pseudo Filesystems ---&gt;
241     [*] /dev file system support (OBSOLETE)
242     [ ] Automatically mount at boot
243     </pre>
244    
245 swift 1.21 <p>
246     If you use <c>genkernel</c>, don't forget to run it with the <c>--udev</c>
247     option to enable all the required kernel configuration directives. The default
248     configuration given by this <c>genkernel</c> invocation is sufficient.
249     </p>
250    
251 swift 1.1 </body>
252     </section>
253     <section>
254     <title>Configuration</title>
255     <body>
256    
257     <p>
258 neysx 1.5 If you want to use the udev-tweaks Gentoo added to make your life
259 swift 1.15 comfortable, then read no more. Gentoo will use udev but keep a static
260     <path>/dev</path> so that you will never have any missing device nodes.
261     The Gentoo init scripts won't run the devfsd daemon and will deactivate devfs
262     when you boot up.
263 swift 1.1 </p>
264    
265     <p>
266     But if you are a die-hard and want to run a udev-only, no-tweaked system as is
267 swift 1.2 intended by the udev development (including the difficulties of missing device
268     nodes because udev doesn't support them yet), by all means, read on :)
269 swift 1.1 </p>
270    
271     <p>
272 bennyc 1.13 We'll deactivate the rules that save the device file nodes: edit the
273 swift 1.2 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
274     <c>no</c>:
275     </p>
276 swift 1.1
277 swift 1.2 <pre caption="/etc/conf.d/rc">
278     RC_DEVICE_TARBALL="no"
279 swift 1.1 </pre>
280    
281     <p>
282 swift 1.8 If you have included devfs support in your kernel, you can deactivate it in
283 swift 1.14 the bootloader configuration: add <c>gentoo=nodevfs</c> as a kernel parameter.
284     If you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
285 swift 1.8 parameter.
286     </p>
287    
288     </body>
289     </section>
290     </chapter>
291    
292     <chapter>
293     <title>Known Issues</title>
294     <section>
295     <title>Missing device node files at boot</title>
296     <body>
297    
298     <p>
299 neysx 1.9 If you can't boot successfully because you get an error about
300 swift 1.8 <path>/dev/null</path> not found, or because the initial console is missing, the
301     problem is that you lack some device files that must be available <e>before</e>
302     <path>/dev</path> is mounted and handled by udev. This is common on Gentoo
303     machines installed from old media.
304     </p>
305    
306     <p>
307     If you run <c>sys-apps/baselayout-1.8.12</c> or later, this problem is
308     alleviated since the boot process should still manage to complete. However, to
309 swift 1.10 get rid of those annoying warnings, you should create the missing device nodes
310 swift 1.8 as described below.
311     </p>
312    
313     <p>
314     To see which devices nodes are present before the <path>/dev</path> filesystem
315     is mounted, run the following commands:
316     </p>
317    
318     <pre caption="Listing device nodes available at boot">
319     # <i>mkdir test</i>
320     # <i>mount --bind / test</i>
321     # <i>cd test/dev</i>
322     # <i>ls</i>
323     </pre>
324    
325     <p>
326 neysx 1.9 The devices needed for a successful boot are <path>/dev/null</path> and
327 swift 1.8 <path>/dev/console</path>. If they didn't show up in the previous test, you have
328 cam 1.12 to create them manually. Issue the following commands in the
329     <path>test/dev/</path> directory:
330 swift 1.1 </p>
331    
332     <pre caption="Creating necessary device node files">
333 cam 1.11 # <i>mknod -m 660 console c 5 1</i>
334     # <i>mknod -m 660 null c 1 3</i>
335 swift 1.1 </pre>
336    
337     <p>
338 swift 1.8 When you're finished, don't forget to unmount the <path>test/</path> directory:
339 swift 1.1 </p>
340    
341 swift 1.8 <pre caption="Unmounting the test/ directory">
342 cam 1.11 # <i>cd ../..</i>
343 swift 1.8 # <i>umount test</i>
344 cam 1.11 # <i>rmdir test</i>
345 swift 1.8 </pre>
346    
347     </body>
348     </section>
349     <section>
350     <title>udev and nvidia</title>
351     <body>
352    
353 swift 1.1 <p>
354 swift 1.8 If you use the proprietary driver from nVidia and the X server fails to start on
355     a udev-only system, then make sure you have:
356 swift 1.1 </p>
357    
358 swift 1.8 <ul>
359     <li>
360     the <c>nvidia</c> module listed in
361     <path>/etc/modules.autoload.d/kernel-2.6</path>
362     </li>
363     <li>
364 swift 1.10 a version of <c>nvidia-kernel</c> equal to or greater than
365 swift 1.8 <c>media-video/nvidia-kernel-1.0.5336-r2</c>
366     </li>
367     <li>
368     a version of baselayout equal to or greater than
369     <c>sys-apps/baselayout-1.8.12</c>
370     </li>
371     </ul>
372    
373 swift 1.28 <p>
374     If <c>xorg-x11</c> refuses to start, it might be because the
375     <path>/dev/nvidia</path> device file is missing. If that is the case, run
376     <path>/sbin/NVmakedevices.sh</path> to (re)create it.
377     </p>
378    
379 swift 1.1 </body>
380     </section>
381     <section>
382 swift 1.17 <title>LVM2 Names Disappear</title>
383     <body>
384    
385     <p>
386     When you use <c>udev</c> and LVM2 together, you might notice that your created
387     volume groups and logical volumes have disappeared. Well, they haven't, but they
388     are unfortunately named <path>/dev/dm-#</path> with # being 0, 1, ...
389     </p>
390    
391     <p>
392     To fix this, edit <path>/etc/udev/rules.d/50-udev.rules</path> and uncomment the
393     following line:
394     </p>
395    
396     <pre caption="Uncomment this line from /etc/udev/rules.d/50-udev.rules">
397     KERNEL="dm-[0-9]*", PROGRAM="/sbin/devmap_name %M %m", NAME="%k", SYMLINK="%c"
398     </pre>
399    
400 swift 1.27 <p>
401     Next, install <c>sys-fs/multipath-tools</c> which contains the
402     <c>devmap_name</c> application.
403     </p>
404    
405     <pre caption="Installing multipath-tools">
406     <comment>(At the moment of writing, multipath-tools is only available in the testing branch:)</comment>
407     # <i>echo "=sys-fs/multipath-tools-0.4.2 ~x86" &gt;&gt; /etc/portage/package.keywords</i>
408     # <i>emerge multipath-tools</i>
409     </pre>
410    
411 swift 1.17 </body>
412     </section>
413     <section>
414 swift 1.18 <title>No Consistent Naming between DevFS and udev</title>
415     <body>
416    
417     <p>
418     Even though our intention is to have a consistent naming scheme between both
419     dynamical device management solutions, sometimes naming differences do occur.
420 swift 1.22 </p>
421    
422     <p>
423 swift 1.18 One reported clash is with a HP Smart Array 5i RAID controller (more precisely
424     the <c>cciss</c> kernel module). With udev, the devices are named
425     <path>/dev/cciss/cXdYpZ</path> with X, Y and Z regular numbers. With devfs, the
426     devices are <path>/dev/hostX/targetY/partZ</path> or symlinked from
427     <path>/dev/cciss/cXdY</path>.
428     </p>
429    
430     <p>
431     If this is the case, don't forget to update your <path>/etc/fstab</path> and
432     bootloader configuration files accordingly.
433     </p>
434    
435 swift 1.22 <p>
436     The same happens with all-round symlinks that used to exist in
437     <path>/dev</path>, such as <path>/dev/mouse</path>, which <c>udev</c> doesn't
438     create anymore. Be certain to check your X configuration file and see if the
439 swift 1.23 Device rule for your mouse points to an existing device file.
440 swift 1.22 </p>
441    
442 fox2mike 1.29 <p>
443     Another issue is the difference in naming of terminals between devfs and udev.
444     While devfs calls its terminals <c>tty</c>, udev calls them <c>vc</c>. This
445     could lead to a problem in case you are restricting root logins from consoles
446     using <path>/etc/securetty</path>. You will need to make sure that <c>tty1</c>
447     is changed to <c>vc/1</c> in <path>/etc/securetty</path> to ensure that root
448     can login using the console.
449     </p>
450    
451 swift 1.18 </body>
452     </section>
453     <section>
454 swift 1.8 <title>Other issues</title>
455 swift 1.1 <body>
456    
457 swift 1.8 <p>
458     If device nodes are not created when a module is loaded from
459     <path>/etc/modules.autoload.d/kernel-2.6</path> but they appear when you load
460     the module manually with modprobe then you should try upgrading to
461     <c>sys-apps/baselayout-1.8.12</c> or later.
462     </p>
463 swift 1.7
464     <p>
465 swift 1.8 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
466     kernel starting from version 2.6.6-rc2.
467 swift 1.7 </p>
468    
469     <p>
470 swift 1.8 For kernels older than 2.6.4 you have to explicitly include support for the
471     <path>/dev/pts</path> filesystem.
472 swift 1.1 </p>
473    
474 swift 1.8 <pre caption="Enabling the /dev/pts filesystem">
475     File systems ---&gt;
476     Pseudo filesystems ---&gt;
477     [*] /dev/pts file system for Unix98 PTYs
478     </pre>
479    
480 swift 1.1 </body>
481     </section>
482     </chapter>
483    
484     <chapter>
485     <title>Resources &amp; Acknowledgements</title>
486     <section>
487     <body>
488    
489     <p>
490     The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
491     Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
492     application.
493     </p>
494    
495     <p>
496     <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
497     UDEV Primer</uri> is an in-depth document about udev and Gentoo.
498     </p>
499    
500 swift 1.8 <p>
501     <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
502     fellow Gentoo developer Daniel Drake is an excellent document to learn how to
503     customize your udev installation.
504     </p>
505    
506 swift 1.1 </body>
507     </section>
508     </chapter>
509    
510     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20