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