The patch below implements the following changes for the iSCSI-SCST HOWTO
[mirror/scst/.git] / iscsi-scst / doc / iscsi-scst-howto.txt
1 Installing and using iSCSI-SCST with scstadmin
2 ----------------------------------------------
3
4 1. Download, build and install iSCSI-SCST.
5
6 Start with downloading the iSCSI-SCST source code. You can either download the
7 released version from the following URL:
8
9   http://sourceforge.net/project/showfiles.php?group_id=110471
10
11 or you can download the latest development version by running the following
12 command in a shell:
13
14   svn co https://scst.svn.sourceforge.net/svnroot/scst/trunk scst
15
16 While iSCSI-SCST works fine with an unpatched Linux kernel with the same
17 or better speed as other open source iSCSI targets, including IET, if
18 you want even better performance you have to patch and rebuild the
19 kernel. Select the patch according to your kernel version (2.6.18.1 in
20 the example below):
21
22   cd /usr/src/kernels/linux-2.6.18.1
23   patch -p1 < $HOME/scst/iscsi-scst/kernel/patches/put_page_callback-2.6.18.1.patch
24   patch -p1 < $HOME/scst/scst/kernel/scst_exec_req_fifo-2.6.18.patch
25   make clean
26
27 Next, build and install the kernel:
28
29   make && make modules
30   make modules_install && make install
31
32 For some Linux distributions (a.o. Ubuntu and openSUSE) the above steps do not
33 rebuild the initial RAM disk. Make sure you regenerate the RAM disk before
34 rebooting. Please look up the documentation of the update-initrd,
35 update-initramfs or the mkinitrd command supplied with your distribution.
36
37 Now reboot the system.
38
39 Once the system is again up and running the next step is to build and install
40 SCST, iSCSI-SCST and scstadmin. You can do this by running the following
41 command from the SCST directory:
42
43   make scst scst_install iscsi iscsi_install scstadm scstadm_install
44
45 iSCSI-SCST includes the following components:
46    * /etc/init.d/iscsi-scst - service script
47    * iscsi-scstd - daemon
48    * man pages
49    * Configuration files (located under iscsi-scst/etc/, need to be copied to
50      /etc if you want to use them):
51       * initiators.allow - used for assigning specific initiators to targets
52       * initiators.deny - used for assigning specific initiators to targets
53       * iscsi-scstd.conf - list of targets and their properties
54
55 2. Set up /etc/iscsi/ininitiatorname.iscsi
56
57 The most convenient way to set up this file is to install the open-iscsi
58 package provided by your Linux distro first and then to run the shell commands
59 shown below. Verify the contents of the generated file.
60
61   /etc/init.d/open-iscsi stop
62   { echo "InitiatorName=$(/usr/sbin/iscsi-iname)"; echo "InitiatorAlias=$(hostname)"; } >/etc/iscsi/initiatorname.iscsi
63   /etc/init.d/open-iscsi start
64   cat /etc/iscsi/initiatorname.iscsi
65
66 3. Set up /etc/iscsi-scstd.conf
67
68 You can do this by e.g. running the following shell commands:
69
70   echo "Target $(sed -n 's/InitiatorName=//p' /etc/iscsi/initiatorname.iscsi):storage" >/etc/iscsi-scstd.conf
71   cat /etc/iscsi-scstd.conf
72
73 4. Set up /etc/scst.conf
74
75 The scst.conf configuration file is loaded at system boot time by the shell
76 script /etc/init.d/scst. All devices known by SCST are defined in this file.
77 The shell statements shown below set up a configuration file for two vdisks.
78 Replace the device names by names that apply to your system:
79
80   scstadmin -ClearConfig /etc/scst.conf
81   scstadmin -adddev disk01 -path /dev/ram0 -handler vdisk -options NV_CACHE
82   scstadmin -adddev disk02 -path /dev/ram1 -handler vdisk -options NV_CACHE
83   scstadmin -WriteConfig /etc/scst.conf
84   cat /etc/scst.conf
85
86 Note that for each SCSI device LUN 0 must exist. This is required by the SCSI
87 protocol and is also documented in SCST's README file.
88
89 5. Edit /etc/init.d/scst
90
91 Remove the modules you do not need from the SCST_MODULES variable,
92 e.g. qla2x00tgt.
93
94 6. Create soft links in /etc/init.d
95
96 This will make SCST to start automatically upon system boot. Use either
97 chkconfig or update-rc.d, depending on the Linux distribution you are using.
98 An example for Debian systems such as Ubuntu:
99
100   update-rc.d scst defaults
101   update-rc.d iscsi-scst defaults
102
103 On openSUSE you can let SCST start automatically through the following commands:
104
105   insserv scst
106   insserv iscsi-scst
107
108 7. Restart SCST and iSCSI-SCST
109
110 If you don't want to reboot now, you can make the above settings effective via
111 the following commands:
112
113   /etc/init.d/iscsi-scst stop
114   /etc/init.d/scst stop
115   /etc/init.d/scst start
116   /etc/init.d/iscsi-scst start
117
118
119 Installing and using iSCSI-SCST without using scstadmin
120 -------------------------------------------------------
121
122 First repeat steps 1, 2 and 3 from the previous section but leave out
123 "scstadm scstadm_install" from the make command in step 1.
124
125 Next load the scst_disk kernel module as follows:
126
127   modprobe scst_disk
128
129 The shell script /etc/init.d/iscsi-scst can now be used to start/stop/restart or
130 check the status of iSCSI-SCST.
131
132
133 Selecting devices to be used by SCST
134 ------------------------------------
135
136 You can see the list of available devices:
137
138 # cat /proc/scsi_tgt/scsi_tgt
139 Device (host:ch:id:lun or name)                             Device handler
140 0:0:0:0                                                     dev_disk
141 1:0:0:0                                                     dev_disk
142 3:0:0:0                                                     dev_disk
143 3:0:0:1                                                     dev_disk
144 3:0:0:2                                                     dev_disk
145 3:0:0:3                                                     dev_disk
146 3:0:0:4                                                     dev_disk
147 3:0:0:5                                                     dev_disk
148 3:0:0:6                                                     dev_disk
149 3:0:0:7                                                     dev_disk
150 2:0:0:0                                                     none
151 4:0:0:0                                                     none
152 4:0:0:5                                                     dev_disk
153 4:0:0:6                                                     dev_disk
154 4:0:0:7                                                     dev_disk
155 4:0:0:8                                                     dev_disk
156 4:0:0:9                                                     dev_disk
157 4:0:1:0                                                     dev_disk
158 4:0:1:1                                                     dev_disk
159 4:0:1:2                                                     dev_disk
160 4:0:1:3                                                     dev_disk
161 4:0:1:4                                                     dev_disk
162 5:0:0:0                                                     none
163 5:0:0:5                                                     dev_disk
164 5:0:0:6                                                     dev_disk
165 5:0:0:7                                                     dev_disk
166 5:0:0:8                                                     dev_disk
167 5:0:0:9                                                     dev_disk
168 5:0:1:0                                                     dev_disk
169 5:0:1:1                                                     dev_disk
170 5:0:1:2                                                     dev_disk
171 5:0:1:3                                                     dev_disk
172 5:0:1:4                                                     dev_disk
173
174
175 LUN masking
176 -----------
177
178 SCST defines security groups. For each group, you can add LUNs. 
179
180 If you want to have all LUNs available for all targets, just add them to
181 the "Default" group:
182
183 # echo "add 5:0:0:8 0" >/proc/scsi_tgt/groups/Default/devices
184 # cat /proc/scsi_tgt/groups/Default/devices
185 Device (host:ch:id:lun or name)                             Virtual lun  Options
186 5:0:0:8                                                        0
187
188 Now, the LUN "5:0:0:8" was added to the "Default" group as LUN #0.
189
190 Note, that you must have LUN 0. That's a SCSI requirement (documented in SCST's README).
191
192
193 Defining LUN masking
194 --------------------
195
196 In order to associate specific LUNs with specific targets, do the following:
197
198    * Create a group for the target:
199
200 echo "add_group Default_iqn.2007-05.com.example:storage.iscsi-scst-1" >/proc/scsi_tgt/scsi_tgt
201
202    * Add LUNs to the group:
203
204 echo "add 4:0:0:8 0" > /proc/scsi_tgt/groups/Default_iqn.2007-05.com.example\:storage.iscsi-scst-1/devices
205
206 This will assign the LUN "4:0:0:8" to the target iqn.2007-05.com.example:storage.iscsi-scst-1.
207 Again, you must have LUN 0 for each group.
208
209
210 Deleting a LUN from a group
211 ---------------------------
212
213 Run the following command:
214
215 echo "del 4:0:0:8 0" > /proc/scsi_tgt/groups/Default_iqn.2007-05.com.example\:storage.iscsi-scst-1/devices
216
217 This will remove the LUN "4:0:0:8" from the target iqn.2007-05.com.example:storage.iscsi-scst-1.
218
219
220 Deleting a group
221 ----------------
222
223 Run the following command:
224
225 echo "del_group Default_iqn.2007-05.com.example:storage.iscsi-scst-1" >/proc/scsi_tgt/scsi_tgt
226
227 For more information about LUN masking, refer to SCST README, section
228 "Access and devices visibility management (LUN masking)".
229
230
231 Creating targets using iscsi-scstd.conf
232 ---------------------------------------
233
234 The easiest way to create targets is to define them in
235 /etc/iscsi-scstd.conf. An example can be found in etc/iscsi-scstd.conf.
236 You need to have this file under /etc/ before starting iSCSI-SCST.
237
238
239 Assigning targets to specific initiators
240 ----------------------------------------
241
242 In order to assign targets to specific initiators, you need to have
243 /etc/initiators.allow  and /etc/initiators.deny. You can find
244 example files in etc/initiators.allow and etc/initiators.deny.
245
246 Note that all targets are allowed to all initiators by default, so if
247 you want to use /etc/initiators.allow, you will need to have
248 /etc/initiators.deny that looks like this:
249
250 ALL ALL
251
252 This will deny all initiators expect for those defined in /etc/initiators.allow.
253
254 Useful examples of iscsi-scst-adm:
255
256 Show a specific target:
257
258 # iscsi-scst-adm --op show --tid=1
259 QueuedCommands=0
260
261 Show the configured parameters for a specific target:
262
263 # iscsi-scst-adm --op show --tid=1 --sid=0
264 InitialR2T=No
265 ImmediateData=
266 MaxConnections=0
267 MaxRecvDataSegmentLength=4269849632
268 MaxXmitDataSegmentLength=10933
269 MaxBurstLength=4294967295
270 FirstBurstLength=32767
271 DefaultTime2Wait=4203042
272 DefaultTime2Retain=5
273 MaxOutstandingR2T=0
274 DataPDUInOrder=No
275 DataSequenceInOrder=Yes
276 ErrorRecoveryLevel=0
277 HeaderDigest=
278 DataDigest=CRC32C
279 OFMarker=
280 IFMarker=No
281 OFMarkInt=Reject
282 IFMarkInt=Reject
283
284
285 Bart Van Assche
286 Erez Zilber
287 Vladislav Bolkhovitin