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