From 5e293c567f2e105c785afb4b902a38d4beb5071e Mon Sep 17 00:00:00 2001
From: Bart Van Assche <bvanassche@acm.org>
Date: Thu, 21 Jul 2011 07:27:15 +0000
Subject: [PATCH] Add man pages for scstadmin, /etc/scst.conf and
 /etc/default/scst, including the scst-devel mailing list address for feedback
 and scstadmin author information

git-svn-id: http://svn.code.sf.net/p/scst/svn/trunk@3700 d57e44dd-8a1f-0410-8b47-8ef2f437770f
---
 scstadmin/Makefile                         |  15 ++
 scstadmin/scstadmin.sysfs/man1/scstadmin.1 | 253 +++++++++++++++++++++
 scstadmin/scstadmin.sysfs/man5/scst.5      |  37 +++
 scstadmin/scstadmin.sysfs/man5/scst.conf.5 | 200 ++++++++++++++++
 4 files changed, 505 insertions(+)
 create mode 100644 scstadmin/scstadmin.sysfs/man1/scstadmin.1
 create mode 100644 scstadmin/scstadmin.sysfs/man5/scst.5
 create mode 100644 scstadmin/scstadmin.sysfs/man5/scst.conf.5

diff --git a/scstadmin/Makefile b/scstadmin/Makefile
index 4948a1119..7c5c42867 100644
--- a/scstadmin/Makefile
+++ b/scstadmin/Makefile
@@ -1,5 +1,6 @@
 SCSTADMIN_DIR = scstadmin
 
