diff --git a/iscsi-scst/README b/iscsi-scst/README
index 4e6b9688e..94c31ebea 100644
--- a/iscsi-scst/README
+++ b/iscsi-scst/README
@@ -121,21 +121,20 @@ Usage
See in doc/iscsi-scst-howto.txt examples how to configure iSCSI-SCST.
ISCSI parameters like iSNS, CHAP and target parameters are configured in
-iscsi-scstd.conf. All LUN information is configured using the regular
-SCST interface. It is highly recommended to use scstadmin utility for
-that purpose. The LUN information in iscsi-scstd.conf will be ignored.
-This is because now responsibilities are divided (as it should be)
-between the target driver (iSCSI-SCST) and the SCST core as it logically
-should be: the target driver is responsible for handling targets and
-their parameters, SCST core is responsible for handling backstorage.
+iscsi-scstd.conf. All LUN information is configured using the
+corresponding SCST interface. See in SCST README file section "Access
+and devices visibility management (LUN masking)" to find out how to do
+it. It is highly recommended to use scstadmin utility for that purpose.
+The LUN information in iscsi-scstd.conf will be ignored. This is because
+now responsibilities are divided between the target driver (iSCSI-SCST)
+and the SCST core as it logically should be: the target driver is
+responsible for handling targets and their parameters, SCST core is
+responsible for handling backstorage.
-If you need to configure different LUs for different targets you should
-create for each target group "Default_target_name", where "target_name"
-means name of the target, for example:
-"Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz", and add there
-all necessary LUNs. Check SCST README file for details.
+IMPORTANT: All LUN information (access control) MUST be configured
+========= BEFORE iscsi-scstd started!
-Check SCST README file how to tune for the best performance.
+Also see SCST README file how to tune for the best performance.
If under high load you experience I/O stalls or see in the kernel log
abort or reset messages, then try to reduce QueuedCommands parameter in
@@ -144,7 +143,7 @@ like 8 (default is 32). See also SCST README file for more details about
that issue.
CAUTION: Working of target and initiator on the same host isn't
-======== supported. See SCST README file for details.
+======= supported. See SCST README file for details.
Performance advices
diff --git a/iscsi-scst/README_in-tree b/iscsi-scst/README_in-tree
index cca3f2061..3c1f27100 100644
--- a/iscsi-scst/README_in-tree
+++ b/iscsi-scst/README_in-tree
@@ -52,21 +52,20 @@ Usage
-----
ISCSI parameters like iSNS, CHAP and target parameters are configured in
-iscsi-scstd.conf. All LUN information is configured using the regular
-SCST interface. It is highly recommended to use scstadmin utility for
-that purpose. The LUN information in iscsi-scstd.conf will be ignored.
-This is because now responsibilities are divided (as it should be)
-between the target driver (iSCSI-SCST) and the SCST core as it logically
-should be: the target driver is responsible for handling targets and
-their parameters, SCST core is responsible for handling backstorage.
+iscsi-scstd.conf. All LUN information is configured using the
+corresponding SCST interface. See in SCST README file section "Access
+and devices visibility management (LUN masking)" to find out how to do
+it. It is highly recommended to use scstadmin utility for that purpose.
+The LUN information in iscsi-scstd.conf will be ignored. This is because
+now responsibilities are divided between the target driver (iSCSI-SCST)
+and the SCST core as it logically should be: the target driver is
+responsible for handling targets and their parameters, SCST core is
+responsible for handling backstorage.
-If you need to configure different LUs for different targets you should
-create for each target group "Default_target_name", where "target_name"
-means name of the target, for example:
-"Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz", and add there
-all necessary LUNs. Check SCST README file for details.
+IMPORTANT: All LUN information (access control) MUST be configured
+========= BEFORE iscsi-scstd started!
-Check SCST README file how to tune for the best performance.
+Also see SCST README file how to tune for the best performance.
If under high load you experience I/O stalls or see in the kernel log
abort or reset messages, then try to reduce QueuedCommands parameter in
@@ -74,8 +73,8 @@ iscsi-scstd.conf file for the corresponding target to some lower value,
like 8 (default is 32). See also SCST README file for more details about
that issue.
-CAUTION: Working of target and initiator on the same host isn't
-======== supported. See SCST README file for details.
+CAUTION: Working of target and initiator on the same host isn't
+======= supported. See SCST README file for details.
Performance advices
diff --git a/scst/README b/scst/README
index f9a02e5ea..85d2eef80 100644
--- a/scst/README
+++ b/scst/README
@@ -261,7 +261,7 @@ in/out in Makefile:
- CONFIG_SCST_MEASURE_LATENCY - if defined, provides in /proc/scsi_tgt/latency
file average commands processing latency. You can clear already
measured results by writing 0 in this file. Note, you need a
- non-preemtible kernel to have correct results.
+ non-preemptible kernel to have correct results.
HIGHMEM kernel configurations are fully supported, but not recommended
for performance reasons, except for scst_user, where they are not
@@ -352,27 +352,49 @@ Access and devices visibility management (LUN masking)
------------------------------------------------------
Access and devices visibility management allows for an initiator or
-group of initiators to have different views of LUs/LUNs (security groups)
-each with appropriate access permissions. It is highly recommended to
-use scstadmin utility for that purpose instead of described in this
-section low level interface.
+group of initiators to see different devices with different LUNs
+with necessary access permissions.
-Initiator is represented as an SCST session. The session is bound to
-security group on its registration time by character "name" parameter of
-the registration function, which provided by target driver, based on its
-internal authentication. For example, for FC "name" could be WWN or just
-loop ID. For iSCSI this could be iSCSI login credentials or iSCSI
-initiator name. Each security group has set of names assigned to it by
-system administrator. Session is bound to security group with provided
-name. If no such groups found, the session bound to either
-"Default_target_name", or "Default" group, depending from either
-"Default_target_name" exists or not. In "Default_target_name" target
-name means name of the target.
+SCST supports two modes of access control:
+
+1. Target-oriented. In this mode you define for each target devices and
+their LUNs, which are accessible to all initiators, connected to that
+target. This is a regular access control mode, which people mean
+thinking about access control in general. For instance, in IET this is
+the only supported mode. In this mode you should create a security group
+with name "Default_TARGET_NAME", where "TARGET_NAME" is name of the
+target, like "Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz"
+for target "iqn.2007-05.com.example:storage.disk1.sys1.xyz". Then you
+should add to it all LUNs, available from that target.
+
+2. Initiator-oriented. In this mode you define which devices and their
+LUNs are accessible for each initiator. In this mode you should create
+for each set of one or more initiators, which should access to the same
+set of devices with the same LUNs, a separate security group, then add
+to it available devices and names of allowed initiator(s).
+
+Both modes can be used simultaneously. In this case initiator-oriented
+mode has higher priority, than target-oriented.
+
+When a target driver registers itself in SCST core, it tells SCST core
+its name. Then, when there is a new connection from a remote initiator,
+the target driver registers this connection in SCST core and tells it
+name of the remote initiator. Then SCST core finds the corresponding
+devices for it using the following algorithm:
+
+1. It searches through all defined groups trying to find group
+containing the initiator name. If it succeeds, the found group is used.
+
+2. Otherwise, it searches through all groups trying to find group with
+name "Default_TARGET_NAME". If it succeeds, the found group is used.
+
+3. Otherwise, the group with name "Default" is used. This group is
+always defined, but empty by default.
In /proc/scsi_tgt each group represented as "groups/GROUP_NAME/"
subdirectory. In it there are files "devices" and "names". File
-"devices" lists all devices and their LUNs in the group, file "names"
-lists all names that should be bound to this group.
+"devices" lists devices and their LUNs in the group, file "names" lists
+names of initiators, which allowed to access devices in this group.
To configure access and devices visibility management SCST provides the
following files and directories under /proc/scsi_tgt:
@@ -382,14 +404,14 @@ following files and directories under /proc/scsi_tgt:
- "del_group GROUP" to /proc/scsi_tgt/scsi_tgt deletes group "GROUP"
- "add H:C:I:L lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds
- device with host:channel:id:lun as LUN "lun" in group "GROUP". Optionally,
+ device with host:channel:id:lun with LUN "lun" in group "GROUP". Optionally,
the device could be marked as read only.
- "del H:C:I:L" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
host:channel:id:lun from group "GROUP"
- "add V_NAME lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds
- device with virtual name "V_NAME" as LUN "lun" in group "GROUP".
+ device with virtual name "V_NAME" with LUN "lun" in group "GROUP".
Optionally, the device could be marked as read only.
- "del V_NAME" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
@@ -419,6 +441,49 @@ Examples:
- "echo "add disk1 1" >/proc/scsi_tgt/groups/Default/devices" will
add virtual VDISK device with name "disk1" to "Default" group
with LUN 1.
+
+Consider you need to have an iSCSI target with name
+"iqn.2007-05.com.example:storage.disk1.sys1.xyz" (you defined it in
+iscsi-scst.conf), which should export virtual device "dev1" with LUN 0
+and virtual device "dev2" with LUN 1, but initiator with name
+"iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" should see only
+virtual device "dev2" with LUN 0. To achieve that you should do the
+following commands:
+
+# echo "add_group Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz" >/proc/scsi_tgt/scsi_tgt
+# echo "add dev1 0" >/proc/scsi_tgt/groups/Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz/devices
+# echo "add dev2 1" >/proc/scsi_tgt/groups/Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz/devices
+
+# echo "add_group spec_ini" >/proc/scsi_tgt/scsi_tgt
+# echo "add iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" >/proc/scsi_tgt/groups/spec_ini/names
+# echo "add dev2 0" >/proc/scsi_tgt/groups/spec_ini/devices
+
+It is highly recommended to use scstadmin utility instead of described
+in this section low level interface.
+
+IMPORTANT
+=========
+
+All the access control must be fully configured BEFORE load of the
+corresponding target driver! When you load a target driver or enable
+target mode in it, as for qla2x00t driver, it will immediately start
+accepting new connections, hence creating new sessions, and those new
+sessions will be assigned to security groups according to the
+*currently* configured access control settings. For instance, to
+"Default" group, instead of "HOST004" as you need, because "HOST004"
+doesn't exist yet. So, one must configure all the security groups before
+new connections from the initiators are created, i.e. before target
+drivers loaded.
+
+Access controls can be altered after the target driver loaded as long as
+the target session doesn't yet exist. And even in the case of the
+session already existing, changes are still possible, but won't be
+reflected on the initiator side.
+
+So, the safest choice is to configure all the access control before any
+target driver load and then only add new devices to new groups for new
+initiators or add new devices to old groups, but not altering existing
+LUNs in them.
VDISK device handler
--------------------
diff --git a/scst/README_in-tree b/scst/README_in-tree
index 5fb3adf33..00afa7b44 100644
--- a/scst/README_in-tree
+++ b/scst/README_in-tree
@@ -209,7 +209,7 @@ your favorit kernel configuration Makefile target, e.g. "make xconfig":
- CONFIG_SCST_MEASURE_LATENCY - if defined, provides in /proc/scsi_tgt/latency
file average commands processing latency. You can clear already
measured results by writing 0 in this file. Note, you need a
- non-preemtible kernel to have correct results.
+ non-preemptible kernel to have correct results.
HIGHMEM kernel configurations are fully supported, but not recommended
for performance reasons, except for scst_user, where they are not
@@ -300,27 +300,49 @@ Access and devices visibility management (LUN masking)
------------------------------------------------------
Access and devices visibility management allows for an initiator or
-group of initiators to have different views of LUs/LUNs (security groups)
-each with appropriate access permissions. It is highly recommended to
-use scstadmin utility for that purpose instead of described in this
-section low level interface.
+group of initiators to see different devices with different LUNs
+with necessary access permissions.
-Initiator is represented as an SCST session. The session is bound to
-security group on its registration time by character "name" parameter of
-the registration function, which provided by target driver, based on its
-internal authentication. For example, for FC "name" could be WWN or just
-loop ID. For iSCSI this could be iSCSI login credentials or iSCSI
-initiator name. Each security group has set of names assigned to it by
-system administrator. Session is bound to security group with provided
-name. If no such groups found, the session bound to either
-"Default_target_name", or "Default" group, depending from either
-"Default_target_name" exists or not. In "Default_target_name" target
-name means name of the target.
+SCST supports two modes of access control:
+
+1. Target-oriented. In this mode you define for each target devices and
+their LUNs, which are accessible to all initiators, connected to that
+target. This is a regular access control mode, which people mean
+thinking about access control in general. For instance, in IET this is
+the only supported mode. In this mode you should create a security group
+with name "Default_TARGET_NAME", where "TARGET_NAME" is name of the
+target, like "Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz"
+for target "iqn.2007-05.com.example:storage.disk1.sys1.xyz". Then you
+should add to it all LUNs, available from that target.
+
+2. Initiator-oriented. In this mode you define which devices and their
+LUNs are accessible for each initiator. In this mode you should create
+for each set of one or more initiators, which should access to the same
+set of devices with the same LUNs, a separate security group, then add
+to it available devices and names of allowed initiator(s).
+
+Both modes can be used simultaneously. In this case initiator-oriented
+mode has higher priority, than target-oriented.
+
+When a target driver registers itself in SCST core, it tells SCST core
+its name. Then, when there is a new connection from a remote initiator,
+the target driver registers this connection in SCST core and tells it
+name of the remote initiator. Then SCST core finds the corresponding
+devices for it using the following algorithm:
+
+1. It searches through all defined groups trying to find group
+containing the initiator name. If it succeeds, the found group is used.
+
+2. Otherwise, it searches through all groups trying to find group with
+name "Default_TARGET_NAME". If it succeeds, the found group is used.
+
+3. Otherwise, the group with name "Default" is used. This group is
+always defined, but empty by default.
In /proc/scsi_tgt each group represented as "groups/GROUP_NAME/"
subdirectory. In it there are files "devices" and "names". File
-"devices" lists all devices and their LUNs in the group, file "names"
-lists all names that should be bound to this group.
+"devices" lists devices and their LUNs in the group, file "names" lists
+names of initiators, which allowed to access devices in this group.
To configure access and devices visibility management SCST provides the
following files and directories under /proc/scsi_tgt:
@@ -330,14 +352,14 @@ following files and directories under /proc/scsi_tgt:
- "del_group GROUP" to /proc/scsi_tgt/scsi_tgt deletes group "GROUP"
- "add H:C:I:L lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds
- device with host:channel:id:lun as LUN "lun" in group "GROUP". Optionally,
+ device with host:channel:id:lun with LUN "lun" in group "GROUP". Optionally,
the device could be marked as read only.
- "del H:C:I:L" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
host:channel:id:lun from group "GROUP"
- "add V_NAME lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds
- device with virtual name "V_NAME" as LUN "lun" in group "GROUP".
+ device with virtual name "V_NAME" with LUN "lun" in group "GROUP".
Optionally, the device could be marked as read only.
- "del V_NAME" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
@@ -368,6 +390,49 @@ Examples:
add virtual VDISK device with name "disk1" to "Default" group
with LUN 1.
+Consider you need to have an iSCSI target with name
+"iqn.2007-05.com.example:storage.disk1.sys1.xyz" (you defined it in
+iscsi-scst.conf), which should export virtual device "dev1" with LUN 0
+and virtual device "dev2" with LUN 1, but initiator with name
+"iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" should see only
+virtual device "dev2" with LUN 0. To achieve that you should do the
+following commands:
+
+# echo "add_group Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz" >/proc/scsi_tgt/scsi_tgt
+# echo "add dev1 0" >/proc/scsi_tgt/groups/Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz/devices
+# echo "add dev2 1" >/proc/scsi_tgt/groups/Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz/devices
+
+# echo "add_group spec_ini" >/proc/scsi_tgt/scsi_tgt
+# echo "add iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" >/proc/scsi_tgt/groups/spec_ini/names
+# echo "add dev2 0" >/proc/scsi_tgt/groups/spec_ini/devices
+
+It is highly recommended to use scstadmin utility instead of described
+in this section low level interface.
+
+IMPORTANT
+=========
+
+All the access control must be fully configured BEFORE load of the
+corresponding target driver! When you load a target driver or enable
+target mode in it, as for qla2x00t driver, it will immediately start
+accepting new connections, hence creating new sessions, and those new
+sessions will be assigned to security groups according to the
+*currently* configured access control settings. For instance, to
+"Default" group, instead of "HOST004" as you need, because "HOST004"
+doesn't exist yet. So, one must configure all the security groups before
+new connections from the initiators are created, i.e. before target
+drivers loaded.
+
+Access controls can be altered after the target driver loaded as long as
+the target session doesn't yet exist. And even in the case of the
+session already existing, changes are still possible, but won't be
+reflected on the initiator side.
+
+So, the safest choice is to configure all the access control before any
+target driver load and then only add new devices to new groups for new
+initiators or add new devices to old groups, but not altering existing
+LUNs in them.
+
VDISK device handler
--------------------
diff --git a/scstadmin/init.d/scst b/scstadmin/init.d/scst
index 98e61e1a3..5deccddb3 100755
--- a/scstadmin/init.d/scst
+++ b/scstadmin/init.d/scst
@@ -4,7 +4,12 @@ PATH=/bin:/usr/bin:/sbin:/usr/sbin:/usr/local/sbin:/usr/local/bin
SCST_CMD=/usr/local/sbin/scstadmin
SCST_CFG=/etc/scst.conf
-# Modules to load/unload
+# Modules to load/unload.
+#
+# !!! DON'T ADD HERE TARGET DRIVERS, WHICH IMMEDIATELLY START ACCEPTING
+# !!! NEW CONNECTIONS, BECAUSE AT THIS POINT ACCESS CONTROL HASN'T CONFIGURED
+# !!! YET!
+#
SCST_MODULES="qla2x00tgt scst_vdisk scst_disk"
OPTIONS=""
diff --git a/www/index.html b/www/index.html
index 9675c37d8..3bd3d7f22 100644
--- a/www/index.html
+++ b/www/index.html
@@ -117,6 +117,7 @@
Documentation
HTML
PDF
+ HOWTO For iSCSI-SCST
HOWTO For QLogic Target Driver
SCST User Interface Description
SCST 0.9.6 graphs
diff --git a/www/target_iscsi.html b/www/target_iscsi.html
index 527dd9c58..b3d9d6abb 100644
--- a/www/target_iscsi.html
+++ b/www/target_iscsi.html
@@ -120,6 +120,7 @@
You can find the latest development version of this driver in the SCST SVN. See the download page how to setup
access to it.