17.4. USB Storage Devices
Prev | Chapter 17. Storage | Next

## 17.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.

### 17.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 17.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

### 17.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.

Prev | Up | Next
17.3. Resizing and Growing Disks | Home | 17.5. Creating and Using CD Media

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>.