From owner-svn-doc-all@FreeBSD.ORG Wed Oct 9 14:17:08 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 9B5B4C07; Wed, 9 Oct 2013 14:17:08 +0000 (UTC) (envelope-from trasz@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 872FC2A71; Wed, 9 Oct 2013 14:17: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 r99EH8vM012215; Wed, 9 Oct 2013 14:17:08 GMT (envelope-from trasz@svn.freebsd.org) Received: (from trasz@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r99EH8Qq012214; Wed, 9 Oct 2013 14:17:08 GMT (envelope-from trasz@svn.freebsd.org) Message-Id: <201310091417.r99EH8Qq012214@svn.freebsd.org> From: Edward Tomasz Napierala Date: Wed, 9 Oct 2013 14:17:08 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42910 - 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, 09 Oct 2013 14:17:08 -0000 Author: trasz (src,ports committer) Date: Wed Oct 9 14:17:08 2013 New Revision: 42910 URL: http://svnweb.freebsd.org/changeset/doc/42910 Log: 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 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 9 11:56:24 2013 (r42909) +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Oct 9 14:17:08 2013 (r42910) @@ -88,6 +88,10 @@ syslogd, to accept logs from remote hosts. + + + How to set up iSCSI. + This chapter assumes a basic knowledge of: @@ -6179,4 +6183,322 @@ Logging to FILE /var/log/messages + + + + + + Edward Tomasz + Napierala + + + + + 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, 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. + + + iSCSI Target + + 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. + + + Basic Operation + + Configuring the iSCSI target is pretty straightforward: + one needs to create /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 + the daemon. + + Simple ctl.conf(5) + configuration file might look 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 + } +} + + First entry in the config file defines a portal group + called "pg0". 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 ctld(8) + 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. + + 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. + + 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. + + After that come LUNs. To the initiator, each LUN will be + visible as a separate disk device - e.g. + /dev/da0, /dev/da1 + 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 ctld(8). + Second line is optional and specifies the size. + + To make sure ctld(8) + daemon is started at boot, one needs to add the following line + to /etc/rc.conf: + + ctld_enable="YES" + + On a new server being configured as iSCSI target, the + ctld(8) + can be started by running this command as root: + + &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: + + &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 configuration like this: + + 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/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. + + 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: + + target iqn.2012-06.com.example:target0 { + portal-group pg0 + chap username1 secretsecret + + lun 0 { + path /data/target0-0 + size 4G + } +} + + + + + iSCSI Initiator + + + The current iSCSI initiator is supported starting with + &os; 10.0-RELEASE. To use iSCSI initiator available in + older versions, refer to the iscontrol(8) + manual page. This chapter only applies to the new + initiator. + + + The iSCSI initiator requires 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 /etc/rc.conf: + + iscsid_enable="YES" + + On a new machine being configured as iSCSI initiator, the + iscsid(8) + 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 + iscsi.conf(8) + configuration file, or without it. + + + Connecting to a Target Without Using a Configuration + File + + To make the initiator connect to a single target, run + this command as root: + + &prompt.root; iscsictl -A -h 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: + + Target name Target addr State +iqn.2012-06.com.example:target0 10.10.10.10 Connected: da0 + + This means the iSCSI session was successfully + established, and you have /dev/da0 + 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 iscictl(8) + output (e.g. "Connected: da0 da1 da2"). + + Various errors are reported in system logs, and visible + in the iscictl(8) + output. For example, this usually means the iscsid(8) + daemon is not running: + + Target name Target addr State +iqn.2012-06.com.example:target0 10.10.10.10 Waiting for iscsid(8) + + The following suggests network-level problem, such as + wrong IP address or port: + + Target name Target addr State +iqn.2012-06.com.example:target0 10.10.10.11 Connection refused + The following means the specified target name was + wrong: + + Target name Target addr State +iqn.2012-06.com.example:atrget0 10.10.10.10 Not found + + The following means the target requires + authentication: + + Target name Target addr State +iqn.2012-06.com.example:target0 10.10.10.10 Authentication failed + + To specify CHAP username and secret, use the following + syntax: + + &prompt.root; iscsictl -A -h 10.10.10.10 -t iqn.2012-06.com.example:target0 -u user -s secretsecret + + + + Connecting to a Target Using a Configuration + File + + To connect using a configuration file, create + /etc/iscsi.conf that might look like + this: + + t0 { + TargetAddress = 10.10.10.10 + TargetName = iqn.2012-06.com.example:target0 + AuthMethod = CHAP + chapIName = user + chapSecret = secretsecret +} + + 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. + + To connect to the target defined above, use: + + &prompt.root; iscsictl -An t0 + + To connect to all targets defined in the configuration + file, use: + + &prompt.root; 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" + + + + +