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