svn commit: r43078 - head/en_US.ISO8859-1/books/handbook/network-servers
Warren Block
wblock at FreeBSD.org
Wed Oct 30 19:42:09 UTC 2013
Author: wblock
Date: Wed Oct 30 19:42:08 2013
New Revision: 43078
URL: http://svnweb.freebsd.org/changeset/doc/43078
Log:
Fix some issues with the iSCSI documents section.
Reviewed by: emaste
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 Oct 30 17:44:56 2013 (r43077)
+++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Oct 30 19:42:08 2013 (r43078)
@@ -5825,40 +5825,41 @@ Logging to FILE /var/log/messages</scree
</sect1info>
-->
- <title>iSCSI Initiator and Target Configuration</title>
+ <title><acronym>iSCSI</acronym> Initiator and Target Configuration</title>
- <para><acronym>iSCSI</acronym> is a way to share storage; to make
+ <para><acronym>iSCSI</acronym> is a way to share storage, to make
disk space at one machine (the server, in iSCSI nomenclature
- known as the target) available to others (clients, in iSCSI
- called initiators). The main difference compared to e.g. NFS is
- that NFS works at a filesystem level, while iSCSI works at block
- device level - to the initiators, remote disks served via iSCSI
- are just like physical disks; they have their respective device
- nodes appearing in /dev/, which need to be separately
+ known as the <emphasis>target</emphasis>) available to others (clients, called <emphasis>initiators</emphasis>
+ in <acronym>iSCSI</acronym>). The main difference when compared to <acronym>NFS</acronym> is
+ that <acronym>NFS</acronym> works at a filesystem level, while <acronym>iSCSI</acronym> works at the block
+ device level. To initiators, remote disks served via <acronym>iSCSI</acronym>
+ are just like physical disks. Their device
+ nodes appear in <filename>/dev/</filename>, and must be separately
mounted.</para>
- <sect2>
- <title>iSCSI Target</title>
+ <sect2 id="network-iscsi-target">
+ <title><acronym>iSCSI</acronym> Target</title>
- <para>Note: the native iSCSI target is supported starting with
- &os; 10.0-RELEASE. To use iSCSI in older versions, use a
- userspace target installed from ports, such as istgt. This
- chapter only applies to the native target.</para>
+ <para>Note: the native <acronym>iSCSI</acronym> target is supported starting with
+ &os; 10.0-RELEASE. To use <acronym>iSCSI</acronym> in older versions of &os;, install a
+ userspace target from the Ports Collection, such as
+ <filename role="package">net/istgt</filename>.
+ This chapter only describes the native target.</para>
<sect3>
<title>Basic Operation</title>
- <para>Configuring the iSCSI target is pretty straightforward:
- one needs to create <filename>/etc/ctl.conf</filename>
+ <para>Configuring an <acronym>iSCSI</acronym> target is straightforward:
+ create the <filename>/etc/ctl.conf</filename>
configuration file, add an appropriate line to
<filename>/etc/rc.conf</filename> to make sure the <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>
- daemon gets automatically started at boot, and then start
+ daemon is automatically started at boot, and then start
the daemon.</para>
- <para>Simple <ulink
+ <para>A simple <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</ulink>
- configuration file might look like this:</para>
+ configuration file looks like this:</para>
<programlisting>portal-group pg0 {
discovery-auth-group no-authentication
@@ -5876,62 +5877,69 @@ target iqn.2012-06.com.example:target0 {
}
}</programlisting>
- <para>First entry in the config file defines a portal group
- called "pg0". Portal groups define network addresses the
+ <para>The first entry defines the <literal>pg0</literal> portal group.
+ Portal groups define network addresses the
<ulink
url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>
- daemon will listen on. First line ("discovery-auth-group
- no-authentication") means that every initiator is allowed to
- perform SendTargets iSCSI discovery without any kind of
- authentication. Following two lines make <ulink
+ 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 <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>
- listen on all IPv4 ("listen 0.0.0.0") and IPv6 ("listen
- [::]") addresses configured on network interfaces, on the
- default port (3560). One does not always need to define
- a new portal group - there is a default one, called
- "default". The difference between "default" and "pg0" above is
- that with the former, the iSCSI SendTargets discovery is
- always denied, while in the latter it is always
+ 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 (3560). 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
allowed.</para>
- <para>The second entry defines a single target. Target has two
- meanings - it is a machine serving iSCSI, but it's also
- a named group of LUNs. In this example, we use the latter
- meaning. The "iqn.2012-06.com.example:target0" is the
- target name. For testing purposes it might be left as it
- is; otherwise, the "com.example" should be changed to the
- real domain name, reversed; the "2012-06" is the year and
+ <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.
+ <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 acquiring control of that domain name, and
- "target0" can be pretty much whatever. There can be any
- number of targets defined in the config file.</para>
+ <literal>target0</literal> can be pretty much whatever.
+ Any
+ number of targets can be defined in the configuration file.</para>
+
+ <para><literal>auth-group no-authentication</literal>
+ allows all initiators to connect to this target.
+ <literal>portal-group pg0</literal>
+ makes the target reachable through the <literal>pg0</literal>
+ portal group.</para>
- <para>The first line in the target configuration ("auth-group
- no-authentication") allows every initiator to connect to it.
- The second line ("portal-group pg0") makes the target reachable
- through the "pg0" portal group.</para>
-
- <para>After that come LUNs. To the initiator, each LUN will
- be visible as a separate disk device - e.g.
+ <para>After that come <acronym>LUNs</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>
- etc. There may be multiple LUNs 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
+ and so on. 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 <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>.
The second line is optional and specifies the size.</para>
<para>To make sure <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>
- daemon is started at boot, one needs to add the following
+ 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 iSCSI target, the
+ <para>On a new server being configured as <acronym>iSCSI</acronym> target,
<ulink
url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>
- can be started by running this command as root:</para>
+ can be started by running this command as <username>root</username>:</para>
<screen>&prompt.root; <userinput>service ctld start</userinput></screen>
@@ -5950,10 +5958,10 @@ target iqn.2012-06.com.example:target0 {
<sect3>
<title>Authentication</title>
- <para>The example above is inherently insecure - it uses no
+ <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 configuration like this:</para>
+ targets, modify the configuration:</para>
<programlisting>auth-group ag0 {
chap username1 secretsecret
@@ -5975,17 +5983,17 @@ target iqn.2012-06.com.example:target0 {
}
}</programlisting>
- <para>The auth-group section defines username/password pairs.
+ <para>The <literal>auth-group</literal> section defines username and password pairs.
An initiator trying to connect to
- iqn.2012-06.com.example:target0 must specify either of
+ <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
- "discovery-auth-group" to something else.</para>
+ <literal>discovery-auth-group</literal> to something else.</para>
- <para>A common case for iSCSI is to have a single exported
- target for every initiator. As a shorthand for syntax
- above, one can specify the username and password directly in the
- target entry, like this:</para>
+ <para>A common case for <acronym>iSCSI</acronym> is to have 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>
<programlisting>target iqn.2012-06.com.example:target0 {
portal-group pg0
@@ -5999,63 +6007,64 @@ target iqn.2012-06.com.example:target0 {
</sect3>
</sect2>
- <sect2>
- <title>iSCSI Initiator</title>
+ <sect2 id="network-iscsi-initiator">
+ <title><acronym>iSCSI</acronym> Initiator</title>
<note>
- <para>The current iSCSI initiator is supported starting with
- &os; 10.0-RELEASE. To use the iSCSI initiator available in
+ <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 <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=iscontrol&sektion=8&manpath=FreeBSD+10-current">iscontrol(8)</ulink>.
This chapter only applies to the new
initiator.</para>
</note>
- <para>The iSCSI initiator requires <ulink
+ <para>The <acronym>iSCSI</acronym> initiator requires the <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</ulink>
- daemon to run. It does not use any kind of configuration
- file. To make sure it gets started automatically at boot, add
- the following line to
+ daemon to run. It does not use a configuration
+ file. To start it automatically at boot, add
+ this line to
<filename>/etc/rc.conf</filename>:</para>
<programlisting>iscsid_enable="YES"</programlisting>
- <para>On a new machine being configured as iSCSI initiator, the
+ <para>On a new machine being configured as an <acronym>iSCSI</acronym> initiator,
<ulink
url="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</ulink>
- can be started by running this command as root:</para>
+ can be started by running this command as <username>root</username>:</para>
<screen>&prompt.root; <userinput>service iscsid start</userinput></screen>
- <para>There are two basic ways to connect to a target: by using
+ <para>Connecting to a target can be done with or without an
<ulink
url="http://www.freebsd.org/cgi/man.cgi?query=iscsi.conf&sektion=5&manpath=FreeBSD+10-current">iscsi.conf(8)</ulink>
- configuration file, or without it.</para>
+ configuration file.</para>
<sect3>
- <title>Connecting to a Target Without Using a Configuration
+ <title>Connecting to a Target Without a Configuration
File</title>
<para>To make the initiator connect to a single target, run
- this command as root:</para>
+ this command as <username>root</username>:</para>
<screen>&prompt.root; <userinput>iscsictl -A -p 10.10.10.10 -t iqn.2012-06.com.example:target0</userinput></screen>
- <para>To verify if it succeeded, run it without arguments. It
- should output something like this:</para>
+ <para>To verify if the connection succeeded, run it without arguments. The
+ output should look like this:</para>
<programlisting>Target name Target portal State
iqn.2012-06.com.example:target0 10.10.10.10 Connected: da0</programlisting>
- <para>This means the iSCSI session was successfully
- established, where <filename>/dev/da0</filename>
- represents the attached LUN. Should the target
- ("iqn.2012-06.com.example:target0") export more than one
- LUN, there will be multiple device nodes in the <ulink
+ <para>This shows that the <acronym>iSCSI</acronym> session was successfully
+ established, with <filename>/dev/da0</filename>
+ representing the attached <acronym>LUN</acronym>. If the
+ <literal>iqn.2012-06.com.example:target0</literal> target exports more than one
+ <acronym>LUN</acronym>, multiple device nodes will be shown in the <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=iscsictl&sektion=8&manpath=FreeBSD+10-current">iscictl(8)</ulink>
- output (e.g. "Connected: da0 da1 da2").</para>
+ output:</para>
+ <screen>Connected: da0 da1 da2.</screen>
- <para>Various errors are reported in system logs, and visible
+ <para>Any errors are reported in the system logs, and also visible
in the <ulink
url="http://www.freebsd.org/cgi/man.cgi?query=iscsictl&sektion=8&manpath=FreeBSD+10-current">iscictl(8)</ulink>
output. For example, this usually means the <ulink
@@ -6071,30 +6080,30 @@ iqn.2012-06.com.example:target0
<programlisting>Target name Target portal State
iqn.2012-06.com.example:target0 10.10.10.11 Connection refused</programlisting>
- <para>The following means the specified target name was
+ <para>This means the specified target name was
wrong:</para>
<programlisting>Target name Target portal State
iqn.2012-06.com.example:atrget0 10.10.10.10 Not found</programlisting>
- <para>The following means the target requires
+ <para>This means the target requires
authentication:</para>
<programlisting>Target name Target portal State
iqn.2012-06.com.example:target0 10.10.10.10 Authentication failed</programlisting>
- <para>To specify a CHAP username and secret, use the following
+ <para>To specify a <acronym>CHAP</acronym> username and secret, use this
syntax:</para>
<screen>&prompt.root; <userinput>iscsictl -A -p 10.10.10.10 -t iqn.2012-06.com.example:target0 -u user -s secretsecret</userinput></screen>
</sect3>
<sect3>
- <title>Connecting to a Target Using a Configuration
+ <title>Connecting to a Target With a Configuration
File</title>
<para>To connect using a configuration file, create
- <filename>/etc/iscsi.conf</filename> that might look like
+ <filename>/etc/iscsi.conf</filename> with contents like
this:</para>
<programlisting>t0 {
@@ -6105,13 +6114,13 @@ iqn.2012-06.com.example:target0
chapSecret = secretsecret
}</programlisting>
- <para>The first line ("t0") specifies a nickname for the
+ <para><literal>t0</literal> specifies a nickname for the
configuration file section, used at the initiator side to
specify which configuration to use. The following
- lines specify various parameters used during connection
- - target address and name are mandatory; others are
- optional; in this case they specify CHAP username and
- secret.</para>
+ lines specify various parameters used during connection.
+ Target address and name are mandatory, others are
+ optional. In this example, <acronym>CHAP</acronym> username and
+ secret are shown.</para>
<para>To connect to the target defined above, use:</para>
More information about the svn-doc-all
mailing list