scst/iscsi-scst/README_in-tree

iSCSI SCST target driver
========================

Version 1.0.1/0.4.16r155, XX XXXX 2008
--------------------------------------

This driver is a forked with all respects version of iSCSI Enterprise
Target (IET) (http://iscsitarget.sourceforge.net/) with updates to work
over SCST as well as with many improvements and bugfixes (see ChangeLog
file). The reason of fork is that the necessary changes are intrusive
and with the current IET merge policy, where only simple bugfix-like
patches, which doesn't touch the core code, could be merged, it is very
unlikely that they will be merged in the main IET trunk.

To let it be installed and work at the same host together with IET
simultaneously all the driver's modules and files were renamed:

 * ietd.conf -> iscsi-scstd.conf
 * ietadm -> iscsi-scst-adm
 * ietd -> iscsi-scstd
 * iscsi-target -> iscsi-scst
 * iscsi-target.ko -> iscsi-scst.ko

To use full power of TCP zero-copy transmit functions, especially
dealing with user space supplied via scst_user module memory, iSCSI-SCST
needs to be notified when Linux networking finished data transmission.
For that you should enable CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION
kernel config option. This is highly recommended, but not required. Basically,
you should consider usage of this option as some optimization, which IET
doesn't have, so if you don't use it, you will just revert to the
original IET behavior, when for data transmission:

 - For in-kernel allocated memory (scst_vdisk and pass-through
   handlers) usage of SGV cache on transmit path (READ-type commands)
   will be disabled. The performance hit will be not big, but performance
   will still remain better, than for IET, because SGV cache will remain
   used on receive path while IET doesn't have such feature.

 - For user space allocated memory (scst_user handler) all transmitted
   data will be additionally copied into temporary TCP buffers. The
   performance hit will be quite noticeable.

Note, that if your network hardware does not support TX offload
functions of has them disabled, then TCP zero-copy transmit functions on
your system will not be used by Linux networking in any case, so
put_page_callback patch will not be able to improve performance for you.
You can check your network hardware offload capabilities by command
"ethtool -k ethX", where X is the network device number. At least
"tx-checksumming" and "scatter-gather" should be enabled.


Usage
-----

See in http://scst.sourceforge.net/iscsi-scst-howto.txt 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
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.

CAUTION: Working of target and initiator on the same host isn't fully
=======  supported. See SCST README file for details.


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 in
iscsi-scstd.conf file 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 advices
-------------------

1. If you use Windows XP or Windows 2003+ as initiators, you should
consider to decrease TcpAckFrequency parameter to 1. See
http://support.microsoft.com/kb/328890/ or google for "TcpAckFrequency"
for more details.


Compilation options
-------------------

There are the following compilation options, that could be commented
in/out in the kernel's module Makefile:

 - CONFIG_SCST_DEBUG - turns on some debugging code, including some logging.
   Makes the driver considerably bigger and slower, producing large amount of
   log data.

 - CONFIG_SCST_TRACING - turns on ability to log events. Makes the driver
   considerably bigger and leads to some performance loss.

 - CONFIG_SCST_EXTRACHECKS - adds extra validity checks in the various places.

 - CONFIG_SCST_ISCSI_DEBUG_DIGEST_FAILURES - simulates digest failures in
   random places.


Credits
-------

Thanks to:

 * IET developers for IET

 * 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 <bart.vanassche@gmail.com> for a lot of help

Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net