Access control docs updated
authorvlnb <vlnb@d57e44dd-8a1f-0410-8b47-8ef2f437770f>
Fri, 26 Dec 2008 17:40:30 +0000 (17:40 +0000)
committervlnb <vlnb@d57e44dd-8a1f-0410-8b47-8ef2f437770f>
Fri, 26 Dec 2008 17:40:30 +0000 (17:40 +0000)
git-svn-id: https://scst.svn.sourceforge.net/svnroot/scst/trunk@624 d57e44dd-8a1f-0410-8b47-8ef2f437770f

iscsi-scst/README
iscsi-scst/README_in-tree
scst/README
scst/README_in-tree
scstadmin/init.d/scst
www/index.html
www/target_iscsi.html

index 4e6b968..94c31eb 100644 (file)
@@ -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.
-
-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.
-
-Check SCST README file how to tune for the best performance.
+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.
+
+IMPORTANT: All LUN information (access control) MUST be configured
+=========  BEFORE iscsi-scstd started!
+
+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
index cca3f20..3c1f271 100644 (file)
@@ -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.
-
-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.
-
-Check SCST README file how to tune for the best performance.
+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.
+
+IMPORTANT: All LUN information (access control) MUST be configured
+=========  BEFORE iscsi-scstd started!
+
+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
index f9a02e5..85d2eef 100644 (file)
@@ -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.
-
-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.
+group of initiators to see different devices with different LUNs
+with necessary access permissions.
+
+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
 --------------------
index 5fb3adf..00afa7b 100644 (file)
@@ -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.
-
-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.
+group of initiators to see different devices with different LUNs
+with necessary access permissions.
+
+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
 --------------------
 
index 98e61e1..5deccdd 100755 (executable)
@@ -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=""
index 9675c37..3bd3d7f 100644 (file)
                                <h1>Documentation</h1>
                                <p><a href="scst_pg.html">HTML</a></p>
                                <p><a href="scst_pg.pdf">PDF</a></p>
+                               <p><a href="iscsi-scst-howto.txt">HOWTO For iSCSI-SCST</a></p>
                                <p><a href="qla2x00t-howto.html">HOWTO For QLogic Target Driver</a></p>
                                <p><a href="scst_user_spec.txt">SCST User Interface Description</a></p>
                                <h1>SCST 0.9.6 graphs</h1>
index 527dd9c..b3d9d6a 100644 (file)
                                <p>You can find the latest development version of this driver in the SCST SVN. See the download page how to setup 
                                access to it.</p>
                                <p class="post-footer align-right">                                     \r
+                                       <a href="iscsi-scst-howto.txt" class="readmore">HOWTO</a>\r
                                        <a href="https://sourceforge.net/project/showfiles.php?group_id=110471&package_id=283228" class="readmore">Download</a>                         \r
                                        <a href="http://scst.svn.sourceforge.net/" class="readmore">SCST SVN Repository</a>\r
                                </p>