Editorial review of USB Storage Devices chapter.
Update examples. Add note for xhci. Incorporate resources into context. Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne
parent
f3add70998
commit
7945bd1282
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=44635
1 changed files with 93 additions and 85 deletions
|
|
@ -431,70 +431,70 @@ super-block backups (for fsck -b #) at:
|
|||
</indexterm>
|
||||
|
||||
<para>Many external storage solutions, such as hard drives,
|
||||
<acronym>USB</acronym> thumbdrives, and CD/DVD burners, use the
|
||||
<acronym>USB</acronym> thumbdrives, and <acronym>CD</acronym>
|
||||
and <acronym>DVD</acronym> burners, use the
|
||||
Universal Serial Bus (<acronym>USB</acronym>). &os; provides
|
||||
support for these devices.</para>
|
||||
support for <acronym>USB</acronym> 1.x, 2.0, and 3.0 devices.</para>
|
||||
|
||||
<sect2>
|
||||
<title>Configuration</title>
|
||||
|
||||
<para>The <acronym>USB</acronym> mass storage devices driver,
|
||||
&man.umass.4;, is built into the <filename>GENERIC</filename>
|
||||
kernel and provides support for <acronym>USB</acronym> storage
|
||||
devices. For a custom kernel, be sure that the following
|
||||
<note>
|
||||
<para><acronym>USB</acronym> 3.0 support is not compatible with
|
||||
some hardware, including Haswell (Lynx point) chipsets. If
|
||||
&os; boots with a <errorname>failed with error 19</errorname>
|
||||
message, disable xHCI/USB3 in the system
|
||||
<acronym>BIOS</acronym>.</para>
|
||||
</note>
|
||||
|
||||
<para>Support for <acronym>USB</acronym> storage devices
|
||||
is built into the <filename>GENERIC</filename>
|
||||
kernel. For a custom kernel, be sure that the following
|
||||
lines are present in the kernel configuration file:</para>
|
||||
|
||||
<programlisting>device scbus
|
||||
device da
|
||||
device pass
|
||||
device uhci
|
||||
device ohci
|
||||
device ehci
|
||||
device usb
|
||||
device umass</programlisting>
|
||||
<programlisting>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</programlisting>
|
||||
|
||||
<para>Since the &man.umass.4; driver uses the
|
||||
<acronym>SCSI</acronym> subsystem to access the
|
||||
<acronym>USB</acronym> storage devices, any
|
||||
<para>&os; uses the &man.umass.4; driver which uses the
|
||||
<acronym>SCSI</acronym> subsystem to access
|
||||
<acronym>USB</acronym> storage devices. Since any
|
||||
<acronym>USB</acronym> device will be seen as a
|
||||
<acronym>SCSI</acronym> device by the system. Depending on
|
||||
the <acronym>USB</acronym> chipset on the motherboard,
|
||||
<literal>device uhci</literal> or
|
||||
<literal>device ohci</literal> is used to provide
|
||||
<acronym>USB</acronym> 1.X support. Support for
|
||||
<acronym>USB</acronym> 2.0 controllers is provided by
|
||||
<literal>device ehci</literal>.</para>
|
||||
<acronym>SCSI</acronym> device by the system,
|
||||
if the <acronym>USB</acronym> device is a
|
||||
<acronym>CD</acronym> or <acronym>DVD</acronym> burner, do
|
||||
<emphasis>not</emphasis> include <option>device atapicam</option>
|
||||
in a custom kernel configuration file.</para>
|
||||
|
||||
<note>
|
||||
<para>If the <acronym>USB</acronym> device is a
|
||||
<acronym>CD</acronym> or <acronym>DVD</acronym> burner,
|
||||
&man.cd.4;, must be added to the kernel via the line:</para>
|
||||
|
||||
<programlisting>device cd</programlisting>
|
||||
|
||||
<para>Since the burner is seen as a <acronym>SCSI</acronym>
|
||||
drive, the driver &man.atapicam.4; should not be used in the
|
||||
kernel configuration.</para>
|
||||
</note>
|
||||
</sect2>
|
||||
<para>The rest of this section demonstrates how to verify that a
|
||||
<acronym>USB</acronym> storage device is recognized by &os; and
|
||||
how to configure the device so that it can be used.</para>
|
||||
|
||||
<sect2>
|
||||
<title>Testing the Configuration</title>
|
||||
<title>Device Configuration</title>
|
||||
|
||||
<para>To test the <acronym>USB</acronym> configuration, plug in
|
||||
the <acronym>USB</acronym> device. In the system message
|
||||
buffer, &man.dmesg.8;, the drive should appear as something
|
||||
like:</para>
|
||||
the <acronym>USB</acronym> device. Use
|
||||
<command>dmesg</command> to confirm that the drive appears in
|
||||
the system message buffer. It should look something
|
||||
like this:</para>
|
||||
|
||||
<screen>umass0: USB Solid state disk, rev 1.10/1.00, addr 2
|
||||
GEOM: create disk da0 dp=0xc2d74850
|
||||
da0 at umass-sim0 bus 0 target 0 lun 0
|
||||
da0: <Generic Traveling Disk 1.11> Removable Direct Access SCSI-2 device
|
||||
da0: 1.000MB/s transfers
|
||||
da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen>
|
||||
<screen>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></screen>
|
||||
|
||||
<para>The brand, device node (<filename>da0</filename>), and
|
||||
other details will differ according to the device.</para>
|
||||
<para>The brand, device node (<filename>da0</filename>), speed,
|
||||
and size will differ according to the device.</para>
|
||||
|
||||
<para>Since the <acronym>USB</acronym> device is seen as a
|
||||
<acronym>SCSI</acronym> one, <command>camcontrol</command> can
|
||||
|
|
@ -502,26 +502,36 @@ da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen>
|
|||
attached to the system:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>camcontrol devlist</userinput>
|
||||
<Generic Traveling Disk 1.11> at scbus0 target 0 lun 0 (da0,pass0)</screen>
|
||||
<STECH Simple Drive 1.04> at scbus4 target 0 lun 0 (pass3,da0)</screen>
|
||||
|
||||
<para>If the drive comes with a file system, it can be mounted.
|
||||
Refer to <xref linkend="disks-adding"/> for instructions on
|
||||
<para>Alternately, <command>usbconfig</command> can be used to
|
||||
list the device. Refer to &man.usbconfig.8; for more
|
||||
information about this command.</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>usbconfig</userinput>
|
||||
ugen0.3: <Simple Drive STECH> at usbus0, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA)</screen>
|
||||
|
||||
<para>If the device has not been formatted,
|
||||
refer to <xref linkend="disks-adding"/> for instructions on
|
||||
how to format and create partitions on the
|
||||
<acronym>USB</acronym> drive.</para>
|
||||
<acronym>USB</acronym> drive. If the drive comes with a file
|
||||
system, it can be mounted by <systemitem
|
||||
class="username">root</systemitem> using the
|
||||
instructions in <xref linkend="mount-unmount"/>.</para>
|
||||
|
||||
<warning>
|
||||
<para>Allowing untrusted users to mount arbitrary media, by
|
||||
enabling <varname>vfs.usermount</varname> as
|
||||
described below, should not be considered safe from a
|
||||
security point of view. Most file systems in &os; were not
|
||||
security point of view. Most file systems were not
|
||||
built to safeguard against malicious devices.</para>
|
||||
</warning>
|
||||
|
||||
<para>To make the device mountable as a normal user, one
|
||||
solution is to make all users of the device a member of the
|
||||
<systemitem class="groupname">operator</systemitem> group
|
||||
using &man.pw.8;. Next, ensure that the <systemitem
|
||||
class="groupname">operator</systemitem> group is able to
|
||||
using &man.pw.8;. Next, ensure that <systemitem
|
||||
class="groupname">operator</systemitem> is able to
|
||||
read and write the device by adding these lines to
|
||||
<filename>/etc/devfs.rules</filename>:</para>
|
||||
|
||||
|
|
@ -529,31 +539,37 @@ da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen>
|
|||
add path 'da*' mode 0660 group operator</programlisting>
|
||||
|
||||
<note>
|
||||
<para>If <acronym>SCSI</acronym> disks are installed in the
|
||||
<para>If internal <acronym>SCSI</acronym> disks are also installed in the
|
||||
system, change the second line as follows:</para>
|
||||
|
||||
<programlisting>add path 'da[3-9]*' mode 0660 group operator</programlisting>
|
||||
<programlisting>add path 'da[<replaceable>3</replaceable>-9]*' mode 0660 group operator</programlisting>
|
||||
|
||||
<para>This will exclude the first three
|
||||
<acronym>SCSI</acronym> disks (<filename>da0</filename> to
|
||||
<filename>da2</filename>)from belonging to the <systemitem
|
||||
class="groupname">operator</systemitem> group.</para>
|
||||
class="groupname">operator</systemitem> group. Replace
|
||||
<replaceable>3</replaceable> with the number of internal
|
||||
<acronym>SCSI</acronym> disks. Refer to &man.devfs.rules.5;
|
||||
for more information about this file.</para>
|
||||
</note>
|
||||
|
||||
<para>Next, enable the &man.devfs.rules.5; ruleset in
|
||||
<para>Next, enable the ruleset in
|
||||
<filename>/etc/rc.conf</filename>:</para>
|
||||
|
||||
<programlisting>devfs_system_ruleset="localrules"</programlisting>
|
||||
|
||||
<para>Next, instruct the running kernel to allow regular users
|
||||
to mount file systems. The easiest way is to add the
|
||||
<para>Then, instruct the system to allow regular users
|
||||
to mount file systems by adding the
|
||||
following line to
|
||||
<filename>/etc/sysctl.conf</filename>:</para>
|
||||
|
||||
<programlisting>vfs.usermount=1</programlisting>
|
||||
|
||||
<para>Since this only takes effect after the next reboot use
|
||||
&man.sysctl.8; to set this variable now.</para>
|
||||
<para>Since this only takes effect after the next reboot, use
|
||||
<command>sysctl</command> to set this variable now:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>sysctl vfs.usermount=1</userinput>
|
||||
vfs.usermount: 0 -> 1</screen>
|
||||
|
||||
<para>The final step is to create a directory where the file
|
||||
system is to be mounted. This directory needs to be owned by
|
||||
|
|
@ -571,32 +587,24 @@ add path 'da*' mode 0660 group operator</programlisting>
|
|||
|
||||
<para>Suppose a <acronym>USB</acronym> thumbdrive is plugged in,
|
||||
and a device <filename>/dev/da0s1</filename> appears. If the
|
||||
device is preformatted with a FAT file system, it can be
|
||||
mounted using:</para>
|
||||
device is formatted with a <acronym>FAT</acronym> file system, the user can
|
||||
mount it using:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/<replaceable>username</replaceable></userinput></screen>
|
||||
|
||||
<para>Before the device can be unplugged, it
|
||||
<emphasis>must</emphasis> be unmounted first. After device
|
||||
<emphasis>must</emphasis> be unmounted first:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>umount /mnt/<replaceable>username</replaceable></userinput></screen>
|
||||
|
||||
<para>After device
|
||||
removal, the system message buffer will show messages similar
|
||||
to the following:</para>
|
||||
|
||||
<screen>umass0: at uhub0 port 1 (addr 2) disconnected
|
||||
(da0:umass-sim0:0:0:0): lost device
|
||||
(da0:umass-sim0:0:0:0): removing device entry
|
||||
GEOM: destroy disk da0 dp=0xc2d74850
|
||||
umass0: detached</screen>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Further Reading</title>
|
||||
|
||||
<para>Beside the <link linkend="disks-adding">Adding
|
||||
Disks</link> and <link linkend="mount-unmount">Mounting and
|
||||
Unmounting File Systems</link> sections, reading various
|
||||
manual pages may also be useful: &man.umass.4;,
|
||||
&man.camcontrol.8;, and &man.usbconfig.8; under &os; 8.X
|
||||
or &man.usbdevs.8; under earlier versions of &os;.</para>
|
||||
<screen>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</screen>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue