docs/106148: [PATCH] extend the documentation for handling USB drives

[Roland Smith]

>Number:         106148
>Category:       docs
>Synopsis:       [PATCH] extend the documentation for handling USB drives
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Dec 01 18:20:10 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator:     Roland Smith
>Release:        FreeBSD 6.2-PRERELEASE amd64
>Organization:
>Environment:
System: FreeBSD slackbox.xs4all.nl 6.2-PRERELEASE FreeBSD 6.2-PRERELEASE #0: Sat Nov 25 00:14:25 CET 2006 rsmith at slackbox.xs4all.nl:/usr/obj/usr/src/sys/RFS amd64


	
>Description:
The disks chapter of the handbook is quite short in its description of the
handling of USB mass-storage drives. The included patch is an attempt to
expand/clarify this for new users.

	
>How-To-Repeat:
N/A
>Fix:
This patch has been tested to apply cleanly on revision 1.265 and 1.267.

------- patch for en_US.ISO8859-1/books/handbook/disks/chapter.sgml -------
--- chapter.sgml.orig	Sun Oct  8 17:01:02 2006
+++ chapter.sgml	Sun Oct  8 17:48:40 2006
@@ -777,6 +777,68 @@
       <para>to your configuration file for USB 2.0 support.  Note
 	&man.uhci.4; and &man.ohci.4; drivers are still needed if you
 	want USB 1.X support.</para>
+
+      <para>To make these devices mountable as a normal user, certain steps
+	have to be taken. First, the devices that are created when a USB
+	storage device is connected need to be accessible. A solution is to
+	create a group (e.g. named usb) that users of these devices need to
+	belong to. This is done with &man.pw.8;. The users in question also
+	need to be added to that group. This is also done with
+	&man.pw.8;. Second, when the devices are created, they have to be
+	accessible by this group. This is accomplished by adding a line for
+	these devices to &man.devfs.rules.5;;
+      </para>
+
+      <programlisting>add path 'da*' mode 0660 group usb</programlisting>
+
+      <note>
+	<para>If you already have SCSI disks in your system, you want to
+	  do this a bit different. E.g., if you already have
+	  disks <filename>da0</filename> through <filename>da2</filename>
+	  attached to the system, change the line as follows:
+	</para>
+
+	<programlisting>add path 'da[3-9]*' mode 0660 group usb</programlisting>
+
+	<para>This will exclude the already existing disks from the usb
+	  group.
+	</para>
+
+      </note>
+
+      <para>Next, the kernel has to be configured to allow regular users to
+	mount filesystems. The easiest way is to add the following line to
+	&man.sysctl.conf.5;:
+      </para>
+
+      <programlisting>vfs.usermount=1</programlisting>
+
+     <para>Note that this only takes effect after the next
+       reboot. Alternatively, one can also use &man.sysctl.8; to set this
+       variable.
+     </para>
+
+     <para>The final step is to create a directory where the filesystem is
+       to be mounted. This directory needs to be owned by the user that is
+       to mount the filesystem. One way to do that is for root to create a
+       subdirectory owned by that user
+       as <filename>/mnt/$USER</filename> (replace $USER by the login name
+       of the actual user):
+     </para>
+
+    <programlisting>
+mkdir /mnt/$USER
+chown $USER:$USER /mnt/$USER</programlisting>
+
+     <para>Suppose a USB thumbdrives is plugged in, and a
+       device <filename>/dev/da0s1</filename> appears. Since these devices
+       usually come preformatted with a FAT filesystem, one can mount them
+       like this:
+     </para>
+
+     <programlisting>mount_msdosfs -m 644 -M 755 /dev/da0s1
+       /mnt/$USER</programlisting>
+
     </sect2>
 
     <sect2>
------- patch for en_US.ISO8859-1/books/handbook/disks/chapter.sgml -------
>Release-Note:
>Audit-Trail:
>Unformatted: