cca3f206104ec1c99bf528b71ccdb079f6a33b02
[mirror/scst/.git] / iscsi-scst / README_in-tree
1 iSCSI SCST target driver
2 ========================
3
4 Version 1.0.1/0.4.16r155, XX XXXX 2008
5 --------------------------------------
6
7 This driver is a forked with all respects version of iSCSI Enterprise
8 Target (IET) (http://iscsitarget.sourceforge.net/) with updates to work
9 over SCST as well as with many improvements and bugfixes (see ChangeLog
10 file). The reason of fork is that the necessary changes are intrusive
11 and with the current IET merge policy, where only simple bugfix-like
12 patches, which doesn't touch the core code, could be merged, it is very
13 unlikely that they will be merged in the main IET trunk.
14
15 To let it be installed and work at the same host together with IET
16 simultaneously all the driver's modules and files were renamed:
17
18  * ietd.conf -> iscsi-scstd.conf
19  * ietadm -> iscsi-scst-adm
20  * ietd -> iscsi-scstd
21  * iscsi-target -> iscsi-scst
22  * iscsi-target.ko -> iscsi-scst.ko
23
24 To use full power of TCP zero-copy transmit functions, especially
25 dealing with user space supplied via scst_user module memory, iSCSI-SCST
26 needs to be notified when Linux networking finished data transmission.
27 For that you should enable CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION
28 kernel config option. This is highly recommended, but not required. Basically,
29 you should consider usage of this option as some optimization, which IET
30 doesn't have, so if you don't use it, you will just revert to the
31 original IET behavior, when for data transmission:
32
33  - For in-kernel allocated memory (scst_vdisk and pass-through
34    handlers) usage of SGV cache on transmit path (READ-type commands)
35    will be disabled. The performance hit will be not big, but performance
36    will still remain better, than for IET, because SGV cache will remain
37    used on receive path while IET doesn't have such feature.
38
39  - For user space allocated memory (scst_user handler) all transmitted
40    data will be additionally copied into temporary TCP buffers. The
41    performance hit will be quite noticeable.
42
43 Note, that if your network hardware does not support TX offload
44 functions of has them disabled, then TCP zero-copy transmit functions on
45 your system will not be used by Linux networking in any case, so
46 put_page_callback patch will not be able to improve performance for you.
47 You can check your network hardware offload capabilities by command
48 "ethtool -k ethX", where X is the network device number. At least
49 "tx-checksumming" and "scatter-gather" should be enabled.
50
51 Usage
52 -----
53
54 ISCSI parameters like iSNS, CHAP and target parameters are configured in
55 iscsi-scstd.conf. All LUN information is configured using the regular
56 SCST interface. It is highly recommended to use scstadmin utility for
57 that purpose. The LUN information in iscsi-scstd.conf will be ignored.
58 This is because now responsibilities are divided (as it should be)
59 between the target driver (iSCSI-SCST) and the SCST core as it logically
60 should be: the target driver is responsible for handling targets and
61 their parameters, SCST core is responsible for handling backstorage.
62
63 If you need to configure different LUs for different targets you should
64 create for each target group "Default_target_name", where "target_name"
65 means name of the target, for example:
66 "Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz", and add there
67 all necessary LUNs. Check SCST README file for details.
68
69 Check SCST README file how to tune for the best performance.
70
71 If under high load you experience I/O stalls or see in the kernel log
72 abort or reset messages, then try to reduce QueuedCommands parameter in
73 iscsi-scstd.conf file for the corresponding target to some lower value,
74 like 8 (default is 32). See also SCST README file for more details about
75 that issue.
76
77 CAUTION:  Working of target and initiator on the same host isn't
78 ========  supported. See SCST README file for details.
79
80
81 Performance advices
82 -------------------
83
84 1. If you use Windows XP or Windows 2003+ as initiators, you should
85 consider to decrease TcpAckFrequency parameter to 1. See
86 http://support.microsoft.com/kb/328890/ or google for "TcpAckFrequency"
87 for more details.
88
89
90 Compilation options
91 -------------------
92
93 There are the following compilation options, that could be commented
94 in/out in the kernel's module Makefile:
95
96  - CONFIG_SCST_DEBUG - turns on some debugging code, including some logging.
97    Makes the driver considerably bigger and slower, producing large amount of
98    log data.
99
100  - CONFIG_SCST_TRACING - turns on ability to log events. Makes the driver
101    considerably bigger and leads to some performance loss.
102
103  - CONFIG_SCST_EXTRACHECKS - adds extra validity checks in the various places.
104
105  - CONFIG_SCST_ISCSI_DEBUG_DIGEST_FAILURES - simulates digest failures in
106    random places.
107
108
109 Credits
110 -------
111
112 Thanks to:
113
114  * IET developers for IET
115
116  * Ming Zhang <blackmagic02881@gmail.com> for fixes
117
118  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes
119
120  * Alexey Kuznetsov <kuznet@ms2.inr.ac.ru> for comments and help in
121    debugging
122
123  * Tomasz Chmielewski <mangoo@wpkg.org> for testing and suggestions
124
125  * Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
126
127 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net