iSCSI 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, called initiators
in iSCSI). The main difference when compared to NFS is
that NFS works at a filesystem level, while iSCSI works at the block
device level. To initiators, remote disks served via iSCSI
are just like physical disks. Their device
nodes appear in /dev/
, and must be separately
mounted.
Note: the native iSCSI target is supported starting with FreeBSD 10.0-RELEASE. To use iSCSI in older versions of FreeBSD, install a userspace target from the Ports Collection, such as net/istgt. This chapter only describes the native target.
Configuring an iSCSI target is straightforward:
create the /etc/ctl.conf
configuration file, add an appropriate line to
/etc/rc.conf
to make sure the ctld(8)
daemon is automatically started at boot, and then start
the daemon.
A simple ctl.conf(5) configuration file looks like this:
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 } }
The first entry defines the pg0
portal group.
Portal groups define network addresses the
ctld(8)
daemon will listen on. discovery-auth-group
no-authentication
means that every initiator is allowed to
perform iSCSI SendTargets discovery without any
authentication. The following two lines make ctld(8)
listen on all IPv4 (listen 0.0.0.0
) and IPv6 (listen
[::]
) addresses on the
default port (3560). It is not necessary to define
a new portal group; there is a default one, called
default
. The difference between default
and pg0
above is
that with default
, the iSCSI SendTargets discovery is
always denied, while with pg0
it is always
allowed.
The second entry defines a single target.
“Target” has two
meanings: it is a machine serving iSCSI, but also
a named group of LUNs. In this example, we use the latter
meaning.
iqn.2012-06.com.example:target0
is the
target name. For testing purposes it can be left as
is; otherwise, 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.
Any
number of targets can be defined in the configuration file.
auth-group no-authentication
allows all initiators to connect to this target.
portal-group pg0
makes the target reachable through the pg0
portal group.
After that come LUNs. To the initiator, each LUN will
be visible as a separate disk device, like
/dev/da0
, /dev/da1
and so on. Multiple LUNs can be 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
exist before starting ctld(8).
The second line is optional and specifies the size.
To make sure ctld(8)
daemon is started at boot, add this
line to /etc/rc.conf
:
ctld_enable="YES"
On a new server being configured as iSCSI target,
ctld(8)
can be started by running this command as root
:
#
service ctld start
The ctld(8) daemon reads ctl.conf(5) file when started. To make configuration changes take effect immediately, force ctld(8) to reread it:
#
service ctld reload
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:
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 } }
The auth-group
section defines username and password pairs.
An 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.
A common case for iSCSI 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:
target iqn.2012-06.com.example:target0 { portal-group pg0 chap username1 secretsecret lun 0 { path /data/target0-0 size 4G } }
The current iSCSI initiator is supported starting with FreeBSD 10.0-RELEASE. To use the iSCSI initiator available in older versions, refer to iscontrol(8). This chapter only applies to the new initiator.
The iSCSI initiator requires the iscsid(8)
daemon to run. It does not use a configuration
file. To start it automatically at boot, add
this line to
/etc/rc.conf
:
iscsid_enable="YES"
On a new machine being configured as an iSCSI initiator,
iscsid(8)
can be started by running this command as root
:
#
service iscsid start
Connecting to a target can be done with or without an iscsi.conf(8) configuration file.
To make the initiator connect to a single target, run
this command as root
:
#
iscsictl -A -p 10.10.10.10 -t iqn.2012-06.com.example:target0
To verify if the connection succeeded, run it without arguments. The output should look like this:
Target name Target portal State iqn.2012-06.com.example:target0 10.10.10.10 Connected: da0
This shows that the iSCSI session was successfully
established, with /dev/da0
representing the attached LUN. If the
iqn.2012-06.com.example:target0
target exports more than one
LUN, multiple device nodes will be shown in the iscictl(8)
output:
Connected: da0 da1 da2.
Any errors are reported in the system logs, and also visible in the iscictl(8) output. For example, this usually means the iscsid(8) daemon is not running:
Target name Target portal State iqn.2012-06.com.example:target0 10.10.10.10 Waiting for iscsid(8)
The following suggests a network-level problem, such as a wrong IP address or port:
Target name Target portal State iqn.2012-06.com.example:target0 10.10.10.11 Connection refused
This means the specified target name was wrong:
Target name Target portal State iqn.2012-06.com.example:atrget0 10.10.10.10 Not found
This means the target requires authentication:
Target name Target portal State iqn.2012-06.com.example:target0 10.10.10.10 Authentication failed
To specify a CHAP username and secret, use this syntax:
#
iscsictl -A -p 10.10.10.10 -t iqn.2012-06.com.example:target0 -u user -s secretsecret
To connect using a configuration file, create
/etc/iscsi.conf
with contents like
this:
t0 { TargetAddress = 10.10.10.10 TargetName = iqn.2012-06.com.example:target0 AuthMethod = CHAP chapIName = user chapSecret = secretsecret }
t0
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 example, CHAP username and
secret are shown.
To connect to the target defined above, use:
#
iscsictl -An t0
To connect to all targets defined in the configuration file, use:
#
iscsictl -Aa
To make the initiator automatically connect to all
targets in /etc/iscsi.conf
, add the
following to /etc/rc.conf
:
iscsictl_enable="YES" iscsictl_flags="-Aa"
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.