svn commit: r44283 - head/en_US.ISO8859-1/books/handbook/network-servers
Dru Lavigne
dru at FreeBSD.org
Wed Mar 19 13:19:47 UTC 2014
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>
More information about the svn-doc-head
mailing list