e3e4d1c312465dfb01c21b5beacbb764ee017f59
[mirror/scst/.git] / iscsi-scst / README_in-tree
1 iSCSI SCST target driver
2 ========================
3
4 ISCSI-SCST is a deeply reworked fork of iSCSI Enterprise Target (IET)
5 (http://iscsitarget.sourceforge.net). Reasons of the fork were:
6
7  - To be able to use full power of SCST core.
8
9  - To fix all the problems, corner cases issues and iSCSI standard
10    violations which IET has.
11
12 See more info at http://scst.sourceforge.net/target_iscsi.html.
13
14 Usage
15 -----
16
17 See in http://scst.sourceforge.net/iscsi-scst-howto.txt how to configure
18 iSCSI-SCST.
19
20 In 2.0.0 usage of iscsi-scstd.conf as well as iscsi-scst-adm is
21 obsolete. Use the sysfs interface facilities instead.
22
23 It is recommended to use TEST UNIT READY ("tur") command to check if
24 iSCSI-SCST target is alive.
25
26 IMPORTANT: In the procfs build all LUN information (access control)
27 =========  MUST be configured BEFORE iscsi-scstd started!
28
29 Also see SCST README file how to tune for the best performance.
30
31 CAUTION: Working of target and initiator on the same host isn't fully
32 =======  supported. See SCST README file for details.
33
34
35 Sysfs interface
36 ---------------
37
38 Starting from 2.0.0 iSCSI-SCST has sysfs interface. You can switch to it
39 by running "make disable_proc". To switch back to the procfs interface
40 you should run "make enable_proc". The procfs interface from version
41 2.0.0 is obsolete and will be removed in one of the next versions.
42
43 Root of SCST sysfs interface is /sys/kernel/scst_tgt. Root of iSCSI-SCST
44 is /sys/kernel/scst_tgt/targets/iscsi. It has the following entries:
45
46  - None, one or more subdirectories for targets with name equal to names
47    of the corresponding targets.
48  
49  - IncomingUser[num] - optional one or more attributes containing user
50    name and password for incoming discovery user name. Not exist by
51    default and can be added through "mgmt" entry, see below.
52
53  - OutgoingUser - optional attribute containing user name and password
54    for outgoing discovery user name. Not exist by default and can be
55    added through "mgmt" entry, see below.
56
57  - iSNSServer - contains name or IP address of iSNS server with optional
58    "AccessControl" attribute, which allows to enable iSNS access
59    control. Empty by default.
60
61  - enabled - using this attribute you can enable or disable iSCSI-SCST
62    accept new connections. It allows to finish configuring global
63    iSCSI-SCST attributes before it starts accepting new connections. 0
64    by default.
65
66  - open_state - read-only attribute, which allows to see if the user
67    space part of iSCSI-SCST connected to the kernel part.
68
69  - trace_level - allows to enable and disable various tracing
70    facilities. See content of this file for help how to use it.
71
72  - version - read-only attribute, which allows to see version of
73    iSCSI-SCST and enabled optional features.
74
75  - mgmt - main management entry, which allows to configure iSCSI-SCST.
76    Namely, add/delete targets as well as add/delete optional global and
77    per-target attributes. See content of this file for help how to use
78    it.
79
80 Each iSCSI-SCST attribute can contain in the last line mark "[key]". It
81 is automatically added mark used to allow scstadmin to see which
82 attributes it should save in the config file. You can ignore it.
83
84 Each target subdirectory contains the following entries:
85
86  - ini_group - subdirectory defining initiator groups for this target,
87    used to define per-initiator access control. See SCST core README for
88    more details.
89  
90  - luns - subdirectory defining LUNs of this target. See SCST core
91    README for more details.
92  
93  - sessions - subdirectory containing connected to this target sessions.
94  
95  - IncomingUser[num] - optional one or more attributes containing user
96    name and password for incoming user name. Not exist by default and can
97    be added through the "mgmt" entry, see above.
98
99  - OutgoingUser - optional attribute containing user name and password
100    for outgoing user name. Not exist by default and can be added through
101    the "mgmt" entry, see above.
102
103  - Entries defining default iSCSI parameters values used during iSCSI
104    parameters negotiation.
105
106  - QueuedCommands - defines maximum number of commands queued to any
107    session of this target.
108
109  - enabled - using this attribute you can enable or disable iSCSI-SCST
110    accept new connections to this target. It allows to finish
111    configuring it before it starts accepting new connections. 0 by
112    default.
113
114  - tid - TID of this target.
115
116 Subdirectory "sessions" contains one subdirectory for each connected
117 session with name equal to name of the connected initiator.
118
119 Each session subdirectory contains the following entries:
120
121  - One subdirectory for each TCP connection in this session. ISCSI-SCST
122    supports 1 connection per session, but the session subdirectory can
123    contain several connections: one active and other being closed.
124    
125  - Entries defining negotiated iSCSI parameters.
126
127  - initiator_name - contains initiator name
128  
129  - sid - contains SID of this session
130  
131  - reinstating - contains reinstatement state of this session
132  
133  - force_close - write-only attribute, which allows to force close this
134    session. This is the only writable session attribute.
135    
136  - active_commands - contains number of active, i.e. not yet or being
137    executed, SCSI commands in this session.
138    
139  - commands - contains overall number of SCSI commands in this session.
140
141 Each connection subdirectory contains the following entries:
142
143  - cid - contains CID of this connection.
144  
145  - ip - contains IP address of the connected initiator.
146  
147  - state - contains processing state of this connection.
148  
149 Below is a sample script, which configures 1 virtual disk "disk1" using
150 /disk1 image and one target iqn.2006-10.net.vlnb:tgt with all default
151 parameters:
152
153 #!/bin/bash
154
155 modprobe scst
156 modprobe scst_vdisk
157
158 echo "open disk1 /disk1 NV_CACHE" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
159
160 service iscsi-scst start
161
162 echo "add_target iqn.2006-10.net.vlnb:tgt" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
163
164 echo "add disk1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
165
166 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
167 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled
168
169
170 Below is more advanced sample script, which configures more virtual
171 devices of various types, including virtual CDROM and 2 targets, one
172 with all default parameters, another one with some not default
173 parameters, incoming and outgoing user names for CHAP authentification,
174 and special permissions for initiator iqn.2005-03.org.open-iscsi:cacdcd2520,
175 which will see another set of devices. Also this sample configures CHAP
176 authentication for discovery sessions and iSNS server with access control.
177
178 #!/bin/bash
179
180 modprobe scst
181 modprobe scst_vdisk
182
183 echo "open disk1 /disk1 NV_CACHE" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
184 echo "open disk2 /disk2 4096 NV_CACHE" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
185 echo "open blockio /dev/sda5" >/sys/kernel/scst_tgt/handlers/vdisk_blockio/mgmt
186 echo "open nullio none" >/sys/kernel/scst_tgt/handlers/vdisk_nullio/mgmt
187 echo "open cdrom" >/sys/kernel/scst_tgt/handlers/vcdrom/mgmt
188
189 service iscsi-scst start
190
191 echo "192.168.1.16 AccessControl" >/sys/kernel/scst_tgt/targets/iscsi/iSNSServer
192 echo "add_attribute IncomingUser joeD 12charsecret" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
193 echo "add_attribute OutgoingUser jackD 12charsecret1" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
194
195 echo "add_target iqn.2006-10.net.vlnb:tgt" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
196
197 echo "add disk1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
198 echo "add cdrom 1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/mgmt
199
200 echo "add_target iqn.2006-10.net.vlnb:tgt1 \
201         IncomingUser1 joe2 12charsecret2; \
202         IncomingUser joe 12charsecret; \
203         OutgoingUser jim1 12charpasswd; \
204         InitialR2T                      No; \
205         ImmediateData                   Yes; \
206         MaxRecvDataSegmentLength        8192; \
207         MaxXmitDataSegmentLength        8192; \
208         MaxBurstLength                  131072; \
209         FirstBurstLength                32768; \
210         MaxOutstandingR2T               1; \
211         HeaderDigest                    CRC32C,None; \
212         DataDigest                      CRC32C,None; \
213         QueuedCommands                  8; \
214         " >/sys/kernel/scst_tgt/targets/iscsi/mgmt
215
216 echo "add disk2 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/mgmt
217 echo "add nullio 26" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/mgmt
218
219 echo "create special_ini" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_group/mgmt
220 echo "add blockio 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_group/special_ini/luns/mgmt
221 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
222
223 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/enabled
224 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/enabled
225
226 echo 1 >/sys/kernel/scst_tgt/targets/iscsi/enabled
227
228 The resulting overall SCST sysfs hierarchy with an initiator connected to
229 both iSCSI-SCST targets will look like:
230
231 /sys/kernel/scst_tgt
232 |-- devices
233 |   |-- blockio
234 |   |   |-- block_size
235 |   |   |-- exported
236 |   |   |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_group/special_ini/luns/0
237 |   |   |-- filename
238 |   |   |-- handler -> ../../handlers/vdisk_blockio
239 |   |   |-- read_only
240 |   |   |-- removable
241 |   |   |-- resync_size
242 |   |   |-- size
243 |   |   |-- t10_dev_id
244 |   |   `-- type
245 |   |-- cdrom
246 |   |   |-- exported
247 |   |   |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/1
248 |   |   |-- filename
249 |   |   |-- handler -> ../../handlers/vcdrom
250 |   |   |-- removable
251 |   |   |-- size
252 |   |   |-- t10_dev_id
253 |   |   `-- type
254 |   |-- disk1
255 |   |   |-- block_size
256 |   |   |-- exported
257 |   |   |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/0
258 |   |   |-- filename
259 |   |   |-- handler -> ../../handlers/vdisk_fileio
260 |   |   |-- nv_cache
261 |   |   |-- o_direct
262 |   |   |-- read_only
263 |   |   |-- removable
264 |   |   |-- resync_size
265 |   |   |-- size
266 |   |   |-- t10_dev_id
267 |   |   |-- type
268 |   |   `-- write_through
269 |   |-- disk2
270 |   |   |-- block_size
271 |   |   |-- exported
272 |   |   |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/0
273 |   |   |-- filename
274 |   |   |-- handler -> ../../handlers/vdisk_fileio
275 |   |   |-- nv_cache
276 |   |   |-- o_direct
277 |   |   |-- read_only
278 |   |   |-- removable
279 |   |   |-- resync_size
280 |   |   |-- size
281 |   |   |-- t10_dev_id
282 |   |   |-- type
283 |   |   `-- write_through
284 |   `-- nullio
285 |       |-- block_size
286 |       |-- exported
287 |       |   `-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/26
288 |       |-- handler -> ../../handlers/vdisk_nullio
289 |       |-- read_only
290 |       |-- removable
291 |       |-- size
292 |       |-- t10_dev_id
293 |       `-- type
294 |-- handlers
295 |   |-- vcdrom
296 |   |   |-- mgmt
297 |   |   |-- trace_level
298 |   |   `-- type
299 |   |-- vdisk_blockio
300 |   |   |-- mgmt
301 |   |   |-- trace_level
302 |   |   `-- type
303 |   |-- vdisk_fileio
304 |   |   |-- mgmt
305 |   |   |-- trace_level
306 |   |   `-- type
307 |   `-- vdisk_nullio
308 |       |-- mgmt
309 |       |-- trace_level
310 |       `-- type
311 |-- sgv
312 |   |-- global_stats
313 |   |-- sgv
314 |   |   `-- stats
315 |   |-- sgv-clust
316 |   |   `-- stats
317 |   `-- sgv-dma
318 |       `-- stats
319 |-- targets
320 |   `-- iscsi
321 |       |-- IncomingUser
322 |       |-- OutgoingUser
323 |       |-- enabled
324 |       |-- iSNSServer
325 |       |-- iqn.2006-10.net.vlnb:tgt
326 |       |   |-- DataDigest
327 |       |   |-- FirstBurstLength
328 |       |   |-- HeaderDigest
329 |       |   |-- ImmediateData
330 |       |   |-- InitialR2T
331 |       |   |-- MaxBurstLength
332 |       |   |-- MaxOutstandingR2T
333 |       |   |-- MaxRecvDataSegmentLength
334 |       |   |-- MaxXmitDataSegmentLength
335 |       |   |-- QueuedCommands
336 |       |   |-- enabled
337 |       |   |-- ini_group
338 |       |   |   `-- mgmt
339 |       |   |-- luns
340 |       |   |   |-- 0
341 |       |   |   |   |-- device -> ../../../../../devices/disk1
342 |       |   |   |   `-- read_only
343 |       |   |   |-- 1
344 |       |   |   |   |-- device -> ../../../../../devices/cdrom
345 |       |   |   |   `-- read_only
346 |       |   |   `-- mgmt
347 |       |   |-- sessions
348 |       |   |   `-- iqn.2005-03.org.open-iscsi:cacdcd2520
349 |       |   |       |-- 10.170.75.2
350 |       |   |       |   |-- cid
351 |       |   |       |   |-- ip
352 |       |   |       |   `-- state
353 |       |   |       |-- DataDigest
354 |       |   |       |-- FirstBurstLength
355 |       |   |       |-- HeaderDigest
356 |       |   |       |-- ImmediateData
357 |       |   |       |-- InitialR2T
358 |       |   |       |-- MaxBurstLength
359 |       |   |       |-- MaxOutstandingR2T
360 |       |   |       |-- MaxRecvDataSegmentLength
361 |       |   |       |-- MaxXmitDataSegmentLength
362 |       |   |       |-- active_commands
363 |       |   |       |-- commands
364 |       |   |       |-- force_close
365 |       |   |       |-- initiator_name
366 |       |   |       |-- reinstating
367 |       |   |       `-- sid
368 |       |   `-- tid
369 |       |-- iqn.2006-10.net.vlnb:tgt1
370 |       |   |-- DataDigest
371 |       |   |-- FirstBurstLength
372 |       |   |-- HeaderDigest
373 |       |   |-- ImmediateData
374 |       |   |-- IncomingUser
375 |       |   |-- IncomingUser1
376 |       |   |-- InitialR2T
377 |       |   |-- MaxBurstLength
378 |       |   |-- MaxOutstandingR2T
379 |       |   |-- MaxRecvDataSegmentLength
380 |       |   |-- MaxXmitDataSegmentLength
381 |       |   |-- OutgoingUser
382 |       |   |-- QueuedCommands
383 |       |   |-- enabled
384 |       |   |-- ini_group
385 |       |   |   |-- mgmt
386 |       |   |   `-- special_ini
387 |       |   |       |-- initiators
388 |       |   |       |   |-- iqn.2005-03.org.open-iscsi:cacdcd2520
389 |       |   |       |   `-- mgmt
390 |       |   |       `-- luns
391 |       |   |           |-- 0
392 |       |   |           |   |-- device -> ../../../../../../../devices/blockio
393 |       |   |           |   `-- read_only
394 |       |   |           `-- mgmt
395 |       |   |-- luns
396 |       |   |   |-- 0
397 |       |   |   |   |-- device -> ../../../../../devices/disk2
398 |       |   |   |   `-- read_only
399 |       |   |   |-- 26
400 |       |   |   |   |-- device -> ../../../../../devices/nullio
401 |       |   |   |   `-- read_only
402 |       |   |   `-- mgmt
403 |       |   |-- sessions
404 |       |   |   `-- iqn.2005-03.org.open-iscsi:cacdcd2520
405 |       |   |       |-- 10.170.75.2
406 |       |   |       |   |-- cid
407 |       |   |       |   |-- ip
408 |       |   |       |   `-- state
409 |       |   |       |-- DataDigest
410 |       |   |       |-- FirstBurstLength
411 |       |   |       |-- HeaderDigest
412 |       |   |       |-- ImmediateData
413 |       |   |       |-- InitialR2T
414 |       |   |       |-- MaxBurstLength
415 |       |   |       |-- MaxOutstandingR2T
416 |       |   |       |-- MaxRecvDataSegmentLength
417 |       |   |       |-- MaxXmitDataSegmentLength
418 |       |   |       |-- active_commands
419 |       |   |       |-- commands
420 |       |   |       |-- force_close
421 |       |   |       |-- initiator_name
422 |       |   |       |-- reinstating
423 |       |   |       `-- sid
424 |       |   `-- tid
425 |       |-- mgmt
426 |       |-- open_state
427 |       |-- trace_level
428 |       `-- version
429 |-- threads
430 |-- trace_level
431 `-- version
432
433
434 Troubleshooting
435 ---------------
436
437 If you have any problems, start troubleshooting from looking at the
438 kernel and system logs. In the kernel log iSCSI-SCST and SCST core send
439 their messages, in the system log iscsi-scstd sends its messages. In
440 most Linux distributions both those logs are put to /var/log/messages
441 file.
442
443 Then, it might be helpful to increase level of logging. For kernel
444 modules you should make the debug build by enabling CONFIG_SCST_DEBUG.
445
446 If after looking on the logs the reason of your problem is still unclear
447 for you, report to SCST mailing list scst-devel@lists.sourceforge.net.
448
449
450 Work if target's backstorage or link is too slow
451 ------------------------------------------------
452
453 In some cases you can experience I/O stalls or see in the kernel log
454 abort or reset messages. It can happen under high I/O load, when your
455 target's backstorage gets overloaded, or working over a slow link, when
456 the link can't serve all the queued commands on time,
457
458 To workaround it you can reduce QueuedCommands parameter for the
459 corresponding target to some lower value, like 8 (default is 32).
460
461 Also see SCST README file for more details about that issue and ways to
462 prevent it.
463
464
465 Performance advices
466 -------------------
467
468 1. If you use Windows XP or Windows 2003+ as initiators, you should
469 consider to decrease TcpAckFrequency parameter to 1. See
470 http://support.microsoft.com/kb/328890/ or google for "TcpAckFrequency"
471 for more details.
472
473 2. See how to get the maximum throughput from iSCSI, for instance, at
474 http://virtualgeek.typepad.com/virtual_geek/2009/01/a-multivendor-post-to-help-our-mutual-iscsi-customers-using-vmware.html.
475 It's about VMware, but its recommendations apply to other environments
476 as well.
477
478 3. ISCSI initiators built in pre-CentOS/RHEL 5 reported to have some
479 performance problems. If you use it, it is strongly advised to upgrade.
480
481
482 Compilation options
483 -------------------
484
485 There are the following compilation options, that could be commented
486 in/out in the kernel's module Makefile:
487
488  - CONFIG_SCST_DEBUG - turns on some debugging code, including some logging.
489    Makes the driver considerably bigger and slower, producing large amount of
490    log data.
491
492  - CONFIG_SCST_TRACING - turns on ability to log events. Makes the driver
493    considerably bigger and leads to some performance loss.
494
495  - CONFIG_SCST_EXTRACHECKS - adds extra validity checks in the various places.
496
497  - CONFIG_SCST_ISCSI_DEBUG_DIGEST_FAILURES - simulates digest failures in
498    random places.
499
500
501 Credits
502 -------
503
504 Thanks to:
505
506  * Ming Zhang <blackmagic02881@gmail.com> for fixes
507
508  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes
509
510  * Alexey Kuznetsov <kuznet@ms2.inr.ac.ru> for comments and help in
511    debugging
512
513  * Tomasz Chmielewski <mangoo@wpkg.org> for testing and suggestions
514
515  * Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
516
517 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net