28.13. iSCSI Initiator and Target Configuration

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.

28.13.1. iSCSI Target

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.

28.13.1.1. Basic Operation

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 (3260). 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

28.13.1.2. Authentication

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
	}
}

28.13.2. iSCSI Initiator

Note:

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.

28.13.2.1. Connecting to a Target Without a 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

28.13.2.2. Connecting to a Target With a Configuration File

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>.