Merge with 1.0.1.x r731:
[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 -assigndev disk01 -group Default -lun 0
84   scstadmin -assigndev disk02 -group Default -lun 0
85   scstadmin -WriteConfig /etc/scst.conf
86   cat /etc/scst.conf
87
88 Note that for each SCSI device LUN 0 must exist. This is required by the SCSI
89 protocol and is also documented in SCST's README file.
90
91 5. Edit /etc/init.d/scst
92
93 Remove the modules you do not need from the SCST_MODULES variable,
94 e.g. qla2x00tgt.
95
96 6. Create soft links in /etc/init.d
97
98 This will make SCST to start automatically upon system boot. Use either
99 chkconfig or update-rc.d, depending on the Linux distribution you are using.
100 An example for Debian systems such as Ubuntu:
101
102   update-rc.d scst defaults
103   update-rc.d iscsi-scst defaults
104
105 On openSUSE you can let SCST start automatically through the following commands:
106
107   insserv scst
108   insserv iscsi-scst
109
110 7. Restart SCST and iSCSI-SCST
111
112 If you don't want to reboot now, you can make the above settings effective via
113 the following commands:
114
115   /etc/init.d/iscsi-scst stop
116   /etc/init.d/scst stop
117   /etc/init.d/scst start
118   /etc/init.d/iscsi-scst start
119
120
121 Installing and using iSCSI-SCST without using scstadmin
122 -------------------------------------------------------
123
124 First repeat steps 1, 2 and 3 from the previous section but leave out
125 "scstadm scstadm_install" from the make command in step 1.
126
127 Next load the scst_disk kernel module as follows:
128
129   modprobe scst_disk
130
131 The shell script /etc/init.d/iscsi-scst can now be used to start/stop/restart or
132 check the status of iSCSI-SCST.
133
134
135 Selecting devices to be used by SCST
136 ------------------------------------
137
138 You can see the list of available devices:
139
140 # cat /proc/scsi_tgt/scsi_tgt
141 Device (host:ch:id:lun or name)                             Device handler
142 0:0:0:0                                                     dev_disk
143 1:0:0:0                                                     dev_disk
144 3:0:0:0                                                     dev_disk
145 3:0:0:1                                                     dev_disk
146 3:0:0:2                                                     dev_disk
147 3:0:0:3                                                     dev_disk
148 3:0:0:4                                                     dev_disk
149 3:0:0:5                                                     dev_disk
150 3:0:0:6                                                     dev_disk
151 3:0:0:7                                                     dev_disk
152 2:0:0:0                                                     none
153 4:0:0:0                                                     none
154 4:0:0:5                                                     dev_disk
155 4:0:0:6                                                     dev_disk
156 4:0:0:7                                                     dev_disk
157 4:0:0:8                                                     dev_disk
158 4:0:0:9                                                     dev_disk
159 4:0:1:0                                                     dev_disk
160 4:0:1:1                                                     dev_disk
161 4:0:1:2                                                     dev_disk
162 4:0:1:3                                                     dev_disk
163 4:0:1:4                                                     dev_disk
164 5:0:0:0                                                     none
165 5:0:0:5                                                     dev_disk
166 5:0:0:6                                                     dev_disk
167 5:0:0:7                                                     dev_disk
168 5:0:0:8                                                     dev_disk
169 5:0:0:9                                                     dev_disk
170 5:0:1:0                                                     dev_disk
171 5:0:1:1                                                     dev_disk
172 5:0:1:2                                                     dev_disk
173 5:0:1:3                                                     dev_disk
174 5:0:1:4                                                     dev_disk
175
176
177 LUN masking
178 -----------
179
180 SCST defines security groups. For each group, you can add LUNs. 
181
182 If you want to have all LUNs available for all targets, just add them to
183 the "Default" group:
184
185 # echo "add 5:0:0:8 0" >/proc/scsi_tgt/groups/Default/devices
186 # cat /proc/scsi_tgt/groups/Default/devices
187 Device (host:ch:id:lun or name)                             Virtual lun  Options
188 5:0:0:8                                                        0
189
190 Now, the LUN "5:0:0:8" was added to the "Default" group as LUN #0.
191
192 Note, that you must have LUN 0. That's a SCSI requirement (documented in SCST's README).
193
194
195 Defining LUN masking
196 --------------------
197
198 In order to associate specific LUNs with specific targets, do the following:
199
200    * Create a group for the target:
201
202 echo "add_group Default_iqn.2007-05.com.example:storage.iscsi-scst-1" >/proc/scsi_tgt/scsi_tgt
203
204    * Add LUNs to the group:
205
206 echo "add 4:0:0:8 0" > /proc/scsi_tgt/groups/Default_iqn.2007-05.com.example\:storage.iscsi-scst-1/devices
207
208 This will assign the LUN "4:0:0:8" to the target iqn.2007-05.com.example:storage.iscsi-scst-1.
209 Again, you must have LUN 0 for each group.
210
211
212 Deleting a LUN from a group
213 ---------------------------
214
215 Run the following command:
216
217 echo "del 4:0:0:8 0" > /proc/scsi_tgt/groups/Default_iqn.2007-05.com.example\:storage.iscsi-scst-1/devices
218
219 This will remove the LUN "4:0:0:8" from the target iqn.2007-05.com.example:storage.iscsi-scst-1.
220
221
222 Deleting a group
223 ----------------
224
225 Run the following command:
226
227 echo "del_group Default_iqn.2007-05.com.example:storage.iscsi-scst-1" >/proc/scsi_tgt/scsi_tgt
228
229 For more information about LUN masking, refer to SCST README, section
230 "Access and devices visibility management (LUN masking)".
231
232
233 Creating targets using iscsi-scstd.conf
234 ---------------------------------------
235
236 The easiest way to create targets is to define them in
237 /etc/iscsi-scstd.conf. An example can be found in etc/iscsi-scstd.conf.
238 You need to have this file under /etc/ before starting iSCSI-SCST.
239
240
241 Assigning targets to specific initiators
242 ----------------------------------------
243
244 In order to assign targets to specific initiators, you need to have
245 /etc/initiators.allow  and /etc/initiators.deny. You can find
246 example files in etc/initiators.allow and etc/initiators.deny.
247
248 Note that all targets are allowed to all initiators by default, so if
249 you want to use /etc/initiators.allow, you will need to have
250 /etc/initiators.deny that looks like this:
251
252 ALL ALL
253
254 This will deny all initiators expect for those defined in /etc/initiators.allow.
255
256 Useful examples of iscsi-scst-adm:
257
258 Show a specific target:
259
260 # iscsi-scst-adm --op show --tid=1
261 QueuedCommands=0
262
263 Show the configured parameters for a specific target:
264
265 # iscsi-scst-adm --op show --tid=1 --sid=0
266 InitialR2T=No
267 ImmediateData=Yes
268 MaxConnections=1
269 MaxRecvDataSegmentLength=2097152
270 MaxXmitDataSegmentLength=131072
271 MaxBurstLength=2097152
272 FirstBurstLength=262144
273 DefaultTime2Wait=2
274 DefaultTime2Retain=0
275 MaxOutstandingR2T=1
276 DataPDUInOrder=Yes
277 DataSequenceInOrder=Yes
278 ErrorRecoveryLevel=0
279 HeaderDigest=None
280 DataDigest=None
281 OFMarker=No
282 IFMarker=No
283 OFMarkInt=Reject
284 IFMarkInt=Reject
285
286
287 Bart Van Assche
288 Erez Zilber
289 Vladislav Bolkhovitin