From owner-svn-doc-all@FreeBSD.ORG Wed Mar 19 13:19:47 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 6F292A0F; Wed, 19 Mar 2014 13:19:47 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 4F34360B; Wed, 19 Mar 2014 13:19:47 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2JDJlod046424; Wed, 19 Mar 2014 13:19:47 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2JDJlDR046423; Wed, 19 Mar 2014 13:19:47 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201403191319.s2JDJlDR046423@svn.freebsd.org> From: Dru Lavigne Date: Wed, 19 Mar 2014 13:19:47 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44283 - head/en_US.ISO8859-1/books/handbook/network-servers 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.17 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: Wed, 19 Mar 2014 13:19:47 -0000 Author: dru Date: Wed Mar 19 13:19:46 2014 New Revision: 44283 URL: http://svnweb.freebsd.org/changeset/doc/44283 Log: Editorial review of iSCSI target section. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Mar 19 13:13:29 2014 (r44282) +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Mar 19 13:19:46 2014 (r44283) @@ -5696,18 +5696,18 @@ Logging to FILE /var/log/messages - Configuring an iSCSI target is - straightforward: create the + To configure an iSCSI target, + create the /etc/ctl.conf configuration file, add - an appropriate line to /etc/rc.conf to - make sure the ctld(8) + a line to /etc/rc.conf to + make sure the &man.ctld.8; daemon is automatically started at boot, and then start the daemon. - A simple ctl.conf(5) - configuration file looks like this: + 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. portal-group pg0 { discovery-auth-group no-authentication @@ -5726,95 +5726,86 @@ target iqn.2012-06.com.example:target0 { } The first entry defines the pg0 - portal group. Portal groups define network addresses the - ctld(8) - daemon will listen on. discovery-auth-group - no-authentication means that every initiator is - allowed to perform iSCSI SendTargets - discovery without any authentication. The following two - lines make ctld(8) + portal group. Portal groups define which network addresses the + &man.ctld.8; + daemon will listen on. The discovery-auth-group + no-authentication entry indicates that any initiator is + allowed to perform iSCSI target + discovery without authentication. Lines three and four + configure &man.ctld.8; to listen on all IPv4 (listen 0.0.0.0) and IPv6 (listen [::]) - addresses on the default port (3260). It is not necessary - to define a new portal group; there is a default one, called - default. The difference between - default and pg0 above - is that with default, the - iSCSI SendTargets discovery is always - denied, while with pg0 it is always + addresses on the default port of 3260. + + It is not necessary + to define a portal group as there is a built-in portal group called + default. In this case, the difference between + default and pg0 + is that with default, target + discovery is always + denied, while with pg0, it is always allowed. The second entry defines a single - target. Target has two - meanings: it is a machine serving iSCSI, - but also a named group of LUNs. In this - example, we use the latter meaning. + target. Target has two possible + meanings: a machine serving iSCSI or + a named group of LUNs. This + example uses the latter meaning, where iqn.2012-06.com.example:target0 is the - target name. For testing purposes it can be left as is; - otherwise, com.example should be changed - to the real domain name, reversed; the - 2012-06 is the year and month of + target name. This target name is suitable for testing purposes. + For actual use, change com.example + to the real domain name, reversed. The + 2012-06 represents the year and month of acquiring control of that domain name, and - target0 can be pretty much whatever. Any - number of targets can be defined in the configuration + target0 can be any value. Any + number of targets can be defined in this configuration file. - auth-group no-authentication allows - all initiators to connect to this target. + The auth-group no-authentication line allows + all initiators to connect to the specified target and portal-group pg0 makes the target reachable through the pg0 portal group. - After that come LUNs. To the + The next section defines the LUN. To the initiator, each LUN will be visible as a - separate disk device, like /dev/da0, - /dev/da1 and so on. Multiple + separate disk device. Multiple LUNs can be defined for each target. - LUNs are identified by numbers; - LUN 0 is mandatory. The first line of - LUN configuration - (path /data/target0-0) defines the full - path to a file or ZVOL backing the LUN. - The file must exist before starting ctld(8). - The second line is optional and specifies the size. + Each LUN is identified by a number, where + LUN 0 is mandatory. 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. - To make sure ctld(8) + Next, to make sure the &man.ctld.8; daemon is started at boot, add this line to /etc/rc.conf: ctld_enable="YES" - On a new server being configured as - iSCSI target, ctld(8) - can be started by running this command as root: + To start &man.ctld.8; now, + run this command: &prompt.root; service ctld start - The ctld(8) - daemon reads ctl.conf(5) - file when started. To make configuration changes take - effect immediately, force ctld(8) - to reread it: + 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 Authentication - The example above is inherently insecure: it uses no - authentication whatsoever, granting anyone full access to - all targets. To require username and password to access - targets, modify the configuration: + The previous example is inherently insecure as it uses no + authentication, granting anyone full access to + all targets. To require a username and password to access + targets, modify the configuration as follows: auth-group ag0 { chap username1 secretsecret @@ -5839,12 +5830,13 @@ target iqn.2012-06.com.example:target0 { The auth-group section defines username and password pairs. An initiator trying to connect to iqn.2012-06.com.example:target0 must - specify either of those. The SendTargets discovery is still - permitted without any kind of authentication; to change it, - set discovery-auth-group to something - else. + first specify a defined username and secret. However, target discovery is still + permitted without authentication. To require target discovery authentication, + set discovery-auth-group to a defined + auth-group name instead of + no-authentication. - A common case for iSCSI is to have a + It is common to define a single exported target for every initiator. As a shorthand for the syntax above, the username and password can be specified directly in the target entry: @@ -5868,8 +5860,7 @@ target iqn.2012-06.com.example:target0 { The current iSCSI initiator is supported starting with &os; 10.0-RELEASE. To use the iSCSI initiator available in older - versions, refer to iscontrol(8). + versions, refer to &man.iscontrol.8;. This chapter only applies to the new initiator.