18.4. USB Storage Devices

Contributed by Marc Fonvieille.

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

Note:

USB 3.0 support is not compatible with some hardware, including Haswell (Lynx point) chipsets. If FreeBSD boots with a failed with error 19 message, disable xHCI/USB3 in the system BIOS.

Support for USB storage devices is built into the GENERIC kernel. For a custom kernel, be sure that the following lines are present in the kernel configuration file:

device scbus	# SCSI bus (required for ATA/SCSI)
device da	# Direct Access (disks)
device pass	# Passthrough device (direct ATA/SCSI access)
device uhci	# provides USB 1.x support
device ohci	# provides USB 1.x support
device ehci	# provides USB 2.0 support
device xhci	# provides USB 3.0 support
device usb	# USB Bus (required)
device umass	# Disks/Mass storage - Requires scbus and da
device cd	# needed for CD and DVD burners

FreeBSD uses the umass(4) driver which uses the SCSI subsystem to access USB storage devices. Since any USB device will be seen as a SCSI device by the system, if the USB device is a CD or DVD burner, do not include device atapicam in a custom kernel configuration file.

The rest of this section demonstrates how to verify that a USB storage device is recognized by FreeBSD and how to configure the device so that it can be used.

18.4.1. Device Configuration

To test the USB configuration, plug in the USB device. Use dmesg to confirm that the drive appears in the system message buffer. It should look something like this:

umass0: <STECH Simple Drive, class 0/0, rev 2.00/1.04, addr 3> on usbus0
umass0:  SCSI over Bulk-Only; quirks = 0x0100
umass0:4:0:-1: Attached to scbus4
da0 at umass-sim0 bus 0 scbus4 target 0 lun 0
da0: <STECH Simple Drive 1.04> Fixed Direct Access SCSI-4 device
da0: Serial Number WD-WXE508CAN263
da0: 40.000MB/s transfers
da0: 152627MB (312581808 512 byte sectors: 255H 63S/T 19457C)
da0: quirks=0x2<NO_6_BYTE>

The brand, device node (da0), speed, and size 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
<STECH Simple Drive 1.04>          at scbus4 target 0 lun 0 (pass3,da0)

Alternately, usbconfig can be used to list the device. Refer to usbconfig(8) for more information about this command.

# usbconfig
ugen0.3: <Simple Drive STECH> at usbus0, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA)

If the device has not been formatted, refer to Section 18.2, “Adding Disks” for instructions on how to format and create partitions on the USB drive. If the drive comes with a file system, it can be mounted by root using the instructions in Section 3.7, “Mounting and Unmounting File Systems”.

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 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 operator 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 internal SCSI disks are also 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. Replace 3 with the number of internal SCSI disks. Refer to devfs.rules(5) for more information about this file.

Next, enable the ruleset in /etc/rc.conf:

devfs_system_ruleset="localrules"

Then, instruct the system to allow regular users to mount file systems by adding the following line to /etc/sysctl.conf:

vfs.usermount=1

Since this only takes effect after the next reboot, use sysctl to set this variable now:

# sysctl vfs.usermount=1
vfs.usermount: 0 -> 1

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 formatted with a FAT file system, the user can mount it using:

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

Before the device can be unplugged, it must be unmounted first:

% umount /mnt/username

After device removal, the system message buffer will show messages similar to the following:

umass0: at uhub3, port 2, addr 3 (disconnected)
da0 at umass-sim0 bus 0 scbus4 target 0 lun 0
da0: <STECH Simple Drive 1.04> s/n WD-WXE508CAN263          detached
(da0:umass-sim0:0:0:0): Periph destroyed

18.4.2. Automounting Removable Media

USB devices can be automatically mounted by uncommenting this line in /etc/auto_master:

/media		-media		-nosuid

Then add these lines to /etc/devd.conf:

notify 100 {
	match "system" "GEOM";
	match "subsystem" "DEV";
	action "/usr/sbin/automount -c";
};

Reload the configuration if autofs(5) and devd(8) are already running:

# service automount restart
# service devd restart

autofs(5) can be set to start at boot by adding this line to /etc/rc.conf:

autofs_enable="YES"

autofs(5) requires devd(8) to be enabled, as it is by default.

Start the services immediately with:

# service automount start
# service automountd start
# service autounmountd start
# service devd start

Each file system that can be automatically mounted appears as a directory in /media/. The directory is named after the file system label. If the label is missing, the directory is named after the device node.

The file system is transparently mounted on the first access, and unmounted after a period of inactivity. Automounted drives can also be unmounted manually:

# automount -fu

This mechanism is typically used for memory cards and USB memory sticks. It can be used with any block device, including optical drives or iSCSI LUNs.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/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>.