scstadmin: Document current configuration interfaces

The scstadmin manuals still describe the 2.0 parser, a database backend and SysV-only service integration. They omit current ALUA operations and call -check_config an offline check even though it reads live sysfs. Commit 3a8d70b166 ("- Remove old scst_db stuff which no longer works with even procfs.") removed the database implementation. The current grammar and apply order live in scstadmin.sysfs/scstadmin, while SCST/SCST.pm consumes the kernel-provided sysfs metadata. Document the current commands, quoting, comments, DEVICE references and systemd environment handling. Keep deprecated-format conversion, but explain that it reconciles live state. Mark conversion, checking, examples, installation and service operations with their root, sysfs and exported-storage effects.
2026-08-22 07:06:22 +00:00 · 2026-08-21 10:05:36 +03:00
parent 9bdffe6fe6
commit 011e52c55a
6 changed files with 131 additions and 60 deletions
@@ -1,11 +1,9 @@
-SCST Configuration/Administration scripts. Here you'll find scstadmin which reads
-a configuration file /etc/scst.conf, or one if your choosing. With it you can manually
-or automatically configure every aspect of SCST including enabling/disabling target mode
-on your target SCSI controller. The old directory contains scst_db which uses a mysql
-backend database to configure SCST but doesn't handle all the things scstadmin handles.
-The perl module SCST::SCST is very generic and tries to handle error checking as well.
+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 init script was written for debian but should work on most distributions.
+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.
@@ -21,24 +19,28 @@ The init script was written for debian but should work on most distributions.

 	examples	Configuration examples.

-	init.d/scst	Init script to start SCST on boot which uses scstadmin.
+	init.d/scst	Generator for the installed SysV init script.
+
+	systemd/scst.service
+			Systemd unit that delegates to the installed init script.


 INSTALLING
 ----------

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

 make
-make install

-This installs scstadmin, the init.d script and the perl module. If you want SCST to
-startup and configure automatically upon boot, enable SCST using your favorite
-SysV init editor.
+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.

-NOTE: The init.d startup & shutdown scripts now depend on lsb-core. Ensure you have
-lsb-core installed or 'make install' will fail. Make sure /usr/lib/lsb/install_initd
-exists.
+Installation and service enablement modify the host. Do not run them without
+authorization for the target system and its existing SCST configuration.


 GETTING HELP
@@ -52,19 +54,23 @@ scstadmin --help
 CONVERTING FROM PROCFS (scst version 1.x)
 -----------------------------------------

-The new scstadmin uses a different configuration file format. However,
-scstadmin will convert your old configuration file for you. No special
-arguments are required, simply:
+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>

-Take note of warnings issued by scstadmin. Manually fix configuration
-errors using scstadmin. Once you're satisfied your running configuration is
-what you expect, save it by typing:
+Review every warning and the resulting live configuration, then save the
+converted form to a new path:

 scstadmin -write_config <new config file>

-Be sure to review this new configuration file to ensure it matches.
+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
@@ -193,10 +199,10 @@ TARGET_DRIVER iscsi {
 	}
 }

-Notice we included a new attribute "IncomingUser" This is a dynamic attribute
-which allows an initiator to scan for LUNs, if added at the driver level, and
-attach to LUNs if added at the target level. To retrieve a list of available
-driver dynamic attributes, type:
+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>

@@ -263,4 +269,3 @@ TARGET_DRIVER iscsi {
 		enabled 1
 	}
 }
-
@@ -1,4 +1,6 @@
-# Sample SCST configuration file for scstadmin v2.0.
+# SCST configuration syntax example.
+# Replace every path and fabric identifier before use. Applying this file
+# changes live SCST state and can export the named backing storage.

 setup_id 0x1234

@@ -2,7 +2,7 @@
 .\" 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"
+.TH scstadmin 1 "August 2026" "scstadmin 3.11.0-pre"
 .SH NAME
 scstadmin \- administer the configuration of SCST
 .SH SYNOPSIS
@@ -11,9 +11,9 @@ scstadmin \- administer the configuration of SCST
 .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. The relevant SCST concepts are:
+configurable at runtime. Scstadmin can query the current state, modify the
+current state, save it to a file and restore it from a file. The relevant SCST
+concepts are:
 .TP
 .B device
 An SCST device represents local storage that is exported via SCST. An SCST
