Add section describing the new iSCSI stack.
This includes fixes by gjb@, including replacing the usual manrefs with direct links; without it, the links would be broken, as the new manpages are only available in 10-CURRENT. Approved by: gjb Sponsored by: FreeBSD Foundation
This commit is contained in:
Edward Tomasz Napierala
parent
a104fcc02a
commit
c1c9bf52a5
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42910
1 changed files with 322 additions and 0 deletions
|
|
@ -88,6 +88,10 @@
|
||||||
<command>syslogd</command>, to accept logs from remote
|
<command>syslogd</command>, to accept logs from remote
|
||||||
hosts.</para>
|
hosts.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>How to set up <acronym>iSCSI</acronym>.</para>
|
||||||
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
|
||||||
<para>This chapter assumes a basic knowledge of:</para>
|
<para>This chapter assumes a basic knowledge of:</para>
|
||||||
|
|
@ -6179,4 +6183,322 @@ Logging to FILE /var/log/messages</screen>
|
||||||
by local users.</para>
|
by local users.</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="network-iscsi">
|
||||||
|
<sect1info>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Edward Tomasz</firstname>
|
||||||
|
<surname>Napierala</surname>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
</sect1info>
|
||||||
|
|
||||||
|
<title>iSCSI Initiator and Target Configuration</title>
|
||||||
|
|
||||||
|
<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
|
||||||
|
mounted.</para>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>iSCSI Target</title>
|
||||||
|
|
||||||
|
<para>Note: the native iSCSI target is supported starting with
|
||||||
|
&os; 10.0-RELEASE. To use iSCSI in older versions, use
|
||||||
|
userspace target installed from ports, such as istgt. This
|
||||||
|
chapter only applies to 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>
|
||||||
|
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
|
||||||
|
the daemon.</para>
|
||||||
|
|
||||||
|
<para>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>
|
||||||
|
|
||||||
|
<programlisting>portal-group pg0 {
|
||||||
|
discovery-auth-group no-authentication
|
||||||
|
listen 0.0.0.0
|
||||||
|
listen [::]
|
||||||
|
}
|
||||||
|
|
||||||
|
target iqn.2012-06.com.example:target0 {
|
||||||
|
auth-group no-authentication
|
||||||
|
portal-group pg0
|
||||||
|
|
||||||
|
lun 0 {
|
||||||
|
path /data/target0-0
|
||||||
|
size 4G
|
||||||
|
}
|
||||||
|
}</programlisting>
|
||||||
|
|
||||||
|
<para>First entry in the config file defines a portal group
|
||||||
|
called "pg0". 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
|
||||||
|
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
|
||||||
|
default port (3560). One does not always need to define
|
||||||
|
a new portal group - there is a default one, called
|
||||||
|
"default". 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
|
||||||
|
allowed.</para>
|
||||||
|
|
||||||
|
<para>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
|
||||||
|
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>
|
||||||
|
|
||||||
|
<para>First line in the target configuration ("auth-group
|
||||||
|
no-authentication") allows every initiator to connect to it.
|
||||||
|
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.
|
||||||
|
<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. First
|
||||||
|
line of LUN configuration ("path /data/target0-0") defines
|
||||||
|
full path to a file or ZVOL backing the LUN. 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>.
|
||||||
|
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 line
|
||||||
|
to <filename>/etc/rc.conf</filename>:</para>
|
||||||
|
|
||||||
|
<programlisting>ctld_enable="YES"</programlisting>
|
||||||
|
|
||||||
|
<para>On a new server being configured as iSCSI target, the
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>service ctld
|
||||||
|
start</userinput></screen>
|
||||||
|
|
||||||
|
<para>The <ulink
|
||||||
|
url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>
|
||||||
|
daemon reads <ulink
|
||||||
|
url="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</ulink>
|
||||||
|
file when started. To make configuration changes take effect
|
||||||
|
immediately, force <ulink
|
||||||
|
url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>
|
||||||
|
to reread it:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>service ctld reload</userinput></screen>
|
||||||
|
</sect3>
|
||||||
|
|
||||||
|
<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 configuration like this:</para>
|
||||||
|
|
||||||
|
<programlisting>auth-group ag0 {
|
||||||
|
chap username1 secretsecret
|
||||||
|
chap username2 anothersecret
|
||||||
|
}
|
||||||
|
|
||||||
|
portal-group pg0 {
|
||||||
|
discovery-auth-group no-authentication
|
||||||
|
listen 0.0.0.0
|
||||||
|
listen [::]
|
||||||
|
}
|
||||||
|
|
||||||
|
target iqn.2012-06.com.example:target0 {
|
||||||
|
auth-group ag0
|
||||||
|
portal-group pg0
|
||||||
|
lun 0 {
|
||||||
|
path /data/target0-0
|
||||||
|
size 4G
|
||||||
|
}
|
||||||
|
}</programlisting>
|
||||||
|
|
||||||
|
<para>The auth-group section defines username/password pairs.
|
||||||
|
Initiator trying to connect to
|
||||||
|
iqn.2012-06.com.example:target0 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>
|
||||||
|
|
||||||
|
<para>Common case for iSCSI is to have a single exported
|
||||||
|
target for every initiator. As a shorthand for syntax
|
||||||
|
above, one can specify username and password directly in the
|
||||||
|
target entry, like this:</para>
|
||||||
|
|
||||||
|
<programlisting>target iqn.2012-06.com.example:target0 {
|
||||||
|
portal-group pg0
|
||||||
|
chap username1 secretsecret
|
||||||
|
|
||||||
|
lun 0 {
|
||||||
|
path /data/target0-0
|
||||||
|
size 4G
|
||||||
|
}
|
||||||
|
}</programlisting>
|
||||||
|
</sect3>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>iSCSI Initiator</title>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>The current iSCSI initiator is supported starting with
|
||||||
|
&os; 10.0-RELEASE. To use iSCSI initiator available in
|
||||||
|
older versions, refer to the <ulink
|
||||||
|
url="http://www.freebsd.org/cgi/man.cgi?query=iscontrol&sektion=8&manpath=FreeBSD+10-current">iscontrol(8)</ulink>
|
||||||
|
manual page. This chapter only applies to the new
|
||||||
|
initiator.</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<para>The iSCSI initiator requires <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 <filename>/etc/rc.conf</filename>:</para>
|
||||||
|
|
||||||
|
<programlisting>iscsid_enable="YES"</programlisting>
|
||||||
|
|
||||||
|
<para>On a new machine being configured as iSCSI initiator, the
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>service iscsid start</userinput></screen>
|
||||||
|
|
||||||
|
<para>There are two basic ways to connect to a target: by using
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<sect3>
|
||||||
|
<title>Connecting to a Target Without Using a Configuration
|
||||||
|
File</title>
|
||||||
|
|
||||||
|
<para>To make the initiator connect to a single target, run
|
||||||
|
this command as root:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>iscsictl -A -h 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>
|
||||||
|
|
||||||
|
<programlisting>Target name Target addr State
|
||||||
|
iqn.2012-06.com.example:target0 10.10.10.10 Connected: da0</programlisting>
|
||||||
|
|
||||||
|
<para>This means the iSCSI session was successfully
|
||||||
|
established, and you have <filename>/dev/da0</filename>
|
||||||
|
representing 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
|
||||||
|
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>
|
||||||
|
|
||||||
|
<para>Various errors are reported in system logs, and 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
|
||||||
|
url="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</ulink>
|
||||||
|
daemon is not running:</para>
|
||||||
|
|
||||||
|
<programlisting>Target name Target addr State
|
||||||
|
iqn.2012-06.com.example:target0 10.10.10.10 Waiting for iscsid(8)</programlisting>
|
||||||
|
|
||||||
|
<para>The following suggests network-level problem, such as
|
||||||
|
wrong IP address or port:</para>
|
||||||
|
|
||||||
|
<programlisting>Target name Target addr State
|
||||||
|
iqn.2012-06.com.example:target0 10.10.10.11 Connection refused</programlisting>
|
||||||
|
<para>The following means the specified target name was
|
||||||
|
wrong:</para>
|
||||||
|
|
||||||
|
<programlisting>Target name Target addr State
|
||||||
|
iqn.2012-06.com.example:atrget0 10.10.10.10 Not found</programlisting>
|
||||||
|
|
||||||
|
<para>The following means the target requires
|
||||||
|
authentication:</para>
|
||||||
|
|
||||||
|
<programlisting>Target name Target addr State
|
||||||
|
iqn.2012-06.com.example:target0 10.10.10.10 Authentication failed</programlisting>
|
||||||
|
|
||||||
|
<para>To specify CHAP username and secret, use the following
|
||||||
|
syntax:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>iscsictl -A -h 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
|
||||||
|
File</title>
|
||||||
|
|
||||||
|
<para>To connect using a configuration file, create
|
||||||
|
<filename>/etc/iscsi.conf</filename> that might look like
|
||||||
|
this:</para>
|
||||||
|
|
||||||
|
<programlisting>t0 {
|
||||||
|
TargetAddress = 10.10.10.10
|
||||||
|
TargetName = iqn.2012-06.com.example:target0
|
||||||
|
AuthMethod = CHAP
|
||||||
|
chapIName = user
|
||||||
|
chapSecret = secretsecret
|
||||||
|
}</programlisting>
|
||||||
|
|
||||||
|
<para>The first line ("t0") specifies a nickname for the
|
||||||
|
configuration file section, used at the initiator side to
|
||||||
|
specify which configuration you want 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>
|
||||||
|
|
||||||
|
<para>To connect to the target defined above, use:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>iscsictl -An t0</userinput></screen>
|
||||||
|
|
||||||
|
<para>To connect to all targets defined in the configuration
|
||||||
|
file, use:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.root; <userinput>iscsictl -Aa</userinput></screen>
|
||||||
|
|
||||||
|
<para>To make the initiator automatically connect to all
|
||||||
|
targets in <filename>/etc/iscsi.conf</filename>, add the
|
||||||
|
following to <filename>/etc/rc.conf</filename>:</para>
|
||||||
|
|
||||||
|
<programlisting>iscsictl_enable="YES"
|
||||||
|
iscsictl_flags="-Aa"</programlisting>
|
||||||
|
|
||||||
|
</sect3>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue