This quick HOWTO provides a reference for setting up and configuring
iSCSI-SCST. For more detailed information, see the SCST and iSCSI-SCST
README files.


Installing and using iSCSI-SCST with scstadmin
==============================================

1. Download, build and install iSCSI-SCST.

SCST release archives are available at:

  https://github.com/SCST-project/scst/releases

Clone the current development tree with:

  git clone https://github.com/SCST-project/scst.git

The next step is to build and install SCST, iSCSI-SCST and scstadmin. Run the
following commands from the SCST directory:

  make 2release
  make scst scst_install iscsi iscsi_install scstadm scstadm_install

The iscsi_install target installs iscsi-scst.ko, iscsi-scstd, the legacy
iscsi-scst-adm utility and their man pages. It also installs isert-scst.ko
when InfiniBand support is available. The scst_install target separately
installs scst.ko and device handlers such as scst_vdisk.ko.

Legacy configuration examples are kept under iscsi-scst/etc/obsolete. The
daemon reads these files from /etc, but use scstadmin and /etc/scst.conf for
new configurations:
   * initiators.allow - used for assigning specific initiators to targets
   * initiators.deny - used for assigning specific initiators to targets
   * iscsi-scstd.conf - list of targets and their properties

2. Set up /etc/scst.conf

By default, the SCST service uses scstadmin to load /etc/scst.conf. Target,
device and LUN configuration is defined in this file.

SCST kernel components expose configuration through sysfs. The scstadmin
utility provides a plain-text configuration interface instead. Load a file
with "scstadmin -config" and save the running configuration with
"scstadmin -write_config". The next section describes direct sysfs use.

The repository provides the following sample as iscsi-scst/etc/scst.conf.
Review it before copying it to /etc/scst.conf:

HANDLER vdisk_fileio {
	DEVICE disk01 {
		filename /dev/ram0
		nv_cache 1
	}
	DEVICE disk02 {
		filename /dev/ram1
		nv_cache 1
	}
}

TARGET_DRIVER iscsi {
	enabled 1

	TARGET iqn.2006-10.net.vlnb:tgt {
		LUN 0 disk01
		LUN 1 disk02

		enabled 1
	}
}

The sample defines no CHAP credentials or initiator restrictions. Without
additional access controls, its default LUN set is available to any initiator
that can reach an enabled portal. Configure authentication, initiator groups,
or allowed_portal restrictions before using it outside an isolated test
environment.

Before enabling a target, configure LUN 0 in every LUN set, including each
initiator group. Otherwise remote initiators will not see the exported
devices, as described in SCST's README file.

On systems using systemd, start SCST and apply /etc/scst.conf with:

  systemctl restart scst

The installed unit delegates these operations to the SCST init script. On
systems without systemd, use the init script directly:

  /etc/init.d/scst restart

You should have a working iSCSI-SCST target now. Apply later scst.conf changes
without unloading the kernel modules by running scstadmin directly:

  scstadmin -config /etc/scst.conf

Enable the service separately if SCST should start automatically at boot.

3. Enable the SCST service at boot

Use the service manager for your distribution. On systems using systemd:

  systemctl enable scst.service

On systems using SysV init, use the distribution's service registration tool.
For example, on Debian systems:

  update-rc.d scst defaults

Installing and using iSCSI-SCST without using scstadmin via /sys interface
==========================================================================

This advanced section is not needed for basic setups. Use it only when
scstadmin is insufficient, for example when configuration is stored in a
database instead of a plain-text file.

The commands below require root privileges and modify live kernel, target and
storage state. Use them only on a prepared host, and verify every backing
device and access-control choice before enabling the target.

In an iSCSI-SCST system, targets expose SCST devices to remote initiators
through LUN mappings. A target is an iSCSI endpoint. An SCST device
represents backing storage. A LUN mapping assigns a device a logical unit
number in either the target's default LUN set or an initiator group that
controls visibility and access. Create the target and devices before adding
LUN mappings, configure any initiator groups, then enable the target and the
iSCSI driver. Once these steps have been completed, authorized remote
initiators can discover and access the exported devices.

First repeat step 1 of the first section but leave out "scstadm
scstadm_install" from the make command in step 1.

Next load the required kernel modules as follows:

modprobe scst_disk
modprobe scst_vdisk
modprobe iscsi-scst

The scst_disk module provides pass-through access to local SCSI devices.
The scst_vdisk module creates virtual LUNs backed by files or block devices,
and iscsi-scst is the iSCSI-SCST target module.

Then start the iSCSI-SCST user-space daemon:

iscsi-scstd


Creating targets
----------------

echo "add_target iqn.2007-05.com.example:storage.iscsi-scst-1" > /sys/kernel/scst_tgt/targets/iscsi/mgmt

This will add target iqn.2007-05.com.example:storage.iscsi-scst-1.


Changing target parameters
--------------------------

echo "8192" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example\:storage.iscsi-scst-1/MaxRecvDataSegmentLength

This will change MaxRecvDataSegmentLength parameter of target
iqn.2007-05.com.example:storage.iscsi-scst-1 to 8192.

Read it back with:

# cat /sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example\:storage.iscsi-scst-1/MaxRecvDataSegmentLength
8192
[key]

The "[key]" marker tells management tools such as scstadmin that the value
differs from the default and should be saved. It is not part of the parameter
value.


Adding vdisk devices
--------------------

The following command creates or overwrites /disk1. Use a new path that does
not contain data you need:

dd if=/dev/zero of=/disk1 bs=1M count=1024

This creates a 1 GiB backing file for virtual device disk1.

echo "add_device disk1 filename=/disk1; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt

This will add new FILEIO device disk1 with backend file /disk1 and
NV_CACHE option enabled.

To use a block device through the BLOCKIO handler, replace /dev/dev1 with a
block device that is not otherwise in use:

echo "add_device dev1 filename=/dev/dev1" >/sys/kernel/scst_tgt/handlers/vdisk_blockio/mgmt


Listing currently registered SCST devices
-----------------------------------------

You can see the list of available devices:

# ls -1 /sys/kernel/scst_tgt/devices

The output depends on the devices currently registered with SCST.

Before exporting a pass-through disk, assign it to the dev_disk handler. Use
lsscsi to identify the H:C:I:L name and select only a device intended for
export. For example, after verifying the device name:

SCST_PT_DEVICE=4:0:0:8
echo "add_device ${SCST_PT_DEVICE}" >/sys/kernel/scst_tgt/handlers/dev_disk/mgmt


Defining LUN masking
--------------------

LUN masking defines which LUNs each initiator can see.

In order to associate specific LUNs with target
iqn.2007-05.com.example:storage.iscsi-scst-1, do the following:

echo "add ${SCST_PT_DEVICE} 0" > /sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example\:storage.iscsi-scst-1/luns/mgmt

This assigns the selected pass-through device to LUN 0 of target
iqn.2007-05.com.example:storage.iscsi-scst-1.

Each LUN set must include LUN 0, as documented in SCST's README.

echo "add disk1 1 read_only=1" > /sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example\:storage.iscsi-scst-1/luns/mgmt

This assigns virtual device disk1 as read-only LUN 1 of the
target iqn.2007-05.com.example:storage.iscsi-scst-1.


Deleting a LUN
--------------

Run the following command:

echo "del 1" > /sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example\:storage.iscsi-scst-1/luns/mgmt

This removes LUN 1 from the target's default LUN set.

For more information about LUN masking, refer to SCST README, section
"Access and devices visibility management (LUN masking)".


Assigning targets to specific initiators
----------------------------------------

To present different LUN sets to specific initiators, use initiator groups
under the target's ini_groups directory. Configure group LUNs and initiator
names before enabling the target. An initiator assigned to an empty group will
not see the target in SendTargets discovery and will not be able to connect.

Additionally, you can make the target be visible only via selected
portals using allowed_portal sysfs attribute. Read iSCSI-SCST's README
file for more details about this facility.


Enabling targets
----------------

After creating and configuring the target, enable it:

echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example\:storage.iscsi-scst-1/enabled

Then enable the iSCSI-SCST driver:

echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled


Legacy configuration interfaces
================================

Obsolete /proc interface
------------------------

SCST no longer provides the former /proc configuration interface. Use
scstadmin or the sysfs interface described above.


Legacy target configuration with iscsi-scstd.conf
-------------------------------------------------

The daemon still supports defining targets in /etc/iscsi-scstd.conf. The
legacy example is in iscsi-scst/etc/obsolete/iscsi-scstd.conf. Copy it to
/etc/ before starting iSCSI-SCST if you use this configuration method.


Legacy initiator access control
-------------------------------

To restrict initiator access with the legacy files, use
/etc/initiators.allow and /etc/initiators.deny. The examples are in
iscsi-scst/etc/obsolete/initiators.allow and
iscsi-scst/etc/obsolete/initiators.deny.

Note that all targets are allowed to all initiators by default, so if
you want to use /etc/initiators.allow, you will need to have
/etc/initiators.deny that looks like this:

ALL ALL

This denies all initiators except those defined in /etc/initiators.allow.

Legacy administration utility
-----------------------------

The legacy iscsi-scst-adm utility communicates with the running daemon. The
following examples query its current state:

Show the current target parameters:

# iscsi-scst-adm --op show --tid=1

Show the configured session parameters for a target:

# iscsi-scst-adm --op show --tid=1 --sid=0

The commands print the values currently held by iscsi-scstd. Target and
session defaults may depend on the registered kernel interface and subsequent
configuration changes.


Bart Van Assche
Erez Zilber
Vladislav Bolkhovitin
