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