/[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.40 - (hide annotations) (download) (as text)
Tue Apr 10 20:55:33 2007 UTC (10 years, 6 months ago) by nightmorph
Branch: MAIN
Changes since 1.39: +3 -35 lines
File MIME type: application/xml
removing outdated LVM2 section by Cardoe's request

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 neysx 1.4
4 nightmorph 1.40 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.39 2007/04/10 06:48:59 nightmorph 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 nightmorph 1.34 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
11 swift 1.8 </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 nightmorph 1.40 <version>0.30</version>
23     <date>2007-04-10</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 nightmorph 1.39 Every time the kernel gets an event in the device structure, it asks udev to
163     take a look. udev follows the rules in the <path>/etc/udev/rules.d/</path>
164     directory. udev then uses the information given by the kernel to perform the
165     necessary actions on the <path>/dev</path> structure (creating or deleting
166     device files).
167 swift 1.1 </p>
168    
169     </body>
170     </section>
171     </chapter>
172    
173     <chapter>
174     <title>Using udev on Gentoo</title>
175     <section>
176     <title>Requirements</title>
177     <body>
178    
179     <p>
180 swift 1.8 udev is meant to be used in combination with a 2.6 kernel (like
181 nightmorph 1.39 <c>gentoo-sources</c> with the default 2007.0 profile). If you're using such a
182 nightmorph 1.37 kernel then you just have to make sure that you have a recent
183     <c>sys-apps/baselayout</c> version. That's all you need.
184 swift 1.1 </p>
185    
186 swift 1.8 <pre caption="Installing udev">
187     # <i>emerge udev</i>
188 swift 1.1 </pre>
189    
190     <p>
191 swift 1.21 Kernelwise, be sure to activate the following options:
192 swift 1.1 </p>
193    
194     <pre caption="Required kernel options">
195 swift 1.6 General setup ---&gt;
196 swift 1.1 [*] Support for hot-pluggable devices
197    
198     File systems ---&gt;
199     Pseudo filesystems ---&gt;
200     [*] /proc file system support
201     [*] Virtual memory file system support (former shm fs)
202     </pre>
203    
204     <p>
205 swift 1.21 If you use <c>genkernel</c>, don't forget to run it with the <c>--udev</c>
206     option to enable all the required kernel configuration directives. The default
207     configuration given by this <c>genkernel</c> invocation is sufficient.
208     </p>
209    
210 swift 1.1 </body>
211     </section>
212     <section>
213     <title>Configuration</title>
214     <body>
215    
216     <p>
217 neysx 1.5 If you want to use the udev-tweaks Gentoo added to make your life
218 swift 1.15 comfortable, then read no more. Gentoo will use udev but keep a static
219     <path>/dev</path> so that you will never have any missing device nodes.
220     The Gentoo init scripts won't run the devfsd daemon and will deactivate devfs
221     when you boot up.
222 swift 1.1 </p>
223    
224     <p>
225     But if you are a die-hard and want to run a udev-only, no-tweaked system as is
226 swift 1.2 intended by the udev development (including the difficulties of missing device
227     nodes because udev doesn't support them yet), by all means, read on :)
228 swift 1.1 </p>
229    
230     <p>
231 bennyc 1.13 We'll deactivate the rules that save the device file nodes: edit the
232 swift 1.2 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
233     <c>no</c>:
234     </p>
235 swift 1.1
236 swift 1.2 <pre caption="/etc/conf.d/rc">
237     RC_DEVICE_TARBALL="no"
238 swift 1.1 </pre>
239    
240     <p>
241 swift 1.8 If you have included devfs support in your kernel, you can deactivate it in
242 swift 1.14 the bootloader configuration: add <c>gentoo=nodevfs</c> as a kernel parameter.
243     If you want to use devfs and deactivate udev, add <c>gentoo=noudev</c> as kernel
244 swift 1.8 parameter.
245     </p>
246    
247     </body>
248     </section>
249     </chapter>
250    
251     <chapter>
252     <title>Known Issues</title>
253     <section>
254     <title>Missing device node files at boot</title>
255     <body>
256    
257     <p>
258 neysx 1.9 If you can't boot successfully because you get an error about
259 swift 1.8 <path>/dev/null</path> not found, or because the initial console is missing, the
260     problem is that you lack some device files that must be available <e>before</e>
261     <path>/dev</path> is mounted and handled by udev. This is common on Gentoo
262     machines installed from old media.
263     </p>
264    
265     <p>
266     If you run <c>sys-apps/baselayout-1.8.12</c> or later, this problem is
267     alleviated since the boot process should still manage to complete. However, to
268 swift 1.10 get rid of those annoying warnings, you should create the missing device nodes
269 swift 1.8 as described below.
270     </p>
271    
272     <p>
273     To see which devices nodes are present before the <path>/dev</path> filesystem
274     is mounted, run the following commands:
275     </p>
276    
277     <pre caption="Listing device nodes available at boot">
278     # <i>mkdir test</i>
279     # <i>mount --bind / test</i>
280     # <i>cd test/dev</i>
281     # <i>ls</i>
282     </pre>
283    
284     <p>
285 neysx 1.9 The devices needed for a successful boot are <path>/dev/null</path> and
286 swift 1.8 <path>/dev/console</path>. If they didn't show up in the previous test, you have
287 cam 1.12 to create them manually. Issue the following commands in the
288     <path>test/dev/</path> directory:
289 swift 1.1 </p>
290    
291     <pre caption="Creating necessary device node files">
292 cam 1.11 # <i>mknod -m 660 console c 5 1</i>
293     # <i>mknod -m 660 null c 1 3</i>
294 swift 1.1 </pre>
295    
296     <p>
297 swift 1.8 When you're finished, don't forget to unmount the <path>test/</path> directory:
298 swift 1.1 </p>
299    
300 swift 1.8 <pre caption="Unmounting the test/ directory">
301 cam 1.11 # <i>cd ../..</i>
302 swift 1.8 # <i>umount test</i>
303 cam 1.11 # <i>rmdir test</i>
304 swift 1.8 </pre>
305    
306     </body>
307     </section>
308     <section>
309     <title>udev and nvidia</title>
310     <body>
311    
312 swift 1.1 <p>
313 swift 1.8 If you use the proprietary driver from nVidia and the X server fails to start on
314     a udev-only system, then make sure you have:
315 swift 1.1 </p>
316    
317 swift 1.8 <ul>
318     <li>
319     the <c>nvidia</c> module listed in
320     <path>/etc/modules.autoload.d/kernel-2.6</path>
321     </li>
322     <li>
323 swift 1.10 a version of <c>nvidia-kernel</c> equal to or greater than
324 swift 1.8 <c>media-video/nvidia-kernel-1.0.5336-r2</c>
325     </li>
326     <li>
327     a version of baselayout equal to or greater than
328     <c>sys-apps/baselayout-1.8.12</c>
329     </li>
330     </ul>
331    
332 swift 1.28 <p>
333     If <c>xorg-x11</c> refuses to start, it might be because the
334     <path>/dev/nvidia</path> device file is missing. If that is the case, run
335     <path>/sbin/NVmakedevices.sh</path> to (re)create it.
336     </p>
337    
338 swift 1.1 </body>
339     </section>
340     <section>
341 swift 1.18 <title>No Consistent Naming between DevFS and udev</title>
342     <body>
343    
344     <p>
345     Even though our intention is to have a consistent naming scheme between both
346     dynamical device management solutions, sometimes naming differences do occur.
347 swift 1.22 </p>
348    
349     <p>
350 swift 1.18 One reported clash is with a HP Smart Array 5i RAID controller (more precisely
351     the <c>cciss</c> kernel module). With udev, the devices are named
352     <path>/dev/cciss/cXdYpZ</path> with X, Y and Z regular numbers. With devfs, the
353     devices are <path>/dev/hostX/targetY/partZ</path> or symlinked from
354     <path>/dev/cciss/cXdY</path>.
355     </p>
356    
357     <p>
358     If this is the case, don't forget to update your <path>/etc/fstab</path> and
359     bootloader configuration files accordingly.
360     </p>
361    
362 swift 1.22 <p>
363     The same happens with all-round symlinks that used to exist in
364     <path>/dev</path>, such as <path>/dev/mouse</path>, which <c>udev</c> doesn't
365     create anymore. Be certain to check your X configuration file and see if the
366 swift 1.23 Device rule for your mouse points to an existing device file.
367 swift 1.22 </p>
368    
369 fox2mike 1.29 <p>
370     Another issue is the difference in naming of terminals between devfs and udev.
371 nightmorph 1.31 While devfs calls its terminals <c>tty</c>, udev calls them <c>vc</c> and
372     <c>tty</c>. This could lead to a problem in case you are restricting root
373     logins from consoles using <path>/etc/securetty</path>. You will need to make
374     sure that both <c>tty1</c> and <c>vc/1</c> are listed in
375     <path>/etc/securetty</path> to ensure that root can login using the console.
376 fox2mike 1.29 </p>
377    
378 swift 1.18 </body>
379     </section>
380     <section>
381 swift 1.8 <title>Other issues</title>
382 swift 1.1 <body>
383    
384 swift 1.8 <p>
385     If device nodes are not created when a module is loaded from
386     <path>/etc/modules.autoload.d/kernel-2.6</path> but they appear when you load
387     the module manually with modprobe then you should try upgrading to
388     <c>sys-apps/baselayout-1.8.12</c> or later.
389     </p>
390 swift 1.7
391     <p>
392 swift 1.8 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
393     kernel starting from version 2.6.6-rc2.
394 swift 1.7 </p>
395    
396     <p>
397 swift 1.8 For kernels older than 2.6.4 you have to explicitly include support for the
398     <path>/dev/pts</path> filesystem.
399 swift 1.1 </p>
400    
401 swift 1.8 <pre caption="Enabling the /dev/pts filesystem">
402     File systems ---&gt;
403     Pseudo filesystems ---&gt;
404     [*] /dev/pts file system for Unix98 PTYs
405     </pre>
406    
407 swift 1.1 </body>
408     </section>
409     </chapter>
410    
411     <chapter>
412     <title>Resources &amp; Acknowledgements</title>
413     <section>
414     <body>
415    
416     <p>
417     The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
418     Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
419     application.
420     </p>
421    
422     <p>
423     <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
424     UDEV Primer</uri> is an in-depth document about udev and Gentoo.
425     </p>
426    
427 swift 1.8 <p>
428     <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
429     fellow Gentoo developer Daniel Drake is an excellent document to learn how to
430     customize your udev installation.
431     </p>
432    
433 swift 1.1 </body>
434     </section>
435     </chapter>
436    
437     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20