fe203f5ff9cce01fa375c384e84c7df011f9691f
[mirror/scst/.git] / scst / README
1 Generic SCSI target mid-level for Linux (SCST)
2 ==============================================
3
4 Version 1.0.1, X XXXX 2008
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 Installation
44 ------------
45
46 Only vanilla kernels from kernel.org are supported, but it should work
47 on vendors' kernels, if you manage to successfully compile on them. The
48 main problem with vendor's kernels is that they often contain patches,
49 which will appear only in the next version of the vanilla kernel,
50 therefore it's quite hard to track such changes. Thus, if during
51 compilation for some vendor kernel your compiler complains about
52 redefinition of some symbol, you should either switch to vanilla kernel,
53 or change as necessary the corresponding to that symbol "#if
54 LINUX_VERSION_CODE" statement.
55
56 At first, make sure that the link "/lib/modules/`you_kernel_version`/build" 
57 points to the source code for your currently running kernel.
58
59 Then, since in the mainstream kernels scsi_do_req()/scsi_execute_async()
60 work in LIFO order, instead of expected and required FIFO, SCST needs a
61 new functions scsi_do_req_fifo()/scsi_execute_async_fifo() to be added
62 in the kernel. Patch scst_exec_req_fifo.patch from "kernel" directory
63 does that. If it doesn't apply to your kernel, apply it manually, it
64 only adds one of those functions and nothing more. You may not patch the
65 kernel if you don't need pass-through support or CONFIG_SCST_STRICT_SERIALIZING is
66 defined during the compilation (see description below).
67
68 Then, to get the maximum performance you should apply export_alloc_io_context
69 patch. This patch simply makes alloc_io_context() function be available
70 for modules, not only for built-in in kernel code.
71
72 To compile SCST type 'make scst'. It will build SCST itself and its
73 device handlers. To install them type 'make scst_install'. The driver
74 modules will be installed in '/lib/modules/`you_kernel_version`/extra'.
75 In addition, scst.h, scst_debug.h as well as Module.symvers or
76 Modules.symvers will be copied to '/usr/local/include/scst'. The first
77 file contains all SCST's public data definition, which are used by
78 target drivers. The other ones support debug messages logging and build
79 process.
80
81 Then you can load any module by typing 'modprobe module_name'. The names
82 are:
83
84  - scst - SCST itself
85  - scst_disk - device handler for disks (type 0)
86  - scst_tape - device handler for tapes (type 1)
87  - scst_processor - device handler for processors (type 3)
88  - scst_cdrom - device handler for CDROMs (type 5)
89  - scst_modisk - device handler for MO disks (type 7)
90  - scst_changer - device handler for medium changers (type 8)
91  - scst_raid - device handler for storage array controller (e.g. raid) (type C)
92  - scst_vdisk - device handler for virtual disks (file, device or ISO CD image).
93  - scst_user - user space device handler
94
95 Then, to see your devices remotely, you need to add them to at least
96 "Default" security group (see below how). By default, no local devices
97 are seen remotely. There must be LUN 0 in each security group, i.e. LUs
98 numeration must not start from, e.g., 1.
99
100 It is highly recommended to use scstadmin utility for configuring
101 devices and security groups.
102
103 If you experience problems during modules load or running, check your
104 kernel logs (or run dmesg command for the few most recent messages).
105
106 IMPORTANT: Without loading appropriate device handler, corresponding devices
107 =========  will be invisible for remote initiators, which could lead to holes
108            in the LUN addressing, so automatic device scanning by remote SCSI
109            mid-level could not notice the devices. Therefore you will have
110            to add them manually via
111            'echo "- - -" >/sys/class/scsi_host/hostX/scan',
112            where X - is the host number.
113
114 IMPORTANT: Working of target and initiator on the same host isn't
115 =========  supported. This is a limitation of the Linux memory/cache
116            manager, because in this case an OOM deadlock like: system
117            needs some memory -> it decides to clear some cache -> cache
118            needs to write on a target exported device -> initiator sends
119            request to the target -> target needs memory -> problem is
120            possible.
121
122 IMPORTANT: In the current version simultaneous access to local SCSI devices
123 =========  via standard high-level SCSI drivers (sd, st, sg, etc.) and
124            SCST's target drivers is unsupported. Especially it is
125            important for execution via sg and st commands that change
126            the state of devices and their parameters, because that could
127            lead to data corruption. If any such command is done, at
128            least related device handler(s) must be restarted. For block
129            devices READ/WRITE commands using direct disk handler look to
130            be safe.
131
132 To uninstall, type 'make scst_uninstall'.
133
134 Device handlers
135 ---------------
136
137 Device specific drivers (device handlers) are plugins for SCST, which
138 help SCST to analyze incoming requests and determine parameters,
139 specific to various types of devices. If an appropriate device handler
140 for a SCSI device type isn't loaded, SCST doesn't know how to handle
141 devices of this type, so they will be invisible for remote initiators
142 (more precisely, "LUN not supported" sense code will be returned).
143
144 In addition to device handlers for real devices, there are VDISK, user
145 space and "performance" device handlers.
146
147 VDISK device handler works over files on file systems and makes from
148 them virtual remotely available SCSI disks or CDROM's. In addition, it
149 allows to work directly over a block device, e.g. local IDE or SCSI disk
150 or ever disk partition, where there is no file systems overhead. Using
151 block devices comparing to sending SCSI commands directly to SCSI
152 mid-level via scsi_do_req()/scsi_execute_async() has advantage that data
153 are transferred via system cache, so it is possible to fully benefit from
154 caching and read ahead performed by Linux's VM subsystem. The only
155 disadvantage here that in the FILEIO mode there is superfluous data
156 copying between the cache and SCST's buffers. This issue is going to be
157 addressed in the next release. Virtual CDROM's are useful for remote
158 installation. See below for details how to setup and use VDISK device
159 handler.
160
161 SCST user space device handler provides an interface between SCST and
162 the user space, which allows to create pure user space devices. The
163 simplest example, where one would want it is if he/she wants to write a
164 VTL. With scst_user he/she can write it purely in the user space. Or one
165 would want it if he/she needs some sophisticated for kernel space
166 processing of the passed data, like encrypting them or making snapshots.
167
168 "Performance" device handlers for disks, MO disks and tapes in their
169 exec() method skip (pretend to execute) all READ and WRITE operations
170 and thus provide a way for direct link performance measurements without
171 overhead of actual data transferring from/to underlying SCSI device.
172
173 NOTE: Since "perf" device handlers on READ operations don't touch the
174 ====  commands' data buffer, it is returned to remote initiators as it
175       was allocated, without even being zeroed. Thus, "perf" device
176       handlers impose some security risk, so use them with caution.
177
178 Compilation options
179 -------------------
180
181 There are the following compilation options, that could be commented
182 in/out in Makefile:
183
184  - CONFIG_SCST_DEBUG - if defined, turns on some debugging code,
185    including some logging. Makes the driver considerably bigger and slower,
186    producing large amount of log data.
187
188  - CONFIG_SCST_TRACING - if defined, turns on ability to log events. Makes the
189    driver considerably bigger and leads to some performance loss.
190
191  - CONFIG_SCST_EXTRACHECKS - if defined, adds extra validity checks in
192    the various places.
193
194  - CONFIG_SCST_USE_EXPECTED_VALUES - if not defined (default), initiator
195    supplied expected data transfer length and direction will be used only for
196    verification purposes to return error or warn in case if one of them
197    is invalid. Instead, locally decoded from SCSI command values will be
198    used. This is necessary for security reasons, because otherwise a
199    faulty initiator can crash target by supplying invalid value in one
200    of those parameters. This is especially important in case of
201    pass-through mode. If CONFIG_SCST_USE_EXPECTED_VALUES is defined, initiator
202    supplied expected data transfer length and direction will override
203    the locally decoded values. This might be necessary if internal SCST
204    commands translation table doesn't contain SCSI command, which is
205    used in your environment. You can know that if you have messages like
206    "Unknown opcode XX for YY. Should you update scst_scsi_op_table?" in
207    your kernel log and your initiator returns an error. Also report
208    those messages in the SCST mailing list
209    scst-devel@lists.sourceforge.net. Note, that not all SCSI transports
210    support supplying expected values.
211
212  - CONFIG_SCST_DEBUG_TM - if defined, turns on task management functions
213    debugging, when on LUN 0 in the default access control group some of the
214    commands will be delayed for about 60 sec., so making the remote
215    initiator send TM functions, eg ABORT TASK and TARGET RESET. Also
216    define CONFIG_SCST_TM_DBG_GO_OFFLINE symbol in the Makefile if you
217    want that the device eventually become completely unresponsive, or
218    otherwise to circle around ABORTs and RESETs code. Needs CONFIG_SCST_DEBUG
219    turned on.
220
221  - CONFIG_SCST_STRICT_SERIALIZING - if defined, makes SCST send all commands to
222    underlying SCSI device synchronously, one after one. This makes task
223    management more reliable, with cost of some performance penalty. This
224    is mostly actual for stateful SCSI devices like tapes, where the
225    result of command's execution depends from device's settings defined
226    by previous commands. Disk and RAID devices are stateless in the most
227    cases. The current SCSI core in Linux doesn't allow to abort all
228    commands reliably if they sent asynchronously to a stateful device.
229    Turned off by default, turn it on if you use stateful device(s) and
230    need as much error recovery reliability as possible. As a side
231    effect, no kernel patching is necessary.
232
233  - CONFIG_SCST_ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ - if defined, it will be
234    allowed to submit pass-through commands to real SCSI devices via the SCSI
235    middle layer using scsi_execute_async() function from soft IRQ
236    context (tasklets). This used to be the default, but currently it
237    seems the SCSI middle layer starts expecting only thread context on
238    the IO submit path, so it is disabled now by default. Enabling it
239    will decrease amount of context switches and improve performance. It
240    is more or less safe, in the worst case, if in your configuration the
241    SCSI middle layer really doesn't expect SIRQ context in
242    scsi_execute_async() function, you will get a warning message in the
243    kernel log.
244
245  - CONFIG_SCST_STRICT_SECURITY - if defined, makes SCST zero allocated data
246    buffers. Undefining it (default) considerably improves performance
247    and eases CPU load, but could create a security hole (information
248    leakage), so enable it, if you have strict security requirements.
249
250  - CONFIG_SCST_ABORT_CONSIDER_FINISHED_TASKS_AS_NOT_EXISTING - if defined,
251    in case when TASK MANAGEMENT function ABORT TASK is trying to abort a
252    command, which has already finished, remote initiator, which sent the
253    ABORT TASK request, will receive TASK NOT EXIST (or ABORT FAILED)
254    response for the ABORT TASK request. This is more logical response,
255    since, because the command finished, attempt to abort it failed, but
256    some initiators, particularly VMware iSCSI initiator, consider TASK
257    NOT EXIST response as if the target got crazy and try to RESET it.
258    Then sometimes get crazy itself. So, this option is disabled by
259    default.
260
261  - CONFIG_SCST_MEASURE_LATENCY - if defined, provides in /proc/scsi_tgt/latency
262    file average commands processing latency. You can clear already
263    measured results by writing 0 in this file. Note, you need a
264    non-preemptible kernel to have correct results.
265
266 HIGHMEM kernel configurations are fully supported, but not recommended
267 for performance reasons, except for scst_user, where they are not
268 supported, because this module deals with user supplied memory on a
269 zero-copy manner. If you need to use it, consider change VMSPLIT option
270 or use 64-bit system configuration instead.
271
272 For changing VMSPLIT option (CONFIG_VMSPLIT to be precise) you should in
273 "make menuconfig" command set the following variables:
274
275  - General setup->Configure standard kernel features (for small systems): ON
276
277  - General setup->Prompt for development and/or incomplete code/drivers: ON
278
279  - Processor type and features->High Memory Support: OFF
280
281  - Processor type and features->Memory split: according to amount of
282    memory you have. If it is less than 800MB, you may not touch this
283    option at all.
284
285 Module parameters
286 -----------------
287
288 Module scst supports the following parameters:
289
290  - scst_threads - allows to set count of SCST's threads. By default it
291    is CPU count.
292
293  - scst_max_cmd_mem - sets maximum amount of memory in Mb allowed to be
294    consumed by the SCST commands for data buffers at any given time. By
295    default it is approximately TotalMem/4.
296
297 SCST "/proc" commands
298 ---------------------
299
300 For communications with user space programs SCST provides proc-based
301 interface in "/proc/scsi_tgt" directory. It contains the following
302 entries:
303
304   - "help" file, which provides online help for SCST commands
305
306   - "scsi_tgt" file, which on read provides information of serving by SCST
307     devices and their dev handlers. On write it supports the following
308     command:
309
310       * "assign H:C:I:L HANDLER_NAME" assigns dev handler "HANDLER_NAME"
311         on device with host:channel:id:lun
312
313   - "sessions" file, which lists currently connected initiators (open sessions)
314
315   - "sgv" file provides some statistic about with which block sizes
316     commands from remote initiators come and how effective sgv_pool in
317     serving those allocations from the cache, i.e. without memory
318     allocations requests to the kernel. "Size" - is the commands data
319     size upper rounded to power of 2, "Hit" - how many there are
320     allocations from the cache, "Total" - total number of allocations.
321
322   - "threads" file, which allows to read and set number of SCST's threads
323
324   - "version" file, which shows version of SCST
325
326   - "trace_level" file, which allows to read and set trace (logging) level
327     for SCST. See "help" file for list of trace levels. If you want to
328     enable logging options, which produce a lot of events, like "debug",
329     to not loose logged events you should also:
330
331      * Increase in .config of your kernel CONFIG_LOG_BUF_SHIFT variable
332        to much bigger value, then recompile it. For example, I use 25,
333        but to use it I needed to modify the maximum allowed value for
334        CONFIG_LOG_BUF_SHIFT in the corresponding Kconfig.
335
336      * Change in your /etc/syslog.conf or other config file of your favorite
337        logging program to store kernel logs in async manner. For example,
338        I added in my rsyslog.conf line "kern.info -/var/log/kernel"
339        and added "kern.none" in line for /var/log/messages, so I had:
340        "*.info;kern.none;mail.none;authpriv.none;cron.none /var/log/messages"
341
342 Each dev handler has own subdirectory. Most dev handler have only two
343 files in this subdirectory: "trace_level" and "type". The first one is
344 similar to main SCST "trace_level" file, the latter one shows SCSI type
345 number of this handler as well as some text description.
346
347 For example, "echo "assign 1:0:1:0 dev_disk" >/proc/scsi_tgt/scsi_tgt"
348 will assign device handler "dev_disk" to real device sitting on host 1,
349 channel 0, ID 1, LUN 0.
350
351 Access and devices visibility management (LUN masking)
352 ------------------------------------------------------
353
354 Access and devices visibility management allows for an initiator or
355 group of initiators to see different devices with different LUNs
356 with necessary access permissions.
357
358 SCST supports two modes of access control:
359
360 1. Target-oriented. In this mode you define for each target devices and
361 their LUNs, which are accessible to all initiators, connected to that
362 target. This is a regular access control mode, which people usually mean
363 thinking about access control in general. For instance, in IET this is
364 the only supported mode. In this mode you should create a security group
365 with name "Default_TARGET_NAME", where "TARGET_NAME" is name of the
366 target, like "Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz"
367 for target "iqn.2007-05.com.example:storage.disk1.sys1.xyz". Then you
368 should add to it all LUNs, available from that target.
369
370 2. Initiator-oriented. In this mode you define which devices and their
371 LUNs are accessible for each initiator. In this mode you should create
372 for each set of one or more initiators, which should access to the same
373 set of devices with the same LUNs, a separate security group, then add
374 to it available devices and names of allowed initiator(s).
375
376 Both modes can be used simultaneously. In this case initiator-oriented
377 mode has higher priority, than target-oriented.
378
379 When a target driver registers itself in SCST core, it tells SCST core
380 its name. Then, when there is a new connection from a remote initiator,
381 the target driver registers this connection in SCST core and tells it
382 the name of the remote initiator. Then SCST core finds the corresponding
383 devices for it using the following algorithm:
384
385 1. It searches through all defined groups trying to find group
386 containing the initiator name. If it succeeds, the found group is used.
387
388 2. Otherwise, it searches through all groups trying to find group with
389 name "Default_TARGET_NAME". If it succeeds, the found group is used.
390
391 3. Otherwise, the group with name "Default" is used. This group is
392 always defined, but empty by default.
393
394 Names of both target and initiator you can clarify in the kernel log. In
395 it SCST reports to which group each session is assigned.
396
397 In /proc/scsi_tgt each group represented as "groups/GROUP_NAME/"
398 subdirectory. In it there are files "devices" and "names". File
399 "devices" lists devices and their LUNs in the group, file "names" lists
400 names of initiators, which allowed to access devices in this group.
401
402 To configure access and devices visibility management SCST provides the
403 following files and directories under /proc/scsi_tgt:
404
405   - "add_group GROUP" to /proc/scsi_tgt/scsi_tgt adds group "GROUP"
406
407   - "del_group GROUP" to /proc/scsi_tgt/scsi_tgt deletes group "GROUP"
408
409   - "add H:C:I:L lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds
410     device with host:channel:id:lun with LUN "lun" in group "GROUP". Optionally,
411     the device could be marked as read only.
412
413   - "del H:C:I:L" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
414     host:channel:id:lun from group "GROUP"
415
416   - "add V_NAME lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds
417     device with virtual name "V_NAME" with LUN "lun" in group "GROUP".
418     Optionally, the device could be marked as read only.
419
420   - "del V_NAME" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
421     virtual name "V_NAME" from group "GROUP"
422
423   - "clear" to /proc/scsi_tgt/groups/GROUP/devices clears the list of devices
424     for group "GROUP"
425
426   - "add NAME" to /proc/scsi_tgt/groups/GROUP/names adds name "NAME" to group
427     "GROUP"
428
429   - "del NAME" to /proc/scsi_tgt/groups/GROUP/names deletes name "NAME" from group
430     "GROUP"
431
432   - "clear" to /proc/scsi_tgt/groups/GROUP/names clears the list of names
433     for group "GROUP"
434
435 Examples:
436
437  - "echo "add 1:0:1:0 0" >/proc/scsi_tgt/groups/Default/devices" will
438  add real device sitting on host 1, channel 0, ID 1, LUN 0 to "Default"
439  group with LUN 0.
440
441  - "echo "add disk1 1" >/proc/scsi_tgt/groups/Default/devices" will
442  add virtual VDISK device with name "disk1" to "Default" group
443  with LUN 1.
444
445 Consider you need to have an iSCSI target with name
446 "iqn.2007-05.com.example:storage.disk1.sys1.xyz" (you defined it in
447 iscsi-scst.conf), which should export virtual device "dev1" with LUN 0
448 and virtual device "dev2" with LUN 1, but initiator with name
449 "iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" should see only
450 virtual device "dev2" with LUN 0. To achieve that you should do the
451 following commands:
452
453 # echo "add_group Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz" >/proc/scsi_tgt/scsi_tgt
454 # echo "add dev1 0" >/proc/scsi_tgt/groups/Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz/devices
455 # echo "add dev2 1" >/proc/scsi_tgt/groups/Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz/devices
456
457 # echo "add_group spec_ini" >/proc/scsi_tgt/scsi_tgt
458 # echo "add iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" >/proc/scsi_tgt/groups/spec_ini/names
459 # echo "add dev2 0" >/proc/scsi_tgt/groups/spec_ini/devices
460
461 It is highly recommended to use scstadmin utility instead of described
462 in this section low level interface.
463
464 IMPORTANT
465 =========
466
467 There must be LUN 0 in each security group, i.e. LUs numeration must not
468 start from, e.g., 1.
469
470 IMPORTANT
471 =========
472
473 All the access control must be fully configured BEFORE load of the
474 corresponding target driver! When you load a target driver or enable
475 target mode in it, as for qla2x00t driver, it will immediately start
476 accepting new connections, hence creating new sessions, and those new
477 sessions will be assigned to security groups according to the
478 *currently* configured access control settings. For instance, to
479 "Default" group, instead of "HOST004" as you may need, because "HOST004"
480 doesn't exist yet. So, one must configure all the security groups before
481 new connections from the initiators are created, i.e. before target
482 drivers loaded.
483
484 Access controls can be altered after the target driver loaded as long as
485 the target session doesn't yet exist. And even in the case of the
486 session already existing, changes are still possible, but won't be
487 reflected on the initiator side.
488
489 So, the safest choice is to configure all the access control before any
490 target driver load and then only add new devices to new groups for new
491 initiators or add new devices to old groups, but not altering existing
492 LUNs in them.
493
494 VDISK device handler
495 --------------------
496
497 After loading VDISK device handler creates in "/proc/scsi_tgt/"
498 subdirectories "vdisk" and "vcdrom". They have similar layout:
499
500   - "trace_level" and "type" files as described for other dev handlers
501
502   - "help" file, which provides online help for VDISK commands
503
504   - "vdisk"/"vcdrom" files, which on read provides information of
505     currently open device files. On write it supports the following
506     command:
507
508     * "open NAME [PATH] [BLOCK_SIZE] [FLAGS]" - opens file "PATH" as
509       device "NAME" with block size "BLOCK_SIZE" bytes with flags
510       "FLAGS". "PATH" could be empty only for VDISK CDROM. "BLOCK_SIZE"
511       and "FLAGS" are valid only for disk VDISK. The block size must be
512       power of 2 and >= 512 bytes. Default is 512. Possible flags:
513
514       - WRITE_THROUGH - write back caching disabled. Note, this option
515         has sense only if you also *manually* disable write-back cache
516         in *all* your backstorage devices and make sure it's actually
517         disabled, since many devices are known to lie about this mode to
518         get better benchmark results.
519
520       - READ_ONLY - read only
521
522       - O_DIRECT - both read and write caching disabled. This mode
523         isn't currently fully implemented, you should use user space
524         fileio_tgt program in O_DIRECT mode instead (see below).
525
526       - NULLIO - in this mode no real IO will be done, but success will be
527         returned. Intended to be used for performance measurements at the same
528         way as "*_perf" handlers.
529
530       - NV_CACHE - enables "non-volatile cache" mode. In this mode it is
531         assumed that the target has a GOOD UPS with ability to cleanly
532         shutdown target in case of power failure and it is
533         software/hardware bugs free, i.e. all data from the target's
534         cache are guaranteed sooner or later to go to the media. Hence
535         all data synchronization with media operations, like
536         SYNCHRONIZE_CACHE, are ignored in order to bring more
537         performance. Also in this mode target reports to initiators that
538         the corresponding device has write-through cache to disable all
539         write-back cache workarounds used by initiators. Use with
540         extreme caution, since in this mode after a crash of the target
541         journaled file systems don't guarantee the consistency after
542         journal recovery, therefore manual fsck MUST be ran. Note, that
543         since usually the journal barrier protection (see "IMPORTANT"
544         note below) turned off, enabling NV_CACHE could change nothing
545         from data protection point of view, since no data
546         synchronization with media operations will go from the
547         initiator. This option overrides WRITE_THROUGH.
548
549       - BLOCKIO - enables block mode, which will perform direct block
550         IO with a block device, bypassing page-cache for all operations.
551         This mode works ideally with high-end storage HBAs and for
552         applications that either do not need caching between application
553         and disk or need the large block throughput. See also below.
554
555       - REMOVABLE - with this flag set the device is reported to remote
556         initiators as removable.
557
558     * "close NAME" - closes device "NAME".
559
560     * "change NAME [PATH]" - changes a virtual CD in the VDISK CDROM.
561
562 By default, if neither BLOCKIO, nor NULLIO option is supplied, FILEIO
563 mode is used.
564
565 For example, "echo "open disk1 /vdisks/disk1" >/proc/scsi_tgt/vdisk/vdisk"
566 will open file /vdisks/disk1 as virtual FILEIO disk with name "disk1".
567
568 CAUTION: If you partitioned/formatted your device with block size X, *NEVER*
569 ======== ever try to export and then mount it (even accidentally) with another
570          block size. Otherwise you can *instantly* damage it pretty
571          badly as well as all your data on it. Messages on initiator
572          like: "attempt to access beyond end of device" is the sign of
573          such damage.
574
575          Moreover, if you want to compare how well different block sizes
576          work for you, you **MUST** EVERY TIME AFTER CHANGING BLOCK SIZE
577          **COMPLETELY** **WIPE OFF** ALL THE DATA FROM THE DEVICE. In
578          other words, THE **WHOLE** DEVICE **MUST** HAVE ONLY **ZEROS**
579          AS THE DATA AFTER YOU SWITCH TO NEW BLOCK SIZE. Switching block
580          sizes isn't like switching between FILEIO and BLOCKIO, after
581          changing block size all previously written with another block
582          size data MUST BE ERASED. Otherwise you will have a full set of
583          very weird behaviors, because blocks addressing will be
584          changed, but initiators in most cases will not have a
585          possibility to detect that old addresses written on the device
586          in, e.g., partition table, don't refer anymore to what they are
587          intended to refer.
588
589 IMPORTANT: By default for performance reasons VDISK FILEIO devices use write
590 =========  back caching policy. This is generally safe from the consistence of
591            journaled file systems, laying over them, point of view, but
592            your unsaved cached data will be lost in case of
593            power/hardware/software failure, so you must supply your
594            target server with some kind of UPS or disable write back
595            caching using WRITE_THROUGH flag. You also should note, that
596            the file systems journaling over write back caching enabled
597            devices works reliably *ONLY* if the order of journal writes
598            is guaranteed or it uses some kind of data protection
599            barriers (i.e. after writing journal data some kind of
600            synchronization with media operations is used), otherwise,
601            because of possible reordering in the cache, even after
602            successful journal rollback, you very much risk to loose your
603            data on the FS. Currently, Linux IO subsystem guarantees
604            order of write operations only using data protection
605            barriers. Some info about it from the XFS point of view could
606            be found at http://oss.sgi.com/projects/xfs/faq.html#wcache.
607            On Linux initiators for EXT3 and ReiserFS file systems the
608            barrier protection could be turned on using "barrier=1" and
609            "barrier=flush" mount options correspondingly. Note, that
610            usually it's turned off by default (see http://lwn.net/Articles/283161).
611            You can check if it's turn on or off by looking in /proc/mounts.
612            Windows and, AFAIK, other UNIX'es don't need any special
613            explicit options and do necessary barrier actions on
614            write-back caching devices by default. Also note
615            that on some real-life workloads write through caching might
616            perform better, than write back one with the barrier
617            protection turned on.
618            Also you should realize that Linux doesn't provide a
619            guarantee that after sync()/fsync() all written data really
620            hit permanent storage, they can be then in the cache of your
621            backstorage device and lost on power failure event. Thus,
622            ever with write-through cache mode, you still need a good UPS
623            to protect yourself from your data loss (note, data loss, not
624            the file system integrity corruption).
625
626 IMPORTANT: Some disk and partition table management utilities don't support
627 =========  block sizes >512 bytes, therefore make sure that your favorite one
628            supports it. Currently only cfdisk is known to work only with
629            512 bytes blocks, other utilities like fdisk on Linux or
630            standard disk manager on Windows are proved to work well with
631            non-512 bytes blocks. Note, if you export a disk file or
632            device with some block size, different from one, with which
633            it was already partitioned, you could get various weird
634            things like utilities hang up or other unexpected behavior.
635            Hence, to be sure, zero the exported file or device before
636            the first access to it from the remote initiator with another
637            block size. On Window initiator make sure you "Set Signature"
638            in the disk manager on the imported from the target drive
639            before doing any other partitioning on it. After you
640            successfully mounted a file system over non-512 bytes block
641            size device, the block size stops matter, any program will
642            work with files on such file system.
643
644 BLOCKIO VDISK mode
645 ------------------
646
647 This module works best for these types of scenarios:
648
649 1) Data that are not aligned to 4K sector boundaries and <4K block sizes
650 are used, which is normally found in virtualization environments where
651 operating systems start partitions on odd sectors (Windows and it's
652 sector 63).
653
654 2) Large block data transfers normally found in database loads/dumps and
655 streaming media.
656
657 3) Advanced relational database systems that perform their own caching
658 which prefer or demand direct IO access and, because of the nature of
659 their data access, can actually see worse performance with
660 non-discriminate caching.
661
662 4) Multiple layers of targets were the secondary and above layers need
663 to have a consistent view of the primary targets in order to preserve
664 data integrity which a page cache backed IO type might not provide
665 reliably.
666
667 Also it has an advantage over FILEIO that it doesn't copy data between
668 the system cache and the commands data buffers, so it saves a
669 considerable amount of CPU power and memory bandwidth.
670
671 IMPORTANT: Since data in BLOCKIO and FILEIO modes are not consistent between
672 =========  them, if you try to use a device in both those modes simultaneously,
673            you will almost instantly corrupt your data on that device.
674
675 Pass-through mode
676 -----------------
677
678 In the pass-through mode (i.e. using the pass-through device handlers
679 scst_disk, scst_tape, etc) SCSI commands, coming from remote initiators,
680 are passed to local SCSI hardware on target as is, without any
681 modifications. As any other hardware, the local SCSI hardware can not
682 handle commands with amount of data and/or segments count in
683 scatter-gather array bigger some values. Therefore, when using the
684 pass-through mode you should note that values for maximum number of
685 segments and maximum amount of transferred data for each SCSI command on
686 devices on initiators can not be bigger, than corresponding values of
687 the corresponding SCSI devices on the target. Otherwise you will see
688 symptoms like small transfers work well, but large ones stall and
689 messages like: "Unable to complete command due to SG IO count
690 limitation" are printed in the kernel logs.
691
692 You can't control from the user space limit of the scatter-gather
693 segments, but for block devices usually it is sufficient if you set on
694 the initiators /sys/block/DEVICE_NAME/queue/max_sectors_kb in the same
695 or lower value as in /sys/block/DEVICE_NAME/queue/max_hw_sectors_kb for
696 the corresponding devices on the target.
697
698 For not-block devices SCSI commands are usually generated directly by
699 applications, so, if you experience large transfers stalls, you should
700 check documentation for your application how to limit the transfer
701 sizes.
702
703 Another way to solve this issue is to build SG entries with more than 1
704 page each. See the following patch as an example:
705 http://scst.sf.net/sgv_big_order_alloc.diff
706
707 User space mode using scst_user dev handler
708 -------------------------------------------
709
710 User space program fileio_tgt uses interface of scst_user dev handler
711 and allows to see how it works in various modes. Fileio_tgt provides
712 mostly the same functionality as scst_vdisk handler with the most
713 noticeable difference that it supports O_DIRECT mode. O_DIRECT mode is
714 basically the same as BLOCKIO, but also supports files, so for some
715 loads it could be significantly faster, than the regular FILEIO access.
716 All the words about BLOCKIO from above apply to O_DIRECT as well. See
717 fileio_tgt's README file for more details.
718
719 Performance
720 -----------
721
722 Before doing any performance measurements note that:
723
724 I. Performance results are very much dependent from your type of load,
725 so it is crucial that you choose access mode (FILEIO, BLOCKIO,
726 O_DIRECT, pass-through), which suits your needs the best.
727
728 II. In order to get the maximum performance you should:
729
730 1. For SCST:
731
732  - Disable in Makefile CONFIG_SCST_STRICT_SERIALIZING, CONFIG_SCST_EXTRACHECKS,
733    CONFIG_SCST_TRACING, CONFIG_SCST_DEBUG*, CONFIG_SCST_STRICT_SECURITY
734
735  - For pass-through devices enable
736    CONFIG_SCST_ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ.
737
738 2. For target drivers:
739
740  - Disable in Makefiles CONFIG_SCST_EXTRACHECKS, CONFIG_SCST_TRACING,
741    CONFIG_SCST_DEBUG*
742
743 3. For device handlers, including VDISK:
744
745  - Disable in Makefile CONFIG_SCST_TRACING and CONFIG_SCST_DEBUG.
746
747  - If your initiator(s) use dedicated exported from the target virtual
748    SCSI devices and have more or equal amount of memory, than the
749    target, it is recommended to use O_DIRECT option (currently it is
750    available only with fileio_tgt user space program) or BLOCKIO. With
751    them you could have up to 100% increase in throughput.
752
753 IMPORTANT: Some of the compilation options enabled by default, i.e. SCST
754 =========  is optimized currently rather for development and bug hunting,
755            than for performance.
756
757 If you use SCST version taken directly from the SVN repository, you can
758 set the above options, except CONFIG_SCST_ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ,
759 using debug2perf Makefile target.
760
761 4. For other target and initiator software parts:
762
763  - Don't enable debug/hacking features in the kernel, i.e. use them as
764    they are by default.
765
766  - The default kernel read-ahead and queuing settings are optimized
767    for locally attached disks, therefore they are not optimal if they
768    attached remotely (SCSI target case), which sometimes could lead to
769    unexpectedly low throughput. You should increase read-ahead size to at
770    least 512KB or even more on all initiators and the target.
771
772    You should also limit on all initiators maximum amount of sectors per
773    SCSI command. To do it on Linux initiators, run:
774
775    echo “64” > /sys/block/sdX/queue/max_sectors_kb
776
777    where specify instead of X your imported from target device letter,
778    like 'b', i.e. sdb.
779
780    To increase read-ahead size on Linux, run:
781
782    blockdev --setra N /dev/sdX
783
784    where N is a read-ahead number in 512-byte sectors and X is a device
785    letter like above.
786
787    Note: you need to set read-ahead setting for device sdX again after
788    you changed the maximum amount of sectors per SCSI command for that
789    device.
790
791  - You may need to increase amount of requests that OS on initiator
792    sends to the target device. To do it on Linux initiators, run
793
794    echo “64” > /sys/block/sdX/queue/nr_requests
795
796    where X is a device letter like above.
797
798    You may also experiment with other parameters in /sys/block/sdX
799    directory, they also affect performance. If you find the best values,
800    please share them with us.
801
802  - On the target CFQ IO scheduler. In most cases it has performance
803    advantage over other IO schedulers, sometimes huge (2+ times
804    aggregate throughput increase).
805
806  - It is recommended to turn the kernel preemption off, i.e. set
807    the kernel preemption model to "No Forced Preemption (Server)".
808
809  - Looks like XFS is the best filesystem on the target to store device
810    files, because it allows considerably better linear write throughput,
811    than ext3.
812
813 5. For hardware on target.
814
815  - Make sure that your target hardware (e.g. target FC or network card)
816    and underlaying IO hardware (e.g. IO card, like SATA, SCSI or RAID to
817    which your disks connected) don't share the same PCI bus. You can
818    check it using lspci utility. They have to work in parallel, so it
819    will be better if they don't compete for the bus. The problem is not
820    only in the bandwidth, which they have to share, but also in the
821    interaction between cards during that competition. This is very
822    important, because in some cases if target and backend storage
823    controllers share the same PCI bus, it could lead up to 5-10 times
824    less performance, than expected. Moreover, some motherboard (by
825    Supermicro, particularly) have serious stability issues if there are
826    several high speed devices on the same bus working in parallel. If
827    you have no choice, but PCI bus sharing, set in the BIOS PCI latency
828    as low as possible.
829
830 6. If you use VDISK IO module in FILEIO mode, NV_CACHE option will
831 provide you the best performance. But using it make sure you use a good
832 UPS with ability to shutdown the target on the power failure.
833
834 IMPORTANT: If you use on initiator some versions of Windows (at least W2K)
835 =========  you can't get good write performance for VDISK FILEIO devices with
836            default 512 bytes block sizes. You could get about 10% of the
837            expected one. This is because of the partition alignment, which
838            is (simplifying) incompatible with how Linux page cache
839            works, so for each write the corresponding block must be read
840            first. Use 4096 bytes block sizes for VDISK devices and you
841            will have the expected write performance. Actually, any OS on
842            initiators, not only Windows, will benefit from block size
843            max(PAGE_SIZE, BLOCK_SIZE_ON_UNDERLYING_FS), where PAGE_SIZE
844            is the page size, BLOCK_SIZE_ON_UNDERLYING_FS is block size
845            on the underlying FS, on which the device file located, or 0,
846            if a device node is used. Both values are from the target.
847            See also important notes about setting block sizes >512 bytes
848            for VDISK FILEIO devices above.
849
850
851 Work if target's backstorage or link is too slow
852 ------------------------------------------------
853
854 Under high I/O load, when your target's backstorage gets overloaded, or
855 working over a slow link between inititor and target, when the link
856 can't serve all the queued commands on time, you can experience I/O
857 stalls or see in the kernel log abort or reset messages.
858
859 At first, consider the case of too slow target's backstorage. On some
860 seek intensive workloads even fast disks or RAIDs, which able to serve
861 continuous data stream on 500+ MB/s speed, can be as slow as 0.3 MB/s.
862 Another possible cause for that can be MD/LVM/RAID on your target as in
863 http://lkml.org/lkml/2008/2/27/96 (check the whole thread as well).
864
865 Thus, in such situations simply processing of one or more commands takes
866 too long time, hence initiator decides that they are stuck on the target
867 and tries to recover. Particularly, it is known that the default amount
868 of simultaneously queued commands (48) is sometimes too high if you do
869 intensive writes from VMware on a target disk, which uses LVM in the
870 snapshot mode. In this case value like 16 or even 8-10 depending of your
871 backstorage speed could be more appropriate.
872
873 Unfortunately, currently SCST lacks dynamic I/O flow control, when the
874 queue depth on the target is dynamically decreased/increased based on
875 how slow/fast the backstorage speed comparing to the target link. So,
876 there are 6 possible actions, which you can do to workaround or fix this
877 issue in this case:
878
879 1. Ignore incoming task management (TM) commands. It's fine if there are
880 not too many of them, so average performance isn't hurt and the
881 corresponding device isn't getting put offline, i.e. if the backstorage
882 isn't too slow.
883
884 2. Decrease /sys/block/sdX/device/queue_depth on the initiator in case
885 if it's Linux (see below how) or/and SCST_MAX_TGT_DEV_COMMANDS constant
886 in scst_priv.h file until you stop seeing incoming TM commands.
887 ISCSI-SCST driver also has its own iSCSI specific parameter for that,
888 see its README file.
889
890 To decrease device queue depth on Linux initiators you can run command:
891
892 # echo Y >/sys/block/sdX/device/queue_depth
893
894 where Y is the new number of simultaneously queued commands, X - your
895 imported device letter, like 'a' for sda device. There are no special
896 limitations for Y value, it can be any value from 1 to possible maximum
897 (usually, 32), so start from dividing the current value on 2, i.e. set
898 16, if /sys/block/sdX/device/queue_depth contains 32.
899
900 3. Increase the corresponding timeout on the initiator. For Linux it is
901 located in
902 /sys/devices/platform/host*/session*/target*:0:0/*:0:0:1/timeout. It can
903 be done automatically by an udev rule. For instance, the following
904 rule will increase it to 300 seconds:
905
906 SUBSYSTEM=="scsi", KERNEL=="[0-9]*:[0-9]*", ACTION=="add", ATTR{type}=="0|7|14", ATTR{timeout}="300"
907
908 By default, this timeout is 30 or 60 seconds, depending on your distribution.
909
910 4. Try to avoid such seek intensive workloads.
911
912 5. Increase speed of the target's backstorage.
913
914 6. Implement in SCST dynamic I/O flow control. This will be an ultimate
915 solution. See "Dynamic I/O flow control" section on
916 http://scst.sourceforge.net/contributing.html page for possible
917 implementation idea.
918
919 Next, consider the case of too slow link between initiator and target,
920 when the initiator tries to simultaneously push N commands to the target
921 over it. In this case time to serve those commands, i.e. send or receive
922 data for them over the link, can be more, than timeout for any single
923 command, hence one or more commands in the tail of the queue can not be
924 served on time less than the timeout, so the initiator will decide that
925 they are stuck on the target and will try to recover.
926
927 To workaround/fix this issue in this case you can use ways 1, 2, 3, 6
928 above or (7): increase speed of the link between target and initiator.
929 But for some initiators implementations for WRITE commands there might
930 be cases when target has no way to detect the issue, so dynamic I/O flow
931 control will not be able to help. In those cases you could also need on
932 the initiator(s) to either decrease the queue depth (way 2), or increase
933 the corresponding timeout (way 3).
934
935 Note, that logged messages about QUEUE_FULL status are quite different
936 by nature. This is a normal work, just SCSI flow control in action.
937 Simply don't enable "mgmt_minor" logging level, or, alternatively, if
938 you are confident in the worst case performance of your back-end storage
939 or inititor-target link, you can increase SCST_MAX_TGT_DEV_COMMANDS in
940 scst_priv.h to 64. Usually initiators don't try to push more commands on
941 the target.
942
943 Credits
944 -------
945
946 Thanks to:
947
948  * Mark Buechler <mark.buechler@gmail.com> for a lot of useful
949    suggestions, bug reports and help in debugging.
950
951  * Ming Zhang <mingz@ele.uri.edu> for fixes and comments.
952
953  * Nathaniel Clark <nate@misrule.us> for fixes and comments.
954
955  * Calvin Morrow <calvin.morrow@comcast.net> for testing and useful
956    suggestions.
957
958  * Hu Gang <hugang@soulinfo.com> for the original version of the
959    LSI target driver.
960
961  * Erik Habbinga <erikhabbinga@inphase-tech.com> for fixes and support
962    of the LSI target driver.
963
964  * Ross S. W. Walker <rswwalker@hotmail.com> for the original block IO
965    code and Vu Pham <huongvp@yahoo.com> who updated it for the VDISK dev
966    handler.
967
968  * Michael G. Byrnes <michael.byrnes@hp.com> for fixes.
969
970  * Alessandro Premoli <a.premoli@andxor.it> for fixes
971
972  * Nathan Bullock <nbullock@yottayotta.com> for fixes.
973
974  * Terry Greeniaus <tgreeniaus@yottayotta.com> for fixes.
975
976  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes and bug reports.
977
978  * Jianxi Chen <pacers@users.sourceforge.net> for fixing problem with
979    devices >2TB in size
980
981  * Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
982
983 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net