Minor cleanups and docs updates
[mirror/scst/.git] / iscsi-scst / README
1 iSCSI SCST target driver
2 ========================
3
4 Version 1.0.0/0.4.16r151, XX June 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 This version is compatible with SCST version 1.0.0 and higher.
25
26 Tested on 2.6.21.1 kernel, but it should also work on other versions,
27 starting from 2.6.16.x.
28
29 Installation
30 ------------
31
32 Basically as in README-IET, where file names are changed as specified
33 above.
34
35 Only vanilla kernels from kernel.org are supported, but it should work
36 on vendors' kernels, if you manage to successfully compile on them. The
37 main problem with vendor's kernels is that they often contain patches,
38 which will appear only in the next version of the vanilla kernel,
39 therefore it's quite hard to track such changes. Thus, if during
40 compilation for some vendor kernel your compiler complains about
41 redefinition of some symbol, you should either switch to vanilla kernel,
42 or change as necessary the corresponding to that symbol "#if
43 LINUX_VERSION_CODE" statement.
44
45 If during compilation you see message like "*** No rule to make target
46 `xxx.h', needed by `yyy.o'.  Stop.", then your autogenerated
47 dependencies don't match your compiler configuration anymore. You should
48 run "make extraclean" to remove them. On the next compilation they will
49 be regenerated.
50
51 If you experience problems during kernel module load or running, check
52 your system and/or kernel logs (or run dmesg command for the few most
53 recent kernel messages).
54
55 To use full power of TCP zero-copy transmit functions, especially
56 dealing with user space supplied via scst_user module memory, iSCSI-SCST
57 needs to be notified when Linux networking finished data transmission.
58 Patch put_page_callback-<kernel-version>.patch provides such
59 functionality. The corresponding version of it should be applied on your
60 kernel. This is highly recommended, but not required. Basically, you
61 should consider using of this patch as some optimization, which IET
62 doesn't have, so if you don't use it, you will just revert to the
63 original IET behavior, when for data transmission:
64
65  - For in-kernel allocated memory (scst_vdisk and pass-through
66    handlers) usage of SGV cache on transmit path (READ-type commands)
67    will be disabled. The performance hit will be not big, but performance
68    will still remain better, than for IET, because SGV cache will remain
69    used on receive path while IET doesn't have such feature.
70
71  - For user space allocated memory (scst_user handler) all transmitted
72    data will be additionally copied into temporary TCP buffers. The
73    performance hit will be quite noticeable.
74
75 Note, that if your network hardware does not support TX offload
76 functions of has them disabled, then TCP zero-copy transmit functions on
77 your system will not be used by Linux networking in any case, so
78 put_page_callback patch will not be able to improve performance for you.
79 You can check your network hardware offload capabilities by command
80 "ethtool -k ethX", where X is the network device number. At least
81 "tx-checksumming" and "scatter-gather" should be enabled.
82
83 If you have in your kernel log error messages like:
84
85 iscsi-scst: ***ERROR*** net_priv isn't NULL and != ref_cmd
86
87 with the corresponding kernel BUG dump, then put_page_callback patch you
88 use isn't sufficient for your kernel. This might be because the kernel
89 you use has some additional patches applied, which affect the
90 functionality, which put_page_callback patch provides. For example,
91 Fedora or Gentoo use kernels, which, although have version number like
92 2.6.18, are greatly differ from the "vanilla" kernel 2.6.18,
93 maintained by Linus Torvalds for that the put_page_callback patch was
94 created. In this case I would recommend you either:
95
96  - Search net/ in your kernel source for "put_page" and "get_page" functions.
97    If you find any in some place, except in net/sunrpc/svc.c and
98    net/core/pktgen.c, then, most likely, you found the reason of your
99    problem. Replace them by "net_put_page" and "net_get_page"
100    correspondingly and try again. If the problem is solved, then please
101    prepare a new put_page_callback patch and send it to the SCST mailing
102    list scst-devel@lists.sourceforge.net.
103
104 or
105
106  - Unapply this patch and use iSCSI-SCST without it. Also report this
107    problem to the SCST mailing list scst-devel@lists.sourceforge.net.
108
109 Usage
110 -----
111
112 ISCSI parameters like iSNS, CHAP and target parameters are configured in
113 iscsi-scstd.conf. All LUN information is configured using the regular
114 SCST interface. It is highly recommended to use scstadmin utility for
115 that purpose. The LUN information in iscsi-scstd.conf will be ignored.
116 This is because now responsibilities are divided (as it should be)
117 between the target driver (iSCSI-SCST) and the SCST core as it logically
118 should be: the target driver is responsible for handling targets and
119 their parameters, SCST core is responsible for handling backstorage.
120
121 If you need to configure different LUs for different targets you should
122 create for each target group "Default_target_name", where "target_name"
123 means name of the target, for example:
124 "Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz", and add there
125 all necessary LUNs. Check SCST README file for details.
126
127 Check SCST README file how to tune for the best performance.
128
129 If under high load you experience I/O stalls or see in the kernel log
130 abort or reset messages, then try to reduce QueuedCommands parameter in
131 iscsi-scstd.conf file for the corresponding target to some lower value,
132 like 8 (default is 32). See also SCST README file for more details about
133 that issue.
134
135 CAUTION:  Working of target and initiator on the same host isn't
136 ========  supported. See SCST README file for details.
137
138 Compilation options
139 -------------------
140
141 There are the following compilation options, that could be commented
142 in/out in the kernel's module Makefile:
143
144  - DEBUG - turns on some debugging code, including some logging. Makes
145    the driver considerably bigger and slower, producing large amount of
146    log data.
147
148  - TRACING - turns on ability to log events. Makes the driver considerably
149    bigger and lead to some performance loss.
150
151  - EXTRACHECKS - adds extra validity checks in the various places.
152
153  - DEBUG_DIGEST_FAILURES - simulates digest failures in random places.
154
155 Known issues
156 ------------
157
158 Currently some iscsi-scst-adm functionality is broken. But, from one
159 side, at the moment I don't have time to look at it and, from other
160 side, in contrast to IET, in iSCSI-SCST this utility doesn't worth much,
161 since all devices management is done using SCST's /proc interface.
162 What's remained for iscsi-scst-adm is managing iSCSI targets and their
163 parameters, but in any case changing of any negotiable iSCSI parameter
164 needs renegotiation, i.e. the corresponding session restart, i.e.
165 iSCSI-SCST restart. But, if you decide to fix iscsi-scst-adm, I will
166 appreciate your patches.
167
168 Creating version of put_page_callback patch for your kernel
169 -----------------------------------------------------------
170
171 If you need your own version of put_page_callback patch for your custom
172 kernel, for which there is no prepared version, you can create it
173 yourself. This is pretty mechanical work, you don't need to understand
174 how it works, you only need to do the following two steps:
175
176 1. Apply the closest version of put_page_callback-<kernel-version>.patch
177 on your kernel. Resolve only failed hanks from include/ and
178 net/core/utils.c, ignore other failures.
179
180 2. Search net/ in your kernel source for "put_page" and "get_page"
181 functions. Replace them by "net_put_page" and "net_get_page"
182 correspondingly. 
183
184 That's all. Then please send your new
185 put_page_callback-<kernel-version>.patch to the SCST mailing list
186 scst-devel@lists.sourceforge.net.
187
188 Credits
189 -------
190
191 Thanks to:
192
193  * IET developers for IET
194
195  * Ming Zhang <blackmagic02881@gmail.com> for fixes
196
197  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes
198
199  * Alexey Kuznetsov <kuznet@ms2.inr.ac.ru> for comments and help in
200    debugging
201
202  * Tomasz Chmielewski <mangoo@wpkg.org> for testing and suggestions
203
204  * Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
205
206 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net