Date: Wed, 19 Mar 2014 13:19:47 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> 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 Message-ID: <201403191319.s2JDJlDR046423@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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</scree native target.</para> </note> - <para>Configuring an <acronym>iSCSI</acronym> target is - straightforward: create the + <para>To configure an <acronym>iSCSI</acronym> target, + create the <filename>/etc/ctl.conf</filename> configuration file, add - an appropriate line to <filename>/etc/rc.conf</filename> to - make sure the <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>; + a line to <filename>/etc/rc.conf</filename> to + make sure the &man.ctld.8; daemon is automatically started at boot, and then start the daemon.</para> - <para>A simple <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</link>; - configuration file looks like this:</para> + <para>The following 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 this file's available options.</para> <programlisting>portal-group pg0 { discovery-auth-group no-authentication @@ -5726,95 +5726,86 @@ target iqn.2012-06.com.example:target0 { }</programlisting> <para>The first entry defines the <literal>pg0</literal> - portal group. Portal groups define network addresses the - <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>; - daemon will listen on. <literal>discovery-auth-group - no-authentication</literal> means that every initiator is - allowed to perform <acronym>iSCSI</acronym> SendTargets - discovery without any authentication. The following two - lines make <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>; + portal group. Portal groups define which network addresses the + &man.ctld.8; + daemon will listen on. The <literal>discovery-auth-group + no-authentication</literal> entry indicates that any initiator is + allowed to perform <acronym>iSCSI</acronym> target + discovery without authentication. Lines three and four + configure &man.ctld.8; to listen on all <acronym>IPv4</acronym> (<literal>listen 0.0.0.0</literal>) and <acronym>IPv6</acronym> (<literal>listen [::]</literal>) - addresses on the default port (3260). It is not necessary - to define a new portal group; there is a default one, called - <literal>default</literal>. The difference between - <literal>default</literal> and <literal>pg0</literal> above - is that with <literal>default</literal>, the - <acronym>iSCSI</acronym> SendTargets discovery is always - denied, while with <literal>pg0</literal> it is always + addresses on the default port of 3260.</para> + + <para>It is not necessary + to define a portal group as there is a built-in portal group called + <literal>default</literal>. In this case, the difference between + <literal>default</literal> and <literal>pg0</literal> + is that with <literal>default</literal>, target + discovery is always + denied, while with <literal>pg0</literal>, it is always allowed.</para> <para>The second entry defines a single - <emphasis>target</emphasis>. <quote>Target</quote> has two - meanings: it is a machine serving <acronym>iSCSI</acronym>, - but also a named group of <acronym>LUNs</acronym>. In this - example, we use the latter meaning. + target. Target has two possible + meanings: a machine serving <acronym>iSCSI</acronym> or + a named group of <acronym>LUNs</acronym>. This + example uses the latter meaning, where <literal>iqn.2012-06.com.example:target0</literal> is the - target name. For testing purposes it can be left as is; - otherwise, <literal>com.example</literal> should be changed - to the real domain name, reversed; the - <literal>2012-06</literal> is the year and month of + target name. This target name is suitable for testing purposes. + For actual use, change <literal>com.example</literal> + to the real domain name, reversed. The + <literal>2012-06</literal> represents the year and month of acquiring control of that domain name, and - <literal>target0</literal> can be pretty much whatever. Any - number of targets can be defined in the configuration + <literal>target0</literal> can be any value. Any + number of targets can be defined in this configuration file.</para> - <para><literal>auth-group no-authentication</literal> allows - all initiators to connect to this target. + <para>The <literal>auth-group no-authentication</literal> line allows + all initiators to connect to the specified target and <literal>portal-group pg0</literal> makes the target reachable through the <literal>pg0</literal> portal group.</para> - <para>After that come <acronym>LUNs</acronym>. To the + <para>The next section defines the <acronym>LUN</acronym>. To the initiator, each <acronym>LUN</acronym> will be visible as a - separate disk device, like <filename>/dev/da0</filename>, - <filename>/dev/da1</filename> and so on. Multiple + separate disk device. Multiple <acronym>LUNs</acronym> can be defined for each target. - <acronym>LUNs</acronym> are identified by numbers; - <acronym>LUN</acronym> 0 is mandatory. The first line of - <acronym>LUN</acronym> configuration - (<literal>path /data/target0-0</literal>) defines the full - path to a file or ZVOL backing the <acronym>LUN</acronym>. - The file must exist before starting <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>. - The second line is optional and specifies the size.</para> + Each <acronym>LUN</acronym> is identified by a number, where + <acronym>LUN</acronym> 0 is mandatory. The + <literal>path /data/target0-0</literal> line defines the full + path to a file or zvol backing the <acronym>LUN</acronym>. + That path 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 <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>; + <para>Next, 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>On a new server being configured as - <acronym>iSCSI</acronym> target, <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>; - can be started by running this command as <systemitem - class="username">root</systemitem>:</para> + <para>To start &man.ctld.8; now, + run this command:</para> <screen>&prompt.root; <userinput>service ctld start</userinput></screen> - <para>The <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>; - daemon reads <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</link>; - file when started. To make configuration changes take - effect immediately, force <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>; - to reread it:</para> + <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, use this + command so that the changes take + effect immediately:</para> <screen>&prompt.root; <userinput>service ctld reload</userinput></screen> <sect3> <title>Authentication</title> - <para>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:</para> + <para>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:</para> <programlisting>auth-group ag0 { chap username1 secretsecret @@ -5839,12 +5830,13 @@ target iqn.2012-06.com.example:target0 { <para>The <literal>auth-group</literal> section defines username and password pairs. An initiator trying to connect to <literal>iqn.2012-06.com.example:target0</literal> must - specify either of those. The SendTargets discovery is still - permitted without any kind of authentication; to change it, - set <literal>discovery-auth-group</literal> to something - else.</para> + first specify a defined username and secret. However, target discovery is still + permitted without authentication. To require target discovery authentication, + set <literal>discovery-auth-group</literal> to a defined + <literal>auth-group</literal> name instead of + <literal>no-authentication</literal>.</para> - <para>A common case for <acronym>iSCSI</acronym> is to have a + <para>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:</para> @@ -5868,8 +5860,7 @@ target iqn.2012-06.com.example:target0 { <para>The current <acronym>iSCSI</acronym> initiator is supported starting with &os; 10.0-RELEASE. To use the <acronym>iSCSI</acronym> initiator available in older - versions, refer to <link - xlink:href="http://www.freebsd.org/cgi/man.cgi?query=iscontrol&sektion=8&manpath=FreeBSD+10-current">iscontrol(8)</link>. + versions, refer to &man.iscontrol.8;. This chapter only applies to the new initiator.</para> </note>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403191319.s2JDJlDR046423>