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)

5 files changed, 313 insertions, 128 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 45e8dbf..bbefdb7 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -205,6 +205,7 @@ MAN=	aac.4 \
 	ipw.4 \
 	ipwfw.4 \
 	isci.4 \
+	iscsi.4 \
 	iscsi_initiator.4 \
 	isp.4 \
 	ispfw.4 \
diff --git a/share/man/man4/iscsi.4 b/share/man/man4/iscsi.4
new file mode 100755
index 0000000..2b0db75
--- /dev/null
+++ b/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.
diff --git a/usr.bin/iscsictl/iscsictl.8 b/usr.bin/iscsictl/iscsictl.8
index 439c8e58..b9231ac 100644
--- a/usr.bin/iscsictl/iscsictl.8
+++ b/usr.bin/iscsictl/iscsictl.8
@@ -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:target0, served by 192.168.1.1:
 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.
diff --git a/usr.sbin/ctld/ctl.conf.5 b/usr.sbin/ctld/ctl.conf.5
index 7abff86..4fc7017 100644
--- a/usr.sbin/ctld/ctl.conf.5
+++ b/usr.sbin/ctld/ctl.conf.5
@@ -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
diff --git a/usr.sbin/iscsid/iscsid.8 b/usr.sbin/iscsid/iscsid.8
index 89c7c25..e21252a 100644
--- a/usr.sbin/iscsid/iscsid.8
+++ b/usr.sbin/iscsid/iscsid.8
@@ -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 discovery.
 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.