5b8453156019cfb367659281338ccea8c16e8281
[mirror/scst/.git] / scst / README_in-tree
1 Generic SCSI target mid-level for Linux (SCST)
2 ==============================================
3
4 SCST is designed to provide unified, consistent interface between SCSI
5 target drivers and Linux kernel and simplify target drivers development
6 as much as possible. Detail description of SCST's features and internals
7 could be found in "Generic SCSI Target Middle Level for Linux" document
8 SCST's Internet page http://scst.sourceforge.net.
9
10 SCST supports the following I/O modes:
11
12  * Pass-through mode with one to many relationship, i.e. when multiple
13    initiators can connect to the exported pass-through devices, for
14    the following SCSI devices types: disks (type 0), tapes (type 1),
15    processors (type 3), CDROMs (type 5), MO disks (type 7), medium
16    changers (type 8) and RAID controllers (type 0xC)
17
18  * FILEIO mode, which allows to use files on file systems or block
19    devices as virtual remotely available SCSI disks or CDROMs with
20    benefits of the Linux page cache
21
22  * BLOCKIO mode, which performs direct block IO with a block device,
23    bypassing page-cache for all operations. This mode works ideally with
24    high-end storage HBAs and for applications that either do not need
25    caching between application and disk or need the large block
26    throughput
27
28  * User space mode using scst_user device handler, which allows to
29    implement in the user space virtual SCSI devices in the SCST
30    environment
31
32  * "Performance" device handlers, which provide in pseudo pass-through
33    mode a way for direct performance measurements without overhead of
34    actual data transferring from/to underlying SCSI device
35
36 In addition, SCST supports advanced per-initiator access and devices
37 visibility management, so different initiators could see different set
38 of devices with different access permissions. See below for details.
39
40
41 Installation
42 ------------
43
44 To see your devices remotely, you need to add them to at least "Default"
45 security group (see below how). By default, no local devices are seen
46 remotely. There must be LUN 0 in each security group, i.e. LUs
47 numeration must not start from, e.g., 1. Otherwise you will see no
48 devices on remote initiators and SCST core will write into the kernel
49 log message: "tgt_dev for LUN 0 not found, command to unexisting LU?"
50
51 It is highly recommended to use scstadmin utility for configuring
52 devices and security groups.
53
54 If you experience problems during modules load or running, check your
55 kernel logs (or run dmesg command for the few most recent messages).
56
57 IMPORTANT: Without loading appropriate device handler, corresponding devices
58 =========  will be invisible for remote initiators, which could lead to holes
59            in the LUN addressing, so automatic device scanning by remote SCSI
60            mid-level could not notice the devices. Therefore you will have
61            to add them manually via
62            'echo "- - -" >/sys/class/scsi_host/hostX/scan',
63            where X - is the host number.
64
65 IMPORTANT: Working of target and initiator on the same host is
66 =========  supported, except the following 2 cases: swap over target exported
67            device and using a writable mmap over a file from target
68            exported device. The latter means you can't mount a file
69            system over target exported device. In other words, you can
70            freely use any sg, sd, st, etc. devices imported from target
71            on the same host, but you can't mount file systems or put
72            swap on them. This is a limitation of Linux memory/cache
73            manager, because in this case an OOM deadlock like: system
74            needs some memory -> it decides to clear some cache -> cache
75            needs to write on target exported device -> initiator sends
76            request to the target -> target needs memory -> system needs
77            even more memory -> deadlock.
78
79 IMPORTANT: In the current version simultaneous access to local SCSI devices
80 =========  via standard high-level SCSI drivers (sd, st, sg, etc.) and
81            SCST's target drivers is unsupported. Especially it is
82            important for execution via sg and st commands that change
83            the state of devices and their parameters, because that could
84            lead to data corruption. If any such command is done, at
85            least related device handler(s) must be restarted. For block
86            devices READ/WRITE commands using direct disk handler look to
87            be safe.
88
89 IMPORTANT: Some versions of Windows have a bug, which makes them consider
90 =========  response of READ CAPACITY(16) longer than 12 bytes as a faulty one.
91            As the result, such Windows'es refuse to see SCST exported
92            devices >2TB in size. This is fixed by MS in latter Windows
93            versions, probably, by some hotfix. But if you're using such
94            buggy Windows and experience this problem, change in
95            scst_vdisk.c::vdisk_exec_read_capacity16() "#if 1" to "#if 0".
96
97
98 Usage in failover mode
99 ----------------------
100
101 It is recommended to use TEST UNIT READY ("tur") command to check if
102 SCST target is alive in MPIO configurations.
103
104
105 Device handlers
106 ---------------
107
108 Device specific drivers (device handlers) are plugins for SCST, which
109 help SCST to analyze incoming requests and determine parameters,
110 specific to various types of devices. If an appropriate device handler
111 for a SCSI device type isn't loaded, SCST doesn't know how to handle
112 devices of this type, so they will be invisible for remote initiators
113 (more precisely, "LUN not supported" sense code will be returned).
114
115 In addition to device handlers for real devices, there are VDISK, user
116 space and "performance" device handlers.
117
118 VDISK device handler works over files on file systems and makes from
119 them virtual remotely available SCSI disks or CDROM's. In addition, it
120 allows to work directly over a block device, e.g. local IDE or SCSI disk
121 or ever disk partition, where there is no file systems overhead. Using
122 block devices comparing to sending SCSI commands directly to SCSI
123 mid-level via scsi_do_req()/scsi_execute_async() has advantage that data
124 are transferred via system cache, so it is possible to fully benefit from
125 caching and read ahead performed by Linux's VM subsystem. The only
126 disadvantage here that in the FILEIO mode there is superfluous data
127 copying between the cache and SCST's buffers. This issue is going to be
128 addressed in the next release. Virtual CDROM's are useful for remote
129 installation. See below for details how to setup and use VDISK device
130 handler.
131
132 SCST user space device handler provides an interface between SCST and
133 the user space, which allows to create pure user space devices. The
134 simplest example, where one would want it is if he/she wants to write a
135 VTL. With scst_user he/she can write it purely in the user space. Or one
136 would want it if he/she needs some sophisticated for kernel space
137 processing of the passed data, like encrypting them or making snapshots.
138
139 "Performance" device handlers for disks, MO disks and tapes in their
140 exec() method skip (pretend to execute) all READ and WRITE operations
141 and thus provide a way for direct link performance measurements without
142 overhead of actual data transferring from/to underlying SCSI device.
143
144 NOTE: Since "perf" device handlers on READ operations don't touch the
145 ====  commands' data buffer, it is returned to remote initiators as it
146       was allocated, without even being zeroed. Thus, "perf" device
147       handlers impose some security risk, so use them with caution.
148
149
150 Compilation options
151 -------------------
152
153 There are the following compilation options, that could be change using
154 your favorite kernel configuration Makefile target, e.g. "make xconfig":
155
156  - CONFIG_SCST_DEBUG - if defined, turns on some debugging code,
157    including some logging. Makes the driver considerably bigger and slower,
158    producing large amount of log data.
159
160  - CONFIG_SCST_TRACING - if defined, turns on ability to log events. Makes the
161    driver considerably bigger and leads to some performance loss.
162
163  - CONFIG_SCST_EXTRACHECKS - if defined, adds extra validity checks in
164    the various places.
165
166  - CONFIG_SCST_USE_EXPECTED_VALUES - if not defined (default), initiator
167    supplied expected data transfer length and direction will be used only for
168    verification purposes to return error or warn in case if one of them
169    is invalid. Instead, locally decoded from SCSI command values will be
170    used. This is necessary for security reasons, because otherwise a
171    faulty initiator can crash target by supplying invalid value in one
172    of those parameters. This is especially important in case of
173    pass-through mode. If CONFIG_SCST_USE_EXPECTED_VALUES is defined, initiator
174    supplied expected data transfer length and direction will override
175    the locally decoded values. This might be necessary if internal SCST
176    commands translation table doesn't contain SCSI command, which is
177    used in your environment. You can know that if you have messages like
178    "Unknown opcode XX for YY. Should you update scst_scsi_op_table?" in
179    your kernel log and your initiator returns an error. Also report
180    those messages in the SCST mailing list
181    scst-devel@lists.sourceforge.net. Note, that not all SCSI transports
182    support supplying expected values.
183
184  - CONFIG_SCST_DEBUG_TM - if defined, turns on task management functions
185    debugging, when on LUN 6 some of the commands will be delayed for
186    about 60 sec., so making the remote initiator send TM functions, eg
187    ABORT TASK and TARGET RESET. Also define
188    CONFIG_SCST_TM_DBG_GO_OFFLINE symbol in the Makefile if you want that
189    the device eventually become completely unresponsive, or otherwise to
190    circle around ABORTs and RESETs code. Needs CONFIG_SCST_DEBUG turned
191    on.
192
193  - CONFIG_SCST_STRICT_SERIALIZING - if defined, makes SCST send all commands to
194    underlying SCSI device synchronously, one after one. This makes task
195    management more reliable, with cost of some performance penalty. This
196    is mostly actual for stateful SCSI devices like tapes, where the
197    result of command's execution depends from device's settings defined
198    by previous commands. Disk and RAID devices are stateless in the most
199    cases. The current SCSI core in Linux doesn't allow to abort all
200    commands reliably if they sent asynchronously to a stateful device.
201    Turned off by default, turn it on if you use stateful device(s) and
202    need as much error recovery reliability as possible. As a side effect
203    of CONFIG_SCST_STRICT_SERIALIZING, on kernels below 2.6.30 no kernel
204    patching is necessary for pass-through device handlers (scst_disk,
205    etc.).
206
207  - CONFIG_SCST_ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ - if defined, it will be
208    allowed to submit pass-through commands to real SCSI devices via the SCSI
209    middle layer using scsi_execute_async() function from soft IRQ
210    context (tasklets). This used to be the default, but currently it
211    seems the SCSI middle layer starts expecting only thread context on
212    the IO submit path, so it is disabled now by default. Enabling it
213    will decrease amount of context switches and improve performance. It
214    is more or less safe, in the worst case, if in your configuration the
215    SCSI middle layer really doesn't expect SIRQ context in
216    scsi_execute_async() function, you will get a warning message in the
217    kernel log.
218
219  - CONFIG_SCST_STRICT_SECURITY - if defined, makes SCST zero allocated data
220    buffers. Undefining it (default) considerably improves performance
221    and eases CPU load, but could create a security hole (information
222    leakage), so enable it, if you have strict security requirements.
223
224  - CONFIG_SCST_ABORT_CONSIDER_FINISHED_TASKS_AS_NOT_EXISTING - if defined,
225    in case when TASK MANAGEMENT function ABORT TASK is trying to abort a
226    command, which has already finished, remote initiator, which sent the
227    ABORT TASK request, will receive TASK NOT EXIST (or ABORT FAILED)
228    response for the ABORT TASK request. This is more logical response,
229    since, because the command finished, attempt to abort it failed, but
230    some initiators, particularly VMware iSCSI initiator, consider TASK
231    NOT EXIST response as if the target got crazy and try to RESET it.
232    Then sometimes get crazy itself. So, this option is disabled by
233    default.
234
235  - CONFIG_SCST_MEASURE_LATENCY - if defined, provides in /proc/scsi_tgt/latency
236    file average commands processing latency. You can clear already
237    measured results by writing 0 in this file. For the sysfs build you
238    can find those results in /sys/kernel/scst_tgt and below. Note, you need a
239    non-preemptible kernel to have correct results.
240
241 HIGHMEM kernel configurations are fully supported, but not recommended
242 for performance reasons, except for scst_user, where they are not
243 supported, because this module deals with user supplied memory on a
244 zero-copy manner. If you need to use it, consider change VMSPLIT option
245 or use 64-bit system configuration instead.
246
247 For changing VMSPLIT option (CONFIG_VMSPLIT to be precise) you should in
248 "make menuconfig" command set the following variables:
249
250  - General setup->Configure standard kernel features (for small systems): ON
251
252  - General setup->Prompt for development and/or incomplete code/drivers: ON
253
254  - Processor type and features->High Memory Support: OFF
255
256  - Processor type and features->Memory split: according to amount of
257    memory you have. If it is less than 800MB, you may not touch this
258    option at all.
259
260
261 Module parameters
262 -----------------
263
264 Module scst supports the following parameters:
265
266  - scst_threads - allows to set count of SCST's threads. By default it
267    is CPU count.
268
269  - scst_max_cmd_mem - sets maximum amount of memory in Mb allowed to be
270    consumed by the SCST commands for data buffers at any given time. By
271    default it is approximately TotalMem/4.
272
273
274 SCST /proc interface
275 --------------------
276
277 For communications with user space programs SCST provides proc-based
278 interface in /proc/scsi_tgt directory. This interface is available in
279 the procfs build only. Starting from version 2.0.0 it is obsolete and
280 will be removed in one of the next versions. It contains the following
281 entries.
282
283   - "help" file, which provides online help for SCST commands
284
285   - "scsi_tgt" file, which on read provides information of serving by SCST
286     devices and their dev handlers. On write it supports the following
287     command:
288
289       * "assign H:C:I:L HANDLER_NAME" assigns dev handler "HANDLER_NAME"
290         on device with host:channel:id:lun. The recommended way to find out
291         H:C:I:L numbers is use of lsscsi utility.
292
293   - "sessions" file, which lists currently connected initiators (open sessions)
294
295   - "sgv" file provides some statistic about with which block sizes
296     commands from remote initiators come and how effective sgv_pool in
297     serving those allocations from the cache, i.e. without memory
298     allocations requests to the kernel. "Size" - is the commands data
299     size upper rounded to power of 2, "Hit" - how many there are
300     allocations from the cache, "Total" - total number of allocations.
301
302   - "threads" file, which allows to read and set number of SCST's threads
303
304   - "version" file, which shows version of SCST
305
306   - "trace_level" file, which allows to read and set trace (logging) level
307     for SCST. See /proc/scsi_tgt/help file for list of commands and
308     trace levels. If you want to enable logging options, which produce a
309     lot of events, like "debug", to not loose logged events you should
310     also:
311
312      * Increase in .config of your kernel CONFIG_LOG_BUF_SHIFT variable
313        to much bigger value, then recompile it. For example, value 25
314        will provide good protection from logging overflow even under
315        high volume of logging events, but to use it you will need to
316        modify the maximum allowed value for CONFIG_LOG_BUF_SHIFT in the
317        corresponding Kconfig file.
318
319      * Change in your /etc/syslog.conf or other config file of your favorite
320        logging program to store kernel logs in async manner. For example,
321        I added in my rsyslog.conf line "kern.info -/var/log/kernel"
322        and added "kern.none" in line for /var/log/messages, so I had:
323        "*.info;kern.none;mail.none;authpriv.none;cron.none /var/log/messages"
324
325 Each dev handler has own subdirectory. Most dev handler have only two
326 files in this subdirectory: "trace_level" and "type". The first one is
327 similar to main SCST "trace_level" file, the latter one shows SCSI type
328 number of this handler as well as some text description.
329
330 For example, "echo "assign 1:0:1:0 dev_disk" >/proc/scsi_tgt/scsi_tgt"
331 will assign device handler "dev_disk" to real device sitting on host 1,
332 channel 0, ID 1, LUN 0.
333
334
335 Access and devices visibility management (LUN masking) - /proc interface
336 ------------------------------------------------------------------------
337
338 Access and devices visibility management allows for an initiator or
339 group of initiators to see different devices with different LUNs
340 with necessary access permissions.
341
342 SCST supports two modes of access control:
343
344 1. Target-oriented. In this mode you define for each target devices and
345 their LUNs, which are accessible to all initiators, connected to that
346 target. This is a regular access control mode, which people usually mean
347 thinking about access control in general. For instance, in IET this is
348 the only supported mode. In this mode you should create a security group
349 with name "Default_TARGET_NAME", where "TARGET_NAME" is name of the
350 target, like "Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz"
351 for target "iqn.2007-05.com.example:storage.disk1.sys1.xyz". Then you
352 should add to it all LUNs, available from that target.
353
354 2. Initiator-oriented. In this mode you define which devices and their
355 LUNs are accessible for each initiator. In this mode you should create
356 for each set of one or more initiators, which should access to the same
357 set of devices with the same LUNs, a separate security group, then add
358 to it available devices and names of allowed initiator(s).
359
360 Both modes can be used simultaneously. In this case initiator-oriented
361 mode has higher priority, than target-oriented.
362
363 When a target driver registers itself in SCST core, it tells SCST core
364 its name. Then, when there is a new connection from a remote initiator,
365 the target driver registers this connection in SCST core and tells it
366 the name of the remote initiator. Then SCST core finds the corresponding
367 devices for it using the following algorithm:
368
369 1. It searches through all defined groups trying to find group
370 containing the initiator name. If it succeeds, the found group is used.
371
372 2. Otherwise, it searches through all groups trying to find group with
373 name "Default_TARGET_NAME". If it succeeds, the found group is used.
374
375 3. Otherwise, the group with name "Default" is used. This group is
376 always defined, but empty by default.
377
378 Names of both target and initiator you can clarify in the kernel log. In
379 it SCST reports to which group each session is assigned.
380
381 In /proc/scsi_tgt each group represented as "groups/GROUP_NAME/"
382 subdirectory. In it there are files "devices" and "names". File
383 "devices" lists devices and their LUNs in the group, file "names" lists
384 names of initiators, which allowed to access devices in this group.
385
386 To configure access and devices visibility management SCST provides the
387 following files and directories under /proc/scsi_tgt:
388
389   - "add_group GROUP_NAME" to /proc/scsi_tgt/scsi_tgt adds group "GROUP_NAME"
390
391   - "del_group GROUP_NAME" to /proc/scsi_tgt/scsi_tgt deletes group "GROUP_NAME"
392
393   - "rename_group OLD_NAME NEW_NAME" to /proc/scsi_tgt/scsi_tgt renames
394     group "OLD_NAME" to "NEW_NAME".
395
396   - "add H:C:I:L lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP_NAME/devices adds
397     device with host:channel:id:lun with LUN "lun" in group "GROUP_NAME". Optionally,
398     the device could be marked as read only. The recommended way to find out
399     H:C:I:L numbers is use of lsscsi utility.
400
401   - "replace H:C:I:L lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP_NAME/devices
402     replaces by device with host:channel:id:lun existing with LUN "lun"
403     device in group "GROUP_NAME" with generation of INQUIRY DATA HAS
404     CHANGED Unit Attention. If the old device doesn't exist, this
405     command acts as the "add" command. Optionally, the device could be
406     marked as read only. The recommended way to find out H:C:I:L numbers
407     is use of lsscsi utility.
408
409   - "del H:C:I:L" to /proc/scsi_tgt/groups/GROUP_NAME/devices deletes device with
410     host:channel:id:lun from group "GROUP_NAME". The recommended way to find out
411     H:C:I:L numbers is use of lsscsi utility.
412
413   - "add V_NAME lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP_NAME/devices adds
414     device with virtual name "V_NAME" with LUN "lun" in group "GROUP_NAME".
415     Optionally, the device could be marked as read only.
416
417   - "replace V_NAME lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP_NAME/devices
418     replaces by device with virtual name "V_NAME" existing with LUN
419     "lun" device in group "GROUP_NAME" with generation of INQUIRY DATA
420     HAS CHANGED Unit Attention. If the old device doesn't exist, this
421     command acts as the "add" command. Optionally, the device could
422     be marked as read only.
423
424   - "del V_NAME" to /proc/scsi_tgt/groups/GROUP_NAME/devices deletes device with
425     virtual name "V_NAME" from group "GROUP_NAME"
426
427   - "clear" to /proc/scsi_tgt/groups/GROUP_NAME/devices clears the list of devices
428     for group "GROUP_NAME"
429
430   - "add NAME" to /proc/scsi_tgt/groups/GROUP_NAME/names adds name "NAME" to group
431     "GROUP_NAME". For NAME you can use simple DOS-type patterns, containing
432     '*' and '?' symbols. '*' means match all any symbols, '?' means
433     match only any single symbol. For instance, "blah.xxx" will match
434     "bl?h.*".
435
436   - "del NAME" to /proc/scsi_tgt/groups/GROUP_NAME/names deletes name "NAME" from group
437     "GROUP_NAME"
438
439   - "move NAME NEW_GROUP_NAME" to /proc/scsi_tgt/groups/OLD_GROUP_NAME/names
440     moves name "NAME" from group "OLD_GROUP_NAME" to group "NEW_GROUP_NAME".
441
442   - "clear" to /proc/scsi_tgt/groups/GROUP_NAME/names clears the list of names
443     for group "GROUP_NAME"
444
445 Examples:
446
447  - "echo "add 1:0:1:0 0" >/proc/scsi_tgt/groups/Default/devices" will
448  add real device sitting on host 1, channel 0, ID 1, LUN 0 to "Default"
449  group with LUN 0.
450
451  - "echo "add disk1 1" >/proc/scsi_tgt/groups/Default/devices" will
452  add virtual VDISK device with name "disk1" to "Default" group
453  with LUN 1.
454
455 - "echo "21:*:e0:?b:83:*'" >/proc/scsi_tgt/groups/LAB1/names" will
456  add a pattern, which matches WWNs of Fibre Channel ports from LAB1.
457
458 Consider you need to have an iSCSI target with name
459 "iqn.2007-05.com.example:storage.disk1.sys1.xyz" (you defined it in
460 iscsi-scst.conf), which should export virtual device "dev1" with LUN 0
461 and virtual device "dev2" with LUN 1, but initiator with name
462 "iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" should see only
463 virtual device "dev2" with LUN 0. To achieve that you should do the
464 following commands:
465
466 # echo "add_group Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz" >/proc/scsi_tgt/scsi_tgt
467 # echo "add dev1 0" >/proc/scsi_tgt/groups/Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz/devices
468 # echo "add dev2 1" >/proc/scsi_tgt/groups/Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz/devices
469
470 # echo "add_group spec_ini" >/proc/scsi_tgt/scsi_tgt
471 # echo "add iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" >/proc/scsi_tgt/groups/spec_ini/names
472 # echo "add dev2 0" >/proc/scsi_tgt/groups/spec_ini/devices
473
474 It is highly recommended to use scstadmin utility instead of described
475 in this section low level interface.
476
477 IMPORTANT
478 =========
479
480 There must be LUN 0 in each security group, i.e. LUs numeration must not
481 start from, e.g., 1. Otherwise you will see no devices on remote
482 initiators and SCST core will write into the kernel log message: "tgt_dev
483 for LUN 0 not found, command to unexisting LU?"
484
485 IMPORTANT
486 =========
487
488 All the access control must be fully configured BEFORE load of the
489 corresponding target driver! When you load a target driver or enable
490 target mode in it, as for qla2x00t driver, it will immediately start
491 accepting new connections, hence creating new sessions, and those new
492 sessions will be assigned to security groups according to the
493 *currently* configured access control settings. For instance, to
494 "Default" group, instead of "HOST004" as you may need, because "HOST004"
495 doesn't exist yet. So, one must configure all the security groups before
496 new connections from the initiators are created, i.e. before target
497 drivers loaded.
498
499 Access controls can be altered after the target driver loaded as long as
500 the target session doesn't yet exist. And even in the case of the
501 session already existing, changes are still possible, but won't be
502 reflected on the initiator side.
503
504 So, the safest choice is to configure all the access control before any
505 target driver load and then only add new devices to new groups for new
506 initiators or add new devices to old groups, but not altering existing
507 LUNs in them.
508
509
510 SCST sysfs interface
511 --------------------
512
513 Starting from 2.0.0 SCST has sysfs interface. You can switch to it by
514 running "make disable_proc". To switch back to the procfs interface you
515 should run "make enable_proc".
516
517 Root of SCST sysfs interface is /sys/kernel/scst_tgt. It has the
518 following entries:
519
520  - devices - this is a root subdirectory for all SCST devices
521
522  - handlers - this is a root subdirectory for all SCST dev handlers
523
524  - sgv - this is a root subdirectory for all SCST SGV caches
525
526  - targets - this is a root subdirectory for all SCST targets
527
528  - setup_id - allows to read and write SCST setup ID. This ID can be
529    used in cases, when the same SCST configuration should be installed
530    on several targets, but exported from those targets devices should
531    have different IDs and SNs. For instance, VDISK dev handler uses this
532    ID to generate T10 vendor specific identifier and SN of the devices.
533
534  - threads - allows to read and set number of global SCST I/O threads.
535    Those threads used with async. dev handlers, for instance, vdisk
536    BLOCKIO or NULLIO.
537
538  - trace_level - allows to enable and disable various tracing
539    facilities. See content of this file for help how to use it.
540
541  - version - read-only attribute, which allows to see version of
542    SCST and enabled optional features.
543
544 Each SCST sysfs file (attribute) can contain in the last line mark
545 "[key]". It is automatically added mark used to allow scstadmin to see
546 which attributes it should save in the config file. You can ignore it.
547
548 "Devices" subdirectory contains subdirectories for each SCST devices.
549
550 Content of each device's subdirectory is dev handler specific. See
551 documentation for your dev handlers for more info about it as well as
552 SysfsRules file for more info about common to all dev handlers rules.
553 Standard SCST dev handlers have at least the following common entries:
554
555  - exported - subdirectory containing links to all LUNs where this
556    device was exported.
557
558  - handler - if dev handler determined for this device, this link points
559    to it. The handler can be not set for pass-through devices.
560
561  - threads_num - shows and allows to set number of threads in this device's
562    threads pool. If 0 - no threads will be created, and global SCST
563    threads pool will be used. If <0 - creation of the threads pool is
564    prohibited.
565
566  - threads_pool_type - shows and allows to sets threads pool type.
567    Possible values: "per_initiator" and "shared". When the value is
568    "per_initiator" (default), each session from each initiator will use
569    separate dedicated pool of threads. When the value is "shared", all
570    sessions from all initiators will share the same per-device pool of
571    threads. Valid only if threads_num attribute >0.
572
573  - type - SCSI type of this device
574  
575 See below for more information about other entries of this subdirectory
576 of the standard SCST dev handlers.
577
578 "Handlers" subdirectory contains subdirectories for each SCST dev
579 handler.
580
581 Content of each handler's subdirectory is dev handler specific. See
582 documentation for your dev handlers for more info about it as well as
583 SysfsRules file for more info about common to all dev handlers rules.
584 Standard SCST dev handlers have at least the following common entries:
585
586  - mgmt - this entry allows to create virtual devices and their
587    attributes (for virtual devices dev handlers) or assign/unassign real
588    SCSI devices to/from this dev handler (for pass-through dev
589    handlers).
590
591  - pass_through - if exists, it contains 1 and this dev handler is a
592    pass-through dev handler.
593
594  - trace_level - allows to enable and disable various tracing
595    facilities. See content of this file for help how to use it.
596
597  - type - SCSI type of devices served by this dev handler.
598
599 See below for more information about other entries of this subdirectory
600 of the standard SCST dev handlers.
601
602 "Sgv" subdirectory contains statistic information of SCST SGV caches. It
603 has the following entries:
604
605  - None, one or more subdirectories for each existing SGV cache.
606  
607  - global_stats - file containing global SGV caches statistics.
608
609 Each SGV cache's subdirectory has the following item:
610
611  - stats - file containing statistics for this SGV caches.
612
613 "Targets" subdirectory contains subdirectories for each SCST target.
614
615 Content of each target's subdirectory is target specific. See
616 documentation for your target for more info about it as well as
617 SysfsRules file for more info about common to all targets rules.
618 Every target should have at least the following entries:
619
620  - ini_groups - subdirectory, which contains and allows to define
621    initiator-oriented access control information, see below.
622
623  - luns - subdirectory, which contains list of available LUNs in the
624    target-oriented access control and allows to define it, see below.
625
626  - sessions - subdirectory containing connected to this target sessions.
627
628  - enabled - using this attribute you can enable or disable this target/
629    It allows to finish configuring it before it starts accepting new
630    connections. 0 by default.
631
632  - addr_method - used LUNs addressing method. Possible values:
633    "Peripheral" and "Flat". Most initiators work well with Peripheral
634    addressing method (default), but some (HP-UX, for instance) may
635    require Flat method. This attribute is also available in the
636    initiators security groups, so you can assign the addressing method
637    on per-initiator basis.
638
639  - io_grouping_type - defines how I/O from sessions to this target are
640    grouped together. This I/O grouping is very important for
641    performance. By setting this attribute in a right value, you can
642    considerably increase performance of your setup. This grouping is
643    performed only if you use CFQ I/O scheduler on the target and for
644    devices with threads_num >= 0 and, if threads_num > 0, with
645    threads_pool_type "per_initiator". Possible values:
646    "this_group_only", "never", "auto", or I/O group number >0. When the
647    value is "this_group_only" all I/O from all sessions in this target
648    will be grouped together. When the value is "never", I/O from
649    different sessions will not be grouped together, i.e. all sessions in
650    this target will have separate dedicated I/O groups. When the value
651    is "auto" (default), all I/O from initiators with the same name
652    (iSCSI initiator name, for instance) in all targets will be grouped
653    together with a separate dedicated I/O group for each initiator name.
654    For iSCSI this mode works well, but other transports usually use
655    different initiator names for different sessions, so using such
656    transports in MPIO configurations you should either use value
657    "this_group_only", or an explicit I/O group number. This attribute is
658    also available in the initiators security groups, so you can assign
659    the I/O groupping on per-initiator basis. See below for more info how
660    to use this attribute.
661
662  - rel_tgt_id - allows to read or write SCSI Relative Target Port
663    Identifier attribute. This identifier is used to identify SCSI Target
664    Ports by some SCSI commands, mainly by Persistent Reservations
665    commands. This identifier must be unique among all SCST targets, but
666    for convenience SCST allows disabled targets to have not unique
667    rel_tgt_id. In this case SCST will not allow to enable this target
668    until rel_tgt_id becomes unique. This attribute initialized unique by
669    SCST by default.
670
671 A target driver may have also the following entries:
672
673  - "hw_target" - if the target driver supports both hardware and virtual
674     targets (for instance, an FC adapter supporting NPIV, which has
675     hardware targets for its physical ports as well as virtual NPIV
676     targets), this read only attribute for all hardware targets will
677     exist and contain value 1.
678
679 Subdirectory "sessions" contains one subdirectory for each connected
680 session with name equal to name of the connected initiator.
681
682 Each session subdirectory contains the following entries:
683
684  - initiator_name - contains initiator name
685
686  - force_close - optional write-only attribute, which allows to force
687    close this session.
688
689  - active_commands - contains number of active, i.e. not yet or being
690    executed, SCSI commands in this session.
691
692  - commands - contains overall number of SCSI commands in this session.
693
694  - other target driver specific attributes and subdirectories.
695
696 See below description of the VDISK's sysfs interface for samples.
697
698
699 Access and devices visibility management (LUN masking) - sysfs interface
700 ------------------------------------------------------------------------
701
702 Access and devices visibility management allows for an initiator or
703 group of initiators to see different devices with different LUNs
704 with necessary access permissions.
705
706 SCST supports two modes of access control:
707
708 1. Target-oriented. In this mode you define for each target a default
709 set of LUNs, which are accessible to all initiators, connected to that
710 target. This is a regular access control mode, which people usually mean
711 thinking about access control in general. For instance, in IET this is
712 the only supported mode.
713
714 2. Initiator-oriented. In this mode you define which LUNs are accessible
715 for each initiator. In this mode you should create for each set of one
716 or more initiators, which should access to the same set of devices with
717 the same LUNs, a separate security group, then add to it devices and
718 names of allowed initiator(s).
719
720 Both modes can be used simultaneously. In this case the
721 initiator-oriented mode has higher priority, than the target-oriented,
722 i.e. initiators are at first searched in all defined security groups for
723 this target and, if none matches, the default target's set of LUNs is
724 used. This set of LUNs might be empty, then the initiator will not see
725 any LUNs from the target.
726
727 You can at any time find out which set of LUNs each session is assigned
728 to by looking where link
729 /sys/kernel/scst_tgt/targets/target_driver/target_name/sessions/initiator_name/luns
730 points to.
731
732 To configure the target-oriented access control SCST provides the
733 following interface. Each target's sysfs subdirectory
734 (/sys/kernel/scst_tgt/targets/target_driver/target_name) has "luns"
735 subdirectory. This subdirectory contains the list of already defined
736 target-oriented access control LUNs for this target as well as file
737 "mgmt". This file has the following commands, which you can send to it,
738 for instance, using "echo" shell command. You can always get a small
739 help about supported commands by looking inside this file. "Parameters"
740 are one or more param_name=value pairs separated by ';'.
741
742  - "add H:C:I:L lun [parameters]" - adds a pass-through device with
743    host:channel:id:lun with LUN "lun". Optionally, the device could be
744    marked as read only by using parameter "read_only". The recommended
745    way to find out H:C:I:L numbers is use of lsscsi utility.
746
747  - "replace H:C:I:L lun [parameters]" - replaces by pass-through device
748    with host:channel:id:lun existing with LUN "lun" device with
749    generation of INQUIRY DATA HAS CHANGED Unit Attention. If the old
750    device doesn't exist, this command acts as the "add" command.
751    Optionally, the device could be marked as read only by using
752    parameter "read_only". The recommended way to find out H:C:I:L
753    numbers is use of lsscsi utility.
754
755  - "del H:C:I:L" - deletes a pass-through device with host:channel:id:lun
756    The recommended way to find out H:C:I:L numbers is use of lsscsi
757    utility.
758
759  - "add VNAME lun [parameters]" - adds a virtual device with name VNAME
760    with LUN "lun". Optionally, the device could be marked as read only
761    by using parameter "read_only".
762
763  - "replace VNAME lun [parameters]" - replaces by virtual device
764    with name VNAME existing with LUN "lun" device with generation of
765    INQUIRY DATA HAS CHANGED Unit Attention. If the old device doesn't
766    exist, this command acts as the "add" command. Optionally, the device
767    could be marked as read only by using parameter "read_only".
768
769  - "del VNAME" - deletes a virtual device with name VNAME.
770
771  - "clear" - clears the list of devices
772
773 To configure the initiator-oriented access control SCST provides the
774 following interface. Each target's sysfs subdirectory
775 (/sys/kernel/scst_tgt/targets/target_driver/target_name) has "ini_groups"
776 subdirectory. This subdirectory contains the list of already defined
777 security groups for this target as well as file "mgmt". This file has
778 the following commands, which you can send to it, for instance, using
779 "echo" shell command. You can always get a small help about supported
780 commands by looking inside this file.
781
782  - "create GROUP_NAME" - creates a new security group.
783
784  - "del GROUP_NAME" - deletes a new security group.
785
786 Each security group's subdirectory contains 2 subdirectories: initiators
787 and luns.
788
789 Each "initiators" subdirectory contains list of added to this groups
790 initiator as well as as well as file "mgmt". This file has the following
791 commands, which you can send to it, for instance, using "echo" shell
792 command. You can always get a small help about supported commands by
793 looking inside this file.
794
795  - "add INITIATOR_NAME" - adds initiator with name INITIATOR_NAME to the
796    group.
797
798  - "del INITIATOR_NAME" - deletes initiator with name INITIATOR_NAME
799    from the group.
800
801  - "move INITIATOR_NAME DEST_GROUP_NAME" moves initiator with name
802    INITIATOR_NAME from the current group to group with name
803    DEST_GROUP_NAME.
804
805  - "clear" - deletes all initiators from this group.
806                                   
807 For "add" and "del" commands INITIATOR_NAME can be a simple DOS-type
808 patterns, containing '*' and '?' symbols. '*' means match all any
809 symbols, '?' means match only any single symbol. For instance,
810 "blah.xxx" will match "bl?h.*".
811
812 Each "luns" subdirectory contains the list of already defined LUNs for
813 this group as well as file "mgmt". Content of this file as well as list
814 of available in it commands is fully identical to the "luns"
815 subdirectory of the target-oriented access control.
816
817 Examples:
818
819  - echo "create INI" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/mgmt -
820    creates security group INI for target iqn.2006-10.net.vlnb:tgt1.
821
822  - echo "add 2:0:1:0 11" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI/luns/mgmt -
823    adds a pass-through device sitting on host 2, channel 0, ID 1, LUN 0
824    to group with name INI as LUN 11.
825
826  - echo "add disk1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI/luns/mgmt -
827    adds a virtual disk with name disk1 to group with name INI as LUN 0.
828
829  - echo "add 21:*:e0:?b:83:*" >/sys/kernel/scst_tgt/targets/21:00:00:a0:8c:54:52:12/ini_groups/INI/initiators/mgmt -
830    adds a pattern to group with name INI to Fibre Channel target with
831    WWN 21:00:00:a0:8c:54:52:12, which matches WWNs of Fibre Channel
832    initiator ports.
833
834 Consider you need to have an iSCSI target with name
835 "iqn.2007-05.com.example:storage.disk1.sys1.xyz", which should export
836 virtual device "dev1" with LUN 0 and virtual device "dev2" with LUN 1,
837 but initiator with name
838 "iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" should see only
839 virtual device "dev2" read only with LUN 0. To achieve that you should
840 do the following commands:
841
842 # echo "iqn.2007-05.com.example:storage.disk1.sys1.xyz" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
843 # echo "add dev1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/luns/mgmt
844 # echo "add dev2 1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/luns/mgmt
845 # echo "create SPEC_INI" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/ini_groups/mgmt
846 # echo "add dev2 0 read_only=1" \
847         >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/ini_groups/SPEC_INI/luns/mgmt
848 # echo "iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" \
849         >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/ini_groups/SPEC_INI/initiators/mgmt
850
851 For Fibre Channel or SAS in the above example you should use target's
852 and initiator ports WWNs instead of iSCSI names.
853
854 It is highly recommended to use scstadmin utility instead of described
855 in this section low level interface.
856
857 IMPORTANT
858 =========
859
860 There must be LUN 0 in each set of LUNs, i.e. LUs numeration must not
861 start from, e.g., 1. Otherwise you will see no devices on remote
862 initiators and SCST core will write into the kernel log message: "tgt_dev
863 for LUN 0 not found, command to unexisting LU?"
864
865 IMPORTANT
866 =========
867
868 All the access control must be fully configured BEFORE the corresponding
869 target is enabled! When you enable a target, it will immediately start
870 accepting new connections, hence creating new sessions, and those new
871 sessions will be assigned to security groups according to the
872 *currently* configured access control settings. For instance, to
873 the default target's set of LUNs, instead of "HOST004" group as you may
874 need, because "HOST004" doesn't exist yet. So, one must configure all
875 the security groups before new connections from the initiators are
876 created, i.e. before the target enabled.
877
878
879 VDISK device handler
880 --------------------
881
882 /proc interface
883 ~~~~~~~~~~~~~~~
884
885 This interface starting from version 2.0.0 is obsolete and will be
886 removed in one of the next versions.
887
888 After loading VDISK device handler creates in /proc/scsi_tgt/
889 subdirectories "vdisk" and "vcdrom". They have the following layout:
890
891   - "trace_level" and "type" files as described above
892
893   - "help" file, which provides online help for VDISK commands
894
895   - "vdisk"/"vcdrom" files, which on read provides information of
896     currently open device files. On write it supports the following
897     command:
898
899     * "open NAME [PATH] [BLOCK_SIZE] [FLAGS]" - opens file "PATH" as
900       device "NAME" with block size "BLOCK_SIZE" bytes with flags
901       "FLAGS". "PATH" could be empty only for VDISK CDROM. "BLOCK_SIZE"
902       and "FLAGS" are valid only for disk VDISK. The block size must be
903       power of 2 and >= 512 bytes. Default is 512. Possible flags:
904
905       - WRITE_THROUGH - write back caching disabled. Note, this option
906         has sense only if you also *manually* disable write-back cache
907         in *all* your backstorage devices and make sure it's actually
908         disabled, since many devices are known to lie about this mode to
909         get better benchmark results.
910
911       - READ_ONLY - read only
912
913       - O_DIRECT - both read and write caching disabled. This mode
914         isn't currently fully implemented, you should use user space
915         fileio_tgt program in O_DIRECT mode instead (see below).
916
917       - NULLIO - in this mode no real IO will be done, but success will be
918         returned. Intended to be used for performance measurements at the same
919         way as "*_perf" handlers.
920
921       - NV_CACHE - enables "non-volatile cache" mode. In this mode it is
922         assumed that the target has a GOOD UPS with ability to cleanly
923         shutdown target in case of power failure and it is
924         software/hardware bugs free, i.e. all data from the target's
925         cache are guaranteed sooner or later to go to the media. Hence
926         all data synchronization with media operations, like
927         SYNCHRONIZE_CACHE, are ignored in order to bring more
928         performance. Also in this mode target reports to initiators that
929         the corresponding device has write-through cache to disable all
930         write-back cache workarounds used by initiators. Use with
931         extreme caution, since in this mode after a crash of the target
932         journaled file systems don't guarantee the consistency after
933         journal recovery, therefore manual fsck MUST be ran. Note, that
934         since usually the journal barrier protection (see "IMPORTANT"
935         note below) turned off, enabling NV_CACHE could change nothing
936         from data protection point of view, since no data
937         synchronization with media operations will go from the
938         initiator. This option overrides WRITE_THROUGH.
939
940       - BLOCKIO - enables block mode, which will perform direct block
941         IO with a block device, bypassing page-cache for all operations.
942         This mode works ideally with high-end storage HBAs and for
943         applications that either do not need caching between application
944         and disk or need the large block throughput. See also below.
945
946       - REMOVABLE - with this flag set the device is reported to remote
947         initiators as removable.
948
949     * "close NAME" - closes device "NAME".
950
951     * "resync_size NAME" - refreshes size of device "NAME". Intended to be
952       used after device resize.
953
954     * "change NAME [PATH]" - changes a virtual CD in the VDISK CDROM.
955
956     * "set_t10_dev_id NAME T10_DEVICE_ID" - sets T10 vendor specific
957       identifier on Device Identification VPD page (0x83) of device
958       "NAME" in INQUIRY data. By default VDISK handler always generates
959       T10_DEVICE_ID for every new created device at creation time.
960       This parameter allows to overwrite generated by VDISK value of
961       T10_DEVICE_ID.
962
963 By default, if neither BLOCKIO, nor NULLIO option is supplied, FILEIO
964 mode is used.
965
966 For example, "echo "open disk1 /vdisks/disk1" >/proc/scsi_tgt/vdisk/vdisk"
967 will open file /vdisks/disk1 as virtual FILEIO disk with name "disk1".
968
969
970 /sys interface
971 ~~~~~~~~~~~~~~
972
973 Starting from 2.0.0 VDISK device handler has sysfs interface. You can
974 switch to it by running "make disable_proc". To switch back to the
975 procfs interface you should run "make enable_proc". The procfs interface
976 starting from version 2.0.0 is obsolete and will be removed in one of
977 the next versions.
978
979 VDISK has 4 built-in dev handlers: vdisk_fileio, vdisk_blockio,
980 vdisk_nullio and vcdrom. Roots of their sysfs interface are
981 /sys/kernel/scst_tgt/handlers/handler_name, e.g. for vdisk_fileio:
982 /sys/kernel/scst_tgt/handlers/vdisk_fileio. Each root has the following
983 entries:
984
985  - None, one or more links to devices with name equal to names
986    of the corresponding devices.
987
988  - trace_level - allows to enable and disable various tracing
989    facilities. See content of this file for help how to use it.
990
991  - mgmt - main management entry, which allows to add/delete VDISK
992    devices with the corresponding type.
993
994 The "mgmt" file has the following commands, which you can send to it,
995 for instance, using "echo" shell command. You can always get a small
996 help about supported commands by looking inside this file. "Parameters"
997 are one or more param_name=value pairs separated by ';'.
998
999  - echo "add_device device_name [parameters]" - adds a virtual device
1000    with name device_name and specified parameters (see below)
1001
1002  - echo "del_device device_name" - deletes a virtual device with name
1003    device_name.
1004
1005 Handler vdisk_fileio provides FILEIO mode to create virtual devices.
1006 This mode uses as backend files and accesses to them using regular
1007 read()/write() file calls. This allows to use full power of Linux page
1008 cache. The following parameters possible for vdisk_fileio:
1009
1010  - filename - specifies path and file name of the backend file. The path
1011    must be absolute.
1012
1013  - blocksize - specifies block size used by this virtual device. The
1014    block size must be power of 2 and >= 512 bytes. Default is 512.
1015
1016  - write_through - disables write back caching. Note, this option
1017    has sense only if you also *manually* disable write-back cache in
1018    *all* your backstorage devices and make sure it's actually disabled,
1019    since many devices are known to lie about this mode to get better
1020    benchmark results. Default is 0.
1021
1022  - read_only - read only. Default is 0.
1023
1024  - o_direct - disables both read and write caching. This mode isn't
1025    currently fully implemented, you should use user space fileio_tgt
1026    program in O_DIRECT mode instead (see below).
1027
1028  - nv_cache - enables "non-volatile cache" mode. In this mode it is
1029    assumed that the target has a GOOD UPS with ability to cleanly
1030    shutdown target in case of power failure and it is software/hardware
1031    bugs free, i.e. all data from the target's cache are guaranteed
1032    sooner or later to go to the media. Hence all data synchronization
1033    with media operations, like SYNCHRONIZE_CACHE, are ignored in order
1034    to bring more performance. Also in this mode target reports to
1035    initiators that the corresponding device has write-through cache to
1036    disable all write-back cache workarounds used by initiators. Use with
1037    extreme caution, since in this mode after a crash of the target
1038    journaled file systems don't guarantee the consistency after journal
1039    recovery, therefore manual fsck MUST be ran. Note, that since usually
1040    the journal barrier protection (see "IMPORTANT" note below) turned
1041    off, enabling NV_CACHE could change nothing from data protection
1042    point of view, since no data synchronization with media operations
1043    will go from the initiator. This option overrides "write_through"
1044    option. Disabled by default.
1045
1046  - removable - with this flag set the device is reported to remote
1047    initiators as removable.
1048
1049 Handler vdisk_blockio provides BLOCKIO mode to create virtual devices.
1050 This mode performs direct block I/O with a block device, bypassing the
1051 page cache for all operations. This mode works ideally with high-end
1052 storage HBAs and for applications that either do not need caching
1053 between application and disk or need the large block throughput. See
1054 below for more info.
1055
1056 The following parameters possible for vdisk_blockio: filename,
1057 blocksize, read_only, removable. See vdisk_fileio above for description
1058 of those parameters.
1059
1060 Handler vdisk_nullio provides NULLIO mode to create virtual devices. In
1061 this mode no real I/O is done, but success returned to initiators.
1062 Intended to be used for performance measurements at the same way as
1063 "*_perf" handlers. The following parameters possible for vdisk_nullio:
1064 blocksize, read_only, removable. See vdisk_fileio above for description
1065 of those parameters.
1066
1067 Handler vcdrom allows emulation of a virtual CDROM device using an ISO
1068 file as backend. It doesn't have any parameters.
1069
1070 For example:
1071
1072 echo "add_device disk1 filename=/disk1; blocksize=4096; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
1073
1074 will create a FILEIO virtual device disk1 with backend file /disk1   
1075 with block size 4K and NV_CACHE enabled.
1076
1077 Each vdisk_fileio's device has the following attributes in
1078 /sys/kernel/scst_tgt/devices/device_name:
1079
1080  - filename - contains path and file name of the backend file.
1081
1082  - blocksize - contains block size used by this virtual device.
1083
1084  - write_through - contains status of write back caching of this virtual
1085    device.
1086
1087  - read_only - contains read only status of this virtual device.
1088
1089  - o_direct - contains O_DIRECT status of this virtual device.
1090
1091  - nv_cache - contains NV_CACHE status of this virtual device.
1092
1093  - removable - contains removable status of this virtual device.
1094
1095  - size_mb - contains size of this virtual device in MB.
1096
1097  - t10_dev_id - contains and allows to set T10 vendor specific
1098    identifier for Device Identification VPD page (0x83) of INQUIRY data.
1099    By default VDISK handler always generates t10_dev_id for every new
1100    created device at creation time based on the device name and
1101    scst_vdisk_ID scst_vdisk.ko module parameter (see below).
1102
1103  - usn - contains the virtual device's serial number of INQUIRY data. It
1104    is created at the device creation time based on the device name and
1105    scst_vdisk_ID scst_vdisk.ko module parameter (see below).
1106
1107  - type - contains SCSI type of this virtual device.
1108
1109  - resync_size - write only attribute, which makes vdisk_fileio to
1110    rescan size of the backend file. It is useful if you changed it, for
1111    instance, if you resized it.
1112
1113 For example:
1114
1115 /sys/kernel/scst_tgt/devices/disk1
1116 |-- blocksize
1117 |-- exported
1118 |   |-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/0
1119 |   |-- export1 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/INI/luns/0
1120 |   |-- export2 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/0
1121 |   |-- export3 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI1/luns/0
1122 |   |-- export4 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI2/luns/0
1123 |-- filename
1124 |-- handler -> ../../handlers/vdisk_fileio
1125 |-- nv_cache
1126 |-- o_direct
1127 |-- read_only
1128 |-- removable
1129 |-- resync_size
1130 |-- size_mb
1131 |-- t10_dev_id
1132 |-- threads_num
1133 |-- threads_pool_type
1134 |-- type
1135 |-- usn
1136 `-- write_through
1137
1138 Each vdisk_blockio's device has the following attributes in
1139 /sys/kernel/scst_tgt/devices/device_name: blocksize, filename,
1140 read_only, removable, resync_size, size_mb, t10_dev_id, threads_num,
1141 threads_pool_type, type, usn. See above description of those parameters.
1142
1143 Each vdisk_nullio's device has the following attributes in
1144 /sys/kernel/scst_tgt/devices/device_name: blocksize, read_only,
1145 removable, size_mb, t10_dev_id, threads_num, threads_pool_type, type,
1146 usn. See above description of those parameters.
1147
1148 Each vcdrom's device has the following attributes in
1149 /sys/kernel/scst_tgt/devices/device_name: filename,  size_mb,
1150 t10_dev_id, threads_num, threads_pool_type, type, usn. See above
1151 description of those parameters. Exception is filename attribute. For
1152 vcdrom it is writable. Writing to it allows to virtually insert or
1153 change virtual CD media in the virtual CDROM device. For example:
1154
1155  - echo "/image.iso" >/sys/kernel/scst_tgt/devices/cdrom/filename - will
1156    insert file /image.iso as virtual media to the virtual CDROM cdrom.
1157
1158  - echo "" >/sys/kernel/scst_tgt/devices/cdrom/filename - will remove
1159    "media" from the virtual CDROM cdrom.
1160
1161 Additionally to the sysfs/procfs interface VDISK handler has module
1162 parameter "num_threads", which specifies count of I/O threads for each
1163 VDISK's device. If you have a workload, which tends to produce rather
1164 random accesses (e.g. DB-like), you should increase this count to a
1165 bigger value, like 32. If you have a rather sequential workload, you
1166 should decrease it to a lower value, like number of CPUs on the target
1167 or even 1. Due to some limitations of Linux I/O subsystem, increasing
1168 number of I/O threads too much leads to sequential performance drop,
1169 especially with deadline scheduler, so decreasing it can improve
1170 sequential performance. The default provides a good compromise between
1171 random and sequential accesses.
1172
1173 You shouldn't be afraid to have too many VDISK I/O threads if you have
1174 many VDISK devices. Kernel threads consume very little amount of
1175 resources (several KBs) and only necessary threads will be used by SCST,
1176 so the threads will not trash your system.
1177
1178 CAUTION: If you partitioned/formatted your device with block size X, *NEVER*
1179 ======== ever try to export and then mount it (even accidentally) with another
1180          block size. Otherwise you can *instantly* damage it pretty
1181          badly as well as all your data on it. Messages on initiator
1182          like: "attempt to access beyond end of device" is the sign of
1183          such damage.
1184
1185          Moreover, if you want to compare how well different block sizes
1186          work for you, you **MUST** EVERY TIME AFTER CHANGING BLOCK SIZE
1187          **COMPLETELY** **WIPE OFF** ALL THE DATA FROM THE DEVICE. In
1188          other words, THE **WHOLE** DEVICE **MUST** HAVE ONLY **ZEROS**
1189          AS THE DATA AFTER YOU SWITCH TO NEW BLOCK SIZE. Switching block
1190          sizes isn't like switching between FILEIO and BLOCKIO, after
1191          changing block size all previously written with another block
1192          size data MUST BE ERASED. Otherwise you will have a full set of
1193          very weird behaviors, because blocks addressing will be
1194          changed, but initiators in most cases will not have a
1195          possibility to detect that old addresses written on the device
1196          in, e.g., partition table, don't refer anymore to what they are
1197          intended to refer.
1198
1199 IMPORTANT: Some disk and partition table management utilities don't support
1200 =========  block sizes >512 bytes, therefore make sure that your favorite one
1201            supports it. Currently only cfdisk is known to work only with
1202            512 bytes blocks, other utilities like fdisk on Linux or
1203            standard disk manager on Windows are proved to work well with
1204            non-512 bytes blocks. Note, if you export a disk file or
1205            device with some block size, different from one, with which
1206            it was already partitioned, you could get various weird
1207            things like utilities hang up or other unexpected behavior.
1208            Hence, to be sure, zero the exported file or device before
1209            the first access to it from the remote initiator with another
1210            block size. On Window initiator make sure you "Set Signature"
1211            in the disk manager on the imported from the target drive
1212            before doing any other partitioning on it. After you
1213            successfully mounted a file system over non-512 bytes block
1214            size device, the block size stops matter, any program will
1215            work with files on such file system.
1216
1217
1218 Caching
1219 -------
1220
1221 By default for performance reasons VDISK FILEIO devices use write back
1222 caching policy. This is generally safe for modern applications who
1223 prepared to work in the write back caching environments, so know when to
1224 flush cache to keep their data consistent and minimize damage caused in
1225 case of power/hardware/software failures by lost in the cache data.
1226
1227 For instance, journaled file systems flush cache on each meta data
1228 update, so they survive power/hardware/software failures pretty well.
1229 Note, Linux IO subsystem guarantees it work reliably only using data
1230 protection barriers, which, for instance, for Ext3 turned off by default
1231 (see http://lwn.net/Articles/283161). Some info about barriers from the
1232 XFS point of view could be found at
1233 http://oss.sgi.com/projects/xfs/faq.html#wcache. On Linux initiators for
1234 Ext3 and ReiserFS file systems the barrier protection could be turned on
1235 using "barrier=1" and "barrier=flush" mount options correspondingly. You
1236 can check if the barriers turn on or off by looking in /proc/mounts.
1237 Windows and, AFAIK, other UNIX'es don't need any special explicit
1238 options and do necessary barrier actions on write-back caching devices
1239 by default. 
1240
1241 But even in case of journaled file systems your unsaved cached data will
1242 still be lost in case of power/hardware/software failures, so you may
1243 need to supply your target server with a good UPS with possibility to
1244 gracefully shutdown your target on power shortage or disable write back
1245 caching using WRITE_THROUGH flag. Note, on some real-life workloads
1246 write through caching might perform better, than write back one with the
1247 barrier protection turned on. Also note that without barriers enabled
1248 (i.e. by default) Linux doesn't provide a guarantee that after
1249 sync()/fsync() all written data really hit permanent storage. They can
1250 be stored in the cache of your backstorage devices and, hence, lost on a
1251 power failure event. Thus, ever with write-through cache mode, you still
1252 either need to enable barriers on your backend file system on the target
1253 (for devices this is, indeed, impossible), or need a good UPS to protect
1254 yourself from not committed data loss.
1255
1256 To limit this data loss you can use files in /proc/sys/vm to limit
1257 amount of unflushed data in the system cache.
1258
1259
1260 BLOCKIO VDISK mode
1261 ------------------
1262
1263 This module works best for these types of scenarios:
1264
1265 1) Data that are not aligned to 4K sector boundaries and <4K block sizes
1266 are used, which is normally found in virtualization environments where
1267 operating systems start partitions on odd sectors (Windows and it's
1268 sector 63).
1269
1270 2) Large block data transfers normally found in database loads/dumps and
1271 streaming media.
1272
1273 3) Advanced relational database systems that perform their own caching
1274 which prefer or demand direct IO access and, because of the nature of
1275 their data access, can actually see worse performance with
1276 non-discriminate caching.
1277
1278 4) Multiple layers of targets were the secondary and above layers need
1279 to have a consistent view of the primary targets in order to preserve
1280 data integrity which a page cache backed IO type might not provide
1281 reliably.
1282
1283 Also it has an advantage over FILEIO that it doesn't copy data between
1284 the system cache and the commands data buffers, so it saves a
1285 considerable amount of CPU power and memory bandwidth.
1286
1287 IMPORTANT: Since data in BLOCKIO and FILEIO modes are not consistent between
1288 =========  them, if you try to use a device in both those modes simultaneously,
1289            you will almost instantly corrupt your data on that device.
1290
1291
1292 Pass-through mode
1293 -----------------
1294
1295 In the pass-through mode (i.e. using the pass-through device handlers
1296 scst_disk, scst_tape, etc) SCSI commands, coming from remote initiators,
1297 are passed to local SCSI devices on target as is, without any
1298 modifications. 
1299
1300 In the SYSFS interface all real SCSI devices are listed in
1301 /sys/kernel/scst_tgt/devices in form host:channel:id:lun numbers, for
1302 instance 1:0:0:0. The recommended way to match those numbers to your
1303 devices is use of lsscsi utility.
1304
1305 When a pass-through dev handler is loaded it assigns itself to all
1306 existing SCSI devices of its SCSI type. If you later want to unassign some
1307 SCSI device from it or assign it to another dev handler you can use the
1308 following interface.
1309
1310 Each pass-through dev handler has in its root subdirectory
1311 /sys/kernel/scst_tgt/handlers/handler_name, e.g.
1312 /sys/kernel/scst_tgt/handlers/dev_disk, "mgmt" file. It allows the
1313 following commands. They can be sent to it using, e.g., echo command.
1314
1315  - "assign" - this command assigns SCSI device with
1316 host:channel:id:lun numbers to this dev handler.
1317
1318 echo "assign 1:0:0:0" >mgmt
1319
1320 will assign SCSI device 1:0:0:0 to this dev handler.
1321
1322  - "unassign" - this command unassigns SCSI device with
1323 host:channel:id:lun numbers from this dev handler.
1324
1325 As usually, on read the "mgmt" file returns small help about available
1326 commands.
1327
1328 As any other hardware, the local SCSI hardware can not handle commands
1329 with amount of data and/or segments count in scatter-gather array bigger
1330 some values. Therefore, when using the pass-through mode you should note
1331 that values for maximum number of segments and maximum amount of
1332 transferred data for each SCSI command on devices on initiators can not
1333 be bigger, than corresponding values of the corresponding SCSI devices
1334 on the target. Otherwise you will see symptoms like small transfers work
1335 well, but large ones stall and messages like: "Unable to complete
1336 command due to SG IO count limitation" are printed in the kernel logs.
1337  
1338 You can't control from the user space limit of the scatter-gather
1339 segments, but for block devices usually it is sufficient if you set on
1340 the initiators /sys/block/DEVICE_NAME/queue/max_sectors_kb in the same
1341 or lower value as in /sys/block/DEVICE_NAME/queue/max_hw_sectors_kb for
1342 the corresponding devices on the target.
1343
1344 For not-block devices SCSI commands are usually generated directly by
1345 applications, so, if you experience large transfers stalls, you should
1346 check documentation for your application how to limit the transfer
1347 sizes.
1348
1349 Another way to solve this issue is to build SG entries with more than 1
1350 page each. See the following patch as an example:
1351 http://scst.sourceforge.net/sgv_big_order_alloc.diff
1352
1353
1354 User space mode using scst_user dev handler
1355 -------------------------------------------
1356
1357 User space program fileio_tgt uses interface of scst_user dev handler
1358 and allows to see how it works in various modes. Fileio_tgt provides
1359 mostly the same functionality as scst_vdisk handler with the most
1360 noticeable difference that it supports O_DIRECT mode. O_DIRECT mode is
1361 basically the same as BLOCKIO, but also supports files, so for some
1362 loads it could be significantly faster, than the regular FILEIO access.
1363 All the words about BLOCKIO from above apply to O_DIRECT as well. See
1364 fileio_tgt's README file for more details.
1365
1366
1367 Performance
1368 -----------
1369
1370 SCST from the very beginning has been designed and implemented to
1371 provide the best possible performance. Since there is no "one fit all"
1372 the best performance configuration for different setups and loads, SCST
1373 provides extensive set of settings to allow to tune it for the best
1374 performance in each particular case. You don't have to necessary use
1375 those settings. If you don't, SCST will do very good job to autotune for
1376 you, so the resulting performance will, in average, be better
1377 (sometimes, much better) than with other SCSI targets. But in some cases
1378 you can by manual tuning improve it even more.
1379
1380 Before doing any performance measurements note that performance results
1381 are very much dependent from your type of load, so it is crucial that
1382 you choose access mode (FILEIO, BLOCKIO, O_DIRECT, pass-through), which
1383 suits your needs the best.
1384
1385 In order to get the maximum performance you should:
1386
1387 1. For SCST:
1388
1389  - Disable in Makefile CONFIG_SCST_STRICT_SERIALIZING, CONFIG_SCST_EXTRACHECKS,
1390    CONFIG_SCST_TRACING, CONFIG_SCST_DEBUG*, CONFIG_SCST_STRICT_SECURITY
1391
1392  - For pass-through devices enable
1393    CONFIG_SCST_ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ.
1394
1395 2. For target drivers:
1396
1397  - Disable in Makefiles CONFIG_SCST_EXTRACHECKS, CONFIG_SCST_TRACING,
1398    CONFIG_SCST_DEBUG*
1399
1400 3. For device handlers, including VDISK:
1401
1402  - Disable in Makefile CONFIG_SCST_TRACING and CONFIG_SCST_DEBUG.
1403
1404
1405 IMPORTANT: Some of the above compilation options in the SCST SVN enabled
1406 =========  by default, i.e. the development version of SCST is optimized
1407            for development and bug hunting, not for performance. For it
1408            you can set the above options, except
1409            CONFIG_SCST_ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ, in the
1410            needed values by command "make debug2perf" performed in
1411            trunk/.
1412
1413 4. Make sure you have io_grouping_type option set correctly, especially
1414 in the following cases:
1415
1416  - Several initiators share your target's backstorage. It can be a
1417    shared LU using some cluster FS, like VMFS, as well as can be
1418    different LUs located on the same backstorage (RAID array). For
1419    instance, if you have 3 initiators and each of them using its own
1420    dedicated FILEIO device file from the same RAID-6 array on the
1421    target.
1422
1423    In this case for the best performance you should have
1424    io_grouping_type option set in value "never" in all the LUNs' targets
1425    and security groups.
1426
1427  - Your initiator connected to your target in MPIO mode. In this case for
1428    the best performance you should:
1429
1430     * Either connect all the sessions from the initiator to a single
1431       target or security group and have io_grouping_type option set in
1432       value "this_group_only" in the target or security group,
1433
1434     * Or, if it isn't possible to connect all the sessions from the
1435       initiator to a single target or security group, assign the same
1436       numeric io_grouping_type value for each target/security group this
1437       initiator connected to. The exact value itself doesn't matter,
1438       important only that all the targets/security groups use the same
1439       value.
1440
1441 Don't forget, io_grouping_type makes sense only if you use CFQ I/O
1442 scheduler on the target and for devices with threads_num >= 0 and, if
1443 threads_num > 0, with threads_pool_type "per_initiator".
1444
1445 You can check if in your setup io_grouping_type set correctly as well as
1446 if the "auto" io_grouping_type value works for you by tests like the
1447 following:
1448
1449  - For not MPIO case you can run single thread sequential reading, e.g.
1450    using buffered dd, from one initiator, then run the same single
1451    thread sequential reading from the second initiator in parallel. If
1452    io_grouping_type is set correctly the aggregate throughput measured
1453    on the target should only slightly decrease as well as all initiators
1454    should have nearly equal share of it. If io_grouping_type is not set
1455    correctly, the aggregate throughput and/or throughput on any
1456    initiator will decrease significantly, in 2 times or even more. For
1457    instance, you have 80MB/s single thread sequential reading from the
1458    target on any initiator. When then both initiators are reading in
1459    parallel you should see on the target aggregate throughput something
1460    like 70-75MB/s with correct io_grouping_type and something like
1461    35-40MB/s or 8-10MB/s on any initiator with incorrect.
1462
1463  - For the MPIO case it's quite easier. With incorrect io_grouping_type
1464    you simply won't see performance increase from adding the second
1465    session (assuming your hardware is capable to transfer data through
1466    both sessions in parallel), or can even see a performance decrease.
1467
1468 5. If you are going to use your target in an VM environment, for
1469 instance as a shared storage with VMware, make sure all your VMs
1470 connected to the target via *separate* sessions. For instance, for iSCSI
1471 it means that each VM has own connection to the target, not all VMs
1472 connected using a single connection. You can check it using SCST proc or
1473 sysfs interface. For other transports you should use available
1474 facilities, like NPIV for Fibre Channel, to make separate sessions for
1475 each VM. If you miss it, you can greatly loose performance of parallel
1476 access to your target from different VMs.
1477
1478 6. For other target and initiator software parts:
1479
1480  - Make sure you applied on your kernel all available SCST patches.
1481    If for your kernel version this patch doesn't exist, it is strongly
1482    recommended to upgrade your kernel to version, for which this patch
1483    exists.
1484
1485  - Don't enable debug/hacking features in the kernel, i.e. use them as
1486    they are by default.
1487
1488  - The default kernel read-ahead and queuing settings are optimized
1489    for locally attached disks, therefore they are not optimal if they
1490    attached remotely (SCSI target case), which sometimes could lead to
1491    unexpectedly low throughput. You should increase read-ahead size to at
1492    least 512KB or even more on all initiators and the target.
1493
1494    You should also limit on all initiators maximum amount of sectors per
1495    SCSI command. This tuning is also recommended on targets with large
1496    read-ahead values. To do it on Linux, run:
1497
1498    echo “64” > /sys/block/sdX/queue/max_sectors_kb
1499
1500    where specify instead of X your imported from target device letter,
1501    like 'b', i.e. sdb.
1502
1503    To increase read-ahead size on Linux, run:
1504
1505    blockdev --setra N /dev/sdX
1506
1507    where N is a read-ahead number in 512-byte sectors and X is a device
1508    letter like above.
1509
1510    Note: you need to set read-ahead setting for device sdX again after
1511    you changed the maximum amount of sectors per SCSI command for that
1512    device.
1513
1514    Note2: you need to restart SCST after you changed read-ahead settings
1515    on the target.
1516
1517  - You may need to increase amount of requests that OS on initiator
1518    sends to the target device. To do it on Linux initiators, run
1519
1520    echo “64” > /sys/block/sdX/queue/nr_requests
1521
1522    where X is a device letter like above.
1523
1524    You may also experiment with other parameters in /sys/block/sdX
1525    directory, they also affect performance. If you find the best values,
1526    please share them with us.
1527
1528  - On the target use CFQ IO scheduler. In most cases it has performance
1529    advantage over other IO schedulers, sometimes huge (2+ times
1530    aggregate throughput increase).
1531
1532  - It is recommended to turn the kernel preemption off, i.e. set
1533    the kernel preemption model to "No Forced Preemption (Server)".
1534
1535  - Looks like XFS is the best filesystem on the target to store device
1536    files, because it allows considerably better linear write throughput,
1537    than ext3.
1538
1539 7. For hardware on target.
1540
1541  - Make sure that your target hardware (e.g. target FC or network card)
1542    and underlaying IO hardware (e.g. IO card, like SATA, SCSI or RAID to
1543    which your disks connected) don't share the same PCI bus. You can
1544    check it using lspci utility. They have to work in parallel, so it
1545    will be better if they don't compete for the bus. The problem is not
1546    only in the bandwidth, which they have to share, but also in the
1547    interaction between cards during that competition. This is very
1548    important, because in some cases if target and backend storage
1549    controllers share the same PCI bus, it could lead up to 5-10 times
1550    less performance, than expected. Moreover, some motherboard (by
1551    Supermicro, particularly) have serious stability issues if there are
1552    several high speed devices on the same bus working in parallel. If
1553    you have no choice, but PCI bus sharing, set in the BIOS PCI latency
1554    as low as possible.
1555
1556 8. If you use VDISK IO module in FILEIO mode, NV_CACHE option will
1557 provide you the best performance. But using it make sure you use a good
1558 UPS with ability to shutdown the target on the power failure.
1559
1560 Baseline performance numbers you can find in those measurements:
1561 http://lkml.org/lkml/2009/3/30/283.
1562
1563 IMPORTANT: If you use on initiator some versions of Windows (at least W2K)
1564 =========  you can't get good write performance for VDISK FILEIO devices with
1565            default 512 bytes block sizes. You could get about 10% of the
1566            expected one. This is because of the partition alignment, which
1567            is (simplifying) incompatible with how Linux page cache
1568            works, so for each write the corresponding block must be read
1569            first. Use 4096 bytes block sizes for VDISK devices and you
1570            will have the expected write performance. Actually, any OS on
1571            initiators, not only Windows, will benefit from block size
1572            max(PAGE_SIZE, BLOCK_SIZE_ON_UNDERLYING_FS), where PAGE_SIZE
1573            is the page size, BLOCK_SIZE_ON_UNDERLYING_FS is block size
1574            on the underlying FS, on which the device file located, or 0,
1575            if a device node is used. Both values are from the target.
1576            See also important notes about setting block sizes >512 bytes
1577            for VDISK FILEIO devices above.
1578
1579 9. In some cases, for instance working with SSD devices, which consume 100%
1580 of a single CPU load for data transfers in their internal threads, to
1581 maximize IOPS it can be needed to assign for those threads dedicated
1582 CPUs using Linux CPU affinity facilities. No IRQ processing should be
1583 done on those CPUs. Check that using /proc/interrupts. See taskset
1584 command and Documentation/IRQ-affinity.txt in your kernel's source tree
1585 for how to assign IRQ affinity to tasks and IRQs.
1586
1587 The reason for that is that processing of coming commands in SIRQ
1588 context might be done on the same CPUs as SSD devices' threads doing data
1589 transfers. As the result, those threads won't receive all the processing
1590 power of those CPUs and perform worse.
1591
1592
1593 Work if target's backstorage or link is too slow
1594 ------------------------------------------------
1595
1596 Under high I/O load, when your target's backstorage gets overloaded, or
1597 working over a slow link between initiator and target, when the link
1598 can't serve all the queued commands on time, you can experience I/O
1599 stalls or see in the kernel log abort or reset messages.
1600
1601 At first, consider the case of too slow target's backstorage. On some
1602 seek intensive workloads even fast disks or RAIDs, which able to serve
1603 continuous data stream on 500+ MB/s speed, can be as slow as 0.3 MB/s.
1604 Another possible cause for that can be MD/LVM/RAID on your target as in
1605 http://lkml.org/lkml/2008/2/27/96 (check the whole thread as well).
1606
1607 Thus, in such situations simply processing of one or more commands takes
1608 too long time, hence initiator decides that they are stuck on the target
1609 and tries to recover. Particularly, it is known that the default amount
1610 of simultaneously queued commands (48) is sometimes too high if you do
1611 intensive writes from VMware on a target disk, which uses LVM in the
1612 snapshot mode. In this case value like 16 or even 8-10 depending of your
1613 backstorage speed could be more appropriate.
1614
1615 Unfortunately, currently SCST lacks dynamic I/O flow control, when the
1616 queue depth on the target is dynamically decreased/increased based on
1617 how slow/fast the backstorage speed comparing to the target link. So,
1618 there are 6 possible actions, which you can do to workaround or fix this
1619 issue in this case:
1620
1621 1. Ignore incoming task management (TM) commands. It's fine if there are
1622 not too many of them, so average performance isn't hurt and the
1623 corresponding device isn't getting put offline, i.e. if the backstorage
1624 isn't too slow.
1625
1626 2. Decrease /sys/block/sdX/device/queue_depth on the initiator in case
1627 if it's Linux (see below how) or/and SCST_MAX_TGT_DEV_COMMANDS constant
1628 in scst_priv.h file until you stop seeing incoming TM commands.
1629 ISCSI-SCST driver also has its own iSCSI specific parameter for that,
1630 see its README file.
1631
1632 To decrease device queue depth on Linux initiators you can run command:
1633
1634 # echo Y >/sys/block/sdX/device/queue_depth
1635
1636 where Y is the new number of simultaneously queued commands, X - your
1637 imported device letter, like 'a' for sda device. There are no special
1638 limitations for Y value, it can be any value from 1 to possible maximum
1639 (usually, 32), so start from dividing the current value on 2, i.e. set
1640 16, if /sys/block/sdX/device/queue_depth contains 32.
1641
1642 3. Increase the corresponding timeout on the initiator. For Linux it is
1643 located in
1644 /sys/devices/platform/host*/session*/target*:0:0/*:0:0:1/timeout. It can
1645 be done automatically by an udev rule. For instance, the following
1646 rule will increase it to 300 seconds:
1647
1648 SUBSYSTEM=="scsi", KERNEL=="[0-9]*:[0-9]*", ACTION=="add", ATTR{type}=="0|7|14", ATTR{timeout}="300"
1649
1650 By default, this timeout is 30 or 60 seconds, depending on your distribution.
1651
1652 4. Try to avoid such seek intensive workloads.
1653
1654 5. Increase speed of the target's backstorage.
1655
1656 6. Implement in SCST dynamic I/O flow control. This will be an ultimate
1657 solution. See "Dynamic I/O flow control" section on
1658 http://scst.sourceforge.net/contributing.html page for possible
1659 implementation idea.
1660
1661 Next, consider the case of too slow link between initiator and target,
1662 when the initiator tries to simultaneously push N commands to the target
1663 over it. In this case time to serve those commands, i.e. send or receive
1664 data for them over the link, can be more, than timeout for any single
1665 command, hence one or more commands in the tail of the queue can not be
1666 served on time less than the timeout, so the initiator will decide that
1667 they are stuck on the target and will try to recover.
1668
1669 To workaround/fix this issue in this case you can use ways 1, 2, 3, 6
1670 above or (7): increase speed of the link between target and initiator.
1671 But for some initiators implementations for WRITE commands there might
1672 be cases when target has no way to detect the issue, so dynamic I/O flow
1673 control will not be able to help. In those cases you could also need on
1674 the initiator(s) to either decrease the queue depth (way 2), or increase
1675 the corresponding timeout (way 3).
1676
1677 Note, that logged messages about QUEUE_FULL status are quite different
1678 by nature. This is a normal work, just SCSI flow control in action.
1679 Simply don't enable "mgmt_minor" logging level, or, alternatively, if
1680 you are confident in the worst case performance of your back-end storage
1681 or initiator-target link, you can increase SCST_MAX_TGT_DEV_COMMANDS in
1682 scst_priv.h to 64. Usually initiators don't try to push more commands on
1683 the target.
1684
1685
1686 Credits
1687 -------
1688
1689 Thanks to:
1690
1691  * Mark Buechler <mark.buechler@gmail.com> for a lot of useful
1692    suggestions, bug reports and help in debugging.
1693
1694  * Ming Zhang <mingz@ele.uri.edu> for fixes and comments.
1695
1696  * Nathaniel Clark <nate@misrule.us> for fixes and comments.
1697
1698  * Calvin Morrow <calvin.morrow@comcast.net> for testing and useful
1699    suggestions.
1700
1701  * Hu Gang <hugang@soulinfo.com> for the original version of the
1702    LSI target driver.
1703
1704  * Erik Habbinga <erikhabbinga@inphase-tech.com> for fixes and support
1705    of the LSI target driver.
1706
1707  * Ross S. W. Walker <rswwalker@hotmail.com> for the original block IO
1708    code and Vu Pham <huongvp@yahoo.com> who updated it for the VDISK dev
1709    handler.
1710
1711  * Michael G. Byrnes <michael.byrnes@hp.com> for fixes.
1712
1713  * Alessandro Premoli <a.premoli@andxor.it> for fixes
1714
1715  * Nathan Bullock <nbullock@yottayotta.com> for fixes.
1716
1717  * Terry Greeniaus <tgreeniaus@yottayotta.com> for fixes.
1718
1719  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes and bug reports.
1720
1721  * Jianxi Chen <pacers@users.sourceforge.net> for fixing problem with
1722    devices >2TB in size
1723
1724  * Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
1725
1726  * Daniel Debonzi <debonzi@linux.vnet.ibm.com> for a big part of SCST sysfs tree
1727    implementation
1728
1729
1730 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net