scst/scstadmin/README

SCST Configuration/Administration scripts. scstadmin reads /etc/scst.conf, or
another configuration file selected by the user, and discovers and modifies
SCST through sysfs. The SCST::SCST Perl module provides the sysfs access layer.

The component includes a generated SysV init script, a systemd unit, and the
default settings file used by the service integration.


	scstadmin.sysfs scstadmin version that supports sysfs.
	scst-1.0.0	This is the SCST Perl module to be used with SCST compiled
                        for sysfs.

	scstadmin	Script which can accept operations on a command line or from
			a configuration file. See scst.conf. For command help,
				#> scstadmin

	scst.conf	Configuration file for scst script. Usually stored
			in /etc.

	examples	Configuration examples.

	init.d/scst	Generator for the installed SysV init script.

	systemd/scst.service
			Systemd unit that delegates to the installed init script.


INSTALLING
----------

For the repository-wide build and installation workflow, see ../INSTALL.md.
For a component build, run:

make

The install target installs scstadmin, its manual pages and Perl module, the
generated init script, the systemd unit, and the service defaults file. It
requires Perl ExtUtils::MakeMaker. The Makefile detects systemctl, chkconfig,
update-rc.d, rc-update, or the LSB helper and prints the applicable command for
enabling the service; it does not enable or start SCST automatically.

Installation and service enablement modify the host. Do not run them without
authorization for the target system and its existing SCST configuration.


GETTING HELP
------------

To see the scstadmin command line options, type:

scstadmin --help


CONVERTING FROM PROCFS (scst version 1.x)
-----------------------------------------

The current scstadmin parser still recognizes the deprecated procfs format and
converts it before applying the configuration. Applying a configuration
changes live SCST state and requires the applicable modules and target daemons.
Perform the conversion during a maintenance window on an authorized host.

Keep the old file unchanged. Apply it with:

scstadmin -config <old config file>

Review every warning and the resulting live configuration, then save the
converted form to a new path:

scstadmin -write_config <new config file>

Review the new file before using it for service startup. Preserve the old file
until devices, targets, LUNs, attributes, and initiator visibility have been
verified.


CREATING A CONFIGURATION FROM SCRATCH
-------------------------------------

* DEVICES *

Devices are defined by their handler. Commonly used handlers are dev_disk,
dev_cdrom, vdisk_fileio, vdisk_blockio and vcdrom.

To list all the available handlers, type:

scstadmin -list_handler

Physical devices used for passthrough handlers like dev_disk and dev_cdrom
are defined by their H:C:I:L :

HANDLER dev_disk {
	DEVICE 1:0:0:0
}

HANDLER dev_cdrom {
	DEVICE 2:0:0:0
}

Virtual devices are opened through special CREATE attributes. For example, a
virtual disk named "disk1" pointing to a disk partition /dev/hda1 would be look
like:

HANDLER vdisk_fileio {
	DEVICE disk1 {
		filename /dev/hda1
	}
}

To list all the available CREATE attributes for a given handler, type:

scstadmin -list_hnd_attr <handler>

* ASSIGNING DEVICES TO TARGET AND INITIATORS *

Now we can assign the device to a target driver. To get a list of available
drivers, type:

scstadmin -list_driver

To list all available targets, type:

scstadmin -list_target

Now we can build our configuration assigning disk1 to LUN 0 for all initiators:

TARGET_DRIVER qla2x00t {
	TARGET 25:00:00:f0:98:87:92:f3 {
		LUN 0 disk1

		enabled 1
	}
}

NOTE: We added the attribute "enabled" and set it to "1". Without this attribute
set to 1, this target will be disabled and no initiators have access to its
LUNs.

This assigns disk1 to LUN 0 using default attributes. To list all available LUN
CREATE attributes, type:

scstadmin -list_tgt_attr <target> -driver <driver>

An example would be to use the CREATE attribute "read_only" to force the LUN to
be read-only:

TARGET_DRIVER qla2x00t {
	TARGET 25:00:00:f0:98:87:92:f3 {
		LUN 0 disk1 {
			read_only 1
		}

		# Assign LUN 1 to passthrough device 1:0:0:0
		LUN 1 1:0:0:0

		enabled 1
	}
}

Since LUNs 0 and 1 will now be available to all targets, we may want to
establish groups to restrict which LUNs are available to which initiators.
To do that, we use the GROUP clause within the TARGET clause:

TARGET_DRIVER qla2x00t {
	TARGET 25:00:00:f0:98:87:92:f3 {
		GROUP production {
			LUN 0 disk1 {
				read_only 1
			}

			INITIATOR 25:00:00:f0:99:87:94:a3
		}

		GROUP development {
			LUN 0 1:0:0:0
			INITIATOR 25:00:00:f0:99:87:94:a4
		}

		# Allow a CDROM device to be LUN 1 for all initiators
		LUN 1 2:0:0:0

		enabled 1
	}
}

For drivers which support virtual targets, like iSCSI, scstadmin will simply
create them on the fly:

TARGET_DRIVER iscsi {
	enabled 1

	IncomingUser "joe 12charsecret"

	TARGET iqn.2006-10.net.vlnb:tgt {
		IncomingUser "joe 12charsecret"

		LUN 0 disk1

		enabled 1
	}
}

IncomingUser is a dynamic iSCSI attribute. At the driver level it authenticates
initiators during discovery; at the target level it authenticates normal login
to that target. The CHAP secret must contain at least 12 bytes. To retrieve a
list of available driver dynamic attributes, type:

scstadmin -list_drv_attr <driver>

To retrieve a list of available target dynamic attributes, type:

scstadmin -list_tgt_attr <target> -driver <driver>

Other attributes called non-key attributes may also be defined, assuming they
are writable. These can be listed using any of the above -list commands using
the extra -nonkey option:

scstadmin -list_tgt_attr <target> -driver <driver> -nonkey

* EXAMPLE CONFIGURATION *

A complete configuration using the above examples would look like:

HANDLER dev_disk {
	DEVICE 1:0:0:0
}

HANDLER dev_cdrom {
	DEVICE 2:0:0:0
}

HANDLER vdisk_fileio {
	DEVICE disk1 {
		filename /dev/hda1
	}
}

TARGET_DRIVER qla2x00t {
	TARGET 25:00:00:f0:98:87:92:f3 {
		GROUP production {
			LUN 0 disk1 {
				read_only 1
			}

			INITIATOR 25:00:00:f0:99:87:94:a3
		}

		GROUP development {
			LUN 0 1:0:0:0
			INITIATOR 25:00:00:f0:99:87:94:a4
		}

		# Allow a CDROM device to be LUN 1 for all initiators
		LUN 1 2:0:0:0

		enabled 1
	}
}

TARGET_DRIVER iscsi {
	enabled 1

	IncomingUser "joe 12charsecret"

	TARGET iqn.2006-10.net.vlnb:tgt {
		IncomingUser "joe 12charsecret"

		LUN 0 disk1

		enabled 1
	}
}