@@ -25,7 +25,7 @@ such device handlers are dev_disk, vdisk_blockio and vdisk_fileio.
 .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
+driver. Examples of target drivers are iscsi, qla2x00t, ib_srpt and
 scst_local.
 .TP
 .B ALUA
@@ -51,6 +51,16 @@ 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.
+.TP
+.B -cont_on_err
+Continue processing after an error instead of stopping at the first error.
+.TP
+.B -lip
+Issue a Fibre Channel LIP after configuration changes that support it.
+.TP
+.B -no_lip
+Suppress the LIP requested by
+.BR -issue_lip .
 .PP
 <COMMAND> is one of:
 .TP
@@ -64,7 +74,9 @@ Identical to -h.
 Read and apply the specified configuration file.
 .TP
 .B -check_config <file>
-Verify the syntax of the specified configuration file.
+Parse the specified configuration and validate it against the currently loaded
+SCST sysfs interface without applying the requested configuration. This command
+requires root access and a live SCST sysfs hierarchy.
 .TP
 .B -write_config <file>
 Save the current configuration to the specified file.
@@ -117,6 +129,9 @@ and also the names of all device creation attributes.
 .B -list_dev_attr <device>
 Show name and value of all attributes of the specified device.
 .TP
+.B -list_dgrp_attr <dgrp>
+Show name and value of all attributes of the specified ALUA device group.
+.TP
 .B -list_drv_attr <driver>
 Show name and value of all attributes of the specified target driver.
 .TP
@@ -131,6 +146,9 @@ 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 <init> -driver <driver> -target <target> -group <group>
+Show name and value of all attributes of the specified initiator entry.
+.TP
 .B -list_sessions
 Show all active sessions for all targets.
 .TP
@@ -159,6 +177,9 @@ Set the value of one or more device handler attributes.
 .B -set_dev_attr <device> -attributes <p=v,...>
 Set the value of one or more device attributes.
 .TP
+.B -set_dgrp_attr <dgrp> -attributes <p=v,...>
+Set the value of one or more ALUA device group attributes.
+.TP
 .B -set_drv_attr <driver> -attributes <p=v,...>
 Set the value of one or more target driver attributes.
 .TP
@@ -173,6 +194,10 @@ 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 <init> -driver <driver> -target <target> -group <group> \
+     -attributes <p=v,...>
+Set one or more attributes of the specified initiator entry.
+.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
@@ -203,6 +228,30 @@ initiator to be notified about the capacity change event.
 .B -close_dev <device> -handler <handler>
 Remove the specified device from SCST.
 .TP
+.B -add_dgrp <dgrp>
+Add an ALUA device group.
+.TP
+.B -rem_dgrp <dgrp>
+Remove an ALUA device group.
+.TP
+.B -add_dgrp_dev <device> -dev_group <dgrp>
+Add an SCST device to an ALUA device group.
+.TP
+.B -rem_dgrp_dev <device> -dev_group <dgrp>
+Remove an SCST device from an ALUA device group.
+.TP
+.B -add_tgrp <tgrp> -dev_group <dgrp>
+Add an ALUA target group to a device group.
+.TP
+.B -rem_tgrp <tgrp> -dev_group <dgrp>
+Remove an ALUA target group from a device group.
+.TP
+.B -add_tgrp_tgt <tgt> -dev_group <dgrp> -tgt_group <tgrp>
+Add a target to an ALUA target group.
+.TP
+.B -rem_tgrp_tgt <tgt> -dev_group <dgrp> -tgt_group <tgrp>
+Remove a target from an ALUA target group.
+.TP
 .B -add_target <target> -driver <driver>
 Add a target to a target driver.
 .TP
@@ -2,13 +2,15 @@
 .\" 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"
+.TH scst 5 "August 2026" "scstadmin 3.11.0-pre"
 .SH NAME
-/etc/default/scst \- Configuration file read by /etc/init.d/scst.
+/etc/default/scst \- Environment file for the SCST service.
 .SH DESCRIPTION
 /etc/default/scst is a configuration file read by the SCST startup script
-/etc/init.d/scst. It contains zero or more variables that control the behavior
-of that startup script. The recognized variables are:
+/etc/init.d/scst. The systemd service also reads this file before invoking the
+startup script. The installer uses /etc/conf.d/scst instead on Gentoo systems.
+The file contains zero or more variables that control service behavior. The
+recognized variable is:
 .TP
 .B ISCSID_OPTIONS
 Specifies which command-line options will be passed to iscsi-scstd by the SCST
