Added additional information about <para>[bdubbs] - Added additional information about

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@8297 af4574ff-66df-0310-9fd7-8a98e5e911e0

general/genlib/libusb.xml

@@ -126,13 +126,8 @@ install -v -m644 doc/html/* \
     <primary sortas="d-USB-device-filesystem">Support for Host-side USB</primary>
     </indexterm>
 
-    <para>To have raw USB devices set up properly, add the following
-    <application>udev</application> rule.</para>
-
-<screen><literal>cat &gt; /etc/udev/rules.d/23-usb.rules &lt;&lt; "EOF"
-# Set group ownership for raw USB devices
-SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", GROUP="usb"
-EOF</literal></screen>
+    <para>For more details on setting up USB devices, see <xref
+    linkend="usb-device-issues"/>.  </para>
 
 <!--
     <para>Fine-tuning of permissions is also possible by creating extra rules,
@@ -152,12 +147,12 @@ SYSFS{idProduct}=="4002", GROUP:="scanner"</literal></screen>
 
 <screen><literal>usbfs  /proc/bus/usb  usbfs  devgid=14,devmode=0660  0  0</literal></screen>
 -->
-
+<!--
     <para>Add any users that need to access raw USB devices to the
     <systemitem class="groupname">usb</systemitem> group.</para>
 
 <screen role="root"><userinput>usermod -a -G usb <replaceable>&lt;username&gt;</replaceable></userinput></screen>
-
+-->
   </sect2>
 
   <sect2 role="content">

introduction/welcome/changelog.xml

@@ -44,6 +44,10 @@
     <listitem>
       <para>March 7th, 2010</para>
       <itemizedlist>
+        <listitem>
+          <para>[bdubbs] - Added additional information about
+          configuring USB devices.</para>
+        </listitem>
         <listitem>
           <para>[randy] - Updated to Freeglut-2.6.0.</para>
         </listitem>

postlfs/config/devices.xml

@@ -50,6 +50,65 @@ 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) is 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 
+    ypu will need ot 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>
 
@@ -71,17 +130,6 @@ options snd-ens1371 index=1</literal></screen>
 
   </sect2>
 
-  <sect2>
-    <title>USB Device Issues</title>
-
-    <para>Some older applications, such as <application>VMware</application>,
-    need the following deprecated entry in the <filename>/etc/fstab</filename>
-    file. This is not normally needed.</para>
-
-<screen><literal>usbfs  /proc/bus/usb  usbfs  devgid=14,devmode=0660  0  0</literal></screen>
-
-  </sect2>
-
 <!--
   <sect2>
     <title>Multiple Network Interfaces</title>