source: postlfs/config/devices.xml@ eede1a3

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;
]>

<sect1 id="postlfs-devices" xreflabel="About Devices">
  <?dbhtml filename="devices.html"?>

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <title>About Devices</title>

  <indexterm zone="postlfs-devices">
    <primary sortas="e-etc-udev-rules">/etc/udev/rules.d</primary>
  </indexterm>

  <para>
    Although most devices needed by packages in BLFS and beyond are set up
    properly by <application>udev</application> using the default rules
    installed by LFS in <filename
    class="directory">/etc/udev/rules.d</filename>, there are cases where
    the rules must be modified or augmented.
  </para>

  <para condition="html" role="usernotes">User Notes:
  <ulink url="&blfs-wiki;/aboutdevices"/></para>

  <sect2>
    <title>Multiple Sound Cards</title>

    <para>
      If there are multiple sound cards in a system, the "default"
      sound card becomes random.  The method to establish sound card order
      depends on whether the drivers are modules or not.  If the sound card
      drivers are compiled into the kernel, control is via kernel command line
      parameters in <filename>/boot/grub/grub.cfg</filename>.  For example,
      if a system has both an FM801 card and a SoundBlaster PCI card, the
      following can be appended to the command line:
    </para>

<screen><literal>snd-fm801.index=0 snd-ens1371.index=1</literal></screen>

    <para>
      If the sound card drivers are built as modules, the order can be
      established in the <filename>/etc/modprobe.conf</filename> file with:
    </para>

<screen><literal>options snd-fm801 index=0
options snd-ens1371 index=1</literal></screen>

  </sect2>

  <sect2 id="usb-device-issues">
    <title>USB Device Issues</title>

    <para>
      USB devices usually have two kinds of device nodes associated with them.
    </para>

    <para>
      The first kind is created by device-specific drivers (e.g.,
      usb_storage/sd_mod or usblp) in the kernel. For example, a USB mass
      storage device would be /dev/sdb, and a USB printer would be
      /dev/usb/lp0. These device nodes exist only when the device-specific
      driver is loaded.
    </para>

    <para>
      The second kind of device nodes (/dev/bus/usb/BBB/DDD, where BBB is
      the bus number and DDD is the device number) are created even if the
      device doesn't have a kernel driver. By using these "raw" USB device
      nodes, an application can exchange arbitrary USB packets with the
      device, i.e., bypass the possibly-existing kernel driver.
    </para>

    <para>
      Access to raw USB device nodes is needed when a userspace program is
      acting as a device driver. However, for the program to open the device
      successfully, the permissions have to be set correctly. By default, due
      to security concerns, all raw USB devices are owned by user root and
      group usb, and have 0664 permissions (the read access is needed, e.g.,
      for lsusb to work and for programs to access USB hubs). Packages (such
      as SANE and libgphoto2) containing userspace USB device drivers also
      ship udev rules that change the permissions of the controlled raw USB
      devices. That is, rules installed by SANE change permissions for known
      scanners, but not printers.  If a package maintainer forgot to write
      a rule for your device, report a bug to both BLFS (if the package is
      there) and upstream, and you will need to write your own rule.
    </para>

    <para>
      There is one situation when such fine-grained access control with
      pre-generated udev rules doesn't work. Namely, PC emulators such as KVM,
      QEMU and VirtualBox use raw USB device nodes to present arbitrary USB
      devices to the guest operating system (note: patches are needed in order
      to get this to work without the obsolete /proc/bus/usb mount point
      described below). Obviously, maintainers of these packages cannot know
      which USB devices are going to be connected to the guest operating
      system. You can either write separate udev rules for all needed USB
      devices yourself, or use the default catch-all "usb" group, members
      of which can send arbitrary commands to all USB devices. 
    </para>

    <para>
      Before Linux-2.6.15, raw USB device access was performed not with
      /dev/bus/usb/BBB/DDD device nodes, but with /proc/bus/usb/BBB/DDD
      pseudofiles. Some applications (e.g., VMware Workstation) still use only
      this deprecated technique and can't use the new device nodes. For them to
      work, use the "usb" group, but remember that members will have
      unrestricted access to all USB devices.  To create the fstab entry for
      the obsolete usbfs filesystem:
    </para>

<screen><literal>usbfs  /proc/bus/usb  usbfs  devgid=14,devmode=0660  0  0</literal></screen>

    <note>
      <para>
        Adding users to the "usb" group is inherently insecure, as they can
        bypass access restrictions imposed through the driver-specific USB
        device nodes. For instance, they can read sensitive data from USB
        hard drives without being in the "disk" group. Avoid adding users
        to this group, if you can.
    </para>
    </note>

  </sect2>

  <sect2>
    <title>Udev Device Attributes</title>

    <para>
      Fine-tuning of device attributes such as group name and permissions
      is possible by creating extra <application>udev</application> rules,
      matching on something like this. The vendor and product can be found by
      searching the <filename class='directory'>/sys/devices</filename>
      directory entries or using <command>udevadm info</command> after the
      device has been attached. See the documentation in the current
      <application>udev</application> directory of <filename
      class='directory'>/usr/share/doc</filename> for details.
    </para>

<screen><literal>SUBSYSTEM=="usb_device", SYSFS{idVendor}=="05d8", SYSFS{idProduct}=="4002", \
  GROUP:="scanner", MODE:="0660"</literal></screen>

    <note>
      <para>
        The above line is used for descriptive purposes only. The
        scanner <application>udev</application> rules are put into place when
        installing <xref linkend='sane'/>.
      </para>
    </note>

  </sect2>

<!--
  <sect2>
    <title>Multiple Network Interfaces</title>


  </sect2>
-->

<!-- These instructions are invalid on systemd because we don't use bootscripts.
     In addition, we should probably verify that these are valid on SysV too.-->

  <sect2 revision="sysv">
    <title>Devices for Servers</title>

    <para>
      In some cases, it makes sense to disable
      <application>udev</application> completely and create static devices.
      Servers are one example of this situation.  Does a server need the
      capability of handling dynamic devices?  Only the system administrator
      can answer that question, but in many cases the answer will be no.
    </para>

    <para>
      If dynamic devices are not desired, then static devices must be
      created on the system.  In the default configuration, the
      <filename>/etc/rc.d/rcS.d/S10udev</filename> boot script mounts a
      <systemitem class="filesystem">tmpfs</systemitem> partition over the
      <filename class="directory">/dev</filename> directory. This problem can
      be overcome by mounting the root partition temporarily:
    </para>

    <warning>
      <para>
        If the instructions below are not followed carefully, your
        system could become unbootable.
      </para>
    </warning>


<screen><userinput>mount --bind / /mnt
cp -a /dev/* /mnt/dev
rm /etc/rc.d/rcS.d/{S10udev,S50udev_retry}
umount /mnt</userinput></screen>

    <para>
      At this point, the system will use static devices upon the next
      reboot.  Create any desired additional devices using
      <command>mknod</command>.
    </para>

    <para>
      If you want to restore the dynamic devices, recreate the
      <filename>/etc/rc.d/rcS.d/{S10udev,S50udev_retry}</filename> symbolic
      links and reboot again.  Static devices do not need to be removed
      (console and null are always needed) because they are covered by the
      <systemitem class="filesystem">tmpfs</systemitem> partition.  Disk
      usage for devices is negligible (about 20&ndash;30 bytes per entry.)
    </para>

  </sect2>

  <sect2 id="dev-dvd">
    <title>Devices for DVD Drives</title>

    <para>
      If the initial boot process does not set up the 
      <systemitem>/dev/dvd</systemitem> device properly, it can
      be installed using the following modification to the default udev rules.
      As the <systemitem class="username">root</systemitem> user, run:
    </para>

<screen><userinput>sed '1d;/SYMLINK.*cdrom/ a\
KERNEL=="sr0", ENV{ID_CDROM_DVD}=="1", SYMLINK+="dvd", OPTIONS+="link_priority=-100"' \
/lib/udev/rules.d/60-cdrom_id.rules > /etc/udev/rules.d/60-cdrom_id.rules</userinput></screen>

  </sect2>

</sect1>