From owner-svn-doc-all@freebsd.org Tue Feb 28 21:57:27 2017 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 97508CF101B; Tue, 28 Feb 2017 21:57:27 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 54F7BF92; Tue, 28 Feb 2017 21:57:27 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v1SLvQ4C060302; Tue, 28 Feb 2017 21:57:26 GMT (envelope-from wblock@FreeBSD.org) Received: (from wblock@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v1SLvQXJ060300; Tue, 28 Feb 2017 21:57:26 GMT (envelope-from wblock@FreeBSD.org) Message-Id: <201702282157.v1SLvQXJ060300@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: wblock set sender to wblock@FreeBSD.org using -f From: Warren Block Date: Tue, 28 Feb 2017 21:57:26 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50019 - in head: en_US.ISO8859-1/books/handbook/disks share/xml X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 28 Feb 2017 21:57:27 -0000 Author: wblock Date: Tue Feb 28 21:57:26 2017 New Revision: 50019 URL: https://svnweb.freebsd.org/changeset/doc/50019 Log: Submit documentation from trasz for his Foundation-sponsored work on the USB Mass Storage CTL front end. Submitted by: trasz Reviewed by: wblock Sponsored by: The FreeBSD Foundation and iXsystems Differential Revision: https://reviews.freebsd.org/D8788 Modified: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml head/share/xml/man-refs.ent Modified: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Tue Feb 28 16:37:05 2017 (r50018) +++ head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Tue Feb 28 21:57:26 2017 (r50019) @@ -580,6 +580,134 @@ da0: <STECH Simple Drive 1.04> s/n any block device, including optical drives or iSCSI LUNs. + + + <acronym>USB</acronym> Mass Storage Target + + + The &man.cfumass.4; driver is a USB + device mode driver that first became available in + &os; 12.0-CURRENT. + + + When running on USB + OTG-compliant hardware like that built into + many embedded boards, the &os; 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 &man.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 &os; + to switch to host mode. Connecting a USB + host like a computer causes &os; to switch to device + mode. + + What &os; presents to the USB host + depends on the hw.usb.template 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 USB bus in a system-specific + way. When &os; is running on the host, &man.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 &os; work as a + USB 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 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 + &man.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: + &man.ctladm.8;, or &man.ctld.8;. Both require the + cfumass.ko kernel module to be loaded. + The module can be loaded manually: + + &prompt.root; 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 + &man.ctld.8; daemon: + + &prompt.root; 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. + + &man.ctld.8; can also be used to manage + LUNs. Create + /etc/ctl.conf, add a line to + /etc/rc.conf to make sure &man.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 &man.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 &man.ctld.8;. The second line is + optional and specifies the size of the + LUN. + + 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, reload the changes so they take + effect immediately: + + &prompt.root; service ctld reload + Modified: head/share/xml/man-refs.ent ============================================================================== --- head/share/xml/man-refs.ent Tue Feb 28 16:37:05 2017 (r50018) +++ head/share/xml/man-refs.ent Tue Feb 28 21:57:26 2017 (r50019) @@ -7060,6 +7060,7 @@ central4"> cfi4"> cfid4"> +cfumass4"> ch4"> ciss4"> clkbrd4">