18.5. USB Storage Devices

Contributed by Marc Fonvieille.

Many external storage solutions, such as hard drives, USB thumbdrives, and CD/DVD burners, use the Universal Serial Bus (USB). FreeBSD provides support for these devices.

18.5.1. Configuration

The USB mass storage devices driver, umass(4), is built into the GENERIC kernel and provides support for USB storage devices. For a custom kernel, be sure that the following lines are present in the kernel configuration file:

device scbus
device da
device pass
device uhci
device ohci
device ehci
device usb
device umass

Since the umass(4) driver uses the SCSI subsystem to access the USB storage devices, any USB device will be seen as a SCSI device by the system. Depending on the USB chipset on the motherboard, device uhci or device ohci is used to provide USB 1.X support. Support for USB 2.0 controllers is provided by device ehci.

Note:

If the USB device is a CD or DVD burner, cd(4), must be added to the kernel via the line:

device cd

Since the burner is seen as a SCSI drive, the driver atapicam(4) should not be used in the kernel configuration.

18.5.2. Testing the Configuration

To test the USB configuration, plug in the USB device. In the system message buffer, dmesg(8), the drive should appear as something like:

umass0: USB Solid state disk, rev 1.10/1.00, addr 2
GEOM: create disk da0 dp=0xc2d74850
da0 at umass-sim0 bus 0 target 0 lun 0
da0: <Generic Traveling Disk 1.11> Removable Direct Access SCSI-2 device
da0: 1.000MB/s transfers
da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)

The brand, device node (da0), and other details will differ according to the device.

Since the USB device is seen as a SCSI one, camcontrol can be used to list the USB storage devices attached to the system:

# camcontrol devlist
<Generic Traveling Disk 1.11>      at scbus0 target 0 lun 0 (da0,pass0)

If the drive comes with a file system, it can be mounted. Refer to Section 18.3, “Adding Disks” for instructions on how to format and create partitions on the USB drive.

Warning:

Allowing untrusted users to mount arbitrary media, by enabling vfs.usermount as described below, should not be considered safe from a security point of view. Most file systems in FreeBSD were not built to safeguard against malicious devices.

To make the device mountable as a normal user, one solution is to make all users of the device a member of the operator group using pw(8). Next, ensure that the operator group is able to read and write the device by adding these lines to /etc/devfs.rules:

[localrules=5]
add path 'da*' mode 0660 group operator

Note:

If SCSI disks are installed in the system, change the second line as follows:

add path 'da[3-9]*' mode 0660 group operator

This will exclude the first three SCSI disks (da0 to da2)from belonging to the operator group.

Next, enable the devfs.rules(5) ruleset in /etc/rc.conf:

devfs_system_ruleset="localrules"

Next, instruct the running kernel to allow regular users to mount file systems. The easiest way is to add the following line to /etc/sysctl.conf:

vfs.usermount=1

Since this only takes effect after the next reboot use sysctl(8) to set this variable now.

The final step is to create a directory where the file system is to be mounted. This directory needs to be owned by the user that is to mount the file system. One way to do that is for root to create a subdirectory owned by that user as /mnt/username. In the following example, replace username with the login name of the user and usergroup with the user's primary group:

# mkdir /mnt/username
# chown username:usergroup /mnt/username

Suppose a USB thumbdrive is plugged in, and a device /dev/da0s1 appears. If the device is preformatted with a FAT file system, it can be mounted using:

% mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/username

Before the device can be unplugged, it must be unmounted first. After device removal, the system message buffer will show messages similar to the following:

umass0: at uhub0 port 1 (addr 2) disconnected
(da0:umass-sim0:0:0:0): lost device
(da0:umass-sim0:0:0:0): removing device entry
GEOM: destroy disk da0 dp=0xc2d74850
umass0: detached

18.5.3. Further Reading

Beside the Adding Disks and Mounting and Unmounting File Systems sections, reading various manual pages may also be useful: umass(4), camcontrol(8), and usbconfig(8) under FreeBSD  8.X or usbdevs(8) under earlier versions of FreeBSD.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.