bb31f4fa12a76eb3a5b32533790d5a480c17d852
[mirror/scst/.git] / iscsi-scst / README
1 iSCSI SCST target driver
2 ========================
3
4 Version 2.0.0, XX XXXXX 2010
5 ----------------------------
6
7 ISCSI-SCST is a deeply reworked fork of iSCSI Enterprise Target (IET)
8 (http://iscsitarget.sourceforge.net). Reasons of the fork were:
9
10  - To be able to use full power of SCST core.
11
12  - To fix all the problems, corner cases issues and iSCSI standard
13    violations which IET has.
14
15 See more info at http://scst.sourceforge.net/target_iscsi.html.
16
17 This version is compatible with SCST version 2.0.0 and higher.
18
19
20 Installation if your Linux kernel already has iSCSI-SCST built-in
21 -----------------------------------------------------------------
22
23 Simply run "make all", then "make install".
24
25
26 Installation out of Linux kernel tree
27 -------------------------------------
28
29 See HOWTOs in the doc/ subdirectory.
30
31 Only vanilla kernels from kernel.org and RHEL/CentOS 5.2 kernels are
32 supported, but it should work on other (vendors') kernels, if you manage
33 to successfully compile on them. The main problem with vendor's kernels
34 is that they often contain patches, which appear only in the next
35 version of the vanilla kernel, therefore it's quite hard to track such
36 changes. Thus, if during compilation for some vendor's kernel your
37 compiler complains about redefinition of some symbol, you should either
38 switch to vanilla kernel, or add or change as necessary the
39 corresponding to that symbol "#if LINUX_VERSION_CODE" statement.
40
41 If during compilation you see message like "*** No rule to make target
42 `xxx.h', needed by `yyy.o'.  Stop.", then your autogenerated
43 dependencies don't match your compiler configuration anymore. You should
44 run "make extraclean" to remove them. On the next compilation they will
45 be regenerated.
46
47 If you experience problems during kernel module load or running, check
48 your system and/or kernel logs (or run dmesg command for the few most
49 recent kernel messages).
50
51 To use full power of TCP zero-copy transmit functions, especially
52 dealing with user space supplied via scst_user module memory, iSCSI-SCST
53 needs to be notified when Linux networking finished data transmission.
54 For that you should enable CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION
55 kernel config option. This is highly recommended, but not required.
56 Basically, iSCSI-SCST works fine with an unpatched Linux kernel with the
57 same or better speed as other open source iSCSI targets, including IET,
58 but if you want even better performance you have to patch and rebuild
59 the kernel. Without CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION
60 enabled you will just revert to the original behavior of other open
61 source iSCSI targets, when for data transmission:
62
63  - For in-kernel allocated memory (scst_vdisk and pass-through
64    handlers) usage of SGV cache on transmit path (READ-type commands)
65    will be disabled, but data will still be sent in zero-copy manner.
66
67  - For user space allocated memory (scst_user handler) all transmitted
68    data will be additionally copied into temporary TCP buffers. The
69    performance hit will be quite noticeable.
70
71 Note, that if your network hardware does not support TX offload
72 functions or has them disabled, then TCP zero-copy transmit functions on
73 your system will not be used by Linux networking in any case, so
74 put_page_callback patch will not be able to improve performance for you.
75 You can check your network hardware offload capabilities by command
76 "ethtool -k ethX", where X is the network device number. At least
77 "tx-checksumming" and "scatter-gather" should be enabled.
78
79 If you have in your kernel log error messages like:
80
81 iscsi-scst: ***ERROR*** net_priv isn't NULL and != ref_cmd
82
83 with the corresponding kernel BUG dump, then put_page_callback patch you
84 use isn't sufficient for your kernel. This might be because the kernel
85 you use has some additional patches applied, which affect the
86 functionality, which put_page_callback patch provides. For example,
87 Fedora or Gentoo use kernels, which, although have version number like
88 2.6.18, are greatly differ from the "vanilla" kernel 2.6.18,
89 maintained by Linus Torvalds for that the put_page_callback patch was
90 created. In this case it is recommended either:
91
92  - Search net/ in your kernel source for "put_page" and "get_page" functions.
93    If you find any in some place, except in net/sunrpc/svc.c and
94    net/core/pktgen.c, then, most likely, you found the reason of your
95    problem. Replace them by "net_put_page" and "net_get_page"
96    correspondingly and try again. If the problem is solved, then please
97    prepare a new put_page_callback patch and send it to the SCST mailing
98    list scst-devel@lists.sourceforge.net.
99
100 or
101
102  - Unapply this patch and use iSCSI-SCST without it. Also report this
103    problem to the SCST mailing list scst-devel@lists.sourceforge.net.
104
105
106 Usage
107 -----
108
109 See HOWTOs in the doc/ subdirectory.
110
111 In 2.0.0 usage of iscsi-scstd.conf as well as iscsi-scst-adm utility is
112 obsolete. Use the sysfs interface facilities instead.
113
114 It is recommended to use TEST UNIT READY ("tur") command to check if
115 iSCSI-SCST target is alive in MPIO configurations.
116
117 Also see SCST README file how to tune for the best performance.
118
119 CAUTION: Working of target and initiator on the same host isn't fully
120 =======  supported. See SCST README file for details.
121
122
123 Sysfs interface
124 ---------------
125
126 Starting from 2.0.0 iSCSI-SCST has sysfs interface. You can switch to it
127 by running "make disable_proc". To switch back to the procfs interface
128 you should run "make enable_proc". The procfs interface starting from
129 version 2.0.0 is obsolete and will be removed in one of the next
130 versions.
131
132 Root of SCST sysfs interface is /sys/kernel/scst_tgt. Root of iSCSI-SCST
133 is /sys/kernel/scst_tgt/targets/iscsi. It has the following entries:
134
135  - None, one or more subdirectories for targets with name equal to names
136    of the corresponding targets.
137
138  - IncomingUser[num] - optional one or more attributes containing user
139    name and password for incoming discovery user name. Not exist by
140    default and can be added through "mgmt" entry, see below.
141
142  - OutgoingUser - optional attribute containing user name and password
143    for outgoing discovery user name. Not exist by default and can be
144    added through "mgmt" entry, see below.
145
146  - iSNSServer - contains name or IP address of iSNS server with optional
147    "AccessControl" attribute, which allows to enable iSNS access
148    control. Empty by default.
149
150  - enabled - using this attribute you can enable or disable iSCSI-SCST
151    accept new connections. It allows to finish configuring global
152    iSCSI-SCST attributes before it starts accepting new connections. 0
153    by default.
154
155  - open_state - read-only attribute, which allows to see if the user
156    space part of iSCSI-SCST connected to the kernel part.
157
158  - trace_level - allows to enable and disable various tracing
159    facilities. See content of this file for help how to use it.
160
161  - version - read-only attribute, which allows to see version of
162    iSCSI-SCST and enabled optional features.
163
164  - mgmt - main management entry, which allows to configure iSCSI-SCST.
165    Namely, add/delete targets as well as add/delete optional global and
166    per-target attributes. See content of this file for help how to use
167    it.
168
169 Each iSCSI-SCST sysfs file (attribute) can contain in the last line mark
170 "[key]". It is automatically added mark used to allow scstadmin to see
171 which attributes it should save in the config file. You can ignore it.
172
173 Each target subdirectory contains the following entries:
174
175  - ini_group - subdirectory defining initiator groups for this target,
176    used to define per-initiator access control. See SCST core README for
177    more details.
178
179  - luns - subdirectory defining LUNs of this target. See SCST core
180    README for more details.
181
182  - sessions - subdirectory containing connected to this target sessions.
183
184  - IncomingUser[num] - optional one or more attributes containing user
185    name and password for incoming user name. Not exist by default and can
186    be added through the "mgmt" entry, see above.
187
188  - OutgoingUser - optional attribute containing user name and password
189    for outgoing user name. Not exist by default and can be added through
190    the "mgmt" entry, see above.
191
192  - Entries defining default iSCSI parameters values used during iSCSI
193    parameters negotiation. Only entries which can be changed or make
194    sense are listed there.
195
196  - QueuedCommands - defines maximum number of commands queued to any
197    session of this target. Default is 32 commands.
198
199  - RspTimeout - defines the maximum time in seconds a command can wait for
200    response from initiator, otherwise the corresponding connection will
201    be closed. For performance reasons it is implemented as a timer,
202    which once in RspTimeout time checks the oldest command waiting for
203    response and, if it's older than RspTimeout, then it closes the
204    connection. Hence, a stalled connection will be closed in time
205    between RspTimeout and 2*RspTimeout. Default is 30 seconds.
206
207  - NopInInterval - defines interval between NOP-In requests, which the
208    target will send on idle connections to check if the initiator is
209    still alive. If there is no NOP-Out reply from the initiator in
210    RspTimeout time, the corresponding connection will be closed. Default
211    is 30 seconds. If it's set to 0, then NOP-In requests are disabled.
212
213  - enabled - using this attribute you can enable or disable iSCSI-SCST
214    accept new connections to this target. It allows to finish
215    configuring it before it starts accepting new connections. 0 by
216    default.
217
218  - rel_tgt_id - allows to read or write SCSI Relative Target Port
219    Identifier attribute. This identifier is used to identify SCSI Target
220    Ports by some SCSI commands, mainly by Persistent Reservations
221    commands. This identifier must be unique among all SCST targets, but
222    for convenience SCST allows disabled targets to have not unique
223    rel_tgt_id. In this case SCST will not allow to enable this target
224    until rel_tgt_id becomes unique. This attribute initialized unique by
225    SCST by default.
226
227  - tid - TID of this target.
228
229 Subdirectory "sessions" contains one subdirectory for each connected
230 session with name equal to name of the connected initiator.
231
232 Each session subdirectory contains the following entries:
233
234  - One subdirectory for each TCP connection in this session. ISCSI-SCST
235    supports 1 connection per session, but the session subdirectory can
236    contain several connections: one active and other being closed.
237
238  - Entries defining negotiated iSCSI parameters. Only parameters which
239    can be changed or make sense are listed there.
240
241  - initiator_name - contains initiator name
242
243  - sid - contains SID of this session
244
245  - reinstating - contains reinstatement state of this session
246
247  - force_close - write-only attribute, which allows to force close this
248    session. This is the only writable session attribute.
249
250  - active_commands - contains number of active, i.e. not yet or being
251    executed, SCSI commands in this session.
252
253  - commands - contains overall number of SCSI commands in this session.
254
255 Each connection subdirectory contains the following entries:
256
257  - cid - contains CID of this connection.
258
259  - ip - contains IP address of the connected initiator.
260
261  - state - contains processing state of this connection.
262
263 Below is a sample script, which configures 1 virtual disk "disk1" using
264 /disk1 image and one target iqn.2006-10.net.vlnb:tgt with all default
265 parameters:
266
267 #!/bin/bash
268
269 modprobe scst
270 modprobe scst_vdisk
271
272 echo "add_device disk1 filename=/disk1; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
273
274 service iscsi-scst start
275
276 echo "add_target iqn.2006-10.net.vlnb:tgt" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
277 echo "add disk1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
278
279 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
280 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled
281
282 Below is more advanced sample script, which configures more virtual
283 devices of various types, including virtual CDROM and 2 targets, one
284 with all default parameters, another one with some not default
285 parameters, incoming and outgoing user names for CHAP authentification,
286 and special permissions for initiator iqn.2005-03.org.open-iscsi:cacdcd2520,
287 which will see another set of devices. Also this sample configures CHAP
288 authentication for discovery sessions and iSNS server with access control.
289
290 #!/bin/bash
291
292 modprobe scst
293 modprobe scst_vdisk
294
295 echo "add_device disk1 filename=/disk1; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
296 echo "add_device disk2 filename=/disk2; blocksize=4096; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
297 echo "add_device blockio filename=/dev/sda5" >/sys/kernel/scst_tgt/handlers/vdisk_blockio/mgmt
298 echo "add_device nullio" >/sys/kernel/scst_tgt/handlers/vdisk_nullio/mgmt
299 echo "add_device cdrom" >/sys/kernel/scst_tgt/handlers/vcdrom/mgmt
300
301 service iscsi-scst start
302
303 echo "192.168.1.16 AccessControl" >/sys/kernel/scst_tgt/targets/iscsi/iSNSServer
304 echo "add_attribute IncomingUser joeD 12charsecret" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
305 echo "add_attribute OutgoingUser jackD 12charsecret1" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
306
307 echo "add_target iqn.2006-10.net.vlnb:tgt" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
308
309 echo "add disk1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
310 echo "add cdrom 1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
311
312 echo "add_target iqn.2006-10.net.vlnb:tgt1" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
313 echo "add_target_attribute iqn.2006-10.net.vlnb:tgt1 IncomingUser1 joe2 12charsecret2" >/sys/kernel/scst_tgt/targets/iscsi/mgmt             
314 echo "add_target_attribute iqn.2006-10.net.vlnb:tgt1 IncomingUser joe 12charsecret" >/sys/kernel/scst_tgt/targets/iscsi/mgmt                
315 echo "add_target_attribute iqn.2006-10.net.vlnb:tgt1 OutgoingUser jim1 12charpasswd" >/sys/kernel/scst_tgt/targets/iscsi/mgmt               
316 echo "No" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/InitialR2T                                                          
317 echo "Yes" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ImmediateData                                                      
318 echo "8192" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/MaxRecvDataSegmentLength                                          
319 echo "8192" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/MaxXmitDataSegmentLength                                          
320 echo "131072" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/MaxBurstLength                                                  
321 echo "32768" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/FirstBurstLength                                                 
322 echo "1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/MaxOutstandingR2T                                                    
323 echo "CRC32C,None" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/HeaderDigest                                               
324 echo "CRC32C,None" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/DataDigest                                                 
325 echo "32" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/QueuedCommands                                                      
326
327 echo "add disk2 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/mgmt
328 echo "add nullio 26" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/mgmt
329
330 echo "create special_ini" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_group/mgmt
331 echo "add blockio 0 read_only=1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_group/special_ini/luns/mgmt
332 echo "add iqn.2005-03.org.open-iscsi:cacdcd2520" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_group/special_ini/initiators/mgmt
333
334 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
335 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/enabled
336
337 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled
338
339 The resulting overall SCST sysfs hierarchy with an initiator connected to
340 both iSCSI-SCST targets will look like:
341
342 /sys/kernel/scst_tgt
343 |-- devices
344 |   |-- blockio
345 |   |   |-- blocksize
346 |   |   |-- exported
347 |   |   |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_group/special_ini/luns/0
348 |   |   |-- filename
349 |   |   |-- handler -> ../../handlers/vdisk_blockio
350 |   |   |-- read_only
351 |   |   |-- removable
352 |   |   |-- resync_size
353 |   |   |-- size_mb
354 |   |   |-- t10_dev_id
355 |   |   |-- type
356 |   |   `-- usn
357 |   |-- cdrom
358 |   |   |-- exported
359 |   |   |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/1
360 |   |   |-- filename
361 |   |   |-- handler -> ../../handlers/vcdrom
362 |   |   |-- size_mb
363 |   |   |-- t10_dev_id
364 |   |   |-- type
365 |   |   `-- usn
366 |   |-- disk1
367 |   |   |-- blocksize
368 |   |   |-- exported
369 |   |   |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/0
370 |   |   |-- filename
371 |   |   |-- handler -> ../../handlers/vdisk_fileio
372 |   |   |-- nv_cache
373 |   |   |-- o_direct
374 |   |   |-- read_only
375 |   |   |-- removable
376 |   |   |-- resync_size
377 |   |   |-- size_mb
378 |   |   |-- t10_dev_id
379 |   |   |-- type
380 |   |   |-- usn
381 |   |   `-- write_through
382 |   |-- disk2
383 |   |   |-- blocksize
384 |   |   |-- exported
385 |   |   |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/0
386 |   |   |-- filename
387 |   |   |-- handler -> ../../handlers/vdisk_fileio
388 |   |   |-- nv_cache
389 |   |   |-- o_direct
390 |   |   |-- read_only
391 |   |   |-- removable
392 |   |   |-- resync_size
393 |   |   |-- size_mb
394 |   |   |-- t10_dev_id
395 |   |   |-- type
396 |   |   |-- usn
397 |   |   `-- write_through
398 |   `-- nullio
399 |       |-- blocksize
400 |       |-- exported
401 |       |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/26
402 |       |-- handler -> ../../handlers/vdisk_nullio
403 |       |-- read_only
404 |       |-- removable
405 |       |-- size_mb
406 |       |-- t10_dev_id
407 |       |-- type
408 |       `-- usn
409 |-- handlers
410 |   |-- vcdrom
411 |   |   |-- cdrom -> ../../devices/cdrom
412 |   |   |-- mgmt
413 |   |   |-- trace_level
414 |   |   `-- type
415 |   |-- vdisk_blockio
416 |   |   |-- blockio -> ../../devices/blockio
417 |   |   |-- mgmt
418 |   |   |-- trace_level
419 |   |   `-- type
420 |   |-- vdisk_fileio
421 |   |   |-- disk1 -> ../../devices/disk1
422 |   |   |-- disk2 -> ../../devices/disk2
423 |   |   |-- mgmt
424 |   |   |-- trace_level
425 |   |   `-- type
426 |   `-- vdisk_nullio
427 |       |-- mgmt
428 |       |-- nullio -> ../../devices/nullio
429 |       |-- trace_level
430 |       `-- type
431 |-- sgv
432 |   |-- global_stats
433 |   |-- sgv
434 |   |   `-- stats
435 |   |-- sgv-clust
436 |   |   `-- stats
437 |   `-- sgv-dma
438 |       `-- stats
439 |-- targets
440 |   `-- iscsi
441 |       |-- IncomingUser
442 |       |-- OutgoingUser
443 |       |-- enabled
444 |       |-- iSNSServer
445 |       |-- iqn.2006-10.net.vlnb:tgt
446 |       |   |-- DataDigest
447 |       |   |-- FirstBurstLength
448 |       |   |-- HeaderDigest
449 |       |   |-- ImmediateData
450 |       |   |-- InitialR2T
451 |       |   |-- MaxBurstLength
452 |       |   |-- MaxOutstandingR2T
453 |       |   |-- MaxRecvDataSegmentLength
454 |       |   |-- MaxXmitDataSegmentLength
455 |       |   |-- QueuedCommands
456 |       |   |-- enabled
457 |       |   |-- ini_group
458 |       |   |   `-- mgmt
459 |       |   |-- luns
460 |       |   |   |-- 0
461 |       |   |   |   |-- device -> ../../../../../devices/disk1
462 |       |   |   |   `-- read_only
463 |       |   |   |-- 1
464 |       |   |   |   |-- device -> ../../../../../devices/cdrom
465 |       |   |   |   `-- read_only
466 |       |   |   `-- mgmt
467 |       |   |-- rel_tgt_id
468 |       |   |-- sessions
469 |       |   |   `-- iqn.2005-03.org.open-iscsi:cacdcd2520
470 |       |   |       |-- 10.170.75.2
471 |       |   |       |   |-- cid
472 |       |   |       |   |-- ip
473 |       |   |       |   `-- state
474 |       |   |       |-- DataDigest
475 |       |   |       |-- FirstBurstLength
476 |       |   |       |-- HeaderDigest
477 |       |   |       |-- ImmediateData
478 |       |   |       |-- InitialR2T
479 |       |   |       |-- MaxBurstLength
480 |       |   |       |-- MaxOutstandingR2T
481 |       |   |       |-- MaxRecvDataSegmentLength
482 |       |   |       |-- MaxXmitDataSegmentLength
483 |       |   |       |-- active_commands
484 |       |   |       |-- commands
485 |       |   |       |-- force_close
486 |       |   |       |-- initiator_name
487 |       |   |       |-- luns -> ../../luns
488 |       |   |       |-- reinstating
489 |       |   |       `-- sid
490 |       |   `-- tid
491 |       |-- iqn.2006-10.net.vlnb:tgt1
492 |       |   |-- DataDigest
493 |       |   |-- FirstBurstLength
494 |       |   |-- HeaderDigest
495 |       |   |-- ImmediateData
496 |       |   |-- IncomingUser
497 |       |   |-- IncomingUser1
498 |       |   |-- InitialR2T
499 |       |   |-- MaxBurstLength
500 |       |   |-- MaxOutstandingR2T
501 |       |   |-- MaxRecvDataSegmentLength
502 |       |   |-- MaxXmitDataSegmentLength
503 |       |   |-- OutgoingUser
504 |       |   |-- QueuedCommands
505 |       |   |-- enabled
506 |       |   |-- ini_group
507 |       |   |   |-- mgmt
508 |       |   |   `-- special_ini
509 |       |   |       |-- initiators
510 |       |   |       |   |-- iqn.2005-03.org.open-iscsi:cacdcd2520
511 |       |   |       |   `-- mgmt
512 |       |   |       `-- luns
513 |       |   |           |-- 0
514 |       |   |           |   |-- device -> ../../../../../../../devices/blockio
515 |       |   |           |   `-- read_only
516 |       |   |           `-- mgmt
517 |       |   |-- luns
518 |       |   |   |-- 0
519 |       |   |   |   |-- device -> ../../../../../devices/disk2
520 |       |   |   |   `-- read_only
521 |       |   |   |-- 26
522 |       |   |   |   |-- device -> ../../../../../devices/nullio
523 |       |   |   |   `-- read_only
524 |       |   |   `-- mgmt
525 |       |   |-- rel_tgt_id
526 |       |   |-- sessions
527 |       |   |   `-- iqn.2005-03.org.open-iscsi:cacdcd2520
528 |       |   |       |-- 10.170.75.2
529 |       |   |       |   |-- cid
530 |       |   |       |   |-- ip
531 |       |   |       |   `-- state
532 |       |   |       |-- DataDigest
533 |       |   |       |-- FirstBurstLength
534 |       |   |       |-- HeaderDigest
535 |       |   |       |-- ImmediateData
536 |       |   |       |-- InitialR2T
537 |       |   |       |-- MaxBurstLength
538 |       |   |       |-- MaxOutstandingR2T
539 |       |   |       |-- MaxRecvDataSegmentLength
540 |       |   |       |-- MaxXmitDataSegmentLength
541 |       |   |       |-- active_commands
542 |       |   |       |-- commands
543 |       |   |       |-- force_close
544 |       |   |       |-- initiator_name
545 |       |   |       |-- luns -> ../../ini_group/special_ini/luns
546 |       |   |       |-- reinstating
547 |       |   |       `-- sid
548 |       |   `-- tid
549 |       |-- mgmt
550 |       |-- open_state
551 |       |-- trace_level
552 |       `-- version
553 |-- threads
554 |-- trace_level
555 `-- version
556
557
558 Troubleshooting
559 ---------------
560
561 If you have any problems, start troubleshooting from looking at the
562 kernel and system logs. In the kernel log iSCSI-SCST and SCST core send
563 their messages, in the system log iscsi-scstd sends its messages. In
564 most Linux distributions both those logs are put to /var/log/messages
565 file.
566
567 Then, it might be helpful to increase level of logging. For kernel
568 modules you should make the debug build, by either running "make
569 release2debug" if you work with SCST SVN tree, or by enabling the
570 corresponding debug symbols (see below).
571
572 If after looking on the logs the reason of your problem is still unclear
573 for you, report to SCST mailing list scst-devel@lists.sourceforge.net.
574
575
576 Work if target's backstorage or link is too slow
577 ------------------------------------------------
578
579 In some cases you can experience I/O stalls or see in the kernel log
580 abort or reset messages. It can happen under high I/O load, when your
581 target's backstorage gets overloaded, or working over a slow link, when
582 the link can't serve all the queued commands on time,
583
584 To workaround it you can reduce QueuedCommands parameter for the
585 corresponding target to some lower value, like 8 (default is 32).
586
587 Also see SCST README file for more details about that issue and ways to
588 prevent it.
589
590
591 Performance advices
592 -------------------
593
594 1. If you use Windows XP or Windows 2003+ as initiators, you should
595 consider to decrease TcpAckFrequency parameter to 1. See
596 http://support.microsoft.com/kb/328890/ or google for "TcpAckFrequency"
597 for more details.
598
599 2. See how to get the maximum throughput from iSCSI, for instance, at
600 http://virtualgeek.typepad.com/virtual_geek/2009/01/a-multivendor-post-to-help-our-mutual-iscsi-customers-using-vmware.html.
601 It's about VMware, but its recommendations apply to other environments
602 as well.
603
604 3. ISCSI initiators from pre-CentOS/RHEL 5 reported to have some
605 performance problems. If you use it, it is strongly advised to upgrade.
606
607
608 Compilation options
609 -------------------
610
611 There are the following compilation options, that could be commented
612 in/out in the kernel's module Makefile:
613
614  - CONFIG_SCST_DEBUG - turns on some debugging code, including some logging.
615    Makes the driver considerably bigger and slower, producing large amount of
616    log data.
617
618  - CONFIG_SCST_TRACING - turns on ability to log events. Makes the driver
619    considerably bigger and leads to some performance loss.
620
621  - CONFIG_SCST_EXTRACHECKS - adds extra validity checks in the various places.
622
623  - CONFIG_SCST_ISCSI_DEBUG_DIGEST_FAILURES - simulates digest failures in
624    random places.
625
626
627 Creating version of put_page_callback patch for your kernel
628 -----------------------------------------------------------
629
630 If you need your own version of put_page_callback patch for your custom
631 kernel, for which there is no prepared version, you can create it
632 yourself. This is pretty mechanical work, you don't need to understand
633 how it works, you only need to do the following two steps:
634
635 1. Apply the closest version of put_page_callback-<kernel-version>.patch
636 on your kernel. Resolve only failed hunks from include/ and
637 net/core/utils.c, ignore other failures.
638
639 2. Search net/ in your kernel source for "put_page" and "get_page"
640 functions. Replace them by "net_put_page" and "net_get_page"
641 correspondingly.
642
643 That's all. Then please send your new
644 put_page_callback-<kernel-version>.patch to the SCST mailing list
645 scst-devel@lists.sourceforge.net.
646
647 Credits
648 -------
649
650 Thanks to:
651
652  * Ming Zhang <blackmagic02881@gmail.com> for fixes
653
654  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes
655
656  * Alexey Kuznetsov <kuznet@ms2.inr.ac.ru> for comments and help in
657    debugging
658
659  * Tomasz Chmielewski <mangoo@wpkg.org> for testing and suggestions
660
661  * Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
662
663 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net