From 011e52c55a5f43e5f1f09d180a769f5bf9d338cb Mon Sep 17 00:00:00 2001 From: Gleb Chesnokov Date: Thu, 20 Aug 2026 16:12:49 +0300 Subject: [PATCH] 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 3a8d70b1665a ("- 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. --- scstadmin/README | 61 +++++++++++---------- scstadmin/examples/scst.conf.sysfs | 4 +- scstadmin/scstadmin.sysfs/man1/scstadmin.1 | 61 +++++++++++++++++++-- scstadmin/scstadmin.sysfs/man5/scst.5 | 18 +++--- scstadmin/scstadmin.sysfs/man5/scst.conf.5 | 34 ++++++++---- scstadmin/scstadmin.sysfs/scst-1.0.0/README | 13 +++-- 6 files changed, 131 insertions(+), 60 deletions(-) diff --git a/scstadmin/README b/scstadmin/README index aff66a3e9..44b93112b 100644 --- a/scstadmin/README +++ b/scstadmin/README @@ -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 -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 -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 @@ -263,4 +269,3 @@ TARGET_DRIVER iscsi { enabled 1 } } - diff --git a/scstadmin/examples/scst.conf.sysfs b/scstadmin/examples/scst.conf.sysfs index b20dfb62d..6886975d0 100644 --- a/scstadmin/examples/scst.conf.sysfs +++ b/scstadmin/examples/scst.conf.sysfs @@ -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 diff --git a/scstadmin/scstadmin.sysfs/man1/scstadmin.1 b/scstadmin/scstadmin.sysfs/man1/scstadmin.1 index 39d7af5a8..763f72d58 100644 --- a/scstadmin/scstadmin.sysfs/man1/scstadmin.1 +++ b/scstadmin/scstadmin.sysfs/man1/scstadmin.1 @@ -2,7 +2,7 @@ .\" Copyright 2011 Bart Van Assche . 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 is one of: .TP @@ -64,7 +74,9 @@ Identical to -h. Read and apply the specified configuration file. .TP .B -check_config -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 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 Show name and value of all attributes of the specified device. .TP +.B -list_dgrp_attr +Show name and value of all attributes of the specified ALUA device group. +.TP .B -list_drv_attr 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 -driver -target -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 -attributes Set the value of one or more device attributes. .TP +.B -set_dgrp_attr -attributes +Set the value of one or more ALUA device group attributes. +.TP .B -set_drv_attr -attributes 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 -driver -target -group \ + -attributes +Set one or more attributes of the specified initiator entry. +.TP .B -add_drv_attr -attributes 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 -handler Remove the specified device from SCST. .TP +.B -add_dgrp +Add an ALUA device group. +.TP +.B -rem_dgrp +Remove an ALUA device group. +.TP +.B -add_dgrp_dev -dev_group +Add an SCST device to an ALUA device group. +.TP +.B -rem_dgrp_dev -dev_group +Remove an SCST device from an ALUA device group. +.TP +.B -add_tgrp -dev_group +Add an ALUA target group to a device group. +.TP +.B -rem_tgrp -dev_group +Remove an ALUA target group from a device group. +.TP +.B -add_tgrp_tgt -dev_group -tgt_group +Add a target to an ALUA target group. +.TP +.B -rem_tgrp_tgt -dev_group -tgt_group +Remove a target from an ALUA target group. +.TP .B -add_target -driver Add a target to a target driver. .TP diff --git a/scstadmin/scstadmin.sysfs/man5/scst.5 b/scstadmin/scstadmin.sysfs/man5/scst.5 index 2e8175228..1e0227249 100644 --- a/scstadmin/scstadmin.sysfs/man5/scst.5 +++ b/scstadmin/scstadmin.sysfs/man5/scst.5 @@ -2,13 +2,15 @@ .\" Copyright 2011 Bart Van Assche . 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 -=. If contains blanks, it must be -surrounded with double quotes. +=. 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) diff --git a/scstadmin/scstadmin.sysfs/man5/scst.conf.5 b/scstadmin/scstadmin.sysfs/man5/scst.conf.5 index edf733eb5..1c8248f64 100644 --- a/scstadmin/scstadmin.sysfs/man5/scst.conf.5 +++ b/scstadmin/scstadmin.sysfs/man5/scst.conf.5 @@ -2,7 +2,7 @@ .\" Copyright 2011 Bart Van Assche . 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 " Defines device handler attributes and also which devices are associated with the specified device handler. is the name of an SCST device handler. .TP .B "DEVICE " -Defines the name and attributes of an SCST device. 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. 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 " Defines target driver attributes and also which targets are associated with @@ -89,7 +96,7 @@ Associates an initiator name with an initiator group. 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 diff --git a/scstadmin/scstadmin.sysfs/scst-1.0.0/README b/scstadmin/scstadmin.sysfs/scst-1.0.0/README index 34e6085ed..c810dfbf6 100644 --- a/scstadmin/scstadmin.sysfs/scst-1.0.0/README +++ b/scstadmin/scstadmin.sysfs/scst-1.0.0/README @@ -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.