os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Fix some issues with the iSCSI documents section.

Browse source 
Reviewed by:	emaste
This commit is contained in:
Warren Block 2013-10-30 19:42:08 +00:00
parent 39405f103f
commit cf7bc3e72e
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=43078
1 changed files with 105 additions and 96 deletions

201
en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
View file

@ -5825,40 +5825,41 @@ Logging to FILE /var/log/messages</screen>
</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&amp;sektion=8&amp;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&amp;sektion=5&amp;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&amp;sektion=8&amp;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&amp;sektion=8&amp;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>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><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>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&amp;sektion=8&amp;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&amp;sektion=8&amp;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&amp;sektion=8&amp;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&amp;sektion=8&amp;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&amp;sektion=8&amp;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&amp;sektion=8&amp;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&amp;sektion=5&amp;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&amp;sektion=8&amp;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&amp;sektion=8&amp;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 10.10.10.10 Waiting for iscs
<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 10.10.10.10 Authentication f
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>