Updated version to 0.9.6 and Makefiles to bring the debug options back
[mirror/scst/.git] / scst / README
1 Generic SCSI target mid-level for Linux (SCST)
2 ==============================================
3
4 Version 0.9.6, XX XXX 200X
5 --------------------------
6
7 SCST is designed to provide unified, consistent interface between SCSI
8 target drivers and Linux kernel and simplify target drivers development
9 as much as possible. Detail description of SCST's features and internals
10 could be found in "Generic SCSI Target Middle Level for Linux" document
11 SCST's Internet page http://scst.sourceforge.net.
12
13 SCST looks to be quite stable (for beta) and useful. It supports disks
14 (SCSI type 0), tapes (type 1), processor (type 3), CDROM's (type 5), MO
15 disks (type 7), medium changers (type 8) and RAID controller (type 0xC)
16 as well as FILEIO and "performance" device handlers. In addition, it
17 supports advanced per-initiator access and devices visibility
18 management, so different initiators could see different set of devices
19 with different access permissions. See below for details.
20
21 This is quite stable (but still beta) version.
22
23 Tested mostly on "vanilla" 2.6.17.8 kernel from kernel.org.
24
25 Installation
26 ------------
27
28 At first, make sure that the link "/lib/modules/`you_kernel_version`/build" 
29 points to the source code for your currently running kernel.
30
31 Then, since in the mainstream kernels scsi_do_req()/scsi_execute_async()
32 work in LIFO order, instead of expected and required FIFO, SCST needs a
33 new functions scsi_do_req_fifo()/scsi_execute_async_fifo() to be added
34 in the kernel. Patch 26_scst-2.6.X.patch from "kernel" directory does
35 that. If it doesn't apply to your kernel, apply it manually, it only
36 adds one of those functions and nothing more. You may not patch the
37 kernel if STRICT_SERIALIZING or FILEIO_ONLY are defined during the
38 compilation (see their description below).
39
40 To compile SCST type 'make'. It will build SCST itself and its device
41 handlers. To install them type 'make install'. The driver modules will
42 be installed in '/lib/modules/`you_kernel_version`/extra'. In addition,
43 scsi_tgt.h, scst_debug.h and scst_debug.c will be copied to
44 '/usr/local/include/scst'. The first file contains all SCST's public
45 data definition, which are used by target drivers. The other ones
46 support debug messages logging.
47
48 Then you can load any module by typing 'modprobe drive_name'. The names are:
49
50  - scsi_tgt - SCST itself
51  - scst_disk - device handler for disks (type 0)
52  - scst_tape - device handler for tapes (type 1)
53  - scst_processor - device handler for processors (type 3)
54  - scst_cdrom - device handler for CDROMs (type 5)
55  - scst_modisk - device handler for MO disks (type 7)
56  - scst_changer - device handler for medium changers (type 8)
57  - scst_raid - device handler for storage array controller (e.g. raid) (type C)
58  - scst_fileio - device handler for FILE IO (disk or ISO CD image).
59
60 Then, to see your devices remotely, you need to add them to at least
61 "Default" security group (see below how). By default, no local devices
62 are seen remotely. There must be LUN 0 in each security group, i.e. LUs
63 numeration must not start from, e.g., 1.
64
65 IMPORTANT: Without loading appropriate device handler, corresponding devices
66 =========  will be invisible for remote initiators, which could lead to holes
67            in the LUN addressing, so automatic device scanning by remote SCSI 
68            mid-level could not notice the devices. Therefore you will have 
69            to add them manually via 
70            'echo "scsi add-single-device A 0 0 B" >/proc/scsi/scsi',
71            where A - is the host number, B - LUN.
72
73 IMPORTANT: In the current version simultaneous access to local SCSI devices
74 =========  via standard high-level SCSI drivers (sd, st, sg, etc.) and
75            SCST's target drivers is unsupported. Especially it is
76            important for execution via sg and st commands that change
77            the state of devices and their parameters, because that could
78            lead to data corruption. If any such command is done, at
79            least related device handler(s) must be restarted. For block
80            devices READ/WRITE commands using direct disk handler look to
81            be safe.
82
83 To uninstall, type 'make uninstall'.
84
85 If you install QLA2x00 target driver's source code in this directory,
86 then you can build, install or uninstall it by typing 'make qla', 'make
87 qla_install' or 'make qla_uninstall' correspondingly. For more details
88 about QLA2x00 target drivers see their README files.
89
90 Device handlers
91 ---------------
92
93 Device specific drivers (device handlers) are plugins for SCST, which
94 help SCST to analyze incoming requests and determine parameters,
95 specific to various types of devices. If an appropriate device handler
96 for a SCSI device type isn't loaded, SCST doesn't know how to handle
97 devices of this type, so they will be invisible for remote initiators
98 (more precisely, "LUN not supported" sense code will be returned).
99
100 In addition to device handlers for real devices, there are FILEIO and
101 "performance" ones.
102
103 FILEIO device handler works over files on file systems and makes from
104 them virtual remotely available SCSI disks or CDROM's. In addition, it
105 allows to work directly over a block device, e.g. local IDE or SCSI disk
106 or ever disk partition, where there is no file systems overhead. Using
107 block devices comparing to sending SCSI commands directly to SCSI
108 mid-level via scsi_do_req()/scsi_execute_async() has advantage that data
109 are transfered via system cache, so it is possible to fully benefit from
110 caching and read ahead performed by Linux's VM subsystem. The only
111 disadvantage here that there is superfluous data copying between the
112 cache and SCST's buffers. This issue is going to be addressed in the
113 next release. Virtual CDROM's are useful for remote installation. See
114 below for details how to setup and use FILEIO device handler.
115
116 "Performance" device handlers for disks, MO disks and tapes in their
117 exec() method skip (pretend to execute) all READ and WRITE operations
118 and thus provide a way for direct link performance measurements without
119 overhead of actual data transferring from/to underlying SCSI device.
120
121 NOTE: Since "perf" device handlers on READ operations don't touch the
122 ====  commands' data buffer, it is returned to remote initiators as it
123       was allocated, without even being zeroed. Thus, "perf" device
124       handlers impose some security risk, so use them with caution.
125
126 Compilation options
127 -------------------
128
129 There are the following compilation options, that could be commented
130 in/out in Makefile:
131
132  - FILEIO_ONLY - if defined, the pass-through device handlers
133    (scst_disk, scst_tape) will not work, but SCST will not require the
134    kernel patching. Defined by default to ease new people try SCST on
135    their kernels.
136
137  - DEBUG - turns on some debugging code, including some logging. Makes
138    the driver considerably bigger and slower, producing large amount of
139    log data.
140
141  - TRACING - turns on ability to log events. Makes the driver considerably
142    bigger and lead to some performance loss.
143
144  - EXTRACHECKS - adds extra validity checks in the various places.
145
146  - DEBUG_TM - turns on task management functions debugging, when on
147    LUN 0 in the "Default" group some of the commands will be delayed for
148    about 60 sec., so making the remote initiator send TM functions, eg
149    ABORT TASK and TARGET RESET. Also set TM_DBG_GO_OFFLINE symbol in the
150    Makefile to 1 if you want that the device eventually become
151    completely unresponsive, or to 0 otherwise to circle around ABORTs
152    and RESETs code. Needs DEBUG turned on.
153
154  - STRICT_SERIALIZING - makes SCST send all commands to underlying SCSI
155    device synchronously, one after one. This makes task management more
156    reliable, with cost of some performance penalty. This is mostly
157    actual for stateful SCSI devices like tapes, where the result of
158    command's execution depends from device's settings set by previous
159    commands. Disk and RAID devices are stateless in the most cases. The
160    current SCSI core in Linux doesn't allow to abort all commands
161    reliably if they sent asynchronously to a stateful device. Turned off
162    by default, turn it on if you use stateful device(s) and need as much
163    error recovery reliability as possible. As a side effect, no kernel
164    patching is necessary.
165
166  - SCST_HIGHMEM - if defined on HIGHMEM systems with 2.6 kernels, it
167    allows SCST to use HIGHMEM. This is very experimental feature and it
168    is unclear, if it brings something valuable, except some performance
169    hit, so in the current version it is disabled. Note, that
170    SCST_HIGHMEM isn't required for HIGHMEM systems and SCST will work
171    fine on them with SCST_HIGHMEM off. Untested.
172   
173  - SCST_STRICT_SECURITY - if defined, makes SCST clean allocated data
174    buffers. Undefining it (default) considerably improves performance
175    and eases CPU load, but could create a security hole (information
176    leakage), so enable it, if you have strict security requirements.
177
178 Module parameters
179 -----------------
180
181 Module scsi_tgt supports the following parameters:
182
183  - scst_threads - allows to set count of SCST's threads. By default it
184    is CPU count.
185
186  - scst_max_cmd_mem - sets maximum amount of memory in Mb allowed to be
187    consumed by the SCST commands for data buffers at any given time. By
188    default it is approximately TotalMem/4.
189
190 SCST "/proc" commands
191 ---------------------
192
193 For communications with user space programs SCST provides proc-based
194 interface in "/proc/scsi_tgt" directory. It contains the following
195 entries:
196
197   - "help" file, which provides online help for SCST commands
198   
199   - "scsi_tgt" file, which on read provides information of serving by SCST
200     devices and their dev handlers. On write it supports the following
201     command:
202     
203       * "assign H:C:I:L HANDLER_NAME" assigns dev handler "HANDLER_NAME" 
204         on device with host:channel:id:lun
205
206   - "sessions" file, which lists currently connected initiators (open sessions)
207
208   - "sgv" file provides some statistic about with which block sizes
209     commands from remote initiators come and how effective sgv_pool in
210     serving those allocations from the cache, i.e. without memory
211     allocations requests to the kernel. "Size" - is the commands data
212     size upper rounded to power of 2, "Hit" - how many there are
213     allocations from the cache, "Total" - total number of allocations.
214         
215   - "threads" file, which allows to read and set number of SCST's threads
216   
217   - "version" file, which shows version of SCST
218   
219   - "trace_level" file, which allows to read and set trace (logging) level
220     for SCST. See "help" file for list of trace levels.
221
222 Each dev handler has own subdirectory. Most dev handler have only two
223 files in this subdirectory: "trace_level" and "type". The first one is
224 similar to main SCST "trace_level" file, the latter one shows SCSI type
225 number of this handler as well as some text description.
226
227 For example, "echo "assign 1:0:1:0 dev_disk" >/proc/scsi_tgt/scsi_tgt"
228 will assign device handler "dev_disk" to real device sitting on host 1,
229 channel 0, ID 1, LUN 0.
230
231 Access and devices visibility management
232 ----------------------------------------
233
234 Access and devices visibility management allows for an initiator or
235 group of initiators to have different limited set of LUs/LUNs (security
236 group) each with appropriate access permissions. Initiator is
237 represented as a SCST session. Session is binded to security group on
238 its registration time by character "name" parameter of the registration
239 function, which provided by target driver, based on its internal
240 authentication. For example, for FC "name" could be WWN or just loop
241 ID. For iSCSI this could be iSCSI login credentials or iSCSI initiator
242 name. Each security group has set of names assigned to it by system
243 administrator. Session is binded to security group with provided name.
244 If no such groups found, the session binded to "Default" group.
245
246 In /proc/scsi_tgt each group represented as "groups/GROUP_NAME/"
247 subdirectory. In it there are files "devices" and "users". File
248 "devices" lists all devices and their LUNs in the group, file "users"
249 lists all names that should be binded to this group.
250
251 To configure access and devices visibility management SCST provides the
252 following files and directories under /proc/scsi_tgt:
253
254   - "add_group GROUP" to /proc/scsi_tgt/scsi_tgt adds group "GROUP"
255   
256   - "del_group GROUP" to /proc/scsi_tgt/scsi_tgt deletes group "GROUP"
257   
258   - "add H:C:I:L lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds 
259     device with host:channel:id:lun as LUN "lun" in group "GROUP". Optionally,
260     the device could be marked as read only.
261   
262   - "del H:C:I:L" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
263     host:channel:id:lun from group "GROUP"
264   
265   - "add V_NAME lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds
266     device with virtual name "V_NAME" as LUN "lun" in group "GROUP".
267     Optionally, the device could be marked as read only.
268   
269   - "del V_NAME" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
270     virtual name "V_NAME" from group "GROUP"
271   
272   - "clear" to /proc/scsi_tgt/groups/GROUP/devices clears the list of devices
273     for group "GROUP"
274   
275   - "add NAME" to /proc/scsi_tgt/groups/GROUP/names adds name "NAME" to group 
276     "GROUP"
277   
278   - "del NAME" to /proc/scsi_tgt/groups/GROUP/names deletes name "NAME" from group 
279     "GROUP"
280   
281   - "clear" to /proc/scsi_tgt/groups/GROUP/names clears the list of names
282     for group "GROUP"
283
284 Examples:
285
286  - "echo "add 1:0:1:0 0" >/proc/scsi_tgt/groups/Default/devices" will
287  add real device sitting on host 1, channel 0, ID 1, LUN 0 to "Default"
288  group with LUN 0.
289
290  - "echo "add disk1 1" >/proc/scsi_tgt/groups/Default/devices" will
291  add virtual FILEIO device with name "disk1" to "Default" group
292  with LUN 1. 
293
294 FILEIO device handler
295 ---------------------
296
297 After loading FILEIO device handler creates in "/proc/scsi_tgt/"
298 subdirectories "disk_fileio" and "cdrom_fileio". They have similar layout:
299
300   - "trace_level" and "type" files as described for other dev handlers
301   
302   - "help" file, which provides online help for FILEIO commands
303   
304   - "disk_fileio"/"cdrom_fileio" files, which on read provides
305     information of currently open device files. On write it supports the
306     following command:
307     
308     * "open NAME [PATH] [BLOCK_SIZE] [FLAGS]" - opens file "PATH" as
309       device "NAME" with block size "BLOCK_SIZE" bytes with flags
310       "FLAGS". "PATH" could be empty only for FILEIO CDROM. "BLOCK_SIZE"
311       and "FLAGS" are valid only for disk FILEIO. The block size must be
312       power of 2 and >= 512 bytes Default is 512. Possible flags:
313       
314       - WRITE_THROUGH - write back caching disabled
315       
316       - READ_ONLY - read only
317       
318       - O_DIRECT - both read and write caching disabled (doesn't work
319         currently).
320
321       - NULLIO - in this mode no real IO will be done, but success will be
322         returned. Intended to be used for performance measurements at the same
323         way as "*_perf" handlers.
324
325       - NV_CACHE - enables "non-volatile cache" mode. In this mode it is
326         assumed that the target has GOOD UPS and software/hardware bug
327         free, i.e. all data from the target's cache are guaranteed
328         sooner or later to go to the media, hence all data
329         synchronization with media operations, like SYNCHRONIZE_CACHE,
330         are ignored (BTW, so violating SCSI standard) in order to bring
331         a bit more performance. Use with extreme caution, since in this
332         mode after a crash of the target journaled file systems don't
333         guarantee the consistency after journal recovery, therefore
334         manual fsck MUST be ran. The main intent for it is to determine
335         the performance impact caused by the cache synchronization.
336         Note, that since usually the journal barrier protection (see
337         "IMPORTANT" below) turned off, enabling NV_CACHE could change
338         nothing, since no data synchronization with media operations
339         will go from the initiator.
340     
341     * "close NAME" - closes device "NAME".
342
343     * "change NAME [PATH]" - changes a virtual CD in the FILEIO CDROM.
344
345 For example, "echo "open disk1 /vdisks/disk1" >/proc/scsi_tgt/disk_fileio/disk_fileio"
346 will open file /vdisks/disk1 as virtual FILEIO disk with name "disk1".
347
348 IMPORTANT: By default for performance reasons FILEIO devices use write back
349 =========  caching policy. This is generally safe from the consistence of
350            journaled file systems, laying over them, point of view, but
351            your unsaved cached data will be lost in case of
352            power/hardware/software failure, so you must supply your
353            target server with some kind of UPS or disable write back
354            caching using WRITE_THROUGH flag. You also should note, that
355            the file systems journaling over write back caching enabled
356            devices works reliably *ONLY* if the order of journal writes
357            is guaranteed or it uses some kind of data protection
358            barriers (i.e. after writing journal data some kind of
359            synchronization with media operations is used), otherwise,
360            because of possible reordering in the cache, even after
361            successful journal rollback, you very much risk to loose your
362            data on the FS. Currently, Linux IO subsystem guarantees
363            order of write operations only using data protection
364            barriers. Some info about it from the XFS point of view could
365            be found at http://oss.sgi.com/projects/xfs/faq.html#wcache.
366            On Linux initiators for EXT3 and ReiserFS file systems the
367            barrier protection could be turned on using "barrier=1" and
368            "barrier=flush" mount options correspondingly. Note, that
369            usually it turned off by default and the status of barriers
370            usage isn't reported anywhere in the system logs as well as
371            there is no way to know it on the mounted file system (at
372            least no known one). Also note that on some real-life
373            workloads write through caching might perform better, than
374            write back one with the barrier protection turned on.
375
376 IMPORTANT: Many disk and partition table management utilities don't support
377 =========  block sizes >512 bytes, therefore make sure that your favorite one
378            supports it. Also, if you export disk file or device with
379            some block size, different from one, with which it was
380            already divided on partitions, you could get various weird
381            things like utilities hang up or other unexpected behavior.
382            Hence, to be sure, zero the exported file or device before the
383            first access to it from the remote initiator with another
384            block size.
385
386 Performance
387 -----------
388
389 Before doing any performance measurements note that:
390
391 I. Currently maximum performance is possible only with real SCSI devices
392 with several simultaneously executed commands (SCSI tagged queuing) or
393 performance handlers. If you have enough CPU power, FILEIO handler also
394 could provide the same results, when aggregate throughput is close to
395 the aggregate throughput locally on the target from the same disks. Also
396 note, that currently IO subsystem in Linux implemented on such way, so a
397 FILEIO device over a single file occupied entire formatted with some
398 file system device (eg /dev/hdc) could perform considerably better, than
399 a FILEIO device over /dev/hdc itself without the file system involved.
400
401 II. In order to get the maximum performance you should:
402
403 1. For SCST:
404
405  - Disable in Makefile STRICT_SERIALIZING, EXTRACHECKS, TRACING, DEBUG,
406    SCST_STRICT_SECURITY, SCST_HIGHMEM
407
408 2. For Qlogic target driver:
409
410  - Disable in Makefile EXTRACHECKS, TRACING, DEBUG_TGT, DEBUG_WORK_IN_THREAD
411
412 3. For device handlers, including FILEIO:
413
414  - Disable in Makefile TRACING, DEBUG
415
416 IMPORTANT: Some of those options enabled by default, i.e. SCST is optimized
417 =========  currently rather for development, not for performance.
418
419 4. For kernel:
420
421  - Don't enable debug/hacking features, i.e. use them as they are by
422    default.
423
424  - The default kernel read-ahead and queuing settings are optimized
425    for locally attached disks, therefore they are not optimal if they
426    attached remotely (our case), which sometimes could lead to
427    unexpectedly low throughput. You should increase read-ahead size
428    (/sys/block/device/queue/read_ahead_kb) to at least 256Kb or even
429    more on all initiators and the target. Also experiment with other
430    parameters in /sys/block/device directory, they also affect the
431    performance. If you find the best values, please share them with us.
432
433  - Also it is recommended to turn the kernel preemption off, i.e. set
434    the kernel preemption model to "No Forced Preemption (Server)".
435
436 5. For hardware.
437
438  - Make sure that your target hardware (e.g. target FC card) and underlaying
439    SCSI hardware (e.g. SCSI card to which your disks connected) stay on
440    different PCI buses. They will have to work in parallel, so it
441    will be better if they don't race for the bus. The problem is not
442    only in the bandwidth, which they have to share, but also in the
443    interaction between the cards during that competition. We have told
444    that in some cases it could lead to 5-10 times less performance, than
445    expected.
446
447 IMPORTANT: If you use on initiator some versions of Windows (at least W2K)
448 =========  you can't get good write performance for FILEIO devices with
449            default 512 bytes block sizes. You could get about 10% of the
450            expected one. This is because of "unusual" write access
451            pattern, with which Windows'es write data and which is
452            (simplifying) incompatible with how Linux page cache works,
453            so for each write the corresponding block must be read first.
454            With 4096 bytes block sizes for FILEIO devices the write
455            performance will be as expected. Actually, any system on
456            initiator, not only Windows, will benefit from block size
457            max(PAGE_SIZE, BLOCK_SIZE_ON_UNDERLYING_FS), where PAGE_SIZE
458            is the page size, BLOCK_SIZE_ON_UNDERLYING_FS is block size on
459            the underlying FS, on which the device file located, or 0, if
460            a device node is used. Both values are on the target.
461
462 Just for reference: we had with 0.9.2 and "old" Qlogic driver on 2.4.2x
463 kernel, where we did careful performance study, aggregate throughput
464 about 390 Mb/sec from 2 qla2300 cards sitting on different 64-bit PCI
465 buses and working simultaneously for two different initiators with
466 several simultaneously working load programs on each. From one card -
467 about 190 Mb/sec. We used tape_perf handler, so there was no influence
468 from underlying SCSI hardware, i.e. we measured only SCST/FC overhead.
469 The target computer configuration was not very modern for the moment:
470 something like 2x1GHz Intel P3 Xeon CPUs. You can estimate the
471 memory/PCI speed from that. CPU load was ~5%, there were ~30K IRQ/sec
472 and no additional SCST related context switches.
473
474 Credits
475 -------
476
477 Thanks to:
478
479  * Mark Buechler <mark.buechler@gmail.com> for a lot of useful
480    suggestions, bug reports and help in debugging.
481
482  * Ming Zhang <mingz@ele.uri.edu> for fixes and comments.
483  
484  * Nathaniel Clark <nate@misrule.us> for fixes and comments.
485
486  * Calvin Morrow <calvin.morrow@comcast.net> for testing and usful
487    suggestions.
488
489 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net