How does udev work?
~~~~~~~~~~~~~~~~~~~
Short summary: when a driver is loaded it makes some information available
in /sys/ and a message is sent to udevd which reads them and creates the
appropriate devices.

This means that:
- modules cannot be loaded on demand when applications open their device,
  because the device is not yet there!
- since modules are not loaded on demand, if for some reason the drivers
  cannot be automatically loaded at boot time you will have to add them
  to /etc/modules.
- some modules are not hardware drivers and cannot be loaded automatically
  by udev, so they will have to be listed in /etc/modules as well.
- some modules for less usual bus types lack the sysfs data needed to be
  automatically loaded and must be loaded manually.
  (See #334238 and #337004 for details.)

udevd also manages the hotplug events and if needed dispatches them to
other programs using RUN rules, as a replacement of the old /sbin/hotplug.


Debugging early boot
~~~~~~~~~~~~~~~~~~~~
If the system hangs at boot time or fails to boot properly, it may be
useful to examine in real time what is happening while "udevadm settle"
is running. A simple way to do this is:

* boot the system passing "init=/bin/bash" on the kernel command line
* start a getty on tty2 (or the serial console) with a command like
  "/sbin/getty 38400 tty2 &"
* continue the boot process with "exec /sbin/init single"

The open console can be used to check which processes are running and
what they are waiting for.

Setting the kernel command line options documented in udevd(8) may also
help to identify system-wide troubles caused by specific kernel drivers.


Required kernel support
~~~~~~~~~~~~~~~~~~~~~~~
The required kernel version and features are documented in the README
file.


Disabling udev
~~~~~~~~~~~~~~
You may configure in /etc/udev/udev.conf a directory other than /dev
or add UDEV_DISABLED=yes to the kernel command line.


Manually creating devices
~~~~~~~~~~~~~~~~~~~~~~~~~
Device nodes present in /lib/udev/devices/ will be copied to /dev/ at
boot time.


The /etc/udev/rules.d/ directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The files are read and processed in alphabetical order, and the directives
of matching rules are applied in order.
If a file with the same name is present in more than one of the
/run/udev/rules.d/, /etc/udev/rules.d/ and /lib/udev/rules.d/ directories
then the latter(s) file will be ignored.
Since the order may be important, files have a specific name which
must be considered when adding custom rules. So far have been defined:

 - 60: path_id and the other *_id programs are run. persistent links
   are set.

 - 70: network interfaces are renamed and generated rules for persistent
   links are processed.

 - 75: the rules generators are run if needed.

 - 80: drivers are loaded.

 - 91: the default permissions and owners are set.

 - 95: $REMOVE_CMD is run, and then processing of tty devices
   is stopped with last_rule.

The persistent-*.rules files are generated by the *-generator.rules files
using the /lib/udev/write_*_rules scripts when new devices are detected.
They set stable names for network interfaces and optical devices aliases.


How to know the attributes of a device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Try something like:
udevadm info --attribute-walk --path=/sys/class/sound/pcmC0D0c/


Devices timestamps
~~~~~~~~~~~~~~~~~~
Most devices will be created at the beginning of the boot process, and will
have the creation time of the kernel clock at that moment.
On systems whose system clock is set on local time instead of UTC, the
kernel clock will be updated in a later phase of the boot process and for
a few hours the devices will have a timestamp in the future.
This is usually not a problem, but if it bothers you it can be fixed by
running touch(1) in an init script.


SCSI block and generic devices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you create a custom rule which matches SCSI devices by some sysfs
attributes, do not forget that it will match not only the sdX device node
you are probably looking for but also the SCSI generic device node sgX.
To get the expected behaviour, you need to add KERNEL="sd*" to your rule.
A typical example for an USB pen drive is:

SUBSYSTEMS=="usb", KERNEL=="sd*", \
	ATTRS{manufacturer}=="hardware vendor", ATTRS{product}=="model", \
	SYMLINK+="pendrive%n"

If a device does not report media changes (like e.g. many SD card readers)
you will also need to add the OPTIONS+="all_partitions" attribute to the
rule. This is not needed if you are using HAL.


Network Interfaces
~~~~~~~~~~~~~~~~~~
After receiving events about network interfaces, net.agent will call
ifupdown using the --allow=hotplug option. This makes the program act
only on interfaces marked with the "allow-hotplug" statement.
E.g: "allow-hotplug eth0" instead of the usual "auto eth0".
The loopback interface must always be configured with "auto lo".

The persistent names of network interfaces by default are automatically
written to /etc/udev/rules.d/70-persistent-net.rules .
Users can add their own rules there or at any other place before 70.
MAC addresses matching is literal, so they must be written in lower case.
To disable persistent naming of network interfaces, create an empty
/etc/udev/rules.d/75-persistent-net-generator.rules file to override
the one in /lib/udev/rules.d/ and delete
/etc/udev/rules.d/70-persistent-net.rules.

Beware: programs which rename network interfaces like ifrename and nameif
will let udev relay events for the old names and should not be used.

Usually network interfaces are renamed after the root file system has
been mounted, so if the root file system is mounted over the network
then the 70-persistent-net.rules file must be copied to the initramfs.
In most cases this is done automatically, but some setups may require
explicitly setting "export NEED_PERSISTENT_NET=yes" in a file in
/etc/initramfs-tools/conf.d/ .
If 70-persistent-net.rules is copied to the initramfs then it must be
updated every time a new interface is added.


Using udev with LDAP or NIS
~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the rules files reference usernames or groups not present in the
/etc/{passwd,group} files and the system is configured to use a
network-based database like LDAP or NIS then udev may fail at boot time
because users and groups are looked up well before the network has been
initialized.
A possible solution is to configure /etc/nsswitch.conf like this:

  passwd:         files ldap [UNAVAIL=return]
  group:          files ldap [UNAVAIL=return]

The nsswitch.conf syntax is documented in the glibc manual.


Other documentation
~~~~~~~~~~~~~~~~~~~
http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
http://www.reactivated.net/udevrules.php
http://www.kroah.com/linux/talks/suse_2005_driver_model/