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