Index: en_US.ISO8859-1/books/handbook/disks/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/handbook/disks/chapter.xml (revision 49693)
+++ en_US.ISO8859-1/books/handbook/disks/chapter.xml (working copy)
@@ -580,6 +580,133 @@
any block device, including optical drives or
iSCSI LUNs.
+
+
+ USB Mass Storage target
+
+
+ cfumass is supported
+ starting with &os; 12.0-CURRENT.
+
+
+ When running on USB OTG-compliant
+ hardware - which includes many embedded boards - the &os;
+ USB stack can run in device mode.
+ This makes it possible to "emulate" various kinds of
+ USB device classes, including serial ports,
+ network adapters, and mass storage, making the USB
+ host - eg a laptop - able to access them just like physical
+ USB devices.
+
+ Device mode support uses the usb_template kernel module.
+ When it's is loaded, switching between host-side and device-side
+ happens automatically, depending on what's connected to the
+ USB port. Connecting a USB
+ device - eg a flash key - to the USB OTG port
+ will make &os; switch to the host mode; connecting an
+ USB host - eg a PC - will result in switching
+ to device mode. It's not possible to connect the
+ USB OTG port to both USB
+ device and another USB host at the same time.
+
+ What &os; presents to the USB host
+ depends on the hw.usb.template sysctl. See
+ usb_template for the list of available values. Note
+ that in order for the host to take notice of the configuration change,
+ it needs to be either physically disconnected and reconnected
+ (unplugged and then plugged back), or forced to rescan the
+ USB bus in system-specific way. In case
+ of &os; running on the host, the "reset" subcommand to
+ &man.usbconfig.8; command can be used. This also needs to be done
+ after loading usb_template.ko if the
+ USB host was already connected to the
+ USB OTG socket.
+
+ To make &os; work as a USB Mass
+ Storage target, the hw.usb.template sysctl
+ needs to be set to 0. This is the default. In addition to
+ usb_template, the cfumass kernel module needs to be loaded.
+ This driver interfaces to the CTL subsystem, the same one that
+ is used for iSCSI or Fibre Channel targets.
+ Note that USB Mass Storage initiators (on the
+ host side) can only access a single LUN,
+ LUN 0.
+
+ Differently from iSCSI, USB Mass Storage
+ does not require the &man.ctld.8; daemon to be running - although
+ it can be used if one wishes so. Thus, there are two ways to
+ configure the target: using &man.ctladm.8; command, or by using
+ &man.ctld.8;. Both require the cfumass.ko
+ kernel module to be loaded. The module can be loaded manually:
+
+ &prompt.root; kldload cfumass
+
+ If the cfumass.ko kernel module
+ has not been built into the kernel, the
+ /boot/loader.conf should be edited to load
+ the module at boot:
+
+ cfumass_load="YES"
+
+ To create a LUN using &man.ctladm.8; - which doesn't
+ require the &man.ctld.8; daemon to be running - one should use the following
+ command:
+
+ &prompt.root; ctladm create -b block -o file=/data/target0
+
+ This will present contents of the image file
+ /data/target0 as a LUN to the
+ USB host. The path must exist before executing
+ the command. To configure the LUN at system startup,
+ add this command to /etc/rc.local.
+
+ Alternatively, one can use &man.ctld.8; to manage the LUNs. To configure
+ it, create the /etc/ctl.conf configuration file,
+ add a line to /etc/rc.conf to make sure the
+ &man.ctld.8; daemon is automatically started at boot, and then
+ start the daemon.
+
+ The following is an example of a simple
+ /etc/ctl.conf configuration file. Refer
+ to &man.ctl.conf.5; for a more complete description of this
+ file's available options.
+
+
+
+target naa.50015178f369f092 {
+ lun 0 {
+ path /data/target0
+ size 4G
+ }
+}
+
+ This a single target with a single LUN.
+ The naa.50015178f369f092 is a device
+ identifier; it's made of random 32 hexadecimal digits.
+ The path /data/target0-0 line
+ defines the full path to a file or zvol backing the
+ LUN. That path must exist before starting
+ &man.ctld.8;. The second line is optional and specifies the
+ size of the LUN.
+
+ Next, to make sure the &man.ctld.8; daemon is started at
+ boot, add this line to
+ /etc/rc.conf:
+
+ ctld_enable="YES"
+
+ To start &man.ctld.8; now, run this command:
+
+ &prompt.root; service ctld start
+
+ As the &man.ctld.8; daemon is started, it reads
+ /etc/ctl.conf. If this file is edited
+ after the daemon starts, use this command so that the changes
+ take effect immediately:
+
+ &prompt.root; service ctld reload
+
+