/[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.27 - (show annotations) (download) (as text)
Fri Aug 12 10:34:52 2005 UTC (12 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.26: +14 -3 lines
File MIME type: application/xml
Add merging of multiphat-tools for the LVM2 name rewriting in udev. Reported by jon@kiwiuk.net.

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3
4 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/udev-guide.xml,v 1.26 2005/07/02 13:02:01 swift Exp $ -->
5
6 <guide link="/doc/en/udev-guide.xml">
7 <title>Gentoo udev Guide</title>
8
9 <author title="Author">
10 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
11 </author>
12 <author title="Contributor">
13 <mail link="greg_g@gentoo.org">Gregorio Guidi</mail>
14 </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 <version>0.21</version>
23 <date>2005-08-12</date>
24
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 people who believe Linux is some sort of virus or brand of coffee, the use of
34 "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 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 the first one disappears? How will that affect ongoing transactions? Wouldn't it
52 be fun that a printing job is suddenly moved from your supernew laserprinter to
53 your almost-dead matrix printer because your mom decided to pull the plug of the
54 laserprinter which happened to be the first printer?
55 </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 <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 </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 by LANANA, used by the majority of Linux systems currently and therefore very
90 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 a given setting provided by the user, the accompanying name is used.
128 </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 udev is meant to be used in combination with a 2.6 kernel (like
182 <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 </p>
186
187 <pre caption="Installing udev">
188 # <i>emerge udev</i>
189 </pre>
190
191 <p>
192 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 </p>
197
198 <pre caption="Installing optional hotplug scripts">
199 # <i>emerge hotplug</i>
200 </pre>
201
202 <p>
203 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 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 Kernelwise, be sure to activate the following options:
221 </p>
222
223 <pre caption="Required kernel options">
224 General setup ---&gt;
225 [*] 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 wish but you have to make sure that "Automatically mount at boot" is disabled:
236 </p>
237
238 <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 <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 </body>
252 </section>
253 <section>
254 <title>Configuration</title>
255 <body>
256
257 <p>
258 If you want to use the udev-tweaks Gentoo added to make your life
259 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 </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 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 </p>
270
271 <p>
272 We'll deactivate the rules that save the device file nodes: edit the
273 <c>RC_DEVICE_TARBALL</c> variable in <path>/etc/conf.d/rc</path> and set it to
274 <c>no</c>:
275 </p>
276
277 <pre caption="/etc/conf.d/rc">
278 RC_DEVICE_TARBALL="no"
279 </pre>
280
281 <p>
282 If you have included devfs support in your kernel, you can deactivate it in
283 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 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 If you can't boot successfully because you get an error about
300 <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 get rid of those annoying warnings, you should create the missing device nodes
310 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 The devices needed for a successful boot are <path>/dev/null</path> and
327 <path>/dev/console</path>. If they didn't show up in the previous test, you have
328 to create them manually. Issue the following commands in the
329 <path>test/dev/</path> directory:
330 </p>
331
332 <pre caption="Creating necessary device node files">
333 # <i>mknod -m 660 console c 5 1</i>
334 # <i>mknod -m 660 null c 1 3</i>
335 </pre>
336
337 <p>
338 When you're finished, don't forget to unmount the <path>test/</path> directory:
339 </p>
340
341 <pre caption="Unmounting the test/ directory">
342 # <i>cd ../..</i>
343 # <i>umount test</i>
344 # <i>rmdir test</i>
345 </pre>
346
347 </body>
348 </section>
349 <section>
350 <title>udev and nvidia</title>
351 <body>
352
353 <p>
354 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 </p>
357
358 <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 a version of <c>nvidia-kernel</c> equal to or greater than
365 <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 </body>
374 </section>
375 <section>
376 <title>LVM2 Names Disappear</title>
377 <body>
378
379 <p>
380 When you use <c>udev</c> and LVM2 together, you might notice that your created
381 volume groups and logical volumes have disappeared. Well, they haven't, but they
382 are unfortunately named <path>/dev/dm-#</path> with # being 0, 1, ...
383 </p>
384
385 <p>
386 To fix this, edit <path>/etc/udev/rules.d/50-udev.rules</path> and uncomment the
387 following line:
388 </p>
389
390 <pre caption="Uncomment this line from /etc/udev/rules.d/50-udev.rules">
391 KERNEL="dm-[0-9]*", PROGRAM="/sbin/devmap_name %M %m", NAME="%k", SYMLINK="%c"
392 </pre>
393
394 <p>
395 Next, install <c>sys-fs/multipath-tools</c> which contains the
396 <c>devmap_name</c> application.
397 </p>
398
399 <pre caption="Installing multipath-tools">
400 <comment>(At the moment of writing, multipath-tools is only available in the testing branch:)</comment>
401 # <i>echo "=sys-fs/multipath-tools-0.4.2 ~x86" &gt;&gt; /etc/portage/package.keywords</i>
402 # <i>emerge multipath-tools</i>
403 </pre>
404
405 </body>
406 </section>
407 <section>
408 <title>No Consistent Naming between DevFS and udev</title>
409 <body>
410
411 <p>
412 Even though our intention is to have a consistent naming scheme between both
413 dynamical device management solutions, sometimes naming differences do occur.
414 </p>
415
416 <p>
417 One reported clash is with a HP Smart Array 5i RAID controller (more precisely
418 the <c>cciss</c> kernel module). With udev, the devices are named
419 <path>/dev/cciss/cXdYpZ</path> with X, Y and Z regular numbers. With devfs, the
420 devices are <path>/dev/hostX/targetY/partZ</path> or symlinked from
421 <path>/dev/cciss/cXdY</path>.
422 </p>
423
424 <p>
425 If this is the case, don't forget to update your <path>/etc/fstab</path> and
426 bootloader configuration files accordingly.
427 </p>
428
429 <p>
430 The same happens with all-round symlinks that used to exist in
431 <path>/dev</path>, such as <path>/dev/mouse</path>, which <c>udev</c> doesn't
432 create anymore. Be certain to check your X configuration file and see if the
433 Device rule for your mouse points to an existing device file.
434 </p>
435
436 </body>
437 </section>
438 <section>
439 <title>Other issues</title>
440 <body>
441
442 <p>
443 If device nodes are not created when a module is loaded from
444 <path>/etc/modules.autoload.d/kernel-2.6</path> but they appear when you load
445 the module manually with modprobe then you should try upgrading to
446 <c>sys-apps/baselayout-1.8.12</c> or later.
447 </p>
448
449 <p>
450 Support for the framebuffer devices (<path>/dev/fb/*</path>) comes with the
451 kernel starting from version 2.6.6-rc2.
452 </p>
453
454 <p>
455 For kernels older than 2.6.4 you have to explicitly include support for the
456 <path>/dev/pts</path> filesystem.
457 </p>
458
459 <pre caption="Enabling the /dev/pts filesystem">
460 File systems ---&gt;
461 Pseudo filesystems ---&gt;
462 [*] /dev/pts file system for Unix98 PTYs
463 </pre>
464
465 </body>
466 </section>
467 </chapter>
468
469 <chapter>
470 <title>Resources &amp; Acknowledgements</title>
471 <section>
472 <body>
473
474 <p>
475 The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
476 Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
477 application.
478 </p>
479
480 <p>
481 <uri link="http://webpages.charter.net/decibelshelp/LinuxHelp_UDEVPrimer.html">Decibel's
482 UDEV Primer</uri> is an in-depth document about udev and Gentoo.
483 </p>
484
485 <p>
486 <uri link="http://www.reactivated.net/udevrules.php">Writing udev rules</uri> by
487 fellow Gentoo developer Daniel Drake is an excellent document to learn how to
488 customize your udev installation.
489 </p>
490
491 </body>
492 </section>
493 </chapter>
494
495 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20