25.1 USB Storage Devices

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

FreeBSD uses the umass(4) driver to access USB storage devices through the SCSI subsystem. The system treats USB devices as SCSI devices.

This section describes how to verify that a USB storage device is recognized by FreeBSD and how to configure the device for use.

Device Configuration

To test the USB configuration, plug in the USB device. Use the dmesg command to confirm that the drive appears in the system message buffer, with output similar to the following:

ugen2.2: <Kingston DataTraveler 3.0> at usbus2
umass0 on uhub3
umass0: <Kingston DataTraveler 3.0, class 0/0, rev 3.20/1.10, addr 1> on usbus2
umass0:  SCSI over Bulk-Only; quirks = 0xc000<NO_SYNCHRONIZE_CACHE,NO_PREVENT_ALLOW>
umass0:3:0: Attached to scbus3
(probe0:umass-sim0:0:0:0): REPORT LUNS. CDB: a0 00 00 00 00 00 00 00 00 10 00 00
(probe0:umass-sim0:0:0:0): CAM status: SCSI Status Error
(probe0:umass-sim0:0:0:0): SCSI status: Check Condition
(probe0:umass-sim0:0:0:0): SCSI sense: ILLEGAL REQUEST asc:20,0 (Invalid command operation code)
(probe0:umass-sim0:0:0:0): Error 22, Unretryable error
da0 at umass-sim0 bus 0 scbus3 target 0 lun 0
da0: <Kingston DataTraveler 3.0 0000> Removable Direct Access SPC-4 SCSI device
da0: Serial Number E0D55EA5359C1750989B07F6
da0: 400.000MB/s transfers
da0: 59120MB (121077761 512 byte sectors)
da0: quirks=0x2<NO_6_BYTE>

The brand (Kingston DataTraveler 3.0), device node (da0), speed (400.000MB/s), and capacity (59120MB) vary depending on the device.

Since the system treats USB devices as SCSI devices, the camcontrol command can be used to list USB storage devices connected to the system:

# camcontrol devlist
<Kingston DataTraveler 3.0 0000>   at scbus3 target 0 lun 0 (da0,pass3)

......other irrelevant output omitted......

The usbconfig command can also be used to list devices.

# usbconfig
ugen2.2: <DataTraveler 100 G3/G4/SE9 G2/50 Kyson Kingston Technology> at usbus2, cfg=0 md=HOST spd=SUPER (5.0Gbps) pwr=ON (36mA)

......other irrelevant output omitted......

Mounting a USB Drive

The output above indicates that the USB device has been recognized as /dev/da0. If the device contains a partition table, its first partition is typically /dev/da0p1.

If the device is formatted with a FAT32 file system, users can mount it to /mnt using the following command:

# mount -t msdosfs /dev/da0p1 /mnt

Before unplugging the device, it must be unmounted first:

# umount /mnt

After physically unplugging the device, the system message buffer will display a message similar to the following:

ugen2.2: <Kingston DataTraveler 3.0> at usbus2 (disconnected)
umass0: at uhub3, port 1, addr 1 (disconnected)
da0 at umass-sim0 bus 0 scbus3 target 0 lun 0
da0: <Kingston DataTraveler 3.0 0000>  s/n E0D55EA5359C1750989B07F6 detached
(da0:umass-sim0:0:0:0): Periph destroyed
umass0: detached

Mounting USB Devices as a Regular User

To allow regular users to mount devices, add all users who will use the device to the operator group. Next, ensure that the operator group can read and write to the device by adding the following lines to /etc/devfs.rules:

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

Note

If other internal SCSI disks are also installed in the system, modify it as follows:

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

This will exclude the first 2 SCSI disks (da0 through da1) from the operator group. Replace 2 with the actual number of internal SCSI disks.

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

devfs_system_ruleset="localrules"

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

vfs.usermount=1

Warning

Although enabling vfs.usermount allows untrusted users to mount arbitrary media, this is not advisable from a security perspective. Most file systems are not designed to defend against malicious devices.

This setting only takes effect after the next reboot.

Finally, create a directory under which to mount the file system. The owner of this directory should be the user who will mount the file system. Use root to create a subdirectory owned by that user, such as /mnt/username. In the following example, replace username with the actual user name and usergroup with the user's primary group:

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

After that, a regular user can mount the USB storage device /dev/da0p1:

$ mount -t msdosfs -o -m=644,-M=755 /dev/da0p1 /mnt/username