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

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

add path 'da[3-9]*' mode 0660 group operator

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

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

When running on USB OTG-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 USB OTG 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 USB OTG 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:

cfumass_load="YES"

A LUN can be created without the ctld(8) daemon:

# ctladm create -b block -o file=/data/target0

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:

ctld_enable="YES"

To start ctld(8) now, run this command:

# service ctld start

As the ctld(8) daemon is started, it reads /etc/ctl.conf. If this file is edited after the daemon starts, reload the changes so they take effect immediately:

# service ctld reload