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.
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.
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”.
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
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/
.
In the following example, replace
username
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
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>.