mirrors/scst
1
0
Fork 0
mirror of https://github.com/SCST-project/scst.git synced 2026-08-17 20:56:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs updates before making the sys interface default

Browse Source 
git-svn-id: http://svn.code.sf.net/p/scst/svn/trunk@2039 d57e44dd-8a1f-0410-8b47-8ef2f437770f
This commit is contained in:
Vladislav Bolkhovitin
2010-09-03 16:38:19 +00:00
parent e1ec75f089
commit 716107a964
16 changed files with 1577 additions and 1488 deletions
Download Patch File Download Diff File Expand all files Collapse all files
fcst/README
-1
View File
@@ -39,7 +39,6 @@ To build for linux-2.6.34, do:
because FCST supports only it. You need to do
cd trunk/scst
make disable_proc # first time only
make
make install
iscsi-scst/README
+36 -11
View File
@@ -12,7 +12,7 @@ ISCSI-SCST is a deeply reworked fork of iSCSI Enterprise Target (IET)
- To fix all the problems, corner cases issues and iSCSI standard
violations which IET has.
See more info at http://iscsi-scst.sourceforge.net.
See for more info http://iscsi-scst.sourceforge.net.
This version is compatible with SCST version 2.0.0 and higher.
@@ -38,9 +38,10 @@ compiler complains about redefinition of some symbol, you should either
switch to vanilla kernel, or add or change as necessary the
corresponding to that symbol "#if LINUX_VERSION_CODE" statement.
The sysfs build supports only kernels 2.6.26 and higher, because in
2.6.26 internal kernel's sysfs interface had a major change, which made
it heavily incompatible with pre-2.6.26 version.
Default sysfs interface supports only kernels 2.6.26 and higher, because
in 2.6.26 internal kernel's sysfs interface had a major change, which
made it heavily incompatible with pre-2.6.26 version. But with the
obsolete procfs interface kernels 2.6.16+ are supported.
If during compilation you see message like "*** No rule to make target
`xxx.h', needed by `yyy.o'. Stop.", then your autogenerated
@@ -124,6 +125,30 @@ CAUTION: Working of target and initiator on the same host isn't fully
======= supported. See SCST README file for details.
Migration from the obsolete proc interface
------------------------------------------
Sysfs enabled scstadmin supports old procfs config file format, so with
it you should do the following steps to migrate your proc-based
configuration to the sysfs interface:
1. Load SCST modules
2. Run "scstadmin -config old_config_file"
3. Start iSCSI-SCST
4. Run "scstadmin -write_config new_config_file"
5. Check new_config_file and make sure it has everything written
properly.
6. Delete /etc/iscsi-scst.conf and forget about it.
7. Start using "scstadmin -config new_config_file" to configure both
SCST and iSCSI-SCST.
Migration from IET
------------------
@@ -151,13 +176,12 @@ ietd.conf files for us to play with).
Sysfs interface
---------------
Starting from 2.0.0 iSCSI-SCST has sysfs interface. You can switch to it
by running "make disable_proc". To switch back to the procfs interface
you should run "make enable_proc". The procfs interface starting from
version 2.0.0 is obsolete and will be removed in one of the next
versions. The sysfs build supports only kernels 2.6.26 and higher,
because in 2.6.26 internal kernel's sysfs interface had a major change,
which made it heavily incompatible with pre-2.6.26 version.
Starting from 2.0.0 iSCSI-SCST uses sysfs interface. The procfs
interface is obsolete and will be removed in one of the next versions.
The sysfs build supports only kernels 2.6.26 and higher, because in
2.6.26 internal kernel's sysfs interface had a major change, which made
it heavily incompatible with pre-2.6.26 version. But with the obsolete
procfs interface kernels 2.6.16+ are supported.
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:
@@ -880,3 +904,4 @@ Thanks to:
* Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net
iscsi-scst/README_in-tree
+2 -1
View File
@@ -9,7 +9,7 @@ ISCSI-SCST is a deeply reworked fork of iSCSI Enterprise Target (IET)
- To fix all the problems, corner cases issues and iSCSI standard
violations which IET has.
See more info at http://iscsi-scst.sourceforge.net.
See for more info http://iscsi-scst.sourceforge.net.
Usage
-----
@@ -731,3 +731,4 @@ Thanks to:
* Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net
iscsi-scst/doc/SCST_Gentoo_HOWTO.txt
+2
View File
@@ -1,3 +1,5 @@
This HOWTO is for iSCSI-SCST v1.x. Updates for v2.x are welcome!
1) If you haven't done so already install a base gentoo installation:
download: http://www.gentoo.org/main/en/where.xml
documentation: http://www.gentoo.org/doc/en/handbook/index.xml
iscsi-scst/doc/iscsi-scst-howto.txt
+62 -36
View File
@@ -6,7 +6,7 @@ Installing and using iSCSI-SCST with scstadmin
Start with downloading the iSCSI-SCST source code. You can either download the
released version from the following URL:
http://sourceforge.net/project/showfiles.php?group_id=110471
http://scst.sourceforge.net/downloads.html
or you can download the latest development version by running the following
command in a shell:
@@ -46,8 +46,9 @@ iSCSI-SCST includes the following components:
* /etc/init.d/iscsi-scst - service script
* iscsi-scstd - daemon
* man pages
* Configuration files (located under iscsi-scst/etc/, need to be copied to
/etc if you want to use them):
* Obsolete configuration files located under iscsi-scst/etc/obsolete, need to be copied to
/etc if you want to use them. In iSCSI-SCST 2.0 it is recommended to use scstadmin
and SCST sysfs interface for that:
* 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
@@ -64,39 +65,60 @@ shown below. Verify the contents of the generated file.
/etc/init.d/open-iscsi start
cat /etc/iscsi/initiatorname.iscsi
3. Set up /etc/iscsi-scstd.conf
3. Set up /etc/scst.conf
You can do this by e.g. running the following shell commands:
The scst.conf configuration file is loaded at system boot time by the
shell script /etc/init.d/scst. All targets, devices and LUNs
configuration defined in this file.
echo "Target $(sed -n 's/InitiatorName=//p' /etc/iscsi/initiatorname.iscsi):storage" >/etc/iscsi-scstd.conf
cat /etc/iscsi-scstd.conf
Here is the sample config file. Copy it in /etc/scst.conf
4. Set up /etc/scst.conf
HANDLER dev_disk {
}
The scst.conf configuration file is loaded at system boot time by the shell
script /etc/init.d/scst. All devices known by SCST are defined in this file.
The shell statements shown below set up a configuration file for two vdisks.
Replace the device names by names that apply to your system:
HANDLER dev_cdrom {
}
HANDLER vdisk_fileio {
DEVICE disk01 {
filename /dev/ram0
nv_cache 1
}
DEVICE disk02 {
filename /dev/ram1
nv_cache 1
}
}
TARGET_DRIVER iscsi {
IncomingUser "joe 12charsecret"
TARGET iqn.2006-10.net.vlnb:tgt {
IncomingUser "joe 12charsecret"
LUN 0 disk01
LUN 1 disk02
enabled 1
}
}
Then run the following commands:
modprobe scst
modprobe scst_vdisk
scstadmin -ClearConfig /etc/scst.conf
scstadmin -adddev disk01 -path /dev/ram0 -handler vdisk -options NV_CACHE
scstadmin -adddev disk02 -path /dev/ram1 -handler vdisk -options NV_CACHE
scstadmin -assigndev disk01 -group Default -lun 0
scstadmin -assigndev disk02 -group Default -lun 1
scstadmin -WriteConfig /etc/scst.conf
cat /etc/scst.conf
service iscsi-scst start
scstadmin -config /etc/scst.conf
Note that for each SCSI device LUN 0 must exist. This is required by the SCSI
protocol and is also documented in SCST's README file.
5. Edit /etc/init.d/scst
4. Edit /etc/init.d/scst
Remove the modules you do not need from the SCST_MODULES variable,
e.g. qla2x00tgt.
6. Create soft links in /etc/init.d
5. Create soft links in /etc/init.d
This will make SCST to start automatically upon system boot. Use either
chkconfig or update-rc.d, depending on the Linux distribution you are using.
@@ -110,21 +132,21 @@ On openSUSE you can let SCST start automatically through the following commands:
insserv scst
insserv iscsi-scst
7. Restart SCST and iSCSI-SCST
6. Restart SCST and iSCSI-SCST
If you don't want to reboot now, you can make the above settings effective via
the following commands:
/etc/init.d/iscsi-scst stop
/etc/init.d/scst stop
/etc/init.d/scst start
/etc/init.d/iscsi-scst stop
/etc/init.d/iscsi-scst start
/etc/init.d/scst start
Installing and using iSCSI-SCST without using scstadmin via /sys interface
==========================================================================
First repeat steps 1, 2 and 3 from the first section but leave out
First repeat steps 1 and 2 from the first section but leave out
"scstadm scstadm_install" from the make command in step 1.
Next load the scst_disk and scst_vdisk kernel modules as follows:
@@ -266,25 +288,29 @@ echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled
Assigning targets to specific initiators
----------------------------------------
In order to assign targets to specific initiators, you need to have
/etc/initiators.allow and /etc/initiators.deny. You can find
example files in etc/initiators.allow and etc/initiators.deny.
In order to assign targets to specific initiators, you should use LUN
masking defined above. If an initiator assigned to an empty security
group of a target, the initiator will not see this target in the
SendTargets discovery and will not be able to connect to it.
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 will deny all initiators expect for those defined in /etc/initiators.allow.
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.
Installing and using iSCSI-SCST without using scstadmin via /proc interface
===========================================================================
First repeat steps 1, 2 and 3 from the previous section but leave out
First repeat steps 1 and 2 from the previous section but leave out
"scstadm scstadm_install" from the make command in step 1.
Next set up /etc/iscsi-scstd.conf
You can do this by e.g. running the following shell commands:
echo "Target $(sed -n 's/InitiatorName=//p' /etc/iscsi/initiatorname.iscsi):storage" >/etc/iscsi-scstd.conf
cat /etc/iscsi-scstd.conf
Next load the scst_disk kernel module as follows:
modprobe scst_disk
iscsi-scst/etc/initiators.allow → iscsi-scst/etc/obsolete/initiators.allow
View File
iscsi-scst/etc/initiators.deny → iscsi-scst/etc/obsolete/initiators.deny
View File
iscsi-scst/etc/iscsi-scstd.conf → iscsi-scst/etc/obsolete/iscsi-scstd.conf
View File
iscsi-scst/etc/scst.conf → iscsi-scst/etc/obsolete/scst.conf
View File
qla2x00t/qla2x00-target/README
+21 -24
View File
@@ -86,17 +86,17 @@ core. It is highly recommended to use scstadmin utility for that
purpose.
Then target mode should be enabled via a sysfs interface on a per card
basis. Under the appropriate scsi_host there is an entry
target_mode_enabled, where you should write "1", like:
echo "1" >/sys/class/scsi_host/host0/target_mode_enabled
For the sysfs build you should instead
basis, like:
echo "1" >/sys/kernel/scst_tgt/targets/qla2x00t/target/enabled
See below for full description of the driver's sysfs interface.
With the obsolete proc interface you should instead use
target_mode_enabled under the appropriate scsi_host entry, like:
echo "1" >/sys/class/scsi_host/host0/target_mode_enabled
You can find some installation and configuration HOWTOs in
http://scst.sourceforge.net/qla2x00t-howto.html and
https://forums.openfiler.com/viewtopic.php?id=3422.
@@ -142,16 +142,14 @@ Explicit conformation
---------------------
This option should (actually, almost always must) be enabled by echoing
"1" in /sys/class/scsi_host/hostX/explicit_conform_enabled, if a target
card exports at least one stateful SCSI device, like tape, and class 2
isn't used, otherwise link-level errors could lead to loss of the
target/initiator state synchronization. Also check if initiator supports
this feature, it is reported in the kernel logs ("confirmed completion
supported" or not). No major performance degradation was noticed, if it
is enabled. Supported only for 23xx+. Disabled by default.
In the sysfs build it is moved in /sys/kernel/scst_tgt/targets/qla2x00t/target/
subdirectory, see the sysfs interface description below.
"1" in /sys/kernel/scst_tgt/targets/qla2x00t/target/host/explicit_conform_enabled,
if a target card exports at least one stateful SCSI device, like tape,
and class 2 isn't used, otherwise link-level errors could lead to loss
of the target/initiator state synchronization. Also check if initiator
supports this feature, it is reported in the kernel logs ("confirmed
completion supported" or not). No major performance degradation was
noticed, if it is enabled. Supported only for 23xx+. Disabled by
default.
Class 2
@@ -159,9 +157,10 @@ Class 2
Class 2 is the close equivalent of the TCP in the IP world. If you
enable it, all the Fibre Channel packets will be acknowledged. By
default, class 3 is used, which is UDP-like. Enable it by echoing
"1" in /sys/class/scsi_host/hostX/class2_enabled. This option needs
a special firmware with class 2 support. Disabled by default.
default, class 3 is used, which is UDP-like. Enable it by echoing "1" in
/sys/kernel/scst_tgt/targets/qla2x00t/target/host/class2_enabled. This
option needs a special firmware with class 2 support. Disabled by
default.
Compilation options
@@ -191,11 +190,9 @@ in/out in Makefile:
Sysfs interface
---------------
Starting from 2.0.0 this driver has sysfs interface. You can switch to
it by running "make disable_proc". To switch back to the procfs
interface you should run "make enable_proc". The procfs interface from
version 2.0.0 is obsolete and will be removed in one of the next
versions.
Starting from 2.0.0 this driver has sysfs interface. The procfs
interface from version 2.0.0 is obsolete and will be removed in one of
the next versions.
Root of SCST sysfs interface is /sys/kernel/scst_tgt. Root of this
driver is /sys/kernel/scst_tgt/targets/qla2x00t. It has the following
qla2x00t/qla2x00-target/qla2x00t-howto.html
+53 -27
View File
@@ -44,12 +44,18 @@ How to configure QLogic target driver for 22xx/23xx/24xx/25xx adapters
[root@proj src ] ln -s /usr/src/linux-2.6.26 linux</br>
[root@proj src ] ln -s /usr/src/linux-2.6.26 kernel</br></br></br>
5: Get the SCST code from their SVN code base.</br>
5: Get the SCST code. It is possibile either from the <a href="http://scst.sourceforge.net/downloads.html">SCST downloads page</a>
or from the SVN code base.</br></br>
Below we will consider the case of the downloaded from the SVN code. For the release code everything is the same.
You only need unpack all downloaded SCST archives in one directory. It then will contain similar content as
~scst/trunk/ below.</br></br>
[root@proj ] svn co https://scst.svn.sourceforge.net/svnroot/scst</br>
If the command returns successfully then you'll have 'scst'</br>
directory under your current directory ( here it is /root )</br></br>
Please check if svn (open source version control system) is installed on
You need subversion (open source version control system) installed on
your Linux box.</br></br></br>
6: Change directory to ~scst/trunk/</br>
@@ -187,7 +193,7 @@ How to configure QLogic target driver for 22xx/23xx/24xx/25xx adapters
&lt snip from dmesg &gt</br></br>
scst: SCST version 1.0.0-rc1 loaded successfully (max mem for commands 16251MB, per device 6500MB)</br>
scst: SCST version 2.0.0 loaded successfully (max mem for commands 16251MB, per device 6500MB)</br>
scst: Enabled features: TRACING</br>
scst: Target template qla2x00tgt registered successfully</br>
scst: Virtual device handler vdisk for type 0 registered successfully</br>
@@ -196,8 +202,7 @@ How to configure QLogic target driver for 22xx/23xx/24xx/25xx adapters
--------</br>
&lt snip from dmesg &gt</br></br></br>
15:To see the devices remotely, we have to add them to atleast "Default" security group.</br>
Where each security group will have LUN 0(LUs numeration must not start from, e.g., 1)</br></br>
15: Now let's create our virtual device:</br></br>
[root@proj ] dd if=/dev/zero of=/mnt/disk1 bs=1024k count=512</br>
@@ -210,33 +215,54 @@ How to configure QLogic target driver for 22xx/23xx/24xx/25xx adapters
[root@proj ] file /mnt/disk1</br>
/mnt/disk1: data</br></br>
[root@proj ] echo "open vm_disk /mnt/disk1" > /proc/scsi_tgt/vdisk/vdisk</br>
[root@proj ] echo "add vm_disk 0" >/proc/scsi_tgt/groups/Default/devices</br></br>
&lt snip from dmesg &gt</br>
dev_vdisk: Attached SCSI target virtual disk vm_disk (file="/mnt/disk1", fs=512MB, bs=512, nblocks=1048576, cyln=512)</br>
scst: Attached SCSI target mid-level to virtual device vm_disk (id 1)</br>
scst: Added device vm_disk to group Default (LUN 0, rd_only 0)</br>
&lt snip from dmesg &gt</br></br>
[root@proj ] cat /proc/scsi_tgt/groups/Default/devices</br>
Device (host:ch:id:lun or name) Virtual lun Options</br>
vm_disk 0 </br></br>
16:To see the device remotely, we have to add it to at least in the LUNs set for our target.</br>
We must have LUN 0 (LUs numeration must not start from, e.g., 1).</br></br>
[root@proj ] cat /proc/scsi_tgt/vdisk/vdisk</br>
Name Size(MB) Block size Options File name</br>
vm_disk 512 512 /mnt/disk1</br></br></br>
16:After the drivers are loaded, the target mode should be enabled via a</br>
The simplest way to do that is to write an scstadmin's config file:</br></br>
sysfs interface on a per card basis. Under the appropriate scsi_host
there is an entry target_mode_enabled, where you should write "1", like:</br>
HANDLER vdisk_fileio {<br>
&nbsp; DEVICE disk1 {<br>
&nbsp;&nbsp; filename /mnt/disk1<br>
&nbsp; }<br>
}</br></br>
[root@proj ] echo "1" >/sys/class/scsi_host/host11/target_mode_enabled</br></br>
TARGET_DRIVER qla2x00t {<br>
&nbsp; TARGET 25:00:00:f0:98:87:92:f3 {<br>
&nbsp;&nbsp; LUN 0 disk1<br><br>
&nbsp;&nbsp; enabled 1<br>
&nbsp; }<br>
}<br><br>
To use it, we need to install scstadmin:<br><br>
[root@proj ]# make<br>
[root@proj ]# make install<br><br>
Let's save our config file as /etc/scst.conf<br><br>
Now run scstadmin:<br><br>
[root@proj ]# scstadmin -config /etc/scst.conf<br><br>
Collecting current configuration: done.<br><br>
-> Checking configuration file 'qq' for errors.<br>
-> Done, 0 warnings found.<br><br>
-> Opening device 'disk1' using handler 'vdisk_fileio': done.<br>
-> Adding device 'disk1' at LUN 0 to driver/target 'qla2x00t/25:00:00:f0:98:87:92:f3': done.<br>
-> Enabling driver/target 'qla2x00t/25:00:00:f0:98:87:92:f3': done.<br><br>
All done.<br><br>
The same can be done directly via SCST's sysfs interface:<br><br>
[root@proj ]# echo "add_device disk1 filename=/mnt/disk1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt<br>
[root@proj ]# echo "add disk1 0" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/luns/mgmt<br>
[root@proj ]# echo "1" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/enabled<br><br>
<div style="text-align: center;"><strong>ON INITIATOR</strong></div></br>
scripts/run-regression-tests
+1 -1
View File
@@ -552,7 +552,7 @@ test_scst_tree_patches || exit $?
compile_scst_unpatched || exit $?
compile_scst_patched debug2release || exit $?
compile_scst_patched debug2perf || exit $?
compile_scst_patched disable_proc || exit $?
compile_scst_patched enable_proc || exit $?
first_iteration="true"
for kv in ${kernel_versions}
scst/README
+1304 -1257
View File
File diff suppressed because it is too large Load Diff
scst/README_in-tree
+93 -115
View File
@@ -4,8 +4,7 @@ Generic SCSI target mid-level for Linux (SCST)
SCST is designed to provide unified, consistent interface between SCSI
target drivers and Linux kernel and simplify target drivers development
as much as possible. Detail description of SCST's features and internals
could be found in "Generic SCSI Target Middle Level for Linux" document
SCST's Internet page http://scst.sourceforge.net.
could be found on its Internet page http://scst.sourceforge.net.
SCST supports the following I/O modes:
@@ -13,37 +12,36 @@ SCST supports the following I/O modes:
initiators can connect to the exported pass-through devices, for
the following SCSI devices types: disks (type 0), tapes (type 1),
processors (type 3), CDROMs (type 5), MO disks (type 7), medium
changers (type 8) and RAID controllers (type 0xC)
changers (type 8) and RAID controllers (type 0xC).
* FILEIO mode, which allows to use files on file systems or block
devices as virtual remotely available SCSI disks or CDROMs with
benefits of the Linux page cache
benefits of the Linux page cache.
* BLOCKIO mode, which performs direct block IO with a block device,
bypassing page-cache for all operations. This mode works ideally with
high-end storage HBAs and for applications that either do not need
caching between application and disk or need the large block
throughput
* User space mode using scst_user device handler, which allows to
implement in the user space virtual SCSI devices in the SCST
environment
throughput.
* "Performance" device handlers, which provide in pseudo pass-through
mode a way for direct performance measurements without overhead of
actual data transferring from/to underlying SCSI device
actual data transferring from/to underlying SCSI device.
In addition, SCST supports advanced per-initiator access and devices
visibility management, so different initiators could see different set
of devices with different access permissions. See below for details.
Full list of SCST features and comparison with other Linux targets you
can find on http://scst.sourceforge.net/comparison.html.
Installation
------------
To see your devices remotely, you need to add them to at least "Default"
security group (see below how). By default, no local devices are seen
remotely. There must be LUN 0 in each security group, i.e. LUs
To see your devices remotely, you need to add a corresponding LUN for
them (see below how). By default, no local devices are seen remotely.
There must be LUN 0 in each LUNs set (security group), i.e. LUs
numeration must not start from, e.g., 1. Otherwise you will see no
devices on remote initiators and SCST core will write into the kernel
log message: "tgt_dev for LUN 0 not found, command to unexisting LU?"
@@ -83,8 +81,8 @@ IMPORTANT: In the current version simultaneous access to local SCSI devices
the state of devices and their parameters, because that could
lead to data corruption. If any such command is done, at
least related device handler(s) must be restarted. For block
devices READ/WRITE commands using direct disk handler look to
be safe.
devices READ/WRITE commands using direct disk handler are
generally safe.
Usage in failover mode
@@ -121,13 +119,6 @@ addressed in the next release. Virtual CDROM's are useful for remote
installation. See below for details how to setup and use VDISK device
handler.
SCST user space device handler provides an interface between SCST and
the user space, which allows to create pure user space devices. The
simplest example, where one would want it is if he/she wants to write a
VTL. With scst_user he/she can write it purely in the user space. Or one
would want it if he/she needs some sophisticated for kernel space
processing of the passed data, like encrypting them or making snapshots.
"Performance" device handlers for disks, MO disks and tapes in their
exec() method skip (pretend to execute) all READ and WRITE operations
and thus provide a way for direct link performance measurements without
@@ -156,22 +147,22 @@ your favorite kernel configuration Makefile target, e.g. "make xconfig":
the various places.
- CONFIG_SCST_USE_EXPECTED_VALUES - if not defined (default), initiator
supplied expected data transfer length and direction will be used only for
verification purposes to return error or warn in case if one of them
is invalid. Instead, locally decoded from SCSI command values will be
used. This is necessary for security reasons, because otherwise a
faulty initiator can crash target by supplying invalid value in one
of those parameters. This is especially important in case of
pass-through mode. If CONFIG_SCST_USE_EXPECTED_VALUES is defined, initiator
supplied expected data transfer length and direction will override
the locally decoded values. This might be necessary if internal SCST
commands translation table doesn't contain SCSI command, which is
used in your environment. You can know that if you have messages like
"Unknown opcode XX for YY. Should you update scst_scsi_op_table?" in
your kernel log and your initiator returns an error. Also report
those messages in the SCST mailing list
scst-devel@lists.sourceforge.net. Note, that not all SCSI transports
support supplying expected values.
supplied expected data transfer length and direction will be used
only for verification purposes to return error or warn in case if one
of them is invalid. Instead, locally decoded from SCSI command values
will be used. This is necessary for security reasons, because
otherwise a faulty initiator can crash target by supplying invalid
value in one of those parameters. This is especially important in
case of pass-through mode. If CONFIG_SCST_USE_EXPECTED_VALUES is
defined, initiator supplied expected data transfer length and
direction will override the locally decoded values. This might be
necessary if internal SCST commands translation table doesn't contain
SCSI command, which is used in your environment. You can know that if
you enable "minor" trace level and have messages like "Unknown
opcode XX for YY. Should you update scst_scsi_op_table?" in your
kernel log and your initiator returns an error. Also report those
messages in the SCST mailing list scst-devel@lists.sourceforge.net.
Note, that not all SCSI transports support supplying expected values.
- CONFIG_SCST_DEBUG_TM - if defined, turns on task management functions
debugging, when on LUN 6 some of the commands will be delayed for
@@ -208,8 +199,8 @@ your favorite kernel configuration Makefile target, e.g. "make xconfig":
CONFIG_QLA_TGT_DEBUG_WORK_IN_THREAD disabled - does. This option is
designed to be used with vdisk NULLIO backend.
WARNING! Using with other backend than vdisk NULLIO is unsafe and can
lead you to a kernel crash!
WARNING! Using this option enabled with other backend than vdisk
NULLIO is unsafe and can lead you to a kernel crash!
- CONFIG_SCST_STRICT_SECURITY - if defined, makes SCST zero allocated data
buffers. Undefining it (default) considerably improves performance
@@ -227,30 +218,13 @@ your favorite kernel configuration Makefile target, e.g. "make xconfig":
Then sometimes get crazy itself. So, this option is disabled by
default.
- CONFIG_SCST_MEASURE_LATENCY - if defined, provides in /sys/kernel/scst_tgt
and below statistics about average commands processing latency. You
can clear already measured results by writing 0 in the corresponding
file. Note, you need a non-preemptible kernel to have correct
results.
- CONFIG_SCST_MEASURE_LATENCY - if defined, provides in "latency" files
global and per-LUN average commands processing latency statistic. You
can clear already measured results by writing 0 in each file. Note,
you need a 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
supported, because this module deals with user supplied memory on a
zero-copy manner. If you need to use it, consider change VMSPLIT option
or use 64-bit system configuration instead.
For changing VMSPLIT option (CONFIG_VMSPLIT to be precise) you should in
"make menuconfig" command set the following variables:
- General setup->Configure standard kernel features (for small systems): ON
- General setup->Prompt for development and/or incomplete code/drivers: ON
- Processor type and features->High Memory Support: OFF
- Processor type and features->Memory split: according to amount of
memory you have. If it is less than 800MB, you may not touch this
option at all.
for performance reasons.
Module parameters
@@ -296,6 +270,17 @@ following entries:
- version - read-only attribute, which allows to see version of
SCST and enabled optional features.
- last_sysfs_mgmt_res - read-only attribute returning completion status
of the last management command. In the sysfs implementation there are
some problems between internal sysfs and internal SCST locking. To
avoid them in some cases sysfs calls can return error with errno
EAGAIN. This doesn't mean the operation failed. It only means that
the operation queued and not yet completed. To wait for it to
complete, an management tool should poll this file. If the operation
hasn't yet completed, it will also return EAGAIN. But after it's
completed, it will return the result of this operation (0 for success
or -errno for error).
Each 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.
@@ -305,7 +290,7 @@ which attributes it should save in the config file. You can ignore it.
Content of each device's subdirectory is dev handler specific. See
documentation for your dev handlers for more info about it as well as
SysfsRules file for more info about common to all dev handlers rules.
Standard SCST dev handlers have at least the following common entries:
SCST dev handlers can have the following common entries:
- exported - subdirectory containing links to all LUNs where this
device was exported.
@@ -339,7 +324,7 @@ handler.
Content of each handler's subdirectory is dev handler specific. See
documentation for your dev handlers for more info about it as well as
SysfsRules file for more info about common to all dev handlers rules.
Standard SCST dev handlers have at least the following common entries:
SCST dev handlers can have the following common entries:
- mgmt - this entry allows to create virtual devices and their
attributes (for virtual devices dev handlers) or assign/unassign real
@@ -446,13 +431,22 @@ Each session subdirectory contains the following entries:
- commands - contains overall number of SCSI commands in this session.
- latency - if CONFIG_SCST_MEASURE_LATENCY enabled, contains latency
statistics for this session.
- luns - a link pointing out to the corresponding LUNs set (security
group) where this session was attached to.
- One or more "lunX" subdirectories, where 'X' is a number, for each LUN
this session has (see below).
- other target driver specific attributes and subdirectories.
See below description of the VDISK's sysfs interface for samples.
Access and devices visibility management (LUN masking) - sysfs interface
------------------------------------------------------------------------
Access and devices visibility management (LUN masking)
------------------------------------------------------
Access and devices visibility management allows for an initiator or
group of initiators to see different devices with different LUNs
@@ -507,10 +501,6 @@ are one or more param_name=value pairs separated by ';'.
parameter "read_only". The recommended way to find out H:C:I:L
numbers is use of lsscsi utility.
- "del H:C:I:L" - deletes a pass-through device with host:channel:id:lun
The recommended way to find out H:C:I:L numbers is use of lsscsi
utility.
- "add VNAME lun [parameters]" - adds a virtual device with name VNAME
with LUN "lun". Optionally, the device could be marked as read only
by using parameter "read_only".
@@ -521,7 +511,7 @@ are one or more param_name=value pairs separated by ';'.
exist, this command acts as the "add" command. Optionally, the device
could be marked as read only by using parameter "read_only".
- "del VNAME" - deletes a virtual device with name VNAME.
- "del lun" - deletes LUN lun
- "clear" - clears the list of devices
@@ -623,12 +613,12 @@ IMPORTANT
=========
All the access control must be fully configured BEFORE the corresponding
target is enabled! When you enable a target, it will immediately start
target is enabled. When you enable a target, 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
the default target's set of LUNs, instead of "HOST004" group as you may
need, because "HOST004" doesn't exist yet. So, one must configure all
need, because "HOST004" doesn't exist yet. So, you must configure all
the security groups before new connections from the initiators are
created, i.e. before the target enabled.
@@ -806,7 +796,7 @@ removable, size_mb, t10_dev_id, threads_num, threads_pool_type, type,
usn. See above description of those parameters.
Each vcdrom's device has the following attributes in
/sys/kernel/scst_tgt/devices/device_name: filename, size_mb,
/sys/kernel/scst_tgt/devices/device_name: filename, size_mb,
t10_dev_id, threads_num, threads_pool_type, type, usn. See above
description of those parameters. Exception is filename attribute. For
vcdrom it is writable. Writing to it allows to virtually insert or
@@ -818,17 +808,17 @@ change virtual CD media in the virtual CDROM device. For example:
- echo "" >/sys/kernel/scst_tgt/devices/cdrom/filename - will remove
"media" from the virtual CDROM cdrom.
Additionally to the sysfs interface VDISK handler has module parameter
"num_threads", which specifies count of I/O threads for each VDISK's
device. If you have a workload, which tends to produce rather random
accesses (e.g. DB-like), you should increase this count to a bigger
value, like 32. If you have a rather sequential workload, you should
decrease it to a lower value, like number of CPUs on the target or even
1. Due to some limitations of Linux I/O subsystem, increasing number of
I/O threads too much leads to sequential performance drop, especially
with deadline scheduler, so decreasing it can improve sequential
performance. The default provides a good compromise between random and
sequential accesses.
Additionally VDISK handler has module parameter "num_threads", which
specifies count of I/O threads for each FILEIO VDISK's or VCDROM device.
If you have a workload, which tends to produce rather random accesses
(e.g. DB-like), you should increase this count to a bigger value, like
32. If you have a rather sequential workload, you should decrease it to
a lower value, like number of CPUs on the target or even 1. Due to some
limitations of Linux I/O subsystem, increasing number of I/O threads too
much leads to sequential performance drop, especially with deadline
scheduler, so decreasing it can improve sequential performance. The
default provides a good compromise between random and sequential
accesses.
You shouldn't be afraid to have too many VDISK I/O threads if you have
many VDISK devices. Kernel threads consume very little amount of
@@ -888,11 +878,6 @@ with suffix ".1". Those backup files are used in case of power or other
failure to prevent Persistent Reservation information from corruption
during update.
The "Persistence Through Power Loss" feature is not available in the
procfs build, because the SCST proc interface doesn't allow to keep
persistent Relative Target IDs of each target between reboots/reloads
(they are load and initialization order dependent).
The Persistent Reservations available on all transports implementing
get_initiator_port_transport_id() callback. Transports not implementing
this callback will act in one of 2 possible scenarios ("all or
@@ -915,10 +900,10 @@ By default for performance reasons VDISK FILEIO devices use write back
caching policy.
Generally, write back caching is safe for use and danger of it is
greatly overestimated, because most modern (especially, enterprise
greatly overestimated, because most modern (especially, Enterprise
level) applications are well prepared to work with write back cached
storage. Particularly, such are all transactions-based applications.
Those applications flush cache to completely AVOID ANY data loss on a
Those applications flush cache to completely avoid ANY data loss on a
crash or power failure. For instance, journaled file systems flush cache
on each meta data update, so they survive power/hardware/software
failures pretty well.
@@ -932,12 +917,12 @@ difference. If application doesn't flush the cache, it's doomed to loose
data in case of a crash or power failure doesn't matter where this cache
located, locally or on the storage.
To illustrate how data loss can be avoided with write back caching,
consider, for example, a user who wants to copy /src directory to /dst
directory reliably, i.e. after the copy finished no power failure or
software/hardware crash could lead to a loss of the data in /dst. There
are 2 ways to achieve this. Let's suppose for simplicity cp opens files
for writing with O_SYNC flag, hence bypassing the local cache.
To illustrate that consider, for example, a user who wants to copy /src
directory to /dst directory reliably, i.e. after the copy finished no
power failure or software/hardware crash could lead to a loss of the
data in /dst. There are 2 ways to achieve this. Let's suppose for
simplicity cp opens files for writing with O_SYNC flag, hence bypassing
the local cache.
1. Slow. Make the device behind /dst working in write through caching
mode and then run "cp -a /src /dst".
@@ -1041,6 +1026,7 @@ IMPORTANT: If SCST 1.x BLOCKIO worked by default in NV_CACHE mode, when
restore 1.x behavior, your should recreate your BLOCKIO
devices in NV_CACHE mode.
Pass-through mode
-----------------
@@ -1049,7 +1035,11 @@ scst_disk, scst_tape, etc) SCSI commands, coming from remote initiators,
are passed to local SCSI devices on target as is, without any
modifications.
In the SYSFS interface all real SCSI devices are listed in
SCST supports 1 to many pass-through, when several initiators can safely
connect a single pass-through device (a tape, for instance). For such
cases SCST emulates all the necessary functionality.
In the sysfs interface all real SCSI devices are listed in
/sys/kernel/scst_tgt/devices in form host:channel:id:lun numbers, for
instance 1:0:0:0. The recommended way to match those numbers to your
devices is use of lsscsi utility.
@@ -1105,19 +1095,6 @@ page each. See the following patch as an example:
http://scst.sourceforge.net/sgv_big_order_alloc.diff
User space mode using scst_user dev handler
-------------------------------------------
User space program fileio_tgt uses interface of scst_user dev handler
and allows to see how it works in various modes. Fileio_tgt provides
mostly the same functionality as scst_vdisk handler with the most
noticeable difference that it supports O_DIRECT mode. O_DIRECT mode is
basically the same as BLOCKIO, but also supports files, so for some
loads it could be significantly faster, than the regular FILEIO access.
All the words about BLOCKIO from above apply to O_DIRECT as well. See
fileio_tgt's README file for more details.
Performance
-----------
@@ -1141,7 +1118,8 @@ In order to get the maximum performance you should:
1. For SCST:
- Disable in Makefile CONFIG_SCST_STRICT_SERIALIZING, CONFIG_SCST_EXTRACHECKS,
CONFIG_SCST_TRACING, CONFIG_SCST_DEBUG*, CONFIG_SCST_STRICT_SECURITY
CONFIG_SCST_TRACING, CONFIG_SCST_DEBUG*, CONFIG_SCST_STRICT_SECURITY,
CONFIG_SCST_MEASURE_LATENCY
2. For target drivers:
@@ -1468,8 +1446,8 @@ Thanks to:
* Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
* Daniel Debonzi <debonzi@linux.vnet.ibm.com> for a big part of SCST sysfs tree
implementation
* Daniel Debonzi <debonzi@linux.vnet.ibm.com> for a big part of the
initial SCST sysfs tree implementation
Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net
scstadmin/README
+3 -7
View File
@@ -51,9 +51,9 @@ NOTE: The init.d startup & shutdown scripts now depend on lsb-core. Ensure you h
lsb-core installed or 'make install' will fail. Make sure /usr/lib/lsb/install_initd
exists.
To enable the newer sysfs version:
To enable the obsolete procfs version:
#> make disable_proc
#> make enable_proc
#> make
#> make install
@@ -61,11 +61,7 @@ To enable the newer sysfs version:
Getting Started:
================
The following pertains to the older procfs based SCST. The new sysfs version is still
a work in progress, but should be mostly complete at this point. You may still use your
old scst.conf, however, I very much recommend you perform a -write_config and review
the resulting configuration file.
The following pertains to the older procfs based SCST.
The scstadmin script is much more functional than scst_db at this point but uses a
standard text-based config file. The original thought behind scst_db was to write
scstadmin/README.sysfs
-8
View File
@@ -1,11 +1,3 @@
ENABLING SYSFS VERSION
----------------------
To enable the sysfs version of scstadmin (you must have the sysfs version of
SCST already installed):
make disable_proc
INSTALLING
----------