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:

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:

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

17.4.3.Â USB Mass Storage Target

Note:

The cfumass(4) driver is a USB
device mode driver first available in FreeBSDÂ 12.0.

When running on USBOTG-compliant hardware like that built into
many embedded boards, the FreeBSD USB stack
can run in device mode. Device mode
makes it possible for the computer to present itself as
different kinds of USB device classes,
including serial ports, network adapters, and mass storage. A
USB host like a laptop or desktop computer
is able to access them just like physical
USB devices.

The usb_template(4) kernel module allows the
USB stack to switch between host-side and
device-side automatically, depending on what is connected to
the USB port. Connecting a
USB device like a memory stick to the
USBOTG port causes FreeBSD
to switch to host mode. Connecting a USB
host like a computer causes FreeBSD to switch to device
mode.

What FreeBSD presents to the USB host
depends on the hw.usb.template sysctl. See
usb_template(4) for the list of available values. Note
that for the host to notice the configuration change, it must
be either physically disconnected and reconnected, or forced
to rescan the USB bus in a system-specific
way. When FreeBSD is running on the host, usbconfig(8)reset can be used. This also must be done
after loading usb_template.ko if the
USB host was already connected to the
USBOTG socket.

The hw.usb.template sysctl
is set to 0 by default, making FreeBSD work as a
USB Mass Storage target. Both
usb_template(4) and cfumass(4) kernel modules must
be loaded. cfumass(4) interfaces to the CTL subsystem,
the same one that is used for iSCSI or
Fibre Channel targets. On the host side,
USB Mass Storage initiators can only access
a single LUN,
LUN 0.

USB Mass Storage does not require the
ctld(8) daemon to be running, although it can be used if
desired. This is different from iSCSI.
Thus, there are two ways to configure the target:
ctladm(8), or ctld(8). Both require the
cfumass.ko kernel module to be loaded.
The module can be loaded manually:

#kldload cfumass

If cfumass.ko has not been built into
the kernel, /boot/loader.conf can be set
to load the module at boot:

This presents the contents of the image file
/data/target0 as a LUN
to the USB host. The file must exist
before executing the command. To configure the
LUN at system startup, add the command to
/etc/rc.local.

ctld(8) can also be used to manage
LUNs. Create
/etc/ctl.conf, add a line to
/etc/rc.conf to make sure ctld(8) is
automatically started at boot, and then start the
daemon.

This is an example of a simple
/etc/ctl.conf configuration file. Refer
to ctl.conf(5) for a more complete description of the
options.

target naa.50015178f369f092 {
lun 0 {
path /data/target0
size 4G
}
}

The example creates a single target with a single
LUN. The
naa.50015178f369f092 is a device identifier
composed of 32 random hexadecimal digits. The
path line defines the full path to a file
or zvol backing the LUN. That file must
exist before starting ctld(8). The second line is
optional and specifies the size of the
LUN.

To make sure the ctld(8) daemon is started at
boot, add this line to
/etc/rc.conf: