Introduce a new chapter on USB Device Mode / USB OTG.
Reviewed by: bcr@ Approved by: bcr@ MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D15513
This commit is contained in:
Edward Tomasz Napierala
parent
4df1e538fc
commit
e6ffac0a54
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=51744
5 changed files with 377 additions and 127 deletions
|
|
@ -200,6 +200,7 @@ SRCS+= preface/preface.xml
|
||||||
SRCS+= printing/chapter.xml
|
SRCS+= printing/chapter.xml
|
||||||
SRCS+= security/chapter.xml
|
SRCS+= security/chapter.xml
|
||||||
SRCS+= serialcomms/chapter.xml
|
SRCS+= serialcomms/chapter.xml
|
||||||
|
SRCS+= usb-device-mode/chapter.xml
|
||||||
SRCS+= virtualization/chapter.xml
|
SRCS+= virtualization/chapter.xml
|
||||||
SRCS+= x11/chapter.xml
|
SRCS+= x11/chapter.xml
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -253,6 +253,7 @@
|
||||||
&chap.l10n;
|
&chap.l10n;
|
||||||
&chap.cutting-edge;
|
&chap.cutting-edge;
|
||||||
&chap.dtrace;
|
&chap.dtrace;
|
||||||
|
&chap.usb-device-mode;
|
||||||
</part>
|
</part>
|
||||||
|
|
||||||
<part xml:id="network-communication">
|
<part xml:id="network-communication">
|
||||||
|
|
|
||||||
|
|
@ -42,6 +42,7 @@
|
||||||
<!ENTITY chap.l10n SYSTEM "l10n/chapter.xml">
|
<!ENTITY chap.l10n SYSTEM "l10n/chapter.xml">
|
||||||
<!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.xml">
|
<!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.xml">
|
||||||
<!ENTITY chap.dtrace SYSTEM "dtrace/chapter.xml">
|
<!ENTITY chap.dtrace SYSTEM "dtrace/chapter.xml">
|
||||||
|
<!ENTITY chap.usb-device-mode SYSTEM "usb-device-mode/chapter.xml">
|
||||||
|
|
||||||
<!-- Part Four -->
|
<!-- Part Four -->
|
||||||
<!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.xml">
|
<!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.xml">
|
||||||
|
|
|
||||||
|
|
@ -588,133 +588,6 @@ da0: <STECH Simple Drive 1.04> s/n WD-WXE508CAN263 detached
|
||||||
any block device, including optical drives or
|
any block device, including optical drives or
|
||||||
<acronym>iSCSI</acronym> <acronym>LUN</acronym>s.</para>
|
<acronym>iSCSI</acronym> <acronym>LUN</acronym>s.</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title><acronym>USB</acronym> Mass Storage Target</title>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>The &man.cfumass.4; driver is a <acronym>USB</acronym>
|
|
||||||
device mode driver first available in &os; 12.0.</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>When running on <acronym>USB</acronym>
|
|
||||||
<acronym>OTG</acronym>-compliant hardware like that built into
|
|
||||||
many embedded boards, the &os; <acronym>USB</acronym> stack
|
|
||||||
can run in <emphasis>device mode</emphasis>. Device mode
|
|
||||||
makes it possible for the computer to present itself as
|
|
||||||
different kinds of <acronym>USB</acronym> device classes,
|
|
||||||
including serial ports, network adapters, and mass storage. A
|
|
||||||
<acronym>USB</acronym> host like a laptop or desktop computer
|
|
||||||
is able to access them just like physical
|
|
||||||
<acronym>USB</acronym> devices.</para>
|
|
||||||
|
|
||||||
<para>The &man.usb.template.4; kernel module allows the
|
|
||||||
<acronym>USB</acronym> stack to switch between host-side and
|
|
||||||
device-side automatically, depending on what is connected to
|
|
||||||
the <acronym>USB</acronym> port. Connecting a
|
|
||||||
<acronym>USB</acronym> device like a memory stick to the
|
|
||||||
<acronym>USB</acronym> <acronym>OTG</acronym> port causes &os;
|
|
||||||
to switch to host mode. Connecting a <acronym>USB</acronym>
|
|
||||||
host like a computer causes &os; to switch to device
|
|
||||||
mode.</para>
|
|
||||||
|
|
||||||
<para>What &os; presents to the <acronym>USB</acronym> host
|
|
||||||
depends on the <varname>hw.usb.template</varname> sysctl. See
|
|
||||||
&man.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 <acronym>USB</acronym> bus in a system-specific
|
|
||||||
way. When &os; is running on the host, &man.usbconfig.8;
|
|
||||||
<command>reset</command> can be used. This also must be done
|
|
||||||
after loading <filename>usb_template.ko</filename> if the
|
|
||||||
<acronym>USB</acronym> host was already connected to the
|
|
||||||
<acronym>USB</acronym> <acronym>OTG</acronym> socket.</para>
|
|
||||||
|
|
||||||
<para>The <varname>hw.usb.template</varname> sysctl
|
|
||||||
is set to 0 by default, making &os; work as a
|
|
||||||
<acronym>USB</acronym> Mass Storage target. Both
|
|
||||||
&man.usb.template.4; and &man.cfumass.4; kernel modules must
|
|
||||||
be loaded. &man.cfumass.4; interfaces to the CTL subsystem,
|
|
||||||
the same one that is used for <acronym>iSCSI</acronym> or
|
|
||||||
Fibre Channel targets. On the host side,
|
|
||||||
<acronym>USB</acronym> Mass Storage initiators can only access
|
|
||||||
a single <acronym>LUN</acronym>,
|
|
||||||
<acronym>LUN</acronym> 0.</para>
|
|
||||||
|
|
||||||
<para><acronym>USB</acronym> Mass Storage does not require the
|
|
||||||
&man.ctld.8; daemon to be running, although it can be used if
|
|
||||||
desired. This is different from <acronym>iSCSI</acronym>.
|
|
||||||
Thus, there are two ways to configure the target:
|
|
||||||
&man.ctladm.8;, or &man.ctld.8;. Both require the
|
|
||||||
<filename>cfumass.ko</filename> kernel module to be loaded.
|
|
||||||
The module can be loaded manually:</para>
|
|
||||||
|
|
||||||
<screen>&prompt.root; <userinput>kldload cfumass</userinput></screen>
|
|
||||||
|
|
||||||
<para>If <filename>cfumass.ko</filename> has not been built into
|
|
||||||
the kernel, <filename>/boot/loader.conf</filename> can be set
|
|
||||||
to load the module at boot:</para>
|
|
||||||
|
|
||||||
<programlisting>cfumass_load="YES"</programlisting>
|
|
||||||
|
|
||||||
<para>A <acronym>LUN</acronym> can be created without the
|
|
||||||
&man.ctld.8; daemon:</para>
|
|
||||||
|
|
||||||
<screen>&prompt.root; <userinput>ctladm create -b block -o file=/data/target0</userinput></screen>
|
|
||||||
|
|
||||||
<para>This presents the contents of the image file
|
|
||||||
<filename>/data/target0</filename> as a <acronym>LUN</acronym>
|
|
||||||
to the <acronym>USB</acronym> host. The file must exist
|
|
||||||
before executing the command. To configure the
|
|
||||||
<acronym>LUN</acronym> at system startup, add the command to
|
|
||||||
<filename>/etc/rc.local</filename>.</para>
|
|
||||||
|
|
||||||
<para>&man.ctld.8; can also be used to manage
|
|
||||||
<acronym>LUN</acronym>s. Create
|
|
||||||
<filename>/etc/ctl.conf</filename>, add a line to
|
|
||||||
<filename>/etc/rc.conf</filename> to make sure &man.ctld.8; is
|
|
||||||
automatically started at boot, and then start the
|
|
||||||
daemon.</para>
|
|
||||||
|
|
||||||
<para>This is an example of a simple
|
|
||||||
<filename>/etc/ctl.conf</filename> configuration file. Refer
|
|
||||||
to &man.ctl.conf.5; for a more complete description of the
|
|
||||||
options.</para>
|
|
||||||
|
|
||||||
<programlisting>target naa.50015178f369f092 {
|
|
||||||
lun 0 {
|
|
||||||
path /data/target0
|
|
||||||
size 4G
|
|
||||||
}
|
|
||||||
}</programlisting>
|
|
||||||
|
|
||||||
<para>The example creates a single target with a single
|
|
||||||
<acronym>LUN</acronym>. The
|
|
||||||
<literal>naa.50015178f369f092</literal> is a device identifier
|
|
||||||
composed of 32 random hexadecimal digits. The
|
|
||||||
<literal>path</literal> line defines the full path to a file
|
|
||||||
or zvol backing the <acronym>LUN</acronym>. That file must
|
|
||||||
exist before starting &man.ctld.8;. The second line is
|
|
||||||
optional and specifies the size of the
|
|
||||||
<acronym>LUN</acronym>.</para>
|
|
||||||
|
|
||||||
<para>To make sure the &man.ctld.8; daemon is started at
|
|
||||||
boot, add this line to
|
|
||||||
<filename>/etc/rc.conf</filename>:</para>
|
|
||||||
|
|
||||||
<programlisting>ctld_enable="YES"</programlisting>
|
|
||||||
|
|
||||||
<para>To start &man.ctld.8; now, run this command:</para>
|
|
||||||
|
|
||||||
<screen>&prompt.root; <userinput>service ctld start</userinput></screen>
|
|
||||||
|
|
||||||
<para>As the &man.ctld.8; daemon is started, it reads
|
|
||||||
<filename>/etc/ctl.conf</filename>. If this file is edited
|
|
||||||
after the daemon starts, reload the changes so they take
|
|
||||||
effect immediately:</para>
|
|
||||||
|
|
||||||
<screen>&prompt.root; <userinput>service ctld reload</userinput></screen>
|
|
||||||
</sect2>
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 xml:id="creating-cds">
|
<sect1 xml:id="creating-cds">
|
||||||
|
|
|
||||||
374
en_US.ISO8859-1/books/handbook/usb-device-mode/chapter.xml
Normal file
374
en_US.ISO8859-1/books/handbook/usb-device-mode/chapter.xml
Normal file
|
|
@ -0,0 +1,374 @@
|
||||||
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||||
|
<!--
|
||||||
|
The FreeBSD Documentation Project
|
||||||
|
|
||||||
|
$FreeBSD$
|
||||||
|
-->
|
||||||
|
|
||||||
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||||
|
xml:id="usb-device-mode">
|
||||||
|
|
||||||
|
<title>USB Device Mode</title>
|
||||||
|
|
||||||
|
<sect1 xml:id="usb-device-mode-synopsis">
|
||||||
|
<title>Synopsis</title>
|
||||||
|
|
||||||
|
<info>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<personname>
|
||||||
|
<firstname>Edward Tomasz</firstname>
|
||||||
|
<surname>Napierala</surname>
|
||||||
|
</personname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>trasz@FreeBSD.org</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
<contrib>Written by </contrib>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
</info>
|
||||||
|
|
||||||
|
<para>This chapter covers the use of USB Device Mode and USB On
|
||||||
|
The Go (<acronym>USB OTG</acronym>) in &os;. This includes
|
||||||
|
virtual serial consoles, virtual network interfaces, and
|
||||||
|
virtual USB drives.</para>
|
||||||
|
|
||||||
|
<para>When running on hardware that supports USB device mode
|
||||||
|
or <acronym>USB OTG</acronym>, like that built into
|
||||||
|
many embedded boards, the &os; <acronym>USB</acronym> stack
|
||||||
|
can run in <emphasis>device mode</emphasis>. Device mode
|
||||||
|
makes it possible for the computer to present itself as
|
||||||
|
different kinds of <acronym>USB</acronym> device classes,
|
||||||
|
including serial ports, network adapters, and mass storage,
|
||||||
|
or a combination thereof. A <acronym>USB</acronym> host like
|
||||||
|
a laptop or desktop computer is able to access them just like
|
||||||
|
physical <acronym>USB</acronym> devices.</para>
|
||||||
|
|
||||||
|
<para>There are two basic ways the hardware can provide the
|
||||||
|
device mode functionality: with a separate "client port", which
|
||||||
|
only supports the device mode, and with a USB OTG port, which
|
||||||
|
can provide both device and host mode. For
|
||||||
|
<acronym>USB OTG</acronym> ports, the <acronym>USB</acronym>
|
||||||
|
stack switches between host-side and device-side automatically,
|
||||||
|
depending on what is connected to the port. Connecting a
|
||||||
|
<acronym>USB</acronym> device like a memory stick to the
|
||||||
|
port causes &os; to switch to host mode. Connecting a
|
||||||
|
<acronym>USB</acronym> host like a computer causes &os; to
|
||||||
|
switch to device mode. Single purpose "client ports" always
|
||||||
|
work in device mode.</para>
|
||||||
|
|
||||||
|
<para>What &os; presents to the <acronym>USB</acronym> host
|
||||||
|
depends on the <varname>hw.usb.template</varname> sysctl. Some
|
||||||
|
templates provide a single device, such as a serial terminal;
|
||||||
|
others provide multiple ones, which can all be used at the same
|
||||||
|
time. An example is the template 10, which provides a mass
|
||||||
|
storage device, a serial console, and a network interface.
|
||||||
|
See &man.usb.template.4; for the list of available
|
||||||
|
values.</para>
|
||||||
|
|
||||||
|
<para>Note that in some cases, depending on the hardware and the
|
||||||
|
hosts operating system, for the host to notice the configuration
|
||||||
|
change, it must be either physically disconnected and
|
||||||
|
reconnected, or forced to rescan the <acronym>USB</acronym>
|
||||||
|
bus in a system-specific way. When &os; is running on the host,
|
||||||
|
&man.usbconfig.8; <command>reset</command> can be used.
|
||||||
|
This also must be done after loading
|
||||||
|
<filename>usb_template.ko</filename> if the
|
||||||
|
<acronym>USB</acronym> host was already connected to the
|
||||||
|
<acronym>USB</acronym> <acronym>OTG</acronym> socket.</para>
|
||||||
|
|
||||||
|
<para>After reading this chapter, you will know:</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>How to set up USB Device Mode functionality on
|
||||||
|
&os;.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>How to configure the virtual serial port on
|
||||||
|
&os;.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>How to connect to the virtual serial port
|
||||||
|
from various operating systems.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>How to configure &os; to provide a virtual
|
||||||
|
<acronym>USB</acronym> network interface.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>How to configure &os; to provide a virtual
|
||||||
|
<acronym>USB</acronym> storage device.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="usb-device-mode-terminals">
|
||||||
|
<title><acronym>USB</acronym> Virtual Serial Ports</title>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Configuring USB Device Mode Serial Ports</title>
|
||||||
|
|
||||||
|
<para>Virtual serial port support is provided by templates
|
||||||
|
number 3, 8, and 10. Note that template 3 works with
|
||||||
|
Microsoft Windows 10 without the need for special drivers
|
||||||
|
and INF files. Other host operating systems work with all
|
||||||
|
three templates. Both &man.usb.template.4; and &man.umodem.4;
|
||||||
|
kernel modules must be loaded.</para>
|
||||||
|
|
||||||
|
<para>To enable USB device mode serial ports, add those lines
|
||||||
|
to <filename>/etc/ttys</filename>:</para>
|
||||||
|
|
||||||
|
<screen>ttyU0 "/usr/libexec/getty 3wire" vt100 onifconsole secure
|
||||||
|
ttyU1 "/usr/libexec/getty 3wire" vt100 onifconsole secure</screen>
|
||||||
|
|
||||||
|
<para>Then add these lines to
|
||||||
|
<filename>/etc/devd.conf</filename>:</para>
|
||||||
|
|
||||||
|
<screen>notify 100 {
|
||||||
|
match "system" "DEVFS";
|
||||||
|
match "subsystem" "CDEV";
|
||||||
|
match "type" "CREATE";
|
||||||
|
match "cdev" "ttyU[0-9]+";
|
||||||
|
action "/sbin/init q";
|
||||||
|
};</screen>
|
||||||
|
|
||||||
|
<para>Reload the configuration if
|
||||||
|
&man.devd.8; is already running:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>service devd restart</userinput></screen>
|
||||||
|
|
||||||
|
<para>Make sure the necessary modules are loaded and the
|
||||||
|
correct template is set at boot by adding
|
||||||
|
those lines to <filename>/boot/loader.conf</filename>,
|
||||||
|
creating it if it does not already exist:</para>
|
||||||
|
|
||||||
|
<screen>umodem_load="YES"
|
||||||
|
hw.usb.template=3</screen>
|
||||||
|
|
||||||
|
<para>To load the module and set the template without rebooting
|
||||||
|
use:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>kldload umodem</userinput>
|
||||||
|
&prompt.root; <userinput>sysctl hw.usb.template=3</userinput></screen>
|
||||||
|
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Connecting to USB Device Mode Serial Ports from
|
||||||
|
&os;</title>
|
||||||
|
|
||||||
|
<para>To connect to a board configured to provide USB device
|
||||||
|
mode serial ports, connect the USB host, such as a laptop, to
|
||||||
|
the boards USB OTG or USB client port. Use
|
||||||
|
<command>pstat -t</command> on the host to list the terminal
|
||||||
|
lines. Near the end of the list you should see a USB serial
|
||||||
|
port, eg "ttyU0". To open the connection, use:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>cu -l /dev/ttyU0</userinput></screen>
|
||||||
|
|
||||||
|
<para>After pressing the Enter key a few times you will see
|
||||||
|
a login prompt.</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Connecting to USB Device Mode Serial Ports from
|
||||||
|
macOS</title>
|
||||||
|
|
||||||
|
<para>To connect to a board configured to provide USB device
|
||||||
|
mode serial ports, connect the USB host, such as a laptop,
|
||||||
|
to the boards USB OTG or USB client port. To open the
|
||||||
|
connection, use:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>cu -l /dev/cu.usbmodemFreeBSD1</userinput></screen>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Connecting to USB Device Mode Serial Ports from
|
||||||
|
Linux</title>
|
||||||
|
|
||||||
|
<para>To connect to a board configured to provide USB device
|
||||||
|
mode serial ports, connect the USB host, such as a laptop,
|
||||||
|
to the boards USB OTG or USB client port. To open the
|
||||||
|
connection, use:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>minicom -D /dev/ttyACM0</userinput></screen>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Connecting to USB Device Mode Serial Ports from
|
||||||
|
Microsoft Windows 10</title>
|
||||||
|
|
||||||
|
<para>To connect to a board configured to provide USB device
|
||||||
|
mode serial ports, connect the USB host, such as a laptop,
|
||||||
|
to the boards USB OTG or USB client port. To open a
|
||||||
|
connection you will need a serial terminal program, such as
|
||||||
|
<application>PuTTY</application>. To check the COM port name
|
||||||
|
used by Windows, run Device Manager, expand "Ports (COM &
|
||||||
|
LPT)". You will see a name similar to "USB Serial Device
|
||||||
|
(COM4)". Run serial terminal program of your choice, for
|
||||||
|
example <application>PuTTY</application>. In the
|
||||||
|
<application>PuTTY</application> dialog set "Connection type"
|
||||||
|
to "Serial", type the COMx obtained from Device Manager in the
|
||||||
|
"Serial line" dialog box and click Open.</para>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="usb-device-mode-network">
|
||||||
|
|
||||||
|
<title><acronym>USB</acronym> Device Mode Network
|
||||||
|
Interfaces</title>
|
||||||
|
|
||||||
|
<para>Virtual network interfaces support is provided by templates
|
||||||
|
number 1, 8, and 10. Note that none of them works with
|
||||||
|
Microsoft Windows. Other host operating systems work with all
|
||||||
|
three templates. Both &man.usb.template.4; and &man.if.cdce.4;
|
||||||
|
kernel modules must be loaded.</para>
|
||||||
|
|
||||||
|
<para>Make sure the necessary modules are loaded and the correct
|
||||||
|
template is set at boot by adding
|
||||||
|
those lines to <filename>/boot/loader.conf</filename>, creating
|
||||||
|
it if it does not already exist:</para>
|
||||||
|
|
||||||
|
<screen>if_cdce_load="YES"
|
||||||
|
hw.usb.template=1</screen>
|
||||||
|
|
||||||
|
<para>To load the module and set the template without rebooting
|
||||||
|
use:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>kldload if_cdce</userinput>
|
||||||
|
&prompt.root; <userinput>sysctl hw.usb.template=1</userinput></screen>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="usb-device-mode-storage">
|
||||||
|
<title><acronym>USB</acronym> Virtual Storage Device</title>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>The &man.cfumass.4; driver is a <acronym>USB</acronym>
|
||||||
|
device mode driver first available in &os; 12.0.</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<para>Mass Storage target is provided by templates 0 and 10.
|
||||||
|
Both &man.usb.template.4; and &man.cfumass.4; kernel modules
|
||||||
|
must be loaded. &man.cfumass.4; interfaces to the CTL
|
||||||
|
subsystem, the same one that is used for
|
||||||
|
<acronym>iSCSI</acronym> or Fibre Channel targets.
|
||||||
|
On the host side, <acronym>USB</acronym> Mass Storage
|
||||||
|
initiators can only access a single <acronym>LUN</acronym>,
|
||||||
|
<acronym>LUN</acronym> 0.</para>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>Configuring USB Mass Storage Target Using the cfumass
|
||||||
|
Startup Script</title>
|
||||||
|
|
||||||
|
<para>The simplest way to set up a read-only USB storage target
|
||||||
|
is to use the <filename>cfumass</filename> rc script. To
|
||||||
|
configure it this way, copy the files to be presented to the
|
||||||
|
USB host machine into the <literal>/var/cfumass</literal>
|
||||||
|
directory, and add this line to
|
||||||
|
<filename>/etc/rc.conf</filename>:</para>
|
||||||
|
|
||||||
|
<programlisting>cfumass_enable="YES"</programlisting>
|
||||||
|
|
||||||
|
<para>To configure the target without restarting,
|
||||||
|
run this command:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>service cfumass start</userinput></screen>
|
||||||
|
|
||||||
|
<para>Differently from serial and network functionality, the
|
||||||
|
template should not be set to 0 or 10 in
|
||||||
|
<filename>/boot/loader.conf</filename>. This is because the
|
||||||
|
LUN must be set up before setting the template. The cfumass
|
||||||
|
startup script sets the correct template number automatically
|
||||||
|
when started.</para>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title>Configuring USB Mass Storage Using Other Means</title>
|
||||||
|
|
||||||
|
<para>The rest of this chapter provides detailed description of
|
||||||
|
setting the target without using the cfumass rc file. This is
|
||||||
|
necessary if eg one wants to provide a writeable LUN.</para>
|
||||||
|
|
||||||
|
<para><acronym>USB</acronym> Mass Storage does not require the
|
||||||
|
&man.ctld.8; daemon to be running, although it can be used if
|
||||||
|
desired. This is different from <acronym>iSCSI</acronym>.
|
||||||
|
Thus, there are two ways to configure the target:
|
||||||
|
&man.ctladm.8;, or &man.ctld.8;. Both require the
|
||||||
|
<filename>cfumass.ko</filename> kernel module to be loaded.
|
||||||
|
The module can be loaded manually:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>kldload cfumass</userinput></screen>
|
||||||
|
|
||||||
|
<para>If <filename>cfumass.ko</filename> has not been built into
|
||||||
|
the kernel, <filename>/boot/loader.conf</filename> can be set
|
||||||
|
to load the module at boot:</para>
|
||||||
|
|
||||||
|
<programlisting>cfumass_load="YES"</programlisting>
|
||||||
|
|
||||||
|
<para>A <acronym>LUN</acronym> can be created without the
|
||||||
|
&man.ctld.8; daemon:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>ctladm create -b block -o file=/data/target0</userinput></screen>
|
||||||
|
|
||||||
|
<para>This presents the contents of the image file
|
||||||
|
<filename>/data/target0</filename> as a <acronym>LUN</acronym>
|
||||||
|
to the <acronym>USB</acronym> host. The file must exist
|
||||||
|
before executing the command. To configure the
|
||||||
|
<acronym>LUN</acronym> at system startup, add the command to
|
||||||
|
<filename>/etc/rc.local</filename>.</para>
|
||||||
|
|
||||||
|
<para>&man.ctld.8; can also be used to manage
|
||||||
|
<acronym>LUN</acronym>s. Create
|
||||||
|
<filename>/etc/ctl.conf</filename>, add a line to
|
||||||
|
<filename>/etc/rc.conf</filename> to make sure &man.ctld.8; is
|
||||||
|
automatically started at boot, and then start the
|
||||||
|
daemon.</para>
|
||||||
|
|
||||||
|
<para>This is an example of a simple
|
||||||
|
<filename>/etc/ctl.conf</filename> configuration file. Refer
|
||||||
|
to &man.ctl.conf.5; for a more complete description of the
|
||||||
|
options.</para>
|
||||||
|
|
||||||
|
<programlisting>target naa.50015178f369f092 {
|
||||||
|
lun 0 {
|
||||||
|
path /data/target0
|
||||||
|
size 4G
|
||||||
|
}
|
||||||
|
}</programlisting>
|
||||||
|
|
||||||
|
<para>The example creates a single target with a single
|
||||||
|
<acronym>LUN</acronym>. The
|
||||||
|
<literal>naa.50015178f369f092</literal> is a device identifier
|
||||||
|
composed of 32 random hexadecimal digits. The
|
||||||
|
<literal>path</literal> line defines the full path to a file
|
||||||
|
or zvol backing the <acronym>LUN</acronym>. That file must
|
||||||
|
exist before starting &man.ctld.8;. The second line is
|
||||||
|
optional and specifies the size of the
|
||||||
|
<acronym>LUN</acronym>.</para>
|
||||||
|
|
||||||
|
<para>To make sure the &man.ctld.8; daemon is started at
|
||||||
|
boot, add this line to
|
||||||
|
<filename>/etc/rc.conf</filename>:</para>
|
||||||
|
|
||||||
|
<programlisting>ctld_enable="YES"</programlisting>
|
||||||
|
|
||||||
|
<para>To start &man.ctld.8; now, run this command:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>service ctld start</userinput></screen>
|
||||||
|
|
||||||
|
<para>As the &man.ctld.8; daemon is started, it reads
|
||||||
|
<filename>/etc/ctl.conf</filename>. If this file is edited
|
||||||
|
after the daemon starts, reload the changes so they take
|
||||||
|
effect immediately:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>service ctld reload</userinput></screen>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
Loading…
Reference in a new issue