+MANDIR := $(DESTDIR)$(PREFIX)/usr/local/man/
 INITDIR := $(shell if [ -f /etc/slackware-version ]; then	\
                      echo $(PREFIX)/etc/rc.d;			\
                    else						\
@@ -35,6 +36,14 @@ install:
 	"Scientific Linux, Fedora) or insserv (SLES, openSUSE) package must"  \
 	"be installed first"; false; fi
 	cd $(SCSTADMIN_DIR) && $(MAKE) $@
+	for m in scstadmin/man*/*.[1-9]; do				\
+	  if [ -e $$m ]; then			    			\
+	    d=$(MANDIR)$$(basename $$(dirname $$m));			\
+	    if install -d $$d; then					\
+	      install -m 644 $$m $$d;					\
+	    fi								\
+	  fi								\
+	done
 	install -d $(DESTDIR)$(INITDIR)
 	install -m 755 init.d/scst $(DESTDIR)$(INITDIR)
 	if [ ! -e  $(DESTDIR)$(DEFAULTDIR)/scst ]; then		\
@@ -63,6 +72,12 @@ uninstall:
 	  fi;							\
 	  rm -f $(DESTDIR)$(INITDIR)/scst;			\
 	fi
+	for m in scstadmin/man*/*.[1-9]; do		\
+	  if [ -e $$m ]; then				\
+	    d=$(MANDIR)$$(basename $$(dirname $$m));	\
+	    rm -f $$d/$$(basename $$m);			\
+	  fi						\
+	done
 	cd $(SCSTADMIN_DIR) && $(MAKE) $@
 
 perl-module:
diff --git a/scstadmin/scstadmin.sysfs/man1/scstadmin.1 b/scstadmin/scstadmin.sysfs/man1/scstadmin.1
new file mode 100644
index 000000000..ec1f8ac2b
--- /dev/null
+++ b/scstadmin/scstadmin.sysfs/man1/scstadmin.1
@@ -0,0 +1,253 @@
+.\" -*- nroff -*-
+.\" Copyright 2011 Bart Van Assche <bvanassche@acm.org>. All rights reserved.
+.\" Permission is granted to copy, distribute and/or modify this document
+.\" under the terms of the GNU General Public License, version 2 (GPLv2). 
+.TH scstadmin 1 "July 2011" "scstadmin 2.0.0"
+.SH NAME
+scstadmin \- administer the configuration of SCST
+.SH SYNOPSIS
+.B scstadmin
+[<OPTION>]* <COMMAND>
+.SH DESCRIPTION
+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.
+.SH OPTIONS
+.PP
+<OPTION> is one of:
+.TP
+.B -debug
+For commands that modify the SCST state, let scstadmin show which SCST state
+information would be modified instead of performing these modifications.
+.TP
+.B -force
+Let certain potentially dangerous operations proceed, e.g. closing a device
+that is still in use or removing an initiator group that is still in use.
+.TP
+.B -nonkey
+When writing a config file or listing attributes, include non-key attributes.
+.TP
+.B -noprompt
+Do not prompt for confirmation before modifying the SCST state.
+.PP
+<COMMAND> is one of:
+.TP
+.B -h
+Show usage information.
+.TP
+.B -help
+Identical to -h.
+.TP
+.B -config <file>
+Read and apply the specified configuration file.
+.TP
+.B -check_config <file>
+Verify the syntax of the specified configuration file.
+.TP
+.B -write_config <file>
+Save the current configuration to the specified file.
+.TP
+.B -clear_config
+Remove all configured devices, targets that do not correspond to a physical
+entity, dynamic target attributes, initiator groups, LUNs and dynamic driver
+attributes. Disable all targets that correspond to a physical entity and
+disable all target drivers. Note: static SCST core, target and target driver
+attributes that have been modified are not reset to their default value unless
+the corresponding kernel modules are reloaded.
+.TP
+.B -list_handler [<handler>]
+If no device handler name has been specified, show the names of all device
+handlers supported by the currently loaded kernel modules. If a device handler
+name has been specified, list the names of the devices that use that device
+handler.
+.TP
+.B -list_device [<device>]
+If no device name has been specified, show the names of all configured
+devices.  If a device name has been specified, show all attributes of the
+specified device.
+.TP
+.B -list_driver [<driver>]
+If no target driver name has been specified, list the names of all target
+drivers supported by the currently loaded kernel modules. If a target driver
+name has been specified, show the names of all targets that use the specified
+target driver.
+.TP
+.B -list_target [<target>] [-driver <driver>]
+If no target driver name has been specified, show all target names for all
+target drivers. If a target driver name has been specified, show all
+configuration information for the specified target. That information includes
+the assigned LUNs and information about all initiator groups associated with
+the target.
+.TP
+.B -list_group [<group>] [-driver <driver>] [-target <target>]
+If either the target driver name or the target name has not been specified,
+show information about all known target drivers, targets and initiator groups.
+If a target driver name and target name have been specified, show
+configuration information for the specified initiator group.
+.TP
+.B -list_scst_attr
+Show name and value of all SCST core attributes.
+.TP
+.B -list_hnd_attr <handler>
+Show name and value of all attributes of the specified device handler,
+and also the names of all device creation attributes.
+.TP
+.B -list_dev_attr <device>
+Show name and value of all attributes of the specified device.
+.TP
+.B -list_drv_attr <driver>
+Show name and value of all attributes of the specified target driver.
+.TP
+.B -list_tgt_attr <target> -driver <driver>
+Show name and value of all attributes of the specified target.
+.TP
+.B -list_grp_attr <group> -target <target> -driver <driver>
+Show name and value of all attributes of the specified initiator group.
+.TP
+.B -list_lun_attr <lun> -driver <driver> -target <target> [-group <group>]
+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_ini_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 -set_scst_attr -attributes <p=v,...>
+Set the value of one or more SCST core attributes.
+.TP
+.B -set_hnd_attr <handler> -attributes <p=v,...>
+Set the value of one or more device handler attributes.
+.TP
+.B -set_dev_attr <device> -attributes <p=v,...>
+Set the value of one or more device attributes.
+.TP
+.B -set_drv_attr <driver> -attributes <p=v,...>
+Set the value of one or more target driver attributes.
+.TP
+.B -set_tgt_attr <target> -driver <driver> -attributes <p=v,...>
+Set the value of one or more target attributes.
+.TP
+.B -set_grp_attr <group> -driver <driver> -target <target> -attributes <p=v,...>
+Set the value of one or more initiator group attributes.
+.TP
+.B -set_lun_attr <lun> -driver <driver> -target <target> [-group <group>] -attributes <p=v,...>
+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_ini_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
+target driver. Adding the same attribute several times will cause multiple
+values to be defined for that attribute.
+.TP
+.B -add_tgt_attr <target> -driver <driver> -attributes <p=v,...>
+Add one or more new attributes to the specified target and set these to the
+specified values. Which attribute names are valid depends on the involved
+target driver. Adding the same attribute several times will cause multiple
+values to be defined for that attribute.
+.TP
+.B -rem_drv_attr <driver> -attributes <p=v,...>
+Remove an (attribute, value) pair from the specified target driver.
+.TP
+.B -rem_tgt_attr <target> -driver <driver> -attributes <p=v,...>
+Remove an (attribute, value) pair from the specified target.
+.TP
+.B -open_dev <device> -handler <handler> -attributes <p=v,...>
+Create a new SCST device using the specified device handler and attributes.
+.TP
+.B -resync_dev <device>
+Update device size. SCST caches the size of devices controlled by the
+vdisk_fileio and the vdisk_blockio device handlers. This command will not only
+cause SCST to update the cached device size but will also cause any logged in
+initiator to be notified about the capacity change event.
+.TP
+.B -close_dev <device> -handler <handler>
+Remove the specified device from SCST.
+.TP
+.B -add_target <target> -driver <driver>
+Add a target to a target driver.
+.TP
+.B -rem_target <target> -driver <driver>
+Remove a target from a target driver.
+.TP
+.B -add_group <group> -driver <driver> -target <target>
+Add an initiator group to the specified target.
+.TP
+.B -rem_group <group> -driver <driver> -target <target>
+Remove an initiator group from the specified target.
+.TP
+.B -add_init <init> -driver <driver> -target <target> -group <group>
+Add an initiator to an initiator group. <init> is either an explicit initiator
+name or an initiator name pattern. The wildcard characters '*', '?' and '!'
+are supported.
+.TP
+.B -rem_init <user> -driver <driver> -target <target> -group <group>
+Remove an initiator name or initiator name pattern from an initiator group.
+.TP
+.B -move_init <init> -driver <driver> -target <target> -group <group1> -to <group2>
+Move an initiator or initiator name pattern from one initiator group to another.
+.TP
+.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,...>
+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,...>
+Replace the device associated with a LUN by another device.
+.TP
+.B -clear_luns -driver <driver> -target <target> [-group <group>]
+Remove all LUNs from a target or initiator group.
+.TP
+.B -enable_target <target> -driver <driver>
+Enable a target.
+.TP
+.B -disable_target <target> -driver <driver>
+Disable a target.
+.TP
+.B -issue_lip [<target>] [-driver <driver>]
+Issue a LIP (Loop Initialization Protocol, fibre channel) for a specific
+target or for all drivers and targets.
+.SH EXAMPLES
+.TP
+.B scstadmin -open_dev disk01 -handler vdisk_fileio -attributes filename=/vdisks/disk01.dsk,read_only
+Lets SCST open the file /vdisks/disk01.dsk as a disk.
+.TP
+.B scstadmin -set_dev_attr disk01 -attributes t10_dev_id=0x2345 
+Sets the T10 device id of SCST device disk01
+.TP
+.B scstadmin -add_group host01 -driver qla2x00t -target 50:06:0B:00:00:39:71:78
+Creates a new initiator group called host01.
+.TP
+.B scstadmin -add_lun 1 -driver qla2x00t -target 50:06:0B:00:00:39:71:78 -group host01 -device disk01 -attributes read_only=1
+Add a LUN to a group in read-only mode.
+.TP
+.B scstadmin -enable_target 50:06:0B:00:00:39:71:78 -driver qla2x00t
+Enables target mode for the fibre channel HCA port with the specified WWN.
+.TP
+.B scstadmin -write_config /etc/scst-new.conf
+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
+scstadmin itself or its documentation to the mailing list
+scst-devel@lists.sourceforge.net. See also
+.br
+https://lists.sourceforge.net/lists/listinfo/scst-devel for more information
+about this mailing list.
+.SH FILES
+/etc/scst.conf
+.SH "SEE ALSO"
+scst.conf(5)
diff --git a/scstadmin/scstadmin.sysfs/man5/scst.5 b/scstadmin/scstadmin.sysfs/man5/scst.5
new file mode 100644
index 000000000..7f0560fa5
--- /dev/null
+++ b/scstadmin/scstadmin.sysfs/man5/scst.5
@@ -0,0 +1,37 @@
+.\" -*- nroff -*-
+.\" Copyright 2011 Bart Van Assche <bvanassche@acm.org>. All rights reserved.
+.\" Permission is granted to copy, distribute and/or modify this document
+.\" under the terms of the GNU General Public License, version 2 (GPLv2). 
+.TH scst 5 "July 2011" "scstadmin 2.0.0"
+.SH NAME
+scst \- /etc/init.d/scst configuration file.
+.SH DESCRIPTION
+/etc/default/scst is a configuration file read by the SCST startup script
+/etc/init.d/scst and that controls the behavior of that startup script. This
+file contains zero or more lists of kernel module parameters that are passed
+by the /etc/init.d/scst script to the appropriate kernel module when such a
+kernel module is loaded.
+.P
+The format of the
+.I scst
+file is as follows:
+.br
+- Blank lines and lines starting with a hash sign (#) are ignored.
+.br
+- All other lines must contain a variable definition using the syntax
+<target_driver>_parameters=<value>. If <value> contains blanks, it must be
+surrounded with double quotes. <target_driver> is the name of an SCST target
+driver kernel module.
+.P
+An example:
+.IP
+# Set the ib_srpt kernel module parameter srp_max_req_size to
+.br
+# 4200 bytes and the srpt_sq_size parameter to 2048 elements.
+.br
+ib_srpt_parameters="srp_max_req_size=4200 srpt_sq_size=2048"
+.SH FILES
+.IP /etc/default/scst
+Configuration file interpret and applied by /etc/init.d/scst.
+.SH "SEE ALSO"
+scstadmin(1), scst.conf(5)
diff --git a/scstadmin/scstadmin.sysfs/man5/scst.conf.5 b/scstadmin/scstadmin.sysfs/man5/scst.conf.5
new file mode 100644
index 000000000..81edd730d
--- /dev/null
+++ b/scstadmin/scstadmin.sysfs/man5/scst.conf.5
@@ -0,0 +1,200 @@
+.\" -*- nroff -*-
+.\" Copyright 2011 Bart Van Assche <bvanassche@acm.org>. All rights reserved.
+.\" Permission is granted to copy, distribute and/or modify this document
+.\" under the terms of the GNU General Public License, version 2 (GPLv2). 
+.TH scst.conf 5 "July 2011" "scstadmin 2.0.0"
+.SH NAME
+scst.conf \- Main SCST configuration file.
+.SH DESCRIPTION
+.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
+.BR scstadmin (1)
+program when the SCST service starts.
+.P
+The format of the
+.I scst.conf
+file is as follows:
+.br
+- Blank lines and lines starting with a hash sign (#) are ignored.
+.br
+- All other lines either define an attribute, mark the start of a new section
+or the end of a section.
+.br
+- An attribute definition consists of an attribute name and an attribute
+value.
+.br
+- Attribute names consist of a sequence of letters, numbers and underscore
+characters (_). Attribute names must not contain blanks.
+.br
+- An attribute name may occur several times in a section with different values.
+.br
+- Attribute values may contain blanks. Any attribute value that contains
+blanks must be surrounded with double quotes.
+.br
+- A line that ends with
+.BR { .
+marks the start of a new section.
+.br
+- A line that contains nothing else than
+.B }
+marks the end of a section.
+.P
+The recognized section names and their arguments are:
+.IP "HANDLER <handler>"
+<handler> is the name of an SCST device handler.
+.IP "DEVICE <name>"
+<name> is either a H:C:I:L quadruplet referring to a local SCSI device
+or an SCST device name.
+.IP "TARGET_DRIVER <driver>"
+<driver> is the name of an SCST target driver.
+.IP "TARGET <target>"
+<target> is the name of an SCST target.
+.IP "LUN <number>"
+.IP "GROUP <group>"
+<group> is the name of an SCST initiator group.
+.IP "INITIATOR <ini>"
+<ini> is either an initiator name or a wildcard pattern matching zero or more
+initiator names. The supported wildcard characters are:
+.BR ! ", " * " and " ? .
+.P
+An example:
+.IP
+# Sample SCST configuration file for scstadmin v2.0.
+.IP
+setup_id 0x1234
+.IP
+HANDLER dev_disk {
+.br
+	DEVICE 1:0:0:0
+.br
+	DEVICE 2:0:0:0
+.br
+}
+.IP
+HANDLER vdisk_fileio {
+.br
+	DEVICE disk1 {
+.br
+		filename /disk1
+.br
+		nv_cache 1
+.br
+	}
+.IP
+	DEVICE disk2 {
+.br
+		filename /disk2
+.br
+		blocksize 4096
+.br
+		removable 1
+.br
+	}
+.br
+}
+.IP
+HANDLER vdisk_blockio {
+.br
+	DEVICE blockio1 {
+.br
+		filename /dev/sda5
+.br
+	}
+.br
+}
+.IP
+HANDLER vcdrom {
+.br
+	DEVICE cdrom1 {
+.br
+		filename /cdrom1.iso
+.br
+	}
+.br
+}
+.IP
+TARGET_DRIVER scst_local {
+.br
+	TARGET scst_local_tgt {
+.br
+		session_name scst_local_host
+.br
+		session_name scst_local_host1
+.IP
+		LUN 0 disk1
+.br
+	}
+.br
+}
+.IP
+TARGET_DRIVER qla2x00t {
+.br
+	TARGET 25:00:00:f0:98:87:92:f3 {
+.br
+		GROUP INI1 {
+.br
+			LUN 0 blockio1
+.br
+			LUN 1 1:0:0:0 {
+.br
+				read_only 1
+.br
+			}
+.br
+			LUN 5 cdrom1
+.IP
+			INITIATOR 25:00:00:f0:99:87:94:a3
+.br
+			INITIATOR 25:00:00:f0:99:87:94:a4
+.br
+		}
+.IP
+		enabled 1
+.br
+	}
+.IP
+	TARGET 25:00:00:f0:98:87:92:f4 {
+.br
+	}
+.br
+}
+.IP
+TARGET_DRIVER iscsi {
+.br
+	IncomingUser "joe 12charsecret"
+.IP
+	TARGET iqn.2006-10.net.vlnb:tgt {
+.br
+		IncomingUser "joe 12charsecret"
+.br
+		IncomingUser "fred 12charsecret2"
+.br
+		IncomingUser "jonas 12charsecret3"
+.br
+		HeaderDigest CRC32C,None
+.IP
+		LUN 0 disk1
+.br
+		LUN 1 disk2
+.br
+		LUN 2 blockio1 {
+.br
+			read_only 1
+.br
+		}
+.IP
+		enabled 1
+.br
+	}
+.IP
+	enabled 1
+.br
+}
+.SH FILES
+.IP "/etc/scst.conf"
+The configuration file read by 
+.BR scstadmin (1).
+.SH "SEE ALSO"
+scstadmin(1), scst(5)