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