From 55593c25924e165282a463e2d7d618451eea1c84 Mon Sep 17 00:00:00 2001 From: Dru Lavigne Date: Wed, 19 Mar 2014 13:19:46 +0000 Subject: [PATCH] Editorial review of iSCSI target section. Sponsored by: iXsystems --- .../handbook/network-servers/chapter.xml | 137 ++++++++---------- 1 file changed, 64 insertions(+), 73 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml index c4c4c24ee4..88c57c18df 100644 --- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml @@ -5696,18 +5696,18 @@ Logging to FILE /var/log/messages native target. - Configuring an iSCSI target is - straightforward: create the + To configure an iSCSI target, + create the /etc/ctl.conf configuration file, add - an appropriate line to /etc/rc.conf to - make sure the ctld(8) + a line to /etc/rc.conf to + make sure the &man.ctld.8; daemon is automatically started at boot, and then start the daemon. - A simple ctl.conf(5) - configuration file looks like this: + The following is an example of a simple + /etc/ctl.conf + configuration file. Refer to &man.ctl.conf.5; for a more + complete description of this file's available options. portal-group pg0 { discovery-auth-group no-authentication @@ -5726,95 +5726,86 @@ target iqn.2012-06.com.example:target0 { } 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) + portal group. Portal groups define which network addresses the + &man.ctld.8; + daemon will listen on. The discovery-auth-group + no-authentication entry indicates that any initiator is + allowed to perform iSCSI target + discovery without authentication. Lines three and four + configure &man.ctld.8; to 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 + addresses on the default port of 3260. + + It is not necessary + to define a portal group as there is a built-in portal group called + default. In this case, the difference between + default and pg0 + is that with default, target + 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. + target. Target has two possible + meanings: a machine serving iSCSI or + a named group of LUNs. This + example uses the latter meaning, where 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 + target name. This target name is suitable for testing purposes. + For actual use, change com.example + to the real domain name, reversed. The + 2012-06 represents 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 + target0 can be any value. Any + number of targets can be defined in this configuration file. - auth-group no-authentication allows - all initiators to connect to this target. + The auth-group no-authentication line allows + all initiators to connect to the specified target and portal-group pg0 makes the target reachable through the pg0 portal group. - After that come LUNs. To the + The next section defines the LUN. To the initiator, each LUN will be visible as a - separate disk device, like /dev/da0, - /dev/da1 and so on. Multiple + separate disk device. 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. + Each LUN is identified by a number, where + LUN 0 is mandatory. The + path /data/target0-0 line defines the full + path to a file or zvol backing the LUN. + That path must exist before starting &man.ctld.8;. + The second line is optional and specifies the size of the + LUN. - To make sure ctld(8) + Next, to make sure the &man.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: + To start &man.ctld.8; now, + run this command: &prompt.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: + As the &man.ctld.8; + daemon is started, it reads /etc/ctl.conf. + If this file is edited after the daemon starts, use this + command so that the changes take + effect immediately: &prompt.root; service ctld reload 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: + The previous example is inherently insecure as it uses no + authentication, granting anyone full access to + all targets. To require a username and password to access + targets, modify the configuration as follows: auth-group ag0 { chap username1 secretsecret @@ -5839,12 +5830,13 @@ target iqn.2012-06.com.example:target0 { 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. + first specify a defined username and secret. However, target discovery is still + permitted without authentication. To require target discovery authentication, + set discovery-auth-group to a defined + auth-group name instead of + no-authentication. - A common case for iSCSI is to have a + It is common to define 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: @@ -5868,8 +5860,7 @@ target iqn.2012-06.com.example:target0 { The current iSCSI initiator is supported starting with &os; 10.0-RELEASE. To use the iSCSI initiator available in older - versions, refer to iscontrol(8). + versions, refer to &man.iscontrol.8;. This chapter only applies to the new initiator.