Update scstadmin and scst.conf man pages with information about ALUA. Update the scst.conf example too.

git-svn-id: http://svn.code.sf.net/p/scst/svn/trunk@3782 d57e44dd-8a1f-0410-8b47-8ef2f437770f

scstadmin/examples/scst.conf.sysfs

@@ -35,14 +35,33 @@ HANDLER vcdrom {
 TARGET_DRIVER scst_local {
 	TARGET scst_local_tgt {
 		session_name scst_local_host
-		session_name scst_local_host1
 
 		LUN 0 disk1
+		LUN 1 disk2
+	}
+}
+
+TARGET_DRIVER iscsi {
+	IncomingUser "joe 12charsecret"
+	enabled 1
+
+	TARGET iqn.2006-10.net.vlnb:tgt {
+		IncomingUser "joe 12charsecret"
+		HeaderDigest CRC32C,None
+		enabled 1
+
+		LUN 0 disk1
+		LUN 1 disk2
+		LUN 2 blockio1 {
+			read_only 1
+		}
 	}
 }
 
 TARGET_DRIVER qla2x00t {
 	TARGET 25:00:00:f0:98:87:92:f3 {
+		enabled 1
+
 		GROUP INI1 {
 			LUN 0 blockio1
 			LUN 1 1:0:0:0 {
@@ -53,30 +72,68 @@ TARGET_DRIVER qla2x00t {
 			INITIATOR 25:00:00:f0:99:87:94:a3
 			INITIATOR 25:00:00:f0:99:87:94:a4
 		}
-
-		enabled 1
 	}
 
 	TARGET 25:00:00:f0:98:87:92:f4 {
 	}
 }
 
-TARGET_DRIVER iscsi {
+TARGET_DRIVER ib_srpt {
-	IncomingUser "joe 12charsecret"
+	TARGET ib_srpt_target_0 {
-
+		enabled 1
-	TARGET iqn.2006-10.net.vlnb:tgt {
-		IncomingUser "joe 12charsecret"
-		HeaderDigest CRC32C,None
 
 		LUN 0 disk1
 		LUN 1 disk2
-		LUN 2 blockio1 {
-			read_only 1
-		}
-
-		enabled 1
 	}
 
-	enabled 1
+	TARGET ib_srpt_target_1 {
+		enabled 1
+
+		LUN 0 disk1
+		LUN 1 disk2
+	}
 }
 
+DEVICE_GROUP dgroup1 {
+	DEVICE disk1
+
+	TARGET_GROUP tgroup1 {
+		group_id 1
+		state active
+
+		TARGET ib_srpt_target_0 {
+			rel_tgt_id 1
+		}
+	}
+
+	TARGET_GROUP tgroup2 {
+		group_id 2
+		state offline
+
+		TARGET ib_srpt_target_1 {
+			rel_tgt_id 2
+		}
+	}
+}
+
+DEVICE_GROUP dgroup2 {
+	DEVICE disk2
+
+	TARGET_GROUP tgroup1 {
+		group_id 1
+		state offline
+
+		TARGET ib_srpt_target_0 {
+			rel_tgt_id 1
+		}
+	}
+
+	TARGET_GROUP tgroup2 {
+		group_id 2
+		state active
+
+		TARGET ib_srpt_target_1 {
+			rel_tgt_id 2
+		}
+	}
+}

scstadmin/scstadmin.sysfs/man1/scstadmin.1

@@ -13,7 +13,27 @@ SCST consists of multiple kernel modules: the SCST core, SCST target drivers
 and SCST device handlers. The state of each of these kernel modules is
 configurable at runtime. Scstadmin allows query the current state, to modify
 the current state, to save the current state to a file and to restore the SCST
-state from a file.
+state from a file. The relevant SCST concepts are:
+.TP
+.B device
+An SCST device represents local storage that is exported via SCST. An SCST
+device is either a local SCSI device (disk, CD-ROM, tape, ...), a block I/O
+device like a disk or RAID controller or a file on a filesystem.  The SCST
+drivers that control SCST devices are called device handlers.  Examples of
+such device handlers are dev_disk, vdisk_blockio and vdisk_fileio.
+.TP
+.B target
+An SCST target is an interface that allows a remote system to access the
+storage exported via SCST. Each target is controlled by a target
+driver. Examples of target drivers are iscsi_scst, qla2x00t, ib_srpt and
+scst_local.
+.TP
+.B ALUA
+An SCST setup can have multiple storage interfaces. A single SCST server can
+be equipped with multiple interfaces or two SCST servers can have been set up
+in a cluster. If there are multiple paths between an initiator and a target
+system or target cluster then configuring ALUA (Asymmetric Logical Unit
+Access) will make SCST to tell the initiator which path to use.
 .SH OPTIONS
 .PP
 <OPTION> is one of:
@@ -111,12 +131,25 @@ Show name and value of all attributes of the specified LUN. The LUN number
 either refers to a LUN associated with a target or to a LUN associated with
 an initiator group of a target.
 .TP
-.B -list_init_attr <ini> -driver <driver> -target <target> -group <group>
-Show name and value of all attributes of the specified initiator.
-.TP
 .B -list_sessions
 Show all active sessions for all targets.
 .TP
+.B -list_dgrp [<dgrp>]
+If no device group name has been specified, show all defined ALUA device
+groups. If a device group name has been specified, show configuration
+information for that device group only.
+.TP
+.B -list_tgrp [<tgrp>] -dev_group <dgrp>
+If no ALUA target group name has been specified, list the target groups
+associated with the specified device group. If a target group name has been
+specified, show configuration information for that target group.
+.TP
+.B -list_tgrp_attr <tgrp> -dev_group <dgrp>
+Show a list with all ALUA attributes of the specified target group.
+.TP
+.B -list_ttgt_attr <tgt> -dev_group <dgrp> -tgt_group <tgrp>
+Show a list with all ALUA attributes of the specified target.
+.TP
 .B -set_scst_attr -attributes <p=v,...>
 Set the value of one or more SCST core attributes.
 .TP
@@ -140,9 +173,6 @@ Set the value of one or more LUN attributes. The LUN number either refers to a
 LUN associated with a target or to a LUN associated with an initiator group of
 a target.
 .TP
-.B -set_init_attr <ini> -driver <driver> -target <target> -group <group> -attributes <p=v,...>
-Set the value of an initiator group attribute.
-.TP
 .B -add_drv_attr <driver> -attributes <p=v,...>
 Add one or more new attributes to the specified target driver and set these to
 the specified values. Which attribute names are valid depends on the affected
@@ -199,13 +229,15 @@ Move an initiator or initiator name pattern from one initiator group to another.
 .B -clear_inits -driver <driver> -target <target> -group <group>
 Remove all initiators from an initiator group.
 .TP
-.B -add_lun <lun> -driver <driver> -target <target> [-group <group>] -device <device> -attributes <p=v,...>
+.B -add_lun <lun> -driver <driver> -target <target> [-group <group>] \
+     -device <device> -attributes <p=v,...>
 Add a LUN to a target or initiator group.
 .TP
 .B -rem_lun <lun> -driver <driver> -target <target> [-group <group>]
 Remove a LUN from a target or initiator group.
 .TP
-.B -replace_lun <lun> -driver <driver> -target <target> [-group <group>] -device <device> -attributes <p=v,...>
+.B -replace_lun <lun> -driver <driver> -target <target> [-group <group>] \
+     -device <device> -attributes <p=v,...>
 Replace the device associated with a LUN by another device.
 .TP
 .B -clear_luns -driver <driver> -target <target> [-group <group>]
@@ -220,6 +252,13 @@ Disable a target.
 .B -issue_lip [<target>] [-driver <driver>]
 Issue a LIP (Loop Initialization Protocol, fibre channel) for a specific
 target or for all drivers and targets.
+.TP
+.B -set_tgrp_attr <tgrp> -dev_group <dgrp> -attributes <p=v,...>
+Set one or more attributes of the specified ALUA target group.
+.TP
+.B -set_ttgt_attr <tgt> -dev_group <dgrp> -tgt_group <tgrp> \
+     -attributes <p=v,...>
+Set one or more attributes of the specified ALUA target.
 .SH EXAMPLES
 .TP
 .B scstadmin -open_dev disk01 -handler vdisk_fileio -attributes filename=/vdisks/disk01.dsk,read_only
@@ -241,10 +280,10 @@ Enables target mode for the fibre channel HCA port with the specified WWN.
 Save the current configuration to the specified file.
 .SH AUTHORS
 The scstadmin software has been developed by Mark R. Buechler and also
-contains contributions from Bart Van Assche.  Please send feedback about
+contains contributions from Bart Van Assche.
-scstadmin itself or its documentation to the mailing list
+.SH REPORTING BUGS
-scst-devel@lists.sourceforge.net. See also
+Please send feedback about scstadmin itself or its documentation to the
-.br
+mailing list scst-devel@lists.sourceforge.net. See also
 https://lists.sourceforge.net/lists/listinfo/scst-devel for more information
 about this mailing list.
 .SH FILES

scstadmin/scstadmin.sysfs/man5/scst.conf.5

@@ -9,7 +9,8 @@ scst.conf \- Main SCST configuration file.
 .I scst.conf
 is the main SCST configuration file. It contains information about the
 configuration of the SCST core, device handlers, devices, target drivers,
-targets, initiator groups and LUNs. This file is read and applied by the
+targets, initiator groups, LUNs and ALUA configuration. This file is read and
+applied by the
 .BR scstadmin (1)
 program when the SCST service starts.
 .P
@@ -17,7 +18,9 @@ The format of the
 .I scst.conf
 file is as follows:
 .br
-- Blank lines and lines starting with a hash sign (#) are ignored.
+- Blank lines and lines starting with a hash sign
+.RB ( # )
+are ignored.
 .br
 - All other lines either define an attribute, mark the start of a new section
 or the end of a section.
@@ -42,22 +45,63 @@ marks the start of a new section.
 marks the end of a section.
 .P
 The recognized section names and their arguments are:
-.IP "HANDLER <handler>"
+.TP
-<handler> is the name of an SCST device handler.
+.B "HANDLER <handler>"
-.IP "DEVICE <name>"
+Defines device handler attributes and also which devices are associated with
-<name> is either a H:C:I:L quadruplet referring to a local SCSI device
+the specified device handler. <handler> is the name of an SCST device handler.
-or an SCST device name.
+.TP
-.IP "TARGET_DRIVER <driver>"
+.B "DEVICE <name>"
-<driver> is the name of an SCST target driver.
+Defines the name and attributes of an SCST device.  <name> is either a H:C:I:L
-.IP "TARGET <target>"
+quadruplet referring to a local SCSI device or an SCST device name. A
-<target> is the name of an SCST target.
+.B DEVICE
-.IP "LUN <number>"
+section is a subsection of a
-.IP "GROUP <group>"
+.B HANDLER
-<group> is the name of an SCST initiator group.
+section. 
-.IP "INITIATOR <ini>"
+.TP
-<ini> is either an initiator name or a wildcard pattern matching zero or more
+.B "TARGET_DRIVER <driver>"
-initiator names. The supported wildcard characters are:
+Defines target driver attributes and also which targets are associated with
-.BR ! ", " * " and " ? .
+the specified target driver. <driver> is the name of an SCST target driver.
+.TP
+.B "TARGET <target>"
+A
+.B TARGET
+section is either a subsection of a
+.B TARGET_DRIVER
+or of a
+.B TARGET_GROUP
+section. The former is the definition of an SCST target while the latter
+is a reference to an SCST target defined on the local system or on
+another system in the same cluster.
+.TP
+.B "LUN <number> <device name>"
+Associates an SCST device with a target and defines its LUN number.
+.RB "A " LUN " section is a subsection of a " TARGET " section."
+.TP
+.B "GROUP <group>"
+Defines an initiator group with the specified name. A
+.B GROUP
+section is a subsection of a
+.B TARGET
+section.
+.TP
+.B "INITIATOR <ini>"
+Associates an initiator name with an initiator group.  <ini> is either an
+initiator name or a wildcard pattern matching zero or more initiator
+names. The supported wildcard characters are:
+.BR ! ", " * " and " ? ". An " INITIATOR
+section is a subsection of a
+.B GROUP
+section.
+.TP
+.B "DEVICE_GROUP <dg>"
+<dg> is the name of a group of devices that share ALUA settings.
+.TP
+.B "TARGET_GROUP <tg>"
+Defines an ALUA target port group. A
+.B TARGET_GROUP
+section is a subsection of a
+.B DEVICE_GROUP
+section.
 .P
 An example:
 .IP
@@ -120,8 +164,6 @@ TARGET_DRIVER scst_local {
 	TARGET scst_local_tgt {
 .br
 		session_name scst_local_host
-.br
-		session_name scst_local_host1
 .IP
 		LUN 0 disk1
 .br
@@ -129,10 +171,44 @@ TARGET_DRIVER scst_local {
 .br
 }
 .IP
+TARGET_DRIVER iscsi {
+.br
+	IncomingUser "joe 12charsecret"
+.br
+	enabled 1
+.IP
+	TARGET iqn.2006-10.net.vlnb:tgt {
+.br
+		IncomingUser "joe 12charsecret"
+.br
+		IncomingUser "fred 12charsecret2"
+.br
+		IncomingUser "jonas 12charsecret3"
+.br
+		HeaderDigest CRC32C,None
+.br
+		enabled 1
+.IP
+		LUN 0 disk1
+.br
+		LUN 1 disk2
+.br
+		LUN 2 blockio1 {
+.br
+			read_only 1
+.br
+		}
+.br
+	}
+.br
+}
+.IP
 TARGET_DRIVER qla2x00t {
 .br
 	TARGET 25:00:00:f0:98:87:92:f3 {
 .br
+		enabled 1
+.IP
 		GROUP INI1 {
 .br
 			LUN 0 blockio1
@@ -150,8 +226,6 @@ TARGET_DRIVER qla2x00t {
 			INITIATOR 25:00:00:f0:99:87:94:a4
 .br
 		}
-.IP
-		enabled 1
 .br
 	}
 .IP
@@ -161,35 +235,95 @@ TARGET_DRIVER qla2x00t {
 .br
 }
 .IP
-TARGET_DRIVER iscsi {
+TARGET_DRIVER ib_srpt {
 .br
-	IncomingUser "joe 12charsecret"
+	TARGET ib_srpt_target_0 {
-.IP
-	TARGET iqn.2006-10.net.vlnb:tgt {
 .br
-		IncomingUser "joe 12charsecret"
+		enabled 1
-.br
-		IncomingUser "fred 12charsecret2"
-.br
-		IncomingUser "jonas 12charsecret3"
-.br
-		HeaderDigest CRC32C,None
 .IP
 		LUN 0 disk1
 .br
 		LUN 1 disk2
 .br
-		LUN 2 blockio1 {
+	}
+.IP
+	TARGET ib_srpt_target_1 {
 .br
-			read_only 1
+		enabled 1
+.IP
+		LUN 0 disk1
+.br
+		LUN 1 disk2
+.br
+	}
+.br
+}
+.IP
+DEVICE_GROUP dgroup1 {
+.br
+	DEVICE disk1
+.IP
+	TARGET_GROUP tgroup1 {
+.br
+		group_id 1
+.br
+		state active
+.IP
+		TARGET ib_srpt_target_0 {
+.br
+			rel_tgt_id 1
 .br
 		}
-.IP
-		enabled 1
 .br
 	}
 .IP
-	enabled 1
+	TARGET_GROUP tgroup2 {
+.br
+		group_id 2
+.br
+		state offline
+.IP
+		TARGET ib_srpt_target_1 {
+.br
+			rel_tgt_id 2
+.br
+		}
+.br
+	}
+.br
+}
+.IP
+DEVICE_GROUP dgroup2 {
+.br
+	DEVICE disk2
+.IP
+	TARGET_GROUP tgroup1 {
+.br
+		group_id 1
+.br
+		state offline
+.IP
+		TARGET ib_srpt_target_0 {
+.br
+			rel_tgt_id 1
+.br
+		}
+.br
+	}
+.IP
+	TARGET_GROUP tgroup2 {
+.br
+		group_id 2
+.br
+		state active
+.IP
+		TARGET ib_srpt_target_1 {
+.br
+			rel_tgt_id 2
+.br
+		}
+.br
+	}
 .br
 }
 .SH FILES