- SysfsRules file added
[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  - mgmt - this entry allows to create virtual devices and their
575    attributes (for virtual devices dev handlers) or assign/unassign real
576    SCSI devices to/from this dev handler (for pass-through dev
577    handlers).
578
579  - pass_through - if exists, it contains 1 and this dev handler is a
580    pass-through dev handler.
581
582  - trace_level - allows to enable and disable various tracing
583    facilities. See content of this file for help how to use it.
584
585  - type - SCSI type of devices served by this dev handler.
586
587 See below for more information about other entries of this subdirectory
588 of the standard SCST dev handlers.
589
590 "Sgv" subdirectory contains statistic information of SCST SGV caches. It
591 has the following entries:
592
593  - None, one or more subdirectories for each existing SGV cache.
594  
595  - global_stats - file containing global SGV caches statistics.
596
597 Each SGV cache's subdirectory has the following item:
598
599  - stats - file containing statistics for this SGV caches.
600
601 "Targets" subdirectory contains subdirectories for each SCST target.
602
603 Content of each target's subdirectory is target specific. See
604 documentation for your target for more info about it as well as
605 SysfsRules file for more info about common to all targets rules.
606 Every target should have at least the following entries:
607
608  - ini_groups - subdirectory, which contains and allows to define
609    initiator-oriented access control information, see below.
610
611  - luns - subdirectory, which contains list of available LUNs in the
612    target-oriented access control and allows to define it, see below.
613
614  - sessions - subdirectory containing connected to this target sessions.
615
616  - enabled - using this attribute you can enable or disable this target/
617    It allows to finish configuring it before it starts accepting new
618    connections. 0 by default.
619
620  - rel_tgt_id - allows to read or write SCSI Relative Target Port
621    Identifier attribute. This identifier is used to identify SCSI Target
622    Ports by some SCSI commands, mainly by Persistent Reservations
623    commands. This identifier must be unique among all SCST targets, but
624    for convenience SCST allows disabled targets to have not unique
625    rel_tgt_id. In this case SCST will not allow to enable this target
626    until rel_tgt_id becomes unique. This attribute initialized unique by
627    SCST by default.
628
629 A target driver may have also the follwoing entries:
630
631  - "hw_target" - if the target driver supports both hardware and virtual
632     targets (for instance, an FC adapter supporting NPIV, which has
633     hardware targets for its physical ports as well as virtual NPIV
634     targets), this read only attribute for all hardware targets will
635     exist and contain value 1.
636
637 Subdirectory "sessions" contains one subdirectory for each connected
638 session with name equal to name of the connected initiator.
639
640 Each session subdirectory contains the following entries:
641
642  - initiator_name - contains initiator name
643
644  - force_close - optional write-only attribute, which allows to force
645    close this session.
646
647  - active_commands - contains number of active, i.e. not yet or being
648    executed, SCSI commands in this session.
649
650  - commands - contains overall number of SCSI commands in this session.
651
652  - other target driver specific attributes and subdirectories.
653
654 See below description of the VDISK's sysfs interface for samples.
655
656
657 Access and devices visibility management (LUN masking) - sysfs interface
658 ------------------------------------------------------------------------
659
660 Access and devices visibility management allows for an initiator or
661 group of initiators to see different devices with different LUNs
662 with necessary access permissions.
663
664 SCST supports two modes of access control:
665
666 1. Target-oriented. In this mode you define for each target a default
667 set of LUNs, which are accessible to all initiators, connected to that
668 target. This is a regular access control mode, which people usually mean
669 thinking about access control in general. For instance, in IET this is
670 the only supported mode.
671
672 2. Initiator-oriented. In this mode you define which LUNs are accessible
673 for each initiator. In this mode you should create for each set of one
674 or more initiators, which should access to the same set of devices with
675 the same LUNs, a separate security group, then add to it devices and
676 names of allowed initiator(s).
677
678 Both modes can be used simultaneously. In this case the
679 initiator-oriented mode has higher priority, than the target-oriented,
680 i.e. initiators are at first searched in all defined security groups for
681 this target and, if none matches, the default target's set of LUNs is
682 used. This set of LUNs might be empty, then the initiator will not see
683 any LUNs from the target.
684
685 You can at any time find out which set of LUNs each session is assigned
686 to by looking where link
687 /sys/kernel/scst_tgt/targets/target_driver/target_name/sessions/initiator_name/luns
688 points to.
689
690 To configure the target-oriented access control SCST provides the
691 following interface. Each target's sysfs subdirectory
692 (/sys/kernel/scst_tgt/targets/target_driver/target_name) has "luns"
693 subdirectory. This subdirectory contains the list of already defined
694 target-oriented access control LUNs for this target as well as file
695 "mgmt". This file has the following commands, which you can send to it,
696 for instance, using "echo" shell command. You can always get a small
697 help about supported commands by looking inside this file. "Parameters"
698 are one or more param_name=value pairs separated by ';'.
699
700  - "add H:C:I:L lun [parameters]" - adds a pass-through device with
701    host:channel:id:lun with LUN "lun". Optionally, the device could be
702    marked as read only by using parameter "read_only". The recommended
703    way to find out H:C:I:L numbers is use of lsscsi utility.
704
705  - "replace H:C:I:L lun [parameters]" - replaces by pass-through device
706    with host:channel:id:lun existing with LUN "lun" device with
707    generation of INQUIRY DATA HAS CHANGED Unit Attention. If the old
708    device doesn't exist, this command acts as the "add" command.
709    Optionally, the device could be marked as read only by using
710    parameter "read_only". The recommended way to find out H:C:I:L
711    numbers is use of lsscsi utility.
712
713  - "del H:C:I:L" - deletes a pass-through device with host:channel:id:lun
714    The recommended way to find out H:C:I:L numbers is use of lsscsi
715    utility.
716
717  - "add VNAME lun [parameters]" - adds a virtual device with name VNAME
718    with LUN "lun". Optionally, the device could be marked as read only
719    by using parameter "read_only".
720
721  - "replace VNAME lun [parameters]" - replaces by virtual device
722    with name VNAME existing with LUN "lun" device with generation of
723    INQUIRY DATA HAS CHANGED Unit Attention. If the old device doesn't
724    exist, this command acts as the "add" command. Optionally, the device
725    could be marked as read only by using parameter "read_only".
726
727  - "del VNAME" - deletes a virtual device with name VNAME.
728
729  - "clear" - clears the list of devices
730
731 To configure the initiator-oriented access control SCST provides the
732 following interface. Each target's sysfs subdirectory
733 (/sys/kernel/scst_tgt/targets/target_driver/target_name) has "ini_groups"
734 subdirectory. This subdirectory contains the list of already defined
735 security groups for this target as well as file "mgmt". This file has
736 the following commands, which you can send to it, for instance, using
737 "echo" shell command. You can always get a small help about supported
738 commands by looking inside this file.
739
740  - "create GROUP_NAME" - creates a new security group.
741
742  - "del GROUP_NAME" - deletes a new security group.
743
744 Each security group's subdirectory contains 2 subdirectories: initiators
745 and luns.
746
747 Each "initiators" subdirectory contains list of added to this groups
748 initiator as well as as well as file "mgmt". This file has the following
749 commands, which you can send to it, for instance, using "echo" shell
750 command. You can always get a small help about supported commands by
751 looking inside this file.
752
753  - "add INITIATOR_NAME" - adds initiator with name INITIATOR_NAME to the
754    group.
755
756  - "del INITIATOR_NAME" - deletes initiator with name INITIATOR_NAME
757    from the group.
758
759  - "move INITIATOR_NAME DEST_GROUP_NAME" moves initiator with name
760    INITIATOR_NAME from the current group to group with name
761    DEST_GROUP_NAME.
762
763  - "clear" - deletes all initiators from this group.
764                                   
765 For "add" and "del" commands INITIATOR_NAME can be a simple DOS-type
766 patterns, containing '*' and '?' symbols. '*' means match all any
767 symbols, '?' means match only any single symbol. For instance,
768 "blah.xxx" will match "bl?h.*".
769
770 Each "luns" subdirectory contains the list of already defined LUNs for
771 this group as well as file "mgmt". Content of this file as well as list
772 of available in it commands is fully identical to the "luns"
773 subdirectory of the target-oriented access control.
774
775 Examples:
776
777  - echo "create INI" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/mgmt -
778    creates security group INI for target iqn.2006-10.net.vlnb:tgt1.
779
780  - echo "add 2:0:1:0 11" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI/luns/mgmt -
781    adds a pass-through device sitting on host 2, channel 0, ID 1, LUN 0
782    to group with name INI as LUN 11.
783
784  - echo "add disk1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI/luns/mgmt -
785    adds a virtual disk with name disk1 to group with name INI as LUN 0.
786
787  - echo "add 21:*:e0:?b:83:*" >/sys/kernel/scst_tgt/targets/21:00:00:a0:8c:54:52:12/ini_groups/INI/initiators/mgmt -
788    adds a pattern to group with name INI to Fibre Channel target with
789    WWN 21:00:00:a0:8c:54:52:12, which matches WWNs of Fibre Channel
790    initiator ports.
791
792 Consider you need to have an iSCSI target with name
793 "iqn.2007-05.com.example:storage.disk1.sys1.xyz", which should export
794 virtual device "dev1" with LUN 0 and virtual device "dev2" with LUN 1,
795 but initiator with name
796 "iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" should see only
797 virtual device "dev2" read only with LUN 0. To achieve that you should
798 do the following commands:
799
800 # echo "iqn.2007-05.com.example:storage.disk1.sys1.xyz" >/sys/kernel/scst_tgt/targets/iscsi/mgmt
801 # echo "add dev1 0" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/luns/mgmt
802 # echo "add dev2 1" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/luns/mgmt
803 # echo "create SPEC_INI" >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/ini_groups/mgmt
804 # echo "add dev2 0 read_only=1" \
805         >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/ini_groups/SPEC_INI/luns/mgmt
806 # echo "iqn.2007-05.com.example:storage.disk1.spec_ini.xyz" \
807         >/sys/kernel/scst_tgt/targets/iscsi/iqn.2007-05.com.example:storage.disk1.sys1.xyz/ini_groups/SPEC_INI/initiators/mgmt
808
809 For Fibre Channel or SAS in the above example you should use target's
810 and initiator ports WWNs instead of iSCSI names.
811
812 It is highly recommended to use scstadmin utility instead of described
813 in this section low level interface.
814
815 IMPORTANT
816 =========
817
818 There must be LUN 0 in each set of LUNs, i.e. LUs numeration must not
819 start from, e.g., 1. Otherwise you will see no devices on remote
820 initiators and SCST core will write into the kernel log message: "tgt_dev
821 for LUN 0 not found, command to unexisting LU?"
822
823 IMPORTANT
824 =========
825
826 All the access control must be fully configured BEFORE the corresponding
827 target is enabled! When you enable a target, it will immediately start
828 accepting new connections, hence creating new sessions, and those new
829 sessions will be assigned to security groups according to the
830 *currently* configured access control settings. For instance, to
831 the default target's set of LUNs, instead of "HOST004" group as you may
832 need, because "HOST004" doesn't exist yet. So, one must configure all
833 the security groups before new connections from the initiators are
834 created, i.e. before the target enabled.
835
836
837 VDISK device handler
838 --------------------
839
840 /proc interface
841 ~~~~~~~~~~~~~~~
842
843 This interface starting from version 2.0.0 is obsolete and will be
844 removed in one of the next versions.
845
846 After loading VDISK device handler creates in /proc/scsi_tgt/
847 subdirectories "vdisk" and "vcdrom". They have the following layout:
848
849   - "trace_level" and "type" files as described above
850
851   - "help" file, which provides online help for VDISK commands
852
853   - "vdisk"/"vcdrom" files, which on read provides information of
854     currently open device files. On write it supports the following
855     command:
856
857     * "open NAME [PATH] [BLOCK_SIZE] [FLAGS]" - opens file "PATH" as
858       device "NAME" with block size "BLOCK_SIZE" bytes with flags
859       "FLAGS". "PATH" could be empty only for VDISK CDROM. "BLOCK_SIZE"
860       and "FLAGS" are valid only for disk VDISK. The block size must be
861       power of 2 and >= 512 bytes. Default is 512. Possible flags:
862
863       - WRITE_THROUGH - write back caching disabled. Note, this option
864         has sense only if you also *manually* disable write-back cache
865         in *all* your backstorage devices and make sure it's actually
866         disabled, since many devices are known to lie about this mode to
867         get better benchmark results.
868
869       - READ_ONLY - read only
870
871       - O_DIRECT - both read and write caching disabled. This mode
872         isn't currently fully implemented, you should use user space
873         fileio_tgt program in O_DIRECT mode instead (see below).
874
875       - NULLIO - in this mode no real IO will be done, but success will be
876         returned. Intended to be used for performance measurements at the same
877         way as "*_perf" handlers.
878
879       - NV_CACHE - enables "non-volatile cache" mode. In this mode it is
880         assumed that the target has a GOOD UPS with ability to cleanly
881         shutdown target in case of power failure and it is
882         software/hardware bugs free, i.e. all data from the target's
883         cache are guaranteed sooner or later to go to the media. Hence
884         all data synchronization with media operations, like
885         SYNCHRONIZE_CACHE, are ignored in order to bring more
886         performance. Also in this mode target reports to initiators that
887         the corresponding device has write-through cache to disable all
888         write-back cache workarounds used by initiators. Use with
889         extreme caution, since in this mode after a crash of the target
890         journaled file systems don't guarantee the consistency after
891         journal recovery, therefore manual fsck MUST be ran. Note, that
892         since usually the journal barrier protection (see "IMPORTANT"
893         note below) turned off, enabling NV_CACHE could change nothing
894         from data protection point of view, since no data
895         synchronization with media operations will go from the
896         initiator. This option overrides WRITE_THROUGH.
897
898       - BLOCKIO - enables block mode, which will perform direct block
899         IO with a block device, bypassing page-cache for all operations.
900         This mode works ideally with high-end storage HBAs and for
901         applications that either do not need caching between application
902         and disk or need the large block throughput. See also below.
903
904       - REMOVABLE - with this flag set the device is reported to remote
905         initiators as removable.
906
907     * "close NAME" - closes device "NAME".
908
909     * "resync_size NAME" - refreshes size of device "NAME". Intended to be
910       used after device resize.
911
912     * "change NAME [PATH]" - changes a virtual CD in the VDISK CDROM.
913
914     * "set_t10_dev_id NAME T10_DEVICE_ID" - sets T10 vendor specific
915       identifier on Device Identification VPD page (0x83) of device
916       "NAME" in INQUIRY data. By default VDISK handler always generates
917       T10_DEVICE_ID for every new created device at creation time.
918       This parameter allows to overwrite generated by VDISK value of
919       T10_DEVICE_ID.
920
921 By default, if neither BLOCKIO, nor NULLIO option is supplied, FILEIO
922 mode is used.
923
924 For example, "echo "open disk1 /vdisks/disk1" >/proc/scsi_tgt/vdisk/vdisk"
925 will open file /vdisks/disk1 as virtual FILEIO disk with name "disk1".
926
927
928 /sys interface
929 ~~~~~~~~~~~~~~
930
931 Starting from 2.0.0 VDISK device handler has sysfs interface. You can
932 switch to it by running "make disable_proc". To switch back to the
933 procfs interface you should run "make enable_proc". The procfs interface
934 starting from version 2.0.0 is obsolete and will be removed in one of
935 the next versions.
936
937 VDISK has 4 built-in dev handlers: vdisk_fileio, vdisk_blockio,
938 vdisk_nullio and vcdrom. Roots of their sysfs interface are
939 /sys/kernel/scst_tgt/handlers/handler_name, e.g. for vdisk_fileio:
940 /sys/kernel/scst_tgt/handlers/vdisk_fileio. Each root has the following
941 entries:
942
943  - None, one or more links to devices with name equal to names
944    of the corresponding devices.
945
946  - trace_level - allows to enable and disable various tracing
947    facilities. See content of this file for help how to use it.
948
949  - mgmt - main management entry, which allows to add/delete VDISK
950    devices with the corresponding type.
951
952 The "mgmt" file has the following commands, which you can send to it,
953 for instance, using "echo" shell command. You can always get a small
954 help about supported commands by looking inside this file. "Parameters"
955 are one or more param_name=value pairs separated by ';'.
956
957  - echo "add_device device_name [parameters]" - adds a virtual device
958    with name device_name and specified parameters (see below)
959
960  - echo "del_device device_name" - deletes a virtual device with name
961    device_name.
962
963 Handler vdisk_fileio provides FILEIO mode to create virtual devices.
964 This mode uses as backend files and accesses to them using regular
965 read()/write() file calls. This allows to use full power of Linux page
966 cache. The following parameters possible for vdisk_fileio:
967
968  - filename - specifies path and file name of the backend file. The path
969    must be absolute.
970
971  - blocksize - specifies block size used by this virtual device. The
972    block size must be power of 2 and >= 512 bytes. Default is 512.
973
974  - write_through - disables write back caching. Note, this option
975    has sense only if you also *manually* disable write-back cache in
976    *all* your backstorage devices and make sure it's actually disabled,
977    since many devices are known to lie about this mode to get better
978    benchmark results. Default is 0.
979
980  - read_only - read only. Default is 0.
981
982  - o_direct - disables both read and write caching. This mode isn't
983    currently fully implemented, you should use user space fileio_tgt
984    program in O_DIRECT mode instead (see below).
985
986  - nv_cache - enables "non-volatile cache" mode. In this mode it is
987    assumed that the target has a GOOD UPS with ability to cleanly
988    shutdown target in case of power failure and it is software/hardware
989    bugs free, i.e. all data from the target's cache are guaranteed
990    sooner or later to go to the media. Hence all data synchronization
991    with media operations, like SYNCHRONIZE_CACHE, are ignored in order
992    to bring more performance. Also in this mode target reports to
993    initiators that the corresponding device has write-through cache to
994    disable all write-back cache workarounds used by initiators. Use with
995    extreme caution, since in this mode after a crash of the target
996    journaled file systems don't guarantee the consistency after journal
997    recovery, therefore manual fsck MUST be ran. Note, that since usually
998    the journal barrier protection (see "IMPORTANT" note below) turned
999    off, enabling NV_CACHE could change nothing from data protection
1000    point of view, since no data synchronization with media operations
1001    will go from the initiator. This option overrides "write_through"
1002    option. Disabled by default.
1003
1004  - removable - with this flag set the device is reported to remote
1005    initiators as removable.
1006
1007 Handler vdisk_blockio provides BLOCKIO mode to create virtual devices.
1008 This mode performs direct block I/O with a block device, bypassing the
1009 page cache for all operations. This mode works ideally with high-end
1010 storage HBAs and for applications that either do not need caching
1011 between application and disk or need the large block throughput. See
1012 below for more info.
1013
1014 The following parameters possible for vdisk_blockio: filename,
1015 blocksize, read_only, removable. See vdisk_fileio above for description
1016 of those parameters.
1017
1018 Handler vdisk_nullio provides NULLIO mode to create virtual devices. In
1019 this mode no real I/O is done, but success returned to initiators.
1020 Intended to be used for performance measurements at the same way as
1021 "*_perf" handlers. The following parameters possible for vdisk_nullio:
1022 blocksize, read_only, removable. See vdisk_fileio above for description
1023 of those parameters.
1024
1025 Handler vcdrom allows emulation of a virtual CDROM device using an ISO
1026 file as backend. It doesn't have any parameters.
1027
1028 For example:
1029
1030 echo "add_device disk1 filename=/disk1; blocksize=4096; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
1031
1032 will create a FILEIO virtual device disk1 with backend file /disk1   
1033 with block size 4K and NV_CACHE enabled.
1034
1035 Each vdisk_fileio's device has the following attributes in
1036 /sys/kernel/scst_tgt/devices/device_name:
1037
1038  - filename - contains path and file name of the backend file.
1039
1040  - blocksize - contains block size used by this virtual device.
1041
1042  - write_through - contains status of write back caching of this virtual
1043    device.
1044
1045  - read_only - contains read only status of this virtual device.
1046
1047  - o_direct - contains O_DIRECT status of this virtual device.
1048
1049  - nv_cache - contains NV_CACHE status of this virtual device.
1050
1051  - removable - contains removable status of this virtual device.
1052
1053  - size_mb - contains size of this virtual device in MB.
1054
1055  - t10_dev_id - contains and allows to set T10 vendor specific
1056    identifier for Device Identification VPD page (0x83) of INQUIRY data.
1057    By default VDISK handler always generates t10_dev_id for every new
1058    created device at creation time based on the device name and
1059    scst_vdisk_ID scst_vdisk.ko module parameter (see below).
1060
1061  - usn - contains the virtual device's serial number of INQUIRY data. It
1062    is created at the device creation time based on the device name and
1063    scst_vdisk_ID scst_vdisk.ko module parameter (see below).
1064
1065  - type - contains SCSI type of this virtual device.
1066
1067  - resync_size - write only attribute, which makes vdisk_fileio to
1068    rescan size of the backend file. It is useful if you changed it, for
1069    instance, if you resized it.
1070
1071 For example:
1072
1073 /sys/kernel/scst_tgt/devices/disk1
1074 |-- blocksize
1075 |-- exported
1076 |   |-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/0
1077 |   |-- export1 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/INI/luns/0
1078 |   |-- export2 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/0
1079 |   |-- export3 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI1/luns/0
1080 |   |-- export4 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI2/luns/0
1081 |-- filename
1082 |-- handler -> ../../handlers/vdisk_fileio
1083 |-- nv_cache
1084 |-- o_direct
1085 |-- read_only
1086 |-- removable
1087 |-- resync_size
1088 |-- size_mb
1089 |-- t10_dev_id
1090 |-- type
1091 |-- usn
1092 `-- write_through
1093
1094 Each vdisk_blockio's device has the following attributes in
1095 /sys/kernel/scst_tgt/devices/device_name: blocksize, filename,
1096 read_only, removable, resync_size, size_mb, t10_dev_id, type, usn. See
1097 description of vdisk_fileio's device for description of those parameters.
1098
1099 Each vdisk_nullio's device has the following attributes in
1100 /sys/kernel/scst_tgt/devices/device_name: blocksize, read_only,
1101 removable, size_mb, t10_dev_id, type, usn. See description
1102 of vdisk_fileio's device for description of those parameters.
1103
1104 Each vcdrom's device has the following attributes in
1105 /sys/kernel/scst_tgt/devices/device_name: filename,  size_mb,
1106 t10_dev_id, type, usn. See description of vdisk_fileio's device for
1107 description of those parameters. Exception is filename attribute. For
1108 vcdrom it is writable. Writing to it allows to virtually insert or
1109 change virtual CD media in the virtual CDROM device. For example:
1110
1111  - echo "/image.iso" >/sys/kernel/scst_tgt/devices/cdrom/filename - will
1112    insert file /image.iso as virtual media to the virtual CDROM cdrom.
1113
1114  - echo "" >/sys/kernel/scst_tgt/devices/cdrom/filename - will remove
1115    "media" from the virtual CDROM cdrom.
1116
1117 Additionally to the sysfs/procfs interface VDISK handler has module
1118 parameter "num_threads", which specifies count of I/O threads for each
1119 VDISK's device. If you have a workload, which tends to produce rather
1120 random accesses (e.g. DB-like), you should increase this count to a
1121 bigger value, like 32. If you have a rather sequential workload, you
1122 should decrease it to a lower value, like number of CPUs on the target
1123 or even 1. Due to some limitations of Linux I/O subsystem, increasing
1124 number of I/O threads too much leads to sequential performance drop,
1125 especially with deadline scheduler, so decreasing it can improve
1126 sequential performance. The default provides a good compromise between
1127 random and sequential accesses.
1128
1129 You shouldn't be afraid to have too many VDISK I/O threads if you have
1130 many VDISK devices. Kernel threads consume very little amount of
1131 resources (several KBs) and only necessary threads will be used by SCST,
1132 so the threads will not trash your system.
1133
1134 CAUTION: If you partitioned/formatted your device with block size X, *NEVER*
1135 ======== ever try to export and then mount it (even accidentally) with another
1136          block size. Otherwise you can *instantly* damage it pretty
1137          badly as well as all your data on it. Messages on initiator
1138          like: "attempt to access beyond end of device" is the sign of
1139          such damage.
1140
1141          Moreover, if you want to compare how well different block sizes
1142          work for you, you **MUST** EVERY TIME AFTER CHANGING BLOCK SIZE
1143          **COMPLETELY** **WIPE OFF** ALL THE DATA FROM THE DEVICE. In
1144          other words, THE **WHOLE** DEVICE **MUST** HAVE ONLY **ZEROS**
1145          AS THE DATA AFTER YOU SWITCH TO NEW BLOCK SIZE. Switching block
1146          sizes isn't like switching between FILEIO and BLOCKIO, after
1147          changing block size all previously written with another block
1148          size data MUST BE ERASED. Otherwise you will have a full set of
1149          very weird behaviors, because blocks addressing will be
1150          changed, but initiators in most cases will not have a
1151          possibility to detect that old addresses written on the device
1152          in, e.g., partition table, don't refer anymore to what they are
1153          intended to refer.
1154
1155 IMPORTANT: Some disk and partition table management utilities don't support
1156 =========  block sizes >512 bytes, therefore make sure that your favorite one
1157            supports it. Currently only cfdisk is known to work only with
1158            512 bytes blocks, other utilities like fdisk on Linux or
1159            standard disk manager on Windows are proved to work well with
1160            non-512 bytes blocks. Note, if you export a disk file or
1161            device with some block size, different from one, with which
1162            it was already partitioned, you could get various weird
1163            things like utilities hang up or other unexpected behavior.
1164            Hence, to be sure, zero the exported file or device before
1165            the first access to it from the remote initiator with another
1166            block size. On Window initiator make sure you "Set Signature"
1167            in the disk manager on the imported from the target drive
1168            before doing any other partitioning on it. After you
1169            successfully mounted a file system over non-512 bytes block
1170            size device, the block size stops matter, any program will
1171            work with files on such file system.
1172
1173
1174 Caching
1175 -------
1176
1177 By default for performance reasons VDISK FILEIO devices use write back
1178 caching policy. This is generally safe for modern applications who
1179 prepared to work in the write back caching environments, so know when to
1180 flush cache to keep their data consistent and minimize damage caused in
1181 case of power/hardware/software failures by lost in the cache data.
1182
1183 For instance, journaled file systems flush cache on each meta data
1184 update, so they survive power/hardware/software failures pretty well.
1185 Note, Linux IO subsystem guarantees it work reliably only using data
1186 protection barriers, which, for instance, for Ext3 turned off by default
1187 (see http://lwn.net/Articles/283161). Some info about barriers from the
1188 XFS point of view could be found at
1189 http://oss.sgi.com/projects/xfs/faq.html#wcache. On Linux initiators for
1190 Ext3 and ReiserFS file systems the barrier protection could be turned on
1191 using "barrier=1" and "barrier=flush" mount options correspondingly. You
1192 can check if the barriers turn on or off by looking in /proc/mounts.
1193 Windows and, AFAIK, other UNIX'es don't need any special explicit
1194 options and do necessary barrier actions on write-back caching devices
1195 by default. 
1196
1197 But even in case of journaled file systems your unsaved cached data will
1198 still be lost in case of power/hardware/software failures, so you may
1199 need to supply your target server with a good UPS with possibility to
1200 gracefully shutdown your target on power shortage or disable write back
1201 caching using WRITE_THROUGH flag. Note, on some real-life workloads
1202 write through caching might perform better, than write back one with the
1203 barrier protection turned on. Also note that without barriers enabled
1204 (i.e. by default) Linux doesn't provide a guarantee that after
1205 sync()/fsync() all written data really hit permanent storage. They can
1206 be stored in the cache of your backstorage devices and, hence, lost on a
1207 power failure event. Thus, ever with write-through cache mode, you still
1208 either need to enable barriers on your backend file system on the target
1209 (for devices this is, indeed, impossible), or need a good UPS to protect
1210 yourself from not committed data loss.
1211
1212 To limit this data loss you can use files in /proc/sys/vm to limit
1213 amount of unflushed data in the system cache.
1214
1215
1216 BLOCKIO VDISK mode
1217 ------------------
1218
1219 This module works best for these types of scenarios:
1220
1221 1) Data that are not aligned to 4K sector boundaries and <4K block sizes
1222 are used, which is normally found in virtualization environments where
1223 operating systems start partitions on odd sectors (Windows and it's
1224 sector 63).
1225
1226 2) Large block data transfers normally found in database loads/dumps and
1227 streaming media.
1228
1229 3) Advanced relational database systems that perform their own caching
1230 which prefer or demand direct IO access and, because of the nature of
1231 their data access, can actually see worse performance with
1232 non-discriminate caching.
1233
1234 4) Multiple layers of targets were the secondary and above layers need
1235 to have a consistent view of the primary targets in order to preserve
1236 data integrity which a page cache backed IO type might not provide
1237 reliably.
1238
1239 Also it has an advantage over FILEIO that it doesn't copy data between
1240 the system cache and the commands data buffers, so it saves a
1241 considerable amount of CPU power and memory bandwidth.
1242
1243 IMPORTANT: Since data in BLOCKIO and FILEIO modes are not consistent between
1244 =========  them, if you try to use a device in both those modes simultaneously,
1245            you will almost instantly corrupt your data on that device.
1246
1247
1248 Pass-through mode
1249 -----------------
1250
1251 In the pass-through mode (i.e. using the pass-through device handlers
1252 scst_disk, scst_tape, etc) SCSI commands, coming from remote initiators,
1253 are passed to local SCSI devices on target as is, without any
1254 modifications. 
1255
1256 In the SYSFS interface all real SCSI devices are listed in
1257 /sys/kernel/scst_tgt/devices in form host:channel:id:lun numbers, for
1258 instance 1:0:0:0. The recommended way to match those numbers to your
1259 devices is use of lsscsi utility.
1260
1261 When a pass-through dev handler is loaded it assigns itself to all
1262 existing SCSI devices of its SCSI type. If you later want to unassign some
1263 SCSI device from it or assign it to another dev handler you can use the
1264 following interface.
1265
1266 Each pass-through dev handler has in its root subdirectory
1267 /sys/kernel/scst_tgt/handlers/handler_name, e.g.
1268 /sys/kernel/scst_tgt/handlers/dev_disk, "mgmt" file. It allows the
1269 following commands. They can be sent to it using, e.g., echo command.
1270
1271  - "assign" - this command assigns SCSI device with
1272 host:channel:id:lun numbers to this dev handler.
1273
1274 echo "assign 1:0:0:0" >mgmt
1275
1276 will assign SCSI device 1:0:0:0 to this dev handler.
1277
1278  - "unassign" - this command unassigns SCSI device with
1279 host:channel:id:lun numbers from this dev handler.
1280
1281 As usually, on read the "mgmt" file returns small help about available
1282 commands.
1283
1284 As any other hardware, the local SCSI hardware can not handle commands
1285 with amount of data and/or segments count in scatter-gather array bigger
1286 some values. Therefore, when using the pass-through mode you should note
1287 that values for maximum number of segments and maximum amount of
1288 transferred data for each SCSI command on devices on initiators can not
1289 be bigger, than corresponding values of the corresponding SCSI devices
1290 on the target. Otherwise you will see symptoms like small transfers work
1291 well, but large ones stall and messages like: "Unable to complete
1292 command due to SG IO count limitation" are printed in the kernel logs.
1293  
1294 You can't control from the user space limit of the scatter-gather
1295 segments, but for block devices usually it is sufficient if you set on
1296 the initiators /sys/block/DEVICE_NAME/queue/max_sectors_kb in the same
1297 or lower value as in /sys/block/DEVICE_NAME/queue/max_hw_sectors_kb for
1298 the corresponding devices on the target.
1299
1300 For not-block devices SCSI commands are usually generated directly by
1301 applications, so, if you experience large transfers stalls, you should
1302 check documentation for your application how to limit the transfer
1303 sizes.
1304
1305 Another way to solve this issue is to build SG entries with more than 1
1306 page each. See the following patch as an example:
1307 http://scst.sf.net/sgv_big_order_alloc.diff
1308
1309
1310 User space mode using scst_user dev handler
1311 -------------------------------------------
1312
1313 User space program fileio_tgt uses interface of scst_user dev handler
1314 and allows to see how it works in various modes. Fileio_tgt provides
1315 mostly the same functionality as scst_vdisk handler with the most
1316 noticeable difference that it supports O_DIRECT mode. O_DIRECT mode is
1317 basically the same as BLOCKIO, but also supports files, so for some
1318 loads it could be significantly faster, than the regular FILEIO access.
1319 All the words about BLOCKIO from above apply to O_DIRECT as well. See
1320 fileio_tgt's README file for more details.
1321
1322
1323 Performance
1324 -----------
1325
1326 Before doing any performance measurements note that:
1327
1328 I. Performance results are very much dependent from your type of load,
1329 so it is crucial that you choose access mode (FILEIO, BLOCKIO,
1330 O_DIRECT, pass-through), which suits your needs the best.
1331
1332 II. In order to get the maximum performance you should:
1333
1334 1. For SCST:
1335
1336  - Disable in Makefile CONFIG_SCST_STRICT_SERIALIZING, CONFIG_SCST_EXTRACHECKS,
1337    CONFIG_SCST_TRACING, CONFIG_SCST_DEBUG*, CONFIG_SCST_STRICT_SECURITY
1338
1339  - For pass-through devices enable
1340    CONFIG_SCST_ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ.
1341
1342 2. For target drivers:
1343
1344  - Disable in Makefiles CONFIG_SCST_EXTRACHECKS, CONFIG_SCST_TRACING,
1345    CONFIG_SCST_DEBUG*
1346
1347 3. For device handlers, including VDISK:
1348
1349  - Disable in Makefile CONFIG_SCST_TRACING and CONFIG_SCST_DEBUG.
1350
1351
1352 IMPORTANT: Some of the above compilation options in the SCST SVN enabled by default,
1353 =========  i.e. development version of SCST is optimized currently rather for
1354            development and bug hunting, than for performance.
1355
1356 You can set the above options, except
1357 CONFIG_SCST_ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ, in the needed values
1358 using debug2perf root Makefile target.
1359
1360 4. For other target and initiator software parts:
1361
1362  - Make sure you applied on your kernel all available SCST patches,
1363    especially io_context-2.6.X.patch. If for your kernel version this
1364    patch doesn't exist, it is strongly recommended to upgrade your
1365    kernel to version, for which this patch exists.
1366
1367  - Don't enable debug/hacking features in the kernel, i.e. use them as
1368    they are by default.
1369
1370  - The default kernel read-ahead and queuing settings are optimized
1371    for locally attached disks, therefore they are not optimal if they
1372    attached remotely (SCSI target case), which sometimes could lead to
1373    unexpectedly low throughput. You should increase read-ahead size to at
1374    least 512KB or even more on all initiators and the target.
1375
1376    You should also limit on all initiators maximum amount of sectors per
1377    SCSI command. This tuning is also recommended on targets with large
1378    read-ahead values. To do it on Linux, run:
1379
1380    echo “64” > /sys/block/sdX/queue/max_sectors_kb
1381
1382    where specify instead of X your imported from target device letter,
1383    like 'b', i.e. sdb.
1384
1385    To increase read-ahead size on Linux, run:
1386
1387    blockdev --setra N /dev/sdX
1388
1389    where N is a read-ahead number in 512-byte sectors and X is a device
1390    letter like above.
1391
1392    Note: you need to set read-ahead setting for device sdX again after
1393    you changed the maximum amount of sectors per SCSI command for that
1394    device.
1395
1396    Note2: you need to restart SCST after you changed read-ahead settings
1397    on the target.
1398
1399  - You may need to increase amount of requests that OS on initiator
1400    sends to the target device. To do it on Linux initiators, run
1401
1402    echo “64” > /sys/block/sdX/queue/nr_requests
1403
1404    where X is a device letter like above.
1405
1406    You may also experiment with other parameters in /sys/block/sdX
1407    directory, they also affect performance. If you find the best values,
1408    please share them with us.
1409
1410  - On the target use CFQ IO scheduler. In most cases it has performance
1411    advantage over other IO schedulers, sometimes huge (2+ times
1412    aggregate throughput increase).
1413
1414  - It is recommended to turn the kernel preemption off, i.e. set
1415    the kernel preemption model to "No Forced Preemption (Server)".
1416
1417  - Looks like XFS is the best filesystem on the target to store device
1418    files, because it allows considerably better linear write throughput,
1419    than ext3.
1420
1421 5. For hardware on target.
1422
1423  - Make sure that your target hardware (e.g. target FC or network card)
1424    and underlaying IO hardware (e.g. IO card, like SATA, SCSI or RAID to
1425    which your disks connected) don't share the same PCI bus. You can
1426    check it using lspci utility. They have to work in parallel, so it
1427    will be better if they don't compete for the bus. The problem is not
1428    only in the bandwidth, which they have to share, but also in the
1429    interaction between cards during that competition. This is very
1430    important, because in some cases if target and backend storage
1431    controllers share the same PCI bus, it could lead up to 5-10 times
1432    less performance, than expected. Moreover, some motherboard (by
1433    Supermicro, particularly) have serious stability issues if there are
1434    several high speed devices on the same bus working in parallel. If
1435    you have no choice, but PCI bus sharing, set in the BIOS PCI latency
1436    as low as possible.
1437
1438 6. If you use VDISK IO module in FILEIO mode, NV_CACHE option will
1439 provide you the best performance. But using it make sure you use a good
1440 UPS with ability to shutdown the target on the power failure.
1441
1442 Baseline performance numbers you can find in those measurements:
1443 http://lkml.org/lkml/2009/3/30/283.
1444
1445 IMPORTANT: If you use on initiator some versions of Windows (at least W2K)
1446 =========  you can't get good write performance for VDISK FILEIO devices with
1447            default 512 bytes block sizes. You could get about 10% of the
1448            expected one. This is because of the partition alignment, which
1449            is (simplifying) incompatible with how Linux page cache
1450            works, so for each write the corresponding block must be read
1451            first. Use 4096 bytes block sizes for VDISK devices and you
1452            will have the expected write performance. Actually, any OS on
1453            initiators, not only Windows, will benefit from block size
1454            max(PAGE_SIZE, BLOCK_SIZE_ON_UNDERLYING_FS), where PAGE_SIZE
1455            is the page size, BLOCK_SIZE_ON_UNDERLYING_FS is block size
1456            on the underlying FS, on which the device file located, or 0,
1457            if a device node is used. Both values are from the target.
1458            See also important notes about setting block sizes >512 bytes
1459            for VDISK FILEIO devices above.
1460
1461 In some cases, for instance working with SSD devices, which consume 100%
1462 of a single CPU load for data transfers in their internal threads, to
1463 maximize IOPS it can be needed to assign for those threads dedicated
1464 CPUs using Linux CPU affinity facilities. No IRQ processing should be
1465 done on those CPUs. Check that using /proc/interrupts. See taskset
1466 command and Documentation/IRQ-affinity.txt in your kernel's source tree
1467 for how to assign IRQ affinity to tasks and IRQs.
1468
1469 The reason for that is that processing of coming commands in SIRQ
1470 context might be done on the same CPUs as SSD devices' threads doing data
1471 transfers. As the result, those threads won't receive all the processing
1472 power of those CPUs and perform worse.
1473
1474
1475 Work if target's backstorage or link is too slow
1476 ------------------------------------------------
1477
1478 Under high I/O load, when your target's backstorage gets overloaded, or
1479 working over a slow link between initiator and target, when the link
1480 can't serve all the queued commands on time, you can experience I/O
1481 stalls or see in the kernel log abort or reset messages.
1482
1483 At first, consider the case of too slow target's backstorage. On some
1484 seek intensive workloads even fast disks or RAIDs, which able to serve
1485 continuous data stream on 500+ MB/s speed, can be as slow as 0.3 MB/s.
1486 Another possible cause for that can be MD/LVM/RAID on your target as in
1487 http://lkml.org/lkml/2008/2/27/96 (check the whole thread as well).
1488
1489 Thus, in such situations simply processing of one or more commands takes
1490 too long time, hence initiator decides that they are stuck on the target
1491 and tries to recover. Particularly, it is known that the default amount
1492 of simultaneously queued commands (48) is sometimes too high if you do
1493 intensive writes from VMware on a target disk, which uses LVM in the
1494 snapshot mode. In this case value like 16 or even 8-10 depending of your
1495 backstorage speed could be more appropriate.
1496
1497 Unfortunately, currently SCST lacks dynamic I/O flow control, when the
1498 queue depth on the target is dynamically decreased/increased based on
1499 how slow/fast the backstorage speed comparing to the target link. So,
1500 there are 6 possible actions, which you can do to workaround or fix this
1501 issue in this case:
1502
1503 1. Ignore incoming task management (TM) commands. It's fine if there are
1504 not too many of them, so average performance isn't hurt and the
1505 corresponding device isn't getting put offline, i.e. if the backstorage
1506 isn't too slow.
1507
1508 2. Decrease /sys/block/sdX/device/queue_depth on the initiator in case
1509 if it's Linux (see below how) or/and SCST_MAX_TGT_DEV_COMMANDS constant
1510 in scst_priv.h file until you stop seeing incoming TM commands.
1511 ISCSI-SCST driver also has its own iSCSI specific parameter for that,
1512 see its README file.
1513
1514 To decrease device queue depth on Linux initiators you can run command:
1515
1516 # echo Y >/sys/block/sdX/device/queue_depth
1517
1518 where Y is the new number of simultaneously queued commands, X - your
1519 imported device letter, like 'a' for sda device. There are no special
1520 limitations for Y value, it can be any value from 1 to possible maximum
1521 (usually, 32), so start from dividing the current value on 2, i.e. set
1522 16, if /sys/block/sdX/device/queue_depth contains 32.
1523
1524 3. Increase the corresponding timeout on the initiator. For Linux it is
1525 located in
1526 /sys/devices/platform/host*/session*/target*:0:0/*:0:0:1/timeout. It can
1527 be done automatically by an udev rule. For instance, the following
1528 rule will increase it to 300 seconds:
1529
1530 SUBSYSTEM=="scsi", KERNEL=="[0-9]*:[0-9]*", ACTION=="add", ATTR{type}=="0|7|14", ATTR{timeout}="300"
1531
1532 By default, this timeout is 30 or 60 seconds, depending on your distribution.
1533
1534 4. Try to avoid such seek intensive workloads.
1535
1536 5. Increase speed of the target's backstorage.
1537
1538 6. Implement in SCST dynamic I/O flow control. This will be an ultimate
1539 solution. See "Dynamic I/O flow control" section on
1540 http://scst.sourceforge.net/contributing.html page for possible
1541 implementation idea.
1542
1543 Next, consider the case of too slow link between initiator and target,
1544 when the initiator tries to simultaneously push N commands to the target
1545 over it. In this case time to serve those commands, i.e. send or receive
1546 data for them over the link, can be more, than timeout for any single
1547 command, hence one or more commands in the tail of the queue can not be
1548 served on time less than the timeout, so the initiator will decide that
1549 they are stuck on the target and will try to recover.
1550
1551 To workaround/fix this issue in this case you can use ways 1, 2, 3, 6
1552 above or (7): increase speed of the link between target and initiator.
1553 But for some initiators implementations for WRITE commands there might
1554 be cases when target has no way to detect the issue, so dynamic I/O flow
1555 control will not be able to help. In those cases you could also need on
1556 the initiator(s) to either decrease the queue depth (way 2), or increase
1557 the corresponding timeout (way 3).
1558
1559 Note, that logged messages about QUEUE_FULL status are quite different
1560 by nature. This is a normal work, just SCSI flow control in action.
1561 Simply don't enable "mgmt_minor" logging level, or, alternatively, if
1562 you are confident in the worst case performance of your back-end storage
1563 or initiator-target link, you can increase SCST_MAX_TGT_DEV_COMMANDS in
1564 scst_priv.h to 64. Usually initiators don't try to push more commands on
1565 the target.
1566
1567
1568 Credits
1569 -------
1570
1571 Thanks to:
1572
1573  * Mark Buechler <mark.buechler@gmail.com> for a lot of useful
1574    suggestions, bug reports and help in debugging.
1575
1576  * Ming Zhang <mingz@ele.uri.edu> for fixes and comments.
1577
1578  * Nathaniel Clark <nate@misrule.us> for fixes and comments.
1579
1580  * Calvin Morrow <calvin.morrow@comcast.net> for testing and useful
1581    suggestions.
1582
1583  * Hu Gang <hugang@soulinfo.com> for the original version of the
1584    LSI target driver.
1585
1586  * Erik Habbinga <erikhabbinga@inphase-tech.com> for fixes and support
1587    of the LSI target driver.
1588
1589  * Ross S. W. Walker <rswwalker@hotmail.com> for the original block IO
1590    code and Vu Pham <huongvp@yahoo.com> who updated it for the VDISK dev
1591    handler.
1592
1593  * Michael G. Byrnes <michael.byrnes@hp.com> for fixes.
1594
1595  * Alessandro Premoli <a.premoli@andxor.it> for fixes
1596
1597  * Nathan Bullock <nbullock@yottayotta.com> for fixes.
1598
1599  * Terry Greeniaus <tgreeniaus@yottayotta.com> for fixes.
1600
1601  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes and bug reports.
1602
1603  * Jianxi Chen <pacers@users.sourceforge.net> for fixing problem with
1604    devices >2TB in size
1605
1606  * Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
1607
1608  * Daniel Debonzi <debonzi@linux.vnet.ibm.com> for a big part of SCST sysfs tree
1609    implementation
1610
1611
1612 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net