Long overdue addition of the iscsi.conf man page.

Help and OK jmc@, OK dlg@

3 files changed, 218 insertions, 4 deletions

diff --git a/usr.sbin/iscsictl/Makefile b/usr.sbin/iscsictl/Makefile
index f85561ef494..0ae4e8c881b 100644
--- a/usr.sbin/iscsictl/Makefile
+++ b/usr.sbin/iscsictl/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.2 2010/09/24 12:31:35 dlg Exp $
+#	$OpenBSD: Makefile,v 1.3 2012/06/26 21:09:44 claudio Exp $
 
 .PATH:		${.CURDIR}/../iscsid
 
@@ -6,7 +6,7 @@ PROG=	iscsictl
 SRCS=	iscsictl.c parse.y parser.c
 SRCS+=	util.c
 
-MAN=	iscsictl.8
+MAN=	iscsictl.8 iscsi.conf.5
 
 CFLAGS+= -Wall -Werror
 CFLAGS+= -Wstrict-prototypes -Wmissing-prototypes
diff --git a/usr.sbin/iscsictl/iscsi.conf.5 b/usr.sbin/iscsictl/iscsi.conf.5
new file mode 100644
index 00000000000..48b7e92401a
--- /dev/null
+++ b/usr.sbin/iscsictl/iscsi.conf.5
@@ -0,0 +1,210 @@
+.\" $OpenBSD: iscsi.conf.5,v 1.1 2012/06/26 21:09:44 claudio Exp $
+.\"
+.\" Copyright (c) 2012 Claudio Jeker <claudio@openbsd.org>
+.\" Copyright (c) 2003, 2004 Henning Brauer <henning@openbsd.org>
+.\" Copyright (c) 2002 Daniel Hartmeier <dhartmei@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: June 26 2012 $
+.Dt ISCSI.CONF 5
+.Os
+.Sh NAME
+.Nm iscsi.conf
+.Nd ISCSI daemon configuration file
+.Sh DESCRIPTION
+The
+.Xr iscsid 8
+daemon implements the Internet Small Computer Systems Interface as described
+in RFC 3720.
+.Sh SECTIONS
+The
+.Nm
+configuration file is divided into three main sections:
+.Bl -tag -width xxxx
+.It Sy Macros
+User-defined variables may be defined and used later, simplifying the
+configuration file.
+.It Sy Global Configuration
+Global settings for
+.Xr iscsid 8 .
+.It Sy Target Configuration
+Target-specific parameters.
+.El
+.Pp
+With the exception of macros,
+the sections should be grouped and appear in
+.Nm
+in the order shown above.
+.Pp
+The current line can be extended over multiple lines using a backslash
+.Pq Sq \e .
+Comments can be put anywhere in the file using a hash mark
+.Pq Sq # ,
+and extend to the end of the current line.
+Care should be taken when commenting out multi-line text:
+the comment is effective until the end of the entire block.
+.Pp
+Argument names not beginning with a letter, digit, or underscore
+must be quoted.
+.Pp
+Additional configuration files can be included with the
+.Ic include
+keyword, for example:
+.Bd -literal -offset indent
+include "/etc/iscsi-target.conf"
+.Ed
+.Sh MACROS
+Macros can be defined that will later be expanded in context.
+Macro names must start with a letter, digit, or underscore,
+and may contain any of those characters.
+Macro names may not be reserved words (for example,
+.Ic target ,
+or
+.Ic port ) .
+Macros are not expanded inside quotes.
+.Pp
+For example:
+.Bd -literal -offset indent
+target1="1.2.3.4"
+target "disk1" {
+        targetaddr $target1
+}
+.Ed
+.Sh GLOBAL CONFIGURATION
+There are a few settings that affect the operation of the
+.Xr iscsid 8
+daemon globally.
+.Pp
+.Bl -tag -width Ds -compact
+.It Xo
+.Ic isid
+.Pq Ic oui Ns | Ns Ic en Ns | Ns Ic rand
+.Ar base Ar qual
+.Xc
+The Initiator Session ID
+.Ic isid
+specifies the initiator part of the Session Identifier.
+It is set during startup of
+.Xr iscsid 8
+and is used for session reinstatement.
+By default a random
+.Ic isid
+is generated on startup.
+The random
+.Ic rand
+form has a 24-bit random number as
+.Ar base
+and a 16-bit
+.Ar qual
+qualifier.
+The
+.Ic oui
+format uses a 22-bit
+.Ar base
+OUI and a 24-bit
+.Ar qual
+qualifier.
+The IANA enterprise number format
+.Ic en
+uses the 24-bit enterprise number in
+.Ar base
+and a 16-bit
+.Ar qual
+qualifier.
+.El
+.Sh TARGET CONFIGURATION
+.Xr iscsid 8
+establishes TCP connections to iSCSI targets.
+Each target is specified by a
+.Em target
+section, which allows properties to be set specifically for that target:
+.Bd -literal -offset indent
+target disk1 {
+	targetaddr 10.0.0.2
+	targetname "iqn.1994-04.org.netbsd.iscsi-target:target:0"
+}
+.Ed
+.Pp
+There are several target properties:
+.Bl -tag -width Ds
+.It Op Ic disabled Ns | Ns Ic enabled
+No session will be established to the target if
+.Ic disabled
+is set.
+The default value is
+.Ic enabled .
+.It Op Ic discovery Ns | Ns Ic normal
+Define the type of session that will be established.
+It is possible to initiate a special
+.Ic discovery
+session to a target to enumerate the available volumes.
+.It Xo
+.Ic initiatoraddr Ar addr
+.Op Ic inet Ns | Ns Ic inet6
+.Op Ic port Ar num
+.Xc
+When
+.Xr iscsid 8
+initiates the TCP connection to the target system, it normally does not
+bind to a specific IP address and port.
+If an
+.Ic initiatoraddr
+is given,
+it binds to this address first.
+.It Ic initiatorname Ar string
+Specify the
+.Ic initiatorname
+used to connect to the remote target.
+The
+.Ic initiatorname
+can be used to restrict access to a target.
+If not given
+.Xr iscsid 8
+will use
+.Em iqn.1995-11.org.openbsd.iscsid
+as default.
+.It Xo
+.Ic targetaddr Ar addr
+.Op Ic inet Ns | Ns Ic inet6
+.Op Ic port Ar num
+.Xc
+Define the target IP address which
+.Xr iscsid 8
+should connect to.
+By default port 3260 will be used.
+.It Ic targetname Ar string
+The
+.Ic targetname
+specifies which LUN or disk should be requested by
+.Xr iscsid 8 .
+It is possible to enumerate remote systems with a
+.Ic discovery
+session.
+.El
+.Sh FILES
+.Bl -tag -width "/etc/iscsi.confXXX" -compact
+.It Pa /etc/iscsi.conf
+.Xr iscsid 8
+configuration file.
+.El
+.Sh SEE ALSO
+.Xr tcp 4 ,
+.Xr iscsictl 8 ,
+.Xr iscsid 8 ,
+.Xr rc.conf.local 8
+.Sh HISTORY
+The
+.Nm
+file format first appeared in
+.Ox 4.9 .
diff --git a/usr.sbin/iscsictl/iscsictl.8 b/usr.sbin/iscsictl/iscsictl.8
index d774813fc54..11b760715fd 100644
--- a/usr.sbin/iscsictl/iscsictl.8
+++ b/usr.sbin/iscsictl/iscsictl.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: iscsictl.8,v 1.1 2010/09/24 12:31:35 dlg Exp $
+.\"	$OpenBSD: iscsictl.8,v 1.2 2012/06/26 21:09:44 claudio Exp $
 .\"
 .\" Copyright (c) 2010 David Gwynne <dlg@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: September 24 2010 $
+.Dd $Mdocdate: June 26 2012 $
 .Dt ISCSICTL 8
 .Os
 .Sh NAME
@@ -51,6 +51,10 @@ Reload the configuration file.
 .El
 .Sh FILES
 .Bl -tag -width "/var/run/iscsid.sockXX" -compact
+.It /etc/iscsi.conf
+Default
+.Xr iscsid 8
+configuration file.
 .It /var/run/iscsid.sock
 .Ux Ns -domain
 socket used for communication with