- Docs updates
[mirror/scst/.git] / iscsi-scst / README
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 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
30 Installation if your Linux kernel already has iSCSI-SCST built-in
31 -----------------------------------------------------------------
32
33 Simply run "make all", then "make install".
34
35
36 Installation out of Linux kernel tree
37 -------------------------------------
38
39 Basically as in README-IET, where file names are changed as specified
40 above.
41
42 Only vanilla kernels from kernel.org and RHEL/CentOS 5.2 kernels are
43 supported, but it should work on other (vendors') kernels, if you manage
44 to successfully compile on them. The main problem with vendor's kernels
45 is that they often contain patches, which will appear only in the next
46 version of the vanilla kernel, therefore it's quite hard to track such
47 changes. Thus, if during compilation for some vendor's kernel your
48 compiler complains about redefinition of some symbol, you should either
49 switch to vanilla kernel, or add or change as necessary the
50 corresponding to that symbol "#if LINUX_VERSION_CODE" statement.
51
52 If during compilation you see message like "*** No rule to make target
53 `xxx.h', needed by `yyy.o'.  Stop.", then your autogenerated
54 dependencies don't match your compiler configuration anymore. You should
55 run "make extraclean" to remove them. On the next compilation they will
56 be regenerated.
57
58 If you experience problems during kernel module load or running, check
59 your system and/or kernel logs (or run dmesg command for the few most
60 recent kernel messages).
61
62 To use full power of TCP zero-copy transmit functions, especially
63 dealing with user space supplied via scst_user module memory, iSCSI-SCST
64 needs to be notified when Linux networking finished data transmission.
65 Patch put_page_callback-<kernel-version>.patch provides such
66 functionality. The corresponding version of it should be applied on your
67 kernel. Then you should enable CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION
68 kernel config option. This is highly recommended, but not required. Basically,
69 you should consider using of this patch as some optimization, which IET
70 doesn't have, so if you don't use it, you will just revert to the
71 original IET behavior, when for data transmission:
72
73  - For in-kernel allocated memory (scst_vdisk and pass-through
74    handlers) usage of SGV cache on transmit path (READ-type commands)
75    will be disabled. The performance hit will be not big, but performance
76    will still remain better, than for IET, because SGV cache will remain
77    used on receive path while IET doesn't have such feature.
78
79  - For user space allocated memory (scst_user handler) all transmitted
80    data will be additionally copied into temporary TCP buffers. The
81    performance hit will be quite noticeable.
82
83 Note, that if your network hardware does not support TX offload
84 functions of has them disabled, then TCP zero-copy transmit functions on
85 your system will not be used by Linux networking in any case, so
86 put_page_callback patch will not be able to improve performance for you.
87 You can check your network hardware offload capabilities by command
88 "ethtool -k ethX", where X is the network device number. At least
89 "tx-checksumming" and "scatter-gather" should be enabled.
90
91 If you have in your kernel log error messages like:
92
93 iscsi-scst: ***ERROR*** net_priv isn't NULL and != ref_cmd
94
95 with the corresponding kernel BUG dump, then put_page_callback patch you
96 use isn't sufficient for your kernel. This might be because the kernel
97 you use has some additional patches applied, which affect the
98 functionality, which put_page_callback patch provides. For example,
99 Fedora or Gentoo use kernels, which, although have version number like
100 2.6.18, are greatly differ from the "vanilla" kernel 2.6.18,
101 maintained by Linus Torvalds for that the put_page_callback patch was
102 created. In this case I would recommend you either:
103
104  - Search net/ in your kernel source for "put_page" and "get_page" functions.
105    If you find any in some place, except in net/sunrpc/svc.c and
106    net/core/pktgen.c, then, most likely, you found the reason of your
107    problem. Replace them by "net_put_page" and "net_get_page"
108    correspondingly and try again. If the problem is solved, then please
109    prepare a new put_page_callback patch and send it to the SCST mailing
110    list scst-devel@lists.sourceforge.net.
111
112 or
113
114  - Unapply this patch and use iSCSI-SCST without it. Also report this
115    problem to the SCST mailing list scst-devel@lists.sourceforge.net.
116
117
118 Usage
119 -----
120
121 See in doc/iscsi-scst-howto.txt examples how to configure iSCSI-SCST.
122
123 ISCSI parameters like iSNS, CHAP and target parameters are configured in
124 iscsi-scstd.conf. All LUN information is configured using the
125 corresponding SCST interface. See in SCST README file section "Access
126 and devices visibility management (LUN masking)" to find out how to do
127 it. It is highly recommended to use scstadmin utility for that purpose.
128 The LUN information in iscsi-scstd.conf will be ignored. This is because
129 now responsibilities are divided between the target driver (iSCSI-SCST)
130 and the SCST core as it logically should be: the target driver is
131 responsible for handling targets and their parameters, SCST core is
132 responsible for handling backstorage.
133
134 IMPORTANT: All LUN information (access control) MUST be configured
135 =========  BEFORE iscsi-scstd started!
136
137 Also see SCST README file how to tune for the best performance.
138
139 CAUTION: Working of target and initiator on the same host isn't fully
140 =======  supported. See SCST README file for details.
141
142
143 Troubleshooting
144 ---------------
145
146 If you have any problems, start troubleshooting from looking at the
147 kernel and system logs. In the kernel log iSCSI-SCST and SCST core send
148 their messages, in the system log iscsi-scstd sends its messages. In
149 most Linux distributions both those logs are put to /var/log/messages
150 file.
151
152 Then, it might be helpful to increase level of logging. For kernel
153 modules you should make the debug build, by either running "make
154 release2debug" if you work with SCST SVN tree, or by enable the
155 corresponding debug symbols (see below). 
156
157 If after looking on the logs the reason of your problem is still unclear
158 for you, report to SCST mailing list scst-devel@lists.sourceforge.net.
159
160
161 Work if target's backstorage or link is too slow
162 ------------------------------------------------
163
164 In some cases you can experience I/O stalls or see in the kernel log
165 abort or reset messages. It can happen under high I/O load, when your
166 target's backstorage gets overloaded, or working over a slow link, when
167 the link can't serve all the queued commands on time, 
168
169 To workaround it you can reduce QueuedCommands parameter in
170 iscsi-scstd.conf file for the corresponding target to some lower value,
171 like 8 (default is 32).
172
173 Also see SCST README file for more details about that issue and ways to
174 prevent it.
175
176
177 Performance advices
178 -------------------
179
180 1. If you use Windows XP or Windows 2003+ as initiators, you should
181 consider to decrease TcpAckFrequency parameter to 1. See
182 http://support.microsoft.com/kb/328890/ or google for "TcpAckFrequency"
183 for more details.
184
185
186 Compilation options
187 -------------------
188
189 There are the following compilation options, that could be commented
190 in/out in the kernel's module Makefile:
191
192  - CONFIG_SCST_DEBUG - turns on some debugging code, including some logging.
193    Makes the driver considerably bigger and slower, producing large amount of
194    log data.
195
196  - CONFIG_SCST_TRACING - turns on ability to log events. Makes the driver
197    considerably bigger and leads to some performance loss.
198
199  - CONFIG_SCST_EXTRACHECKS - adds extra validity checks in the various places.
200
201  - CONFIG_SCST_ISCSI_DEBUG_DIGEST_FAILURES - simulates digest failures in
202    random places.
203
204
205 Creating version of put_page_callback patch for your kernel
206 -----------------------------------------------------------
207
208 If you need your own version of put_page_callback patch for your custom
209 kernel, for which there is no prepared version, you can create it
210 yourself. This is pretty mechanical work, you don't need to understand
211 how it works, you only need to do the following two steps:
212
213 1. Apply the closest version of put_page_callback-<kernel-version>.patch
214 on your kernel. Resolve only failed hunks from include/ and
215 net/core/utils.c, ignore other failures.
216
217 2. Search net/ in your kernel source for "put_page" and "get_page"
218 functions. Replace them by "net_put_page" and "net_get_page"
219 correspondingly. 
220
221 That's all. Then please send your new
222 put_page_callback-<kernel-version>.patch to the SCST mailing list
223 scst-devel@lists.sourceforge.net.
224
225 Credits
226 -------
227
228 Thanks to:
229
230  * IET developers for IET
231
232  * Ming Zhang <blackmagic02881@gmail.com> for fixes
233
234  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes
235
236  * Alexey Kuznetsov <kuznet@ms2.inr.ac.ru> for comments and help in
237    debugging
238
239  * Tomasz Chmielewski <mangoo@wpkg.org> for testing and suggestions
240
241  * Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
242
243 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net