mirrors/scst
1
0
Fork 0
mirror of https://github.com/SCST-project/scst.git synced 2026-08-22 15:16:33 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
aa5cc2dd70f9c2d0dfd30d2d8821986023c34aba
scst/iscsi-scst/README_in-tree
T
Gleb Chesnokov 9a45498bc7 iscsi-scst: Document current administration interfaces 
The iSCSI READMEs, HOWTO and man pages combine current code with procfs,
old daemon configuration and fixed runtime output. The result documents
invalid paths, the wrong object creation order and unsafe live commands.

Commit 08e532715d ("Remove procfs support") removed the main obsolete
interface. Commit 70eb596f60 ("Rework iSCSI aborts to make them more
correct and remove recent workarounds (one more post-IET cleanup)")
added the SCST abort callback requested by an old ToDo entry.

Use iscsi_scst.h, kernel/config.c and usr/config.c for the kernel and
daemon contract. Correct sysfs ownership, authentication limits, setup
ordering, logging and dynamic output, and remove the completed task.

Keep iscsi-scstd.conf and iscsi-scst-adm documented because current code
still consumes them, but direct new setups to scst.conf. Replace the
removed service command and warn before exposing storage, credentials,
portals or sessions.
2026-08-21 10:05:36 +03:00

747 lines
29 KiB
Plaintext
Raw Blame History

iSCSI SCST target driver
========================
ISCSI-SCST is a deeply reworked fork of iSCSI Enterprise Target (IET)
(http://iscsitarget.sourceforge.net). Reasons of the fork were:
- To be able to use full power of SCST core.
- To fix all the problems, corner cases issues and iSCSI standard
violations which IET has.
See for more info http://iscsi-scst.sourceforge.net.
Usage
-----
See iscsi-scst/doc/iscsi-scst-howto.txt in the SCST source tree for
configuration instructions.
If you want to use Intel CRC32 offload and have corresponding hardware,
you should load crc32c-intel module. Then iSCSI-SCST will do all digest
calculations using this facility.
iscsi-scstd.conf and iscsi-scst-adm are legacy interfaces retained for
compatibility. Use scstadmin and the sysfs interface for new configurations.
The flow of iSCSI-SCST inialization should be as the following:
1. Load of SCST and iSCSI-SCST kernel modules with necessary module
parameters, if needed.
2. Start iSCSI-SCST service.
3. Configure targets, devices, LUNs, etc. either using scstadmin
(recommended), or using the sysfs interface directly as described below.
It is recommended to use TEST UNIT READY ("tur") command to check if
iSCSI-SCST target is alive in MPIO configurations.
Also see SCST README file how to tune for the best performance.
CAUTION: Working of target and initiator on the same host isn't fully
======= supported. See SCST README file for details.
Sysfs interface
---------------
Root of SCST sysfs interface is /sys/kernel/scst_tgt. Root of iSCSI-SCST
is /sys/kernel/scst_tgt/targets/iscsi. It has the following entries:
- None, one or more subdirectories for targets with name equal to names
of the corresponding targets.
- IncomingUser[num] - optional one or more attributes containing user
name and password for incoming discovery user name. Not exist by
default and can be added through "mgmt" entry, see below.
- OutgoingUser - optional attribute containing user name and password
for outgoing discovery user name. Not exist by default and can be
added through "mgmt" entry, see below.
- iSNSServer - contains name or IP address of iSNS server with optional
"AccessControl" attribute, which allows to enable iSNS access
control. Empty by default.
- isns_entity_name - specifies the source iSCSI name used for iSNS
registrations. If empty, the first target name is used.
- enabled - using this attribute you can enable or disable iSCSI-SCST
accept new connections. It allows to finish configuring global
iSCSI-SCST attributes before it starts accepting new connections. 0
by default.
- internal_portal - May designate one or more existing portals as being
internal. This will eliminate the need to supply a CHAP user/secret
during discovery or target login to any targets configured on those
portals. This is particularly useful for internal targets used as
part of ALUA configuration. Multiple addresses may be supplied,
separated by space characters. Empty by default.
- link_local - if set, makes the response to an IPv6 SendTargets include
any link local addresses. Default is set.
- open_state - read-only attribute, which allows to see if the user
space part of iSCSI-SCST connected to the kernel part.
- trace_level - allows to enable and disable various tracing
facilities. See content of this file for help how to use it.
- version - read-only attribute, which allows to see version of
iSCSI-SCST and enabled optional features.
- mgmt - main management entry, which allows to configure iSCSI-SCST.
Namely, add/delete targets as well as add/delete optional global and
per-target attributes. See content of this file for help how to use
it.
Each iSCSI-SCST sysfs file (attribute) can contain in the last line mark
"[key]". It is automatically added mark used to allow scstadmin to see
which attributes it should save in the config file. You can ignore it.
Each target subdirectory contains the following entries:
- ini_groups - subdirectory defining initiator groups for this target,
used to define per-initiator access control. See SCST core README for
more details.
- luns - subdirectory defining LUNs of this target. See SCST core
README for more details.
- sessions - subdirectory containing connected to this target sessions.
- IncomingUser[num] - optional one or more attributes containing user
name and password for incoming user name. Not exist by default and can
be added through the "mgmt" entry, see above.
- OutgoingUser - optional attribute containing user name and password
for outgoing user name. Not exist by default and can be added through
the "mgmt" entry, see above.
- allowed_portal[num] - optional attribute, which specifies, on which
portals (target's IP addresses) this target will be available. If not
specified (default) the target will be available on all portals.
As soon as at least one allowed_portal specified, the target will be
accessible for initiators only on the specified portals. There might
be any number of the allowed_portal attributes. The portals
specification in the allowed_portal attributes can be a simple
DOS-type patterns, containing '*' and '?' symbols. '*' means match
all any symbols, '?' means match only any single symbol. For
instance, "10.170.77.2" will match "10.170.7?.*". Additionally, you
can use negative sign '!' to revert the value of the pattern. For
instance, "10.170.67.2" will match "!10.170.7?.*". See examples
below.
- per_portal_acl - if set, makes iSCSI-SCST work in the per-portal
access control mode. In this mode iSCSI-SCST registers all initiators
in SCST core as "initiator_name#portal_IP_address" pattern, like
"iqn.2006-10.net.vlnb:ini#10.170.77.2" for initiator
iqn.2006-10.net.vlnb connected through portal 10.170.77.2. This mode
allows to make particular initiators be able to use only particular
portals on the target and don't see/be able to connect through
others. See below for more details.
- Entries defining default iSCSI parameters values used during iSCSI
parameters negotiation. Only entries which can be changed or make
sense are listed there.
- QueuedCommands - defines maximum number of commands queued to any
session of this target. Default is 32 commands.
- MaxSessions - defines the maximum number of concurrent sessions for
this target. The default value 0 means no limit.
- NopInInterval - defines interval between NOP-In requests, which the
target will send on idle connections to check if the initiator is
still alive. If there is no NOP-Out reply from the initiator in
NopInTimeout seconds, the corresponding connection will be closed. Default
is 30 seconds. If it's set to 0, then NOP-In requests are disabled.
- NopInTimeout - defines the maximum time in seconds a NOP-In request
can wait for response from initiator, otherwise the corresponding
connection will be closed. Default is 30 seconds.
- RspTimeout - defines the maximum time in seconds a command can wait for
response from initiator, otherwise the corresponding connection will
be closed. Default is 90 seconds.
- enabled - using this attribute you can enable or disable iSCSI-SCST
accept new connections to this target. It allows to finish
configuring it before it starts accepting new connections. 0 by
default.
- redirect - allows to temporarily or permanently redirect login to the
target to another portal. Discovery sessions will not be impacted,
but normal sessions will be redirected before security negotiation.
The destination should be specified using format "<ip_addr>[:port] temp|perm".
IPv6 addresses need to be enclosed in [] brackets. To remove
redirection, provide an empty string. For example:
echo "10.170.77.2:32600 temp" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/redirect
will temporarily redirect login to portal 10.170.77.2 and port 32600.
- tid - TID of this target.
- alias - TargetAlias of this target. If not set, it will default to the
empty string and no TargetAlias will be reported in LOGIN RESPONSE or iSNS
for this target.
Subdirectory "sessions" contains one subdirectory for each connected
session with name equal to name of the connected initiator.
Each session subdirectory contains the following entries:
- One subdirectory for each TCP connection in this session. ISCSI-SCST
supports 1 connection per session, but the session subdirectory can
contain several connections: one active and other being closed.
- Entries defining negotiated iSCSI parameters. Only parameters which
can be changed or make sense are listed there.
- initiator_name - contains initiator name
- sid - contains SID of this session
- reinstating - contains reinstatement state of this session
- force_close - write-only attribute, which allows to force close this
session. This is the only writable session attribute.
- active_commands - contains number of active, i.e. not yet or being
executed, SCSI commands in this session.
- commands - contains overall number of SCSI commands in this session.
- thread_pid - Process IDs (PIDs) of the iscsi{wr,rd} kernel threads that
process the SCSI commands for this session.
Each connection subdirectory contains the following entries:
- cid - contains CID of this connection.
- ip - contains IP address of the connected initiator.
- state - contains processing state of this connection.
Each initiator group subdirectory contains:
- per_sess_dedicated_tgt_threads - if set, each iSCSI session has
dedicated, i.e. not shared with other sessions, pool of the
iscsi{wr,rd} kernel threads. Useful to control per-session CPU
affinity to improve performance. Default: not set.
See SCST README for info about other attributes.
WARNING: The examples below load kernel modules, start the iSCSI daemon, write
live SCST sysfs state, create targets and export writable backing paths.
They include a real SCSI device and /dev/sda5. Do not run them until the
host, backing storage, initiators, portals and credentials have been
identified and approved. Replace every example value before use.
Below is a sample script, which configures 1 virtual disk "disk1" using
/disk1 image and one target iqn.2006-10.net.vlnb:tgt with all default
parameters:
#!/bin/bash
modprobe scst
modprobe scst_vdisk
echo "add_device disk1 filename=/disk1; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
modprobe iscsi-scst
iscsi-scstd
echo "add_target iqn.2006-10.net.vlnb:tgt" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "add disk1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled
Below is another sample script, which configures 1 real local SCSI disk
0:0:1:0 and one target iqn.2006-10.net.vlnb:tgt with all default parameters:
#!/bin/bash
modprobe scst
modprobe scst_disk
echo "add_device 0:0:1:0" >/sys/kernel/scst_tgt/handlers/dev_disk/mgmt
modprobe iscsi-scst
iscsi-scstd
echo "add_target iqn.2006-10.net.vlnb:tgt" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "add 0:0:1:0 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled
Below is an advanced sample script, which configures more virtual
devices of various types, including virtual CDROM and 2 targets, one
with all default parameters, another one with some not default
parameters, incoming and outgoing user names for CHAP authentication,
and special permissions for initiator iqn.2005-03.org.open-iscsi:cacdcd2520,
which will see another set of devices. Also this sample configures CHAP
authentication for discovery sessions and iSNS server with access
control.
#!/bin/bash
modprobe scst
modprobe scst_vdisk
echo "add_device disk1 filename=/disk1; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
echo "add_device disk2 filename=/disk2; blocksize=4096; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
echo "add_device blockio filename=/dev/sda5" >/sys/kernel/scst_tgt/handlers/vdisk_blockio/mgmt
echo "add_device nullio" >/sys/kernel/scst_tgt/handlers/vdisk_nullio/mgmt
echo "add_device cdrom" >/sys/kernel/scst_tgt/handlers/vcdrom/mgmt
modprobe iscsi-scst
iscsi-scstd
echo "192.168.1.16 AccessControl" >/sys/kernel/scst_tgt/targets/iscsi/iSNSServer
echo "add_attribute IncomingUser joeD 12charsecret" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "add_attribute OutgoingUser jackD 12charsecret1" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "add_target iqn.2006-10.net.vlnb:tgt" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "add disk1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
echo "add cdrom 1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
echo "add_target iqn.2006-10.net.vlnb:tgt1" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "add_target_attribute iqn.2006-10.net.vlnb:tgt1 IncomingUser1 joe2 12charsecret2" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "add_target_attribute iqn.2006-10.net.vlnb:tgt1 IncomingUser joe 12charsecret" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "add_target_attribute iqn.2006-10.net.vlnb:tgt1 OutgoingUser jim1 12charpasswd" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo "No" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/InitialR2T
echo "Yes" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ImmediateData
echo "8192" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/MaxRecvDataSegmentLength
echo "8192" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/MaxXmitDataSegmentLength
echo "131072" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/MaxBurstLength
echo "32768" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/FirstBurstLength
echo "1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/MaxOutstandingR2T
echo "CRC32C,None" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/HeaderDigest
echo "CRC32C,None" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/DataDigest
echo "32" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/QueuedCommands
echo "add disk2 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/mgmt
echo "add nullio 26" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/mgmt
echo "create special_ini" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/mgmt
echo "add blockio 0 read_only=1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/special_ini/luns/mgmt
echo "add iqn.2005-03.org.open-iscsi:cacdcd2520" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/special_ini/initiators/mgmt
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/enabled
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled
The following example shows the overall SCST sysfs hierarchy with an initiator
connected to both iSCSI-SCST targets. The exact set of entries depends on the
configured devices, targets and sessions:
/sys/kernel/scst_tgt
|-- devices
| |-- blockio
| | |-- blocksize
| | |-- exported
| | | `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/special_ini/luns/0
| | |-- filename
| | |-- handler -> ../../handlers/vdisk_blockio
| | |-- nv_cache
| | |-- read_only
| | |-- removable
| | |-- resync_size
| | |-- size_mb
| | |-- t10_dev_id
| | |-- threads_num
| | |-- threads_pool_type
| | |-- type
| | `-- usn
| |-- cdrom
| | |-- exported
| | | `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/1
| | |-- filename
| | |-- handler -> ../../handlers/vcdrom
| | |-- size_mb
| | |-- t10_dev_id
| | |-- threads_num
| | |-- threads_pool_type
| | |-- type
| | `-- usn
| |-- disk1
| | |-- blocksize
| | |-- exported
| | | `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/0
| | |-- filename
| | |-- handler -> ../../handlers/vdisk_fileio
| | |-- nv_cache
| | |-- o_direct
| | |-- read_only
| | |-- removable
| | |-- resync_size
| | |-- size_mb
| | |-- t10_dev_id
| | |-- threads_num
| | |-- threads_pool_type
| | |-- type
| | |-- usn
| | `-- write_through
| |-- disk2
| | |-- blocksize
| | |-- exported
| | | `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/0
| | |-- filename
| | |-- handler -> ../../handlers/vdisk_fileio
| | |-- nv_cache
| | |-- o_direct
| | |-- read_only
| | |-- removable
| | |-- resync_size
| | |-- size_mb
| | |-- t10_dev_id
| | |-- threads_num
| | |-- threads_pool_type
| | |-- type
| | |-- usn
| | `-- write_through
| `-- nullio
| |-- blocksize
| |-- exported
| | `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/26
| |-- handler -> ../../handlers/vdisk_nullio
| |-- read_only
| |-- removable
| |-- size_mb
| |-- t10_dev_id
| |-- threads_num
| |-- threads_pool_type
| |-- type
| `-- usn
|-- handlers
| |-- vcdrom
| | |-- cdrom -> ../../devices/cdrom
| | |-- mgmt
| | |-- trace_level
| | `-- type
| |-- vdisk_blockio
| | |-- blockio -> ../../devices/blockio
| | |-- mgmt
| | |-- trace_level
| | `-- type
| |-- vdisk_fileio
| | |-- disk1 -> ../../devices/disk1
| | |-- disk2 -> ../../devices/disk2
| | |-- mgmt
| | |-- trace_level
| | `-- type
| `-- vdisk_nullio
| |-- mgmt
| |-- nullio -> ../../devices/nullio
| |-- trace_level
| `-- type
|-- sgv
| |-- global_stats
| |-- sgv
| | `-- stats
| |-- sgv-clust
| | `-- stats
| `-- sgv-dma
| `-- stats
|-- targets
| `-- iscsi
| |-- IncomingUser
| |-- OutgoingUser
| |-- enabled
| |-- internal_portal
| |-- iSNSServer
| |-- isns_entity_name
| |-- iqn.2006-10.net.vlnb:tgt
| | |-- DataDigest
| | |-- FirstBurstLength
| | |-- HeaderDigest
| | |-- ImmediateData
| | |-- InitialR2T
| | |-- MaxBurstLength
| | |-- MaxOutstandingR2T
| | |-- MaxRecvDataSegmentLength
| | |-- MaxSessions
| | |-- MaxXmitDataSegmentLength
| | |-- NopInInterval
| | |-- NopInTimeout
| | |-- QueuedCommands
| | |-- RspTimeout
| | |-- alias
| | |-- enabled
| | |-- ini_groups
| | | `-- mgmt
| | |-- luns
| | | |-- 0
| | | | |-- device -> ../../../../../devices/disk1
| | | | `-- read_only
| | | |-- 1
| | | | |-- device -> ../../../../../devices/cdrom
| | | | `-- read_only
| | | `-- mgmt
| | |-- per_portal_acl
| | |-- redirect
| | |-- rel_tgt_id
| | |-- sessions
| | | `-- iqn.2005-03.org.open-iscsi:cacdcd2520
| | | |-- 10.170.75.2
| | | | |-- cid
| | | | |-- ip
| | | | `-- state
| | | |-- DataDigest
| | | |-- FirstBurstLength
| | | |-- HeaderDigest
| | | |-- ImmediateData
| | | |-- InitialR2T
| | | |-- MaxBurstLength
| | | |-- MaxOutstandingR2T
| | | |-- MaxRecvDataSegmentLength
| | | |-- MaxXmitDataSegmentLength
| | | |-- active_commands
| | | |-- commands
| | | |-- force_close
| | | |-- initiator_name
| | | |-- luns -> ../../luns
| | | |-- reinstating
| | | |-- sid
| | | `-- thread_pid
| | `-- tid
| |-- iqn.2006-10.net.vlnb:tgt1
| | |-- DataDigest
| | |-- FirstBurstLength
| | |-- HeaderDigest
| | |-- ImmediateData
| | |-- IncomingUser
| | |-- IncomingUser1
| | |-- InitialR2T
| | |-- MaxBurstLength
| | |-- MaxOutstandingR2T
| | |-- MaxRecvDataSegmentLength
| | |-- MaxSessions
| | |-- MaxXmitDataSegmentLength
| | |-- OutgoingUser
| | |-- NopInInterval
| | |-- NopInTimeout
| | |-- QueuedCommands
| | |-- RspTimeout
| | |-- alias
| | |-- enabled
| | |-- ini_groups
| | | |-- mgmt
| | | `-- special_ini
| | | |-- initiators
| | | | |-- iqn.2005-03.org.open-iscsi:cacdcd2520
| | | | `-- mgmt
| | | `-- luns
| | | |-- 0
| | | | |-- device -> ../../../../../../../devices/blockio
| | | | `-- read_only
| | | `-- mgmt
| | |-- luns
| | | |-- 0
| | | | |-- device -> ../../../../../devices/disk2
| | | | `-- read_only
| | | |-- 26
| | | | |-- device -> ../../../../../devices/nullio
| | | | `-- read_only
| | | `-- mgmt
| | |-- per_portal_acl
| | |-- redirect
| | |-- rel_tgt_id
| | |-- sessions
| | | `-- iqn.2005-03.org.open-iscsi:cacdcd2520
| | | |-- 10.170.75.2
| | | | |-- cid
| | | | |-- ip
| | | | `-- state
| | | |-- DataDigest
| | | |-- FirstBurstLength
| | | |-- HeaderDigest
| | | |-- ImmediateData
| | | |-- InitialR2T
| | | |-- MaxBurstLength
| | | |-- MaxOutstandingR2T
| | | |-- MaxRecvDataSegmentLength
| | | |-- MaxXmitDataSegmentLength
| | | |-- active_commands
| | | |-- commands
| | | |-- force_close
| | | |-- initiator_name
| | | |-- luns -> ../../ini_groups/special_ini/luns
| | | |-- reinstating
| | | |-- sid
| | | `-- thread_pid
| | `-- tid
| |-- link_local
| |-- mgmt
| |-- open_state
| |-- trace_level
| `-- version
|-- threads
|-- trace_level
`-- version
Advanced initiators access control
----------------------------------
ISCSI-SCST allows you to optionally control visibility and accessibility
of your target and its portals (IP addresses) to remote initiators. This
control includes both the target's portals SendTargets discovery as well
as regular LUNs access.
This facility supersedes the legacy initiators.allow and initiators.deny
files. The current daemon still reads those files, but new configurations
should use initiator groups and transport access-control attributes.
By default, all portals are available for the initiators.
1. If you want to enable/disable one or more target's portals for all
initiators, you should define one ore more allowed_portal attributes.
For example:
echo 'add_target_attribute iqn.2006-10.net.vlnb:tgt allowed_portal 10.170.77.2' >/sys/kernel/scst_tgt/targets/iscsi/mgmt
will enable only portal 10.170.77.2 and disable all other portals
echo 'add_target_attribute iqn.2006-10.net.vlnb:tgt allowed_portal 10.170.77.2' >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo 'add_target_attribute iqn.2006-10.net.vlnb:tgt allowed_portal 10.170.75.2' >/sys/kernel/scst_tgt/targets/iscsi/mgmt
will enable only portals 10.170.77.2 and 10.170.75.2 and disable all
other portals.
echo 'add_target_attribute iqn.2006-10.net.vlnb:tgt allowed_portal 10.170.7?.2' >/sys/kernel/scst_tgt/targets/iscsi/mgmt
will enable only portals 10.170.7x.2 and disable all other portals.
echo 'add_target_attribute iqn.2006-10.net.vlnb:tgt allowed_portal !*' >/sys/kernel/scst_tgt/targets/iscsi/mgmt
will disable all portals.
2. If you want to want to allow only specific set of initiators be
able to connect to your target, you should don't add any default LUNs
for the target and create for allowed initiators a security group to
which they will be assigned.
For example, we want initiator iqn.2005-03.org.vlnb:cacdcd2520 and only
it be able to access target iqn.2006-10.net.vlnb:tgt:
echo 'add_target iqn.2006-10.net.vlnb:tgt' >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo 'create allowed_ini' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/mgmt
echo 'add dev1 0' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/allowed_ini/luns/mgmt
echo 'add iqn.2005-03.org.vlnb:cacdcd2520' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/allowed_ini/initiators/mgmt
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
Since there will be no default LUNs for the target, all initiators other
than iqn.2005-03.org.vlnb:cacdcd2520 will be blocked from accessing it.
Alternatively, you can create an empty security group and filter out in
it all initiators except the allowed one:
echo 'add_target iqn.2006-10.net.vlnb:tgt' >/sys/kernel/scst_tgt/targets/iscsi/mgmt
echo 'add dev1 0' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
echo 'create denied_inis' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/mgmt
echo 'add !iqn.2005-03.org.vlnb:cacdcd2520' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/denied_inis/initiators/mgmt
echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
3. If you want to enable/disable one or more target's portals for
particular initiators, you should set per_portal_acl attribute to 1 and
specify SCST access control to those initiators. If an SCST security
group doesn't have any LUNs, all the initiator, which should be assigned
to it, will not see this target and/or its portal. For example:
(We assume that an empty group "BLOCKING_GROUP" is already created by for
target iqn.2006-10.net.vlnb:tgt by command (see above for more information):
"echo 'create BLOCKING_GROUP' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/mgmt)
echo 'add iqn.2005-03.org.vlnb:cacdcd2520#10.170.77.2' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/BLOCKING_GROUP/initiators/mgmt
will block access of initiator iqn.2005-03.org.vlnb:cacdcd2520 to
target iqn.2006-10.net.vlnb:tgt portal 10.170.77.2.
Another example:
echo 'add iqn.2005-03.org.vlnb:cacdcd2520*' >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/BLOCKING_GROUP/initiators/mgmt
will block access of initiator iqn.2005-03.org.vlnb:cacdcd2520 to
all target iqn.2006-10.net.vlnb:tgt portals.
Troubleshooting
---------------
Start troubleshooting with the kernel and daemon logs. The iSCSI-SCST kernel
component and SCST core report through the kernel log. iscsi-scstd reports
through syslog when daemonized and through standard error in foreground mode.
The journal or file that stores these messages is determined by the host's
logging configuration; do not assume /var/log/messages.
Then, it might be helpful to increase level of logging. For kernel
modules you should make the debug build by enabling CONFIG_SCST_DEBUG.
If after looking on the logs the reason of your problem is still unclear
for you, report to SCST mailing list scst-devel@lists.sourceforge.net.
Work if target's backstorage or link is too slow
------------------------------------------------
In some cases you can experience I/O stalls or see in the kernel log
abort or reset messages. It can happen under high I/O load, when your
target's backstorage gets overloaded, or working over a slow link, when
the link can't serve all the queued commands on time,
To workaround it you can reduce QueuedCommands parameter for the
corresponding target to some lower value, like 8 (default is 32).
Also see SCST README file for more details about that issue and ways to
prevent it.
Performance guidance
--------------------
Measure local backing storage, the storage network, a nullio target, and the
initiator-visible result separately before tuning. The SCST source
distribution's README.performance describes this workflow.
QueuedCommands, session and MPIO layout, IRQ and CPU affinity, NIC offloads,
and initiator TCP settings are workload-, kernel-, and hardware-specific.
Establish a baseline, change one variable at a time, and validate the result on
the intended initiators. Do not carry operating-system or adapter tuning from
an old deployment into a current host without revalidation.
Build diagnostics
-----------------
Select CONFIG_SCST_DEBUG, CONFIG_SCST_TRACING, and CONFIG_SCST_EXTRACHECKS
through the SCST Kconfig entries. Debugging, tracing, and extra checks add
logging or validation overhead and should be enabled deliberately.
CONFIG_SCST_ISCSI_DEBUG_DIGEST_FAILURES is an iSCSI Kconfig option that injects
digest failures for testing initiator recovery. It is not a normal diagnostic
setting.
Credits
-------
Thanks to:
* Ming Zhang <blackmagic02881@gmail.com> for fixes
* Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes
* Alexey Kuznetsov <kuznet@ms2.inr.ac.ru> for comments and help in
debugging
* Tomasz Chmielewski <mangoo@wpkg.org> for testing and suggestions
* Bart Van Assche <bvanassche@acm.org> for a lot of help
Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net
Reference in New Issue View Git Blame Copy Permalink