@@ -16,13 +18,13 @@ init script when SCST is started. This variable is ignored if no iSCSI target
 entries have been defined in /etc/scst.conf. See also the iscsi-scstd man page
 for more information about the supported command-line options.
 .P
-The format of the /etc/default/scst file is as follows:
+The init script sources this file as a shell fragment. Keep its contents to
+variable assignments and comments. The supported format 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
-<name>=<value>. If <value> contains blanks, it must be
-surrounded with double quotes.
+<name>=<value>. Quote values that contain blanks or shell metacharacters.
 .P
 An example:
 .IP
@@ -36,5 +38,7 @@ ISCSID_OPTIONS="-u0 -g0 -p3260"
 .IP /etc/default/scst
 Configuration file that controls the behavior of some aspects of
 /etc/init.d/scst.
+.IP /etc/conf.d/scst
+Installation path used instead on Gentoo systems.
 .SH "SEE ALSO"
 scstadmin(1), scst.conf(5), iscsi-scstd(8)
@@ -2,7 +2,7 @@
 .\" 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"
+.TH scst.conf 5 "August 2026" "scstadmin 3.11.0-pre"
 .SH NAME
 scst.conf \- Main SCST configuration file.
 .SH DESCRIPTION
@@ -22,14 +22,20 @@ file is as follows:
 .RB ( # )
 are ignored.
 .br
+- Elsewhere, an unescaped hash sign starts a trailing comment. The hash sign,
+the remainder of the line and the character immediately before the hash sign
+are removed. Precede a literal hash sign with a backslash. A backslash used for
+escaping is removed before the configuration is parsed.
+.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.
+- Attribute names must not contain blanks. Names and values are validated
+against the interfaces exported by the currently loaded SCST modules when the
+configuration is checked or applied.
 .br
 - An attribute name may occur several times in a section with different values.
 .br
@@ -44,19 +50,20 @@ marks the start of a new section.
 .B }
 marks the end of a section.
 .P
-The recognized section names and their arguments are:
+The recognized entries and their arguments are:
 .TP
 .B "HANDLER <handler>"
 Defines device handler attributes and also which devices are associated with
 the specified device handler. <handler> is the name of an SCST device handler.
 .TP
 .B "DEVICE <name>"
-Defines the name and attributes of an SCST device.  <name> is either a H:C:I:L
-quadruplet referring to a local SCSI device or an SCST device name. A
-.B DEVICE
-section is a subsection of a
+Within a
 .B HANDLER
-section.
+section, associates a device with the handler and optionally defines its
+attributes. <name> is either a H:C:I:L quadruplet referring to a local SCSI
+device or an SCST device name. Within a
+.B DEVICE_GROUP
+section, this entry references an SCST device defined elsewhere in the file.
 .TP
 .B "TARGET_DRIVER <driver>"
 Defines target driver attributes and also which targets are associated with
@@ -89,7 +96,7 @@ 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
+entry belongs to a
 .B GROUP
 section.
 .TP
@@ -103,9 +110,12 @@ section is a subsection of a
 .B DEVICE_GROUP
 section.
 .P
-An example:
+The following is a syntax example. Device paths, target names, initiator names,
+and fabric identifiers are placeholders. Applying a configuration changes live
+SCST state and can export the named backing storage; do not apply this example
+unchanged.
 .IP
-# Sample SCST configuration file for scstadmin v2.0.
+# Sample SCST configuration file.
 .IP
 setup_id 0x1234
 .IP
@@ -1,19 +1,20 @@
-SCST_SCST is a perl module for querying and configuring SCST.
+SCST_SCST is the Perl module used by scstadmin to query and configure SCST
+through sysfs.


 AVAILABILITY

-Currently SCST_SCST ships with SCST itself available from
-http://scst.sourceforge.net.
+SCST_SCST ships in the SCST source tree:
+https://github.com/SCST-project/scst.


 INSTALLATION

-Install SCST_SCST as you would any other perl module:
+The parent scstadmin Makefile builds and installs this module as part of
+scstadmin. To build the module directly, use the standard MakeMaker workflow:

   perl Makefile.PL
   make
   make install

-NOTE: This version (0.9.00+) requires SCST to be
-compiled with sysfs support!
+At runtime, the SCST core must be loaded and expose /sys/kernel/scst_tgt.