Date: Thu, 18 Sep 2014 03:02:01 +0000 (UTC) From: Allan Jude <allanjude@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-10@freebsd.org Subject: svn commit: r271734 - in stable/10: share/man/man4 usr.bin/iscsictl usr.sbin/ctld usr.sbin/iscsid Message-ID: <201409180302.s8I3215e044600@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: allanjude (doc committer) Date: Thu Sep 18 03:02:00 2014 New Revision: 271734 URL: http://svnweb.freebsd.org/changeset/base/271734 Log: MFC r271445,r271446,r271560: Improve markup and language throughout the ctl.conf man page MFC r271543: Add the new iscsi(4) man page Cross reference it from iscsid(8) and iscsictl(8) Approved by: re (gjb), bcr (mentor) Added: stable/10/share/man/man4/iscsi.4 - copied unchanged from r271543, head/share/man/man4/iscsi.4 Modified: stable/10/share/man/man4/Makefile stable/10/usr.bin/iscsictl/iscsictl.8 stable/10/usr.sbin/ctld/ctl.conf.5 stable/10/usr.sbin/iscsid/iscsid.8 Directory Properties: stable/10/ (props changed) Modified: stable/10/share/man/man4/Makefile ============================================================================== --- stable/10/share/man/man4/Makefile Thu Sep 18 02:22:02 2014 (r271733) +++ stable/10/share/man/man4/Makefile Thu Sep 18 03:02:00 2014 (r271734) @@ -205,6 +205,7 @@ MAN= aac.4 \ ipw.4 \ ipwfw.4 \ isci.4 \ + iscsi.4 \ iscsi_initiator.4 \ isp.4 \ ispfw.4 \ Copied: stable/10/share/man/man4/iscsi.4 (from r271543, head/share/man/man4/iscsi.4) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/10/share/man/man4/iscsi.4 Thu Sep 18 03:02:00 2014 (r271734, copy of r271543, head/share/man/man4/iscsi.4) @@ -0,0 +1,111 @@ +.\" Copyright (c) 2014 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.Dd September 11, 2014 +.Dt ISCSI 4 +.Os +.Sh NAME +.Nm iscsi +.Nd iSCSI initiator +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iscsi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iscsi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +subsystem provides the kernel component of an iSCSI initiator. +The initiator is the iSCSI client, which connects to an iSCSI target, +providing local access to a remote block device. +The userland component is provided by +.Xr iscsid 8 +and both the kernel and userland are configured using +.Xr iscsictl 8 . +The +.Nm +subsystem is responsible for implementing the +.Qq Full Feature Phase +of the iSCSI protocol. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.iscsi.ping_timeout +The number of seconds to wait for the target to respond to a NOP-Out +PDU. +In the event that there is no response within that time the session gets +forcibly restarted. +.It Va kern.iscsi.iscsid_timeout +The number of seconds to wait for +.Xr ctld 8 +to establish a session. +After that time +.Nm +will abort and retry. +.It Va kern.iscsi.login_timeout +The number of seconds to wait for a login attempt to succeed. +After that time +.Nm +will abort and retry. +.It Va kern.iscsi.maxtags +The maximum number of outstanding IO requests. +.It Va kern.iscsi.fail_on_disconnection +Controls the behavior after an iSCSI connection has been dropped due to +network problems. +When set to 1, a dropped connection causes the iSCSI device nodes +to be destroyed. +After reconnecting, they will be created again. +By default, the device nodes are left intact. +While the connection is down all input/output operations are suspended, to be +retried after the connection is reestablished. +.El +.Sh SEE ALSO +.Xr iscsi.conf 5 , +.Xr iscsictl 8 , +.Xr iscsid 8 +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Fx 10.0 . +.Sh AUTHORS +The +.Nm +subsystem was developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. Modified: stable/10/usr.bin/iscsictl/iscsictl.8 ============================================================================== --- stable/10/usr.bin/iscsictl/iscsictl.8 Thu Sep 18 02:22:02 2014 (r271733) +++ stable/10/usr.bin/iscsictl/iscsictl.8 Thu Sep 18 03:02:00 2014 (r271734) @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd June 18, 2014 +.Dd September 12, 2014 .Dt ISCSICTL 8 .Os .Sh NAME @@ -171,6 +171,7 @@ Attach to target iqn.2012-06.com.example Disconnect all iSCSI sessions: .Dl Nm Fl Ra .Sh SEE ALSO +.Xr iscsi 4 , .Xr iscsi.conf 5 , .Xr iscsid 8 .Sh HISTORY @@ -181,6 +182,6 @@ command appeared in .Sh AUTHORS The .Nm -was developed by +utility was developed by .An Edward Tomasz Napierala Aq trasz@FreeBSD.org under sponsorship from the FreeBSD Foundation. Modified: stable/10/usr.sbin/ctld/ctl.conf.5 ============================================================================== --- stable/10/usr.sbin/ctld/ctl.conf.5 Thu Sep 18 02:22:02 2014 (r271733) +++ stable/10/usr.sbin/ctld/ctl.conf.5 Thu Sep 18 03:02:00 2014 (r271734) @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 28, 2014 +.Dd September 11, 2014 .Dt CTL.CONF 5 .Os .Sh NAME @@ -46,179 +46,249 @@ The general syntax of the .Nm file is: .Bd -literal -offset indent -pidfile <path> +.No pidfile Ar path -auth-group <name> { - chap <user> <secret> - ... +.No auth-group Ar name No { +.Dl chap Ar user Ar secret +.Dl ... } -portal-group <name> { - listen <address> - listen-iser <address> - discovery-auth-group <name> - ... +.No portal-group Ar name No { +.Dl listen Ar address +.Dl listen-iser Ar address +.Dl discovery-auth-group Ar name +.Dl ... } -target <name> { - auth-group <name> - portal-group <name> - lun <number> { - path <path> - } - ... +.No target Ar name { +.Dl auth-group Ar name +.Dl portal-group Ar name +.Dl lun Ar number No { +.Dl path Ar path +.Dl } +.Dl ... } .Ed -.Ss global level -The following statements are available at the global level: +.Ss Global Context .Bl -tag -width indent -.It Ic auth-group Aq Ar name -Opens an auth-group section, defining an authentication group, +.It Ic auth-group Ar name +Create an +.Sy auth-group +configuration context, +defining a new auth-group, which can then be assigned to any number of targets. -.It Ic debug Aq Ar level -Specifies debug level. +.It Ic debug Ar level +The debug verbosity level. The default is 0. -.It Ic maxproc Aq Ar number -Specifies limit for concurrently running child processes handling +.It Ic maxproc Ar number +The limit for concurrently running child processes handling incoming connections. The default is 30. -Setting it to 0 disables the limit. -.It Ic pidfile Aq Ar path -Specifies path to pidfile. +A setting of 0 disables the limit. +.It Ic pidfile Ar path +The path to the pidfile. The default is .Pa /var/run/ctld.pid . -.It Ic portal-group Aq Ar name -Opens a portal-group section, defining a portal group, +.It Ic portal-group Ar name +Create a +.Sy portal-group +configuration context, which can then be assigned to any number of targets. -.It Ic target Aq Ar name -Opens a target configuration section. -.It Ic timeout Aq Ar seconds -Specifies timeout for login session, after which the connection +.It Ic target Ar name +Create a +.Sy target +configuration context, which can contain one or more +.Sy lun +contexts. +.It Ic timeout Ar seconds +The timeout for login sessions, after which the connection will be forcibly terminated. The default is 60. -Setting it to 0 disables the timeout. +A setting of 0 disables the timeout. .El -.Ss auth-group level -The following statements are available at the auth-group level: +.Ss auth-group Context .Bl -tag -width indent -.It Ic auth-type Ao Ar type Ac -Specifies authentication type. -Type can be either "none", "deny", "chap", or "chap-mutual". + +.It Ic auth-type Ar type +Sets the authentication type. +Type can be either +.Qq Ar none , +.Qq Ar deny , +.Qq Ar chap , +or +.Qq Ar chap-mutual . In most cases it is not necessary to set the type using this clause; -it is usually used to disable authentication for a given auth-group. -.It Ic chap Ao Ar user Ac Aq Ar secret -Specifies CHAP authentication credentials. -.It Ic chap-mutual Ao Ar user Ac Ao Ar secret Ac Ao Ar mutualuser Ac Aq Ar mutualsecret -Specifies mutual CHAP authentication credentials. -Note that for any auth-group, configuration may contain either chap, -or chap-mutual entries; it is an error to mix them. -.It Ic initiator-name Ao Ar initiator-name Ac -Specifies iSCSI initiator name. +it is usually used to disable authentication for a given +.Sy auth-group . +.It Ic chap Ar user Ar secret +A set of CHAP authentication credentials. +Note that for any +.Sy auth-group , +the configuration may only contain either +.Sy chap +or +.Sy chap-mutual +entries; it is an error to mix them. +.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret +A set of mutual CHAP authentication credentials. +Note that for any +.Sy auth-group , +the configuration may only contain either +.Sy chap +or +.Sy chap-mutual +entries; it is an error to mix them. +.It Ic initiator-name Ar initiator-name +An iSCSI initiator name. +Only initiators with a name matching one of the defined +names will be allowed to connect. If not defined, there will be no restrictions based on initiator name. -Otherwise, only initiators with names matching one of defined -ones will be allowed to connect. -.It Ic initiator-portal Ao Ar address Ac -Specifies iSCSI initiator portal - IPv4 or IPv6 address or network. +.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen +An iSCSI initiator portal: an IPv4 or IPv6 address, optionally +followed by a literal slash and a prefix length. +Only initiators with an address matching one of the defined +addresses will be allowed to connect. If not defined, there will be no restrictions based on initiator address. -Otherwise, only initiators with addresses matching one of defined -ones will be allowed to connect. .El -.Ss portal-group level -The following statements are available at the portal-group level: +.Ss portal-group Context .Bl -tag -width indent -.It Ic discovery-auth-group Aq Ar name -Assigns previously defined authentication group to the portal group, +.It Ic discovery-auth-group Ar name +Assign a previously defined authentication group to the portal group, to be used for target discovery. By default, portal groups that do not specify their own auth settings, -using clauses such as "chap" or "initiator-name", are assigned -predefined auth-group "default", which denies discovery. -Another predefined auth-group, "no-authentication", may be used +using clauses such as +.Sy chap +or +.Sy initiator-name , +are assigned +predefined +.Sy auth-group +.Qq Ar default , +which denies discovery. +Another predefined +.Sy auth-group , +.Qq Ar no-authentication , +may be used to permit discovery without authentication. -.It Ic listen Aq Ar address -Specifies IPv4 or IPv6 address and port to listen on for incoming connections. -.It Ic listen-iser Aq Ar address -Specifies IPv4 or IPv6 address and port to listen on for incoming connections +.It Ic listen Ar address +An IPv4 or IPv6 address and port to listen on for incoming connections. +.It Ic listen-iser Ar address +An IPv4 or IPv6 address and port to listen on for incoming connections using iSER (iSCSI over RDMA) protocol. .El -.Ss target level: -The following statements are available at the target level: +.Ss target Context .Bl -tag -width indent -.It Ic alias Aq Ar text -Assigns human-readable description to the target. +.It Ic alias Ar text +Assign a human-readable description to the target. There is no default. -.It Ic auth-group Aq Ar name -Assigns previously defined authentication group to the target. +.It Ic auth-group Ar name +Assign a previously defined authentication group to the target. By default, targets that do not specify their own auth settings, -using clauses such as "chap" or "initiator-name", are assigned -predefined auth-group "default", which denies all access. -Another predefined auth-group, "no-authentication", may be used to permit access +using clauses such as +.Sy chap +or +.Sy initiator-name , +are assigned +predefined +.Sy auth-group +.Qq Ar default , +which denies all access. +Another predefined +.Sy auth-group , +.Qq Ar no-authentication , +may be used to permit access without authentication. -.It Ic auth-type Ao Ar type Ac -Specifies authentication type. -Type can be either "none", "deny", "chap", or "chap-mutual". +Note that targets must only use one of +.Sy auth-group , chap , No or Sy chap-mutual ; +it is a configuration error to mix multiple types in one target. +.It Ic auth-type Ar type +Sets the authentication type. +Type can be either +.Qq Ar none , +.Qq Ar deny , +.Qq Ar chap , +or +.Qq Ar chap-mutual . In most cases it is not necessary to set the type using this clause; -it is usually used to disable authentication for a given target. -This clause is mutually exclusive with auth-group; one cannot use +it is usually used to disable authentication for a given +.Sy target . +This clause is mutually exclusive with +.Sy auth-group ; +one cannot use both in a single target. -.It Ic chap Ao Ar user Ac Aq Ar secret -Specifies CHAP authentication credentials. -Note that targets must use either auth-group, or chap, -or chap-mutual clauses; it is a configuration error to mix them in one target. -.It Ic chap-mutual Ao Ar user Ac Ao Ar secret Ac Ao Ar mutualuser Ac Aq Ar mutualsecret -Specifies mutual CHAP authentication credentials. -Note that targets must use either auth-group, chap, or -chap-mutual clauses; it is a configuration error to mix them in one target. -.It Ic initiator-name Ao Ar initiator-name Ac -Specifies iSCSI initiator name. +.It Ic chap Ar user Ar secret +A set of CHAP authentication credentials. +Note that targets must only use one of +.Sy auth-group , chap , No or Sy chap-mutual ; +it is a configuration error to mix multiple types in one target. +.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret +A set of mutual CHAP authentication credentials. +Note that targets must only use one of +.Sy auth-group , chap , No or Sy chap-mutual ; +it is a configuration error to mix multiple types in one target. +.It Ic initiator-name Ar initiator-name +An iSCSI initiator name. +Only initiators with a name matching one of the defined +names will be allowed to connect. If not defined, there will be no restrictions based on initiator name. -Otherwise, only initiators with names matching one of defined -ones will be allowed to connect. -This clause is mutually exclusive with auth-group; one cannot use +This clause is mutually exclusive with +.Sy auth-group ; +one cannot use both in a single target. -.It Ic initiator-portal Ao Ar address Ac -Specifies iSCSI initiator portal - IPv4 or IPv6 address. +.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen +An iSCSI initiator portal: an IPv4 or IPv6 address, optionally +followed by a literal slash and a prefix length. +Only initiators with an address matching one of the defined +addresses will be allowed to connect. If not defined, there will be no restrictions based on initiator address. -Otherwise, only initiators with addresses matching one of defined -ones will be allowed to connect. -This clause is mutually exclusive with auth-group; one cannot use +This clause is mutually exclusive with +.Sy auth-group ; +one cannot use both in a single target. -.It Ic portal-group Aq Ar name -Assigns previously defined portal group to the target. -Default portal group is "default", which makes the target available +.It Ic portal-group Ar name +Assign a previously defined portal group to the target. +The default portal group is +.Qq Ar default , +which makes the target available on TCP port 3260 on all configured IPv4 and IPv6 addresses. -.It Ic lun Aq Ar number -Opens a lun configuration section, defining LUN exported by a target. +.It Ic lun Ar number +Create a +.Sy lun +configuration context, defining a LUN exported by the parent target. .El -.Ss lun level -The following statements are available at the lun level: +.Ss lun Context .Bl -tag -width indent -.It Ic backend Ao Ar block | Ar ramdisk Ac -Specifies the CTL backend to use for a given LUN. +.It Ic backend Ar block No | Ar ramdisk +The CTL backend to use for a given LUN. Valid choices are -.Dq block +.Qq Ar block and -.Dq ramdisk ; +.Qq Ar ramdisk ; block is used for LUNs backed by files or disk device nodes; ramdisk is a bitsink device, used mostly for testing. The default backend is block. -.It Ic blocksize Aq Ar size -Specifies blocksize visible to the initiator. +.It Ic blocksize Ar size +The blocksize visible to the initiator. The default blocksize is 512. -.It Ic device-id Aq Ar string -Specifies SCSI Device Identification string presented to the initiator. -.It Ic option Ao Ar name Ac Aq Ar value -Specifies CTL-specific options passed to the kernel. -.It Ic path Aq Ar path -Specifies path to file or device node used to back the LUN. -.It Ic serial Aq Ar string -Specifies SCSI serial number presented to the initiator. -.It Ic size Aq Ar size -Specifies LUN size, in bytes. +.It Ic device-id Ar string +The SCSI Device Identification string presented to the initiator. +.It Ic option Ar name Ar value +The CTL-specific options passed to the kernel. +All CTL-specific options are documented in the +.Sx OPTIONS +section of +.Xr ctladm 8 +.It Ic path Ar path +The path to the file or device node used to back the LUN. +.It Ic serial Ar string +The SCSI serial number presented to the initiator. +.It Ic size Ar size +The LUN size, in bytes. .El .Sh FILES .Bl -tag -width ".Pa /etc/ctl.conf" -compact Modified: stable/10/usr.sbin/iscsid/iscsid.8 ============================================================================== --- stable/10/usr.sbin/iscsid/iscsid.8 Thu Sep 18 02:22:02 2014 (r271733) +++ stable/10/usr.sbin/iscsid/iscsid.8 Thu Sep 18 03:02:00 2014 (r271734) @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 20, 2012 +.Dd September 12, 2014 .Dt ISCSID 8 .Os .Sh NAME @@ -49,12 +49,13 @@ as well as performing SendTargets discov Upon startup, the .Nm daemon opens the iSCSI initiator device file and waits for kernel requests. -It doesn't use any configuration file; all the information it needs it gets -from the kernel. +.Nm +does not use any configuration files. +All needed information is supplied by the kernel. .Pp When the .Nm -damon is not running, already established iSCSI connections continue +daemon is not running, already established iSCSI connections continue to work. However, establishing new connections, or recovering existing ones in case of connection error, is not possible. @@ -99,6 +100,7 @@ The .Nm utility exits 0 on success, and >0 if an error occurs. .Sh SEE ALSO +.Xr iscsi 4 , .Xr iscsictl 8 .Sh HISTORY The @@ -108,6 +110,6 @@ command appeared in .Sh AUTHORS The .Nm -was developed by +utility was developed by .An Edward Tomasz Napierala Aq trasz@FreeBSD.org under sponsorship from the FreeBSD Foundation.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409180302.s8I3215e044600>