From owner-svn-doc-all@FreeBSD.ORG Wed Oct 30 19:42:09 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 107381E7; Wed, 30 Oct 2013 19:42:09 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id DEC0C2E14; Wed, 30 Oct 2013 19:42:08 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r9UJg8QU018410; Wed, 30 Oct 2013 19:42:08 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r9UJg8rm018409; Wed, 30 Oct 2013 19:42:08 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201310301942.r9UJg8rm018409@svn.freebsd.org> From: Warren Block Date: Wed, 30 Oct 2013 19:42:08 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43078 - head/en_US.ISO8859-1/books/handbook/network-servers X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 30 Oct 2013 19:42:09 -0000 Author: wblock Date: Wed Oct 30 19:42:08 2013 New Revision: 43078 URL: http://svnweb.freebsd.org/changeset/doc/43078 Log: Fix some issues with the iSCSI documents section. Reviewed by: emaste Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Oct 30 17:44:56 2013 (r43077) +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Oct 30 19:42:08 2013 (r43078) @@ -5825,40 +5825,41 @@ Logging to FILE /var/log/messages --> - iSCSI Initiator and Target Configuration + <acronym>iSCSI</acronym> Initiator and Target Configuration - iSCSI is a way to share storage; to make + 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, 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 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. - - iSCSI Target + + <acronym>iSCSI</acronym> Target - 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. + Note: the native iSCSI target is supported starting with + &os; 10.0-RELEASE. To use iSCSI in older versions of &os;, install a + userspace target from the Ports Collection, such as + net/istgt. + This chapter only describes the native target. Basic Operation - Configuring the iSCSI target is pretty straightforward: - one needs to create /etc/ctl.conf + 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 gets automatically started at boot, and then start + daemon is automatically started at boot, and then start the daemon. - Simple A simple ctl.conf(5) - configuration file might look like this: + configuration file looks like this: portal-group pg0 { discovery-auth-group no-authentication @@ -5876,62 +5877,69 @@ target iqn.2012-06.com.example:target0 { } } - First entry in the config file defines a portal group - called "pg0". Portal groups define network addresses the + The first entry defines the pg0 portal group. + Portal groups define network addresses the ctld(8) - 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 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 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 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 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 + 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. There can be any - number of targets defined in the config file. + 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. - 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. - - After that come LUNs. To the initiator, each LUN will - be visible as a separate disk device - e.g. + After that come LUNs. To the initiator, each LUN will + be visible as a separate disk device, like /dev/da0, /dev/da1 - 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 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, one needs to add the following + daemon is started at boot, add this line to /etc/rc.conf: ctld_enable="YES" - On a new server being configured as iSCSI target, the + On a new server being configured as iSCSI target, ctld(8) - can be started by running this command as root: + can be started by running this command as root: &prompt.root; service ctld start @@ -5950,10 +5958,10 @@ target iqn.2012-06.com.example:target0 { Authentication - The example above is inherently insecure - it uses no + 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: + targets, modify the configuration: auth-group ag0 { chap username1 secretsecret @@ -5975,17 +5983,17 @@ target iqn.2012-06.com.example:target0 { } } - The auth-group section defines username/password pairs. + 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 + 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. + 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 syntax - above, one can specify the username and password directly in the - target entry, like this: + 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 @@ -5999,63 +6007,64 @@ target iqn.2012-06.com.example:target0 { - - iSCSI Initiator + + <acronym>iSCSI</acronym> Initiator - The current iSCSI initiator is supported starting with - &os; 10.0-RELEASE. To use the iSCSI initiator available in + 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). This chapter only applies to the new initiator. - The iSCSI initiator requires The iSCSI initiator requires the iscsid(8) - 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 /etc/rc.conf: iscsid_enable="YES" - On a new machine being configured as iSCSI initiator, the + On a new machine being configured as an iSCSI initiator, iscsid(8) - can be started by running this command as root: + can be started by running this command as root: &prompt.root; service iscsid start - There are two basic ways to connect to a target: by using + Connecting to a target can be done with or without an iscsi.conf(8) - configuration file, or without it. + configuration file. - Connecting to a Target Without Using a Configuration + <title>Connecting to a Target Without a Configuration File To make the initiator connect to a single target, run - this command as root: + this command as root: &prompt.root; iscsictl -A -p 10.10.10.10 -t iqn.2012-06.com.example:target0 - To verify if it succeeded, run it without arguments. It - should output something like this: + 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 means the iSCSI session was successfully - established, where /dev/da0 - 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 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 (e.g. "Connected: da0 da1 da2"). + output: + Connected: da0 da1 da2. - Various errors are reported in system logs, and visible + Any errors are reported in the system logs, and also visible in the iscictl(8) output. For example, this usually means the Target name Target portal State iqn.2012-06.com.example:target0 10.10.10.11 Connection refused - The following means the specified target name was + 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 - The following means the target requires + 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 the following + To specify a CHAP username and secret, use this syntax: &prompt.root; iscsictl -A -p 10.10.10.10 -t iqn.2012-06.com.example:target0 -u user -s secretsecret - Connecting to a Target Using a Configuration + <title>Connecting to a Target With a Configuration File To connect using a configuration file, create - /etc/iscsi.conf that might look like + /etc/iscsi.conf with contents like this: t0 { @@ -6105,13 +6114,13 @@ iqn.2012-06.com.example:target0 chapSecret = secretsecret } - The first line ("t0") specifies a nickname for the + 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 case they specify CHAP username and - secret. + 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: