Date: Wed, 30 Oct 2013 19:42:08 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43078 - head/en_US.ISO8859-1/books/handbook/network-servers Message-ID: <201310301942.r9UJg8rm018409@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310301942.r9UJg8rm018409>