Gentoo udev Guide
1. What is udev?
The /dev Directory
When Linux-users talk about the hardware on their system in the vicinity of
people who believe Linux is some sort of virus or brand of coffee, the use of
"slash dev slash foo" will return a strange look for sure. But for the fortunate
user (and that includes you) using /dev/hda1 is just a fast way of
explaining that we are talking about the primary master IDE, first partition. Or
We all know what a device file is. Some even know why device files have special
numbers when we take a closer look at them when we issue ls -l in
/dev. But what we always take for granted is that the primary
master IDE disk is referred to as /dev/hda. You might not see it
this way, but this is a flaw by design.
Think about hotpluggable devices like USB, IEEE1394, hot-swappable PCI, ... What
is the first device? And for how long? What will the other devices be named when
the first one disappears? How will that affect ongoing transactions? Wouldn't it
be fun that a printing job is suddenly moved from your supernew laserprinter to
your almost-dead matrix printer because your mom decided to pull the plug of the
laserprinter which happened to be the first printer?
Enter udev. The goals of the udev project are both interesting and
- Runs in userspace
- Dynamically creates/removes device files
- Provides consistent naming
- Provides a user-space API
To provide these features, udev is developed in three separate projects:
namedev, libsysfs and, of course, udev.
Namedev allows you to define the device naming separately from the udev program.
This allows for flexible naming policies and naming schemes developed by
separate entities. This device naming subsystem provides a standard interface
that udev can use.
Currently only a single naming scheme is provided by namedev; the one provided
by LANANA, used by the majority of Linux systems currently and therefore very
suitable for the majority of Linux users.
Namedev uses a 5-step procedure to find out the name of a given device. If the
device name is found in one of the given steps, that name is used. The steps
- label or serial number
- bus device number
- bus topology
- statically given name
- kernel provided name
The label or serial number step checks if the device has a unique
identifier. For instance USB devices have a unique USB serial number; SCSI
devices have a unique UUID. If namedev finds a match between this unique number
and a given configuration file, the name provided in the configuration file is
The bus device number step checks the device bus number. For
non-hot-swappable environments this procedure is sufficient to
identify a hardware device. For instance PCI bus numbers rarely change in the
lifetime of a system. Again, if namedev finds a match between this position and
a given configuration file, the name provided in that configuration file is
Likewise the bus topology is a rather static way of defining devices as
long as the user doesn't switch devices. When the position of the device matches
a given setting provided by the user, the accompanying name is used.
The fourth step, statically given name, is a simple string replacement.
When the kernel name (the default name) matches a given replacement string, the
substitute name will be used.
The final step (kernel provided name) is a catch-all: this one takes
the default name provided by the kernel. In the majority of cases this is
sufficient as it matches the device naming used on current Linux systems.
udev interacts with the kernel through the sysfs pseudo filesystem. The libsysfs
project provides a common API to access the information given by the sysfs
filesystem in a generic way. This allows for querying all kinds of hardware
without having to make assumptions on the kind of hardware.
Every time the kernel gets an event in the device structure, it asks udev to
take a look. udev follows the rules in the /etc/udev/rules.d/
directory. udev then uses the information given by the kernel to perform the
necessary actions on the /dev structure (creating or deleting
2. Using udev on Gentoo
udev is meant to be used in combination with a 2.6 kernel (like
gentoo-sources with the default 2007.0 profile). If you're using such a
kernel then you just have to make sure that you have a recent
sys-apps/baselayout version. That's all you need.
Code Listing 2.1: Installing udev
# emerge udev
Kernelwise, be sure to activate the following options:
Code Listing 2.2: Required kernel options
General setup --->
[*] Support for hot-pluggable devices
File systems --->
Pseudo filesystems --->
[*] /proc file system support
[*] Virtual memory file system support (former shm fs)
If you use genkernel, don't forget to run it with the --udev
option to enable all the required kernel configuration directives. The default
configuration given by this genkernel invocation is sufficient.
If you want to use the udev-tweaks Gentoo added to make your life
comfortable, then read no more. Gentoo will use udev but keep a static
/dev so that you will never have any missing device nodes.
The Gentoo init scripts won't run the devfsd daemon and will deactivate devfs
when you boot up.
But if you are a die-hard and want to run a udev-only, no-tweaked system as is
intended by the udev development (including the difficulties of missing device
nodes because udev doesn't support them yet), by all means, read on :)
We'll deactivate the rules that save the device file nodes: edit the
RC_DEVICE_TARBALL variable in /etc/conf.d/rc and set it to
Code Listing 2.3: /etc/conf.d/rc
If you have included devfs support in your kernel, you can deactivate it in
the bootloader configuration: add gentoo=nodevfs as a kernel parameter.
If you want to use devfs and deactivate udev, add gentoo=noudev as kernel
3. Known Issues
Missing device node files at boot
If you can't boot successfully because you get an error about
/dev/null not found, or because the initial console is missing, the
problem is that you lack some device files that must be available before
/dev is mounted and handled by udev. This is common on Gentoo
machines installed from old media.
If you run sys-apps/baselayout-1.8.12 or later, this problem is
alleviated since the boot process should still manage to complete. However, to
get rid of those annoying warnings, you should create the missing device nodes
as described below.
To see which devices nodes are present before the /dev filesystem
is mounted, run the following commands:
Code Listing 3.1: Listing device nodes available at boot
# mkdir test
# mount --bind / test
# cd test/dev
The devices needed for a successful boot are /dev/null and
/dev/console. If they didn't show up in the previous test, you have
to create them manually. Issue the following commands in the
Code Listing 3.2: Creating necessary device node files
# mknod -m 660 console c 5 1
# mknod -m 660 null c 1 3
When you're finished, don't forget to unmount the test/ directory:
Code Listing 3.3: Unmounting the test/ directory
# cd ../..
# umount test
# rmdir test
udev and nvidia
If you use the proprietary driver from nVidia and the X server fails to start on
a udev-only system, then make sure you have:
the nvidia module listed in
a version of baselayout equal to or greater than
No Consistent Naming between DevFS and udev
Even though our intention is to have a consistent naming scheme between both
dynamical device management solutions, sometimes naming differences do occur.
One reported clash is with a HP Smart Array 5i RAID controller (more precisely
the cciss kernel module). With udev, the devices are named
/dev/cciss/cXdYpZ with X, Y and Z regular numbers. With devfs, the
devices are /dev/hostX/targetY/partZ or symlinked from
If this is the case, don't forget to update your /etc/fstab and
bootloader configuration files accordingly.
The same happens with all-round symlinks that used to exist in
/dev, such as /dev/mouse, which udev doesn't
create anymore. Be certain to check your X configuration file and see if the
Device rule for your mouse points to an existing device file.
Another issue is the difference in naming of terminals between devfs and udev.
While devfs calls its terminals tty, udev calls them vc and
tty. This could lead to a problem in case you are restricting root
logins from consoles using /etc/securetty. You will need to make
sure that both tty1 and vc/1 are listed in
/etc/securetty to ensure that root can login using the console.
Recent versions of udev (104 and up) along with newer kernel versions (2.6.19
and up) may change your disc device names, due to a change in the kernel's
libata implementation. A CD-RW device at /dev/hdc may be changed to
/dev/sr0. While this is not normally a problem, it may cause issues
for some applications that are hardcoded to look for devices at other locations.
For example, media-sound/rip expects to find discs at
/dev/cdrom, which becomes a problem if you use a newer kernel and
udev renames your device to /dev/cdrom1.
To work around these issues, you must edit
/etc/udev/rules.d/70-persistent-cd.rules and assign the correct
name to the device.
For more information on writing udev rules, be sure to read Daniel Drake's guide.
udev loads modules in an unpredictable order
Sometimes udev loads modules in an undesired, unpredictable, or seemingly random
order. This is especially common for systems that have multiple devices of the
same type, as well as multimedia devices. This can affect the assigned numbers
of devices; for example, sound cards may sometimes swap numbers.
There are a few solutions to fix device numbers and/or module load order.
Ideally, you can just use module parameters to specify your desired device
number. Some modules, such as ALSA, include the "index" parameter. Modules that
use the index parameter can be adjusted as shown. This example is for a system
with two sound cards. The card with an index of 0 is designated as the first
card. Once the parameters are changed, the module config files must be updated.
Code Listing 3.4: Specifying module parameters
# echo "option snd-ice1724 index=0" >> /etc/modules.d/alsa
# echo "option snd-ymfpci index=1" >> /etc/modules.d/alsa
The above example is the preferred solution, but not all modules support
parameters such as index. For these modules, you'll have to force the correct
module load order. First, you must stop udev from autoloading the modules by
blacklisting them. Be sure to use the exact name of the module being loaded.
For PCI devices, you'll need to use the module names obtained from the output of
pcimodules, available in the pciutils package. The following
example uses DVB modules.
Code Listing 3.5: Blacklisting modules
# echo "blacklist b2c2-flexcop-pci" >> /etc/modules.d/dvb
# echo "blacklist budget" >> /etc/modules.d/dvb
Next, load the modules in the correct order. Add them to
/etc/modules.autoload.d/kernel-2.6 in the exact order you want
Code Listing 3.6: Loading modules in the correct order
# echo "budget" >> /etc/modules.autoload.d/kernel-2.6
# echo "b2c2-flexcop-pci" >> /etc/modules.autoload.d/kernel-2.6
If device nodes are not created when a module is loaded from
/etc/modules.autoload.d/kernel-2.6 but they appear when you load
the module manually with modprobe then you should try upgrading to
sys-apps/baselayout-1.8.12 or later.
Support for the framebuffer devices (/dev/fb/*) comes with the
kernel starting from version 2.6.6-rc2.
For kernels older than 2.6.4 you have to explicitly include support for the
Code Listing 3.7: Enabling the /dev/pts filesystem
File systems --->
Pseudo filesystems --->
[*] /dev/pts file system for Unix98 PTYs
4. Resources & Acknowledgements
The udev talk on the Linux Symposium (Ottawa, Ontario Canada - 2003) given by
Greg Kroah-Hartman (IBM Corporation) provided a solid understanding on the udev
UDEV Primer is an in-depth document about udev and Gentoo.
Writing udev rules by
fellow Gentoo developer Daniel Drake is an excellent document to learn how to
customize your udev installation.
The contents of this document are licensed under the Creative Commons -
Attribution / Share Alike license.