ba2803a8416f36a18c7ab3a922edf80f62f895bd
[mirror/scst/.git] / iscsi-scst / doc / iscsi-scst-howto.txt
1 How to set up iSCSI-SCST using scstadmin.
2
3 1. Download, build and install iSCSI-SCST.
4
5 Download the source code: 
6
7 Released version from http://sourceforge.net/project/showfiles.php?group_id=110471
8
9 or the latest development version by command:
10
11 svn co https://scst.svn.sourceforge.net/svnroot/scst/trunk
12
13 You need to patch the kernel and rebuild it. Only vanilla kernels from
14 kernel.org are officially supported, but in most cases your favorite
15 kernel will work fine as well. Select the patch according to your kernel
16 version (2.6.18.1 in the example below):
17
18 cd /usr/src/kernels/linux-2.6.18.1
19 patch -p1 < /home/erezz/work/scst/iscsi-scst/kernel/patches/put_page_callback-2.6.18.1.patch
20 patch -p1 < /home/erezz/work/scst/scst/kernel/scst_exec_req_fifo-2.6.18.patch
21 make clean
22
23 Then, build the kernel (i.e. make, make modules_install, make install)
24 and restart the machine.
25
26 In order to build and install SCST and iSCSI, run 
27
28 make scst scst_install iscsi iscsi_install
29
30 ISCSI-SCST includes the following components:
31    * /etc/init.d/iscsi-scst - service script
32    * iscsi-scstd - daemon
33    * iscsi-scst-adm - admin tool (not built in 1.0.0)
34    * man pages
35    * Configuration files (located under iscsi-scst/etc/, need to be copied to /etc if you want to use them):
36       * initiators.allow - used for assigning specific initiators to targets
37       * initiators.deny - used for assigning specific initiators to targets
38       * iscsi-scstd.conf - list of targets and their properties
39
40 2. Set up /etc/iscsi/ininitiatorname.iscsi. The most convenient way to
41 set up this file is to install the open-iscsi package provided by your
42 Linux distro first and then to run the bash commands shown below.
43 Verify the contents of the generated file.
44   /etc/init.d/open-iscsi stop
45   { echo "InitiatorName=$(/usr/sbin/iscsi-iname)"; echo "InitiatorAlias=$(hostname)"; } >/etc/iscsi/initiatorname.iscsi
46   /etc/init.d/open-iscsi start
47
48 3. Set up /etc/iscsi-scstd.conf, e.g. by running the following shell commands:
49   cat <<EOF >/etc/iscsi-scstd.conf
50   Target $(sed -n 's/InitiatorName=//p' /etc/iscsi/initiatorname.iscsi):storage
51   EOF
52
53 4. Set up /etc/scst.conf. The bash statements shown below set up a
54 configuration file for two vdisks. Replace the device names in the
55 array 'disk' by those that apply to your system:
56   {
57     echo "[HANDLER vdisk]"
58     echo "#DEVICE <vdisk name>,<device path>,<options>,<block size>"
59     disk=(/dev/md733 /dev/md734)
60     for ((i=0;i<${#disk[*]};i++))
61     do
62       echo "DEVICE vdisk$i,${disk[$i]},NV_CACHE,512"
63     done
64     echo "[ASSIGNMENT Default]"
65     echo "#DEVICE <device name>,<lun>"
66     for ((i=0;i<${#disk[*]};i++))
67     do
68       echo "DEVICE vdisk$i,$i"
69     done
70   } > /etc/scst.conf
71
72 Note, that you must have LUN 0. That's a SCSI requirement (documented in SCST's README).
73
74 5. Install scstadmin:
75   cd scstadmin-x.y.z
76   make install
77
78 6. Edit /etc/init.d/scst: remove the modules you do not need from the
79 SCST_MODULES variable, e.g. qla2x00tgt.
80
81 6. Create soft links in /etc/init.d such that SCST starts up
82 automatically. Use either chkconfig or update-rc.d, depending on the
83 Linux distribution you are using. An example for Debian systems:
84   update-rc.d scst defaults
85   update-rc.d iscsi-scst defaults
86
87 7. Restart SCST and iSCSI-SCST such that the new settings become effective:
88   /etc/init.d/iscsi-scst stop
89   /etc/init.d/scst stop
90   /etc/init.d/scst start
91   /etc/init.d/iscsi-scst start
92
93
94 How to install and use iSCSI-SCST without using scstadmin
95
96 First, start scst_disk: modprobe scst_disk
97
98 /etc/init.d/iscsi-scst can be used to start/stop/restart/check status.
99
100 Selecting devices to be used by SCST.
101
102 You can see the list of available devices:
103
104 # cat /proc/scsi_tgt/scsi_tgt
105 Device (host:ch:id:lun or name)                             Device handler
106 0:0:0:0                                                     dev_disk
107 1:0:0:0                                                     dev_disk
108 3:0:0:0                                                     dev_disk
109 3:0:0:1                                                     dev_disk
110 3:0:0:2                                                     dev_disk
111 3:0:0:3                                                     dev_disk
112 3:0:0:4                                                     dev_disk
113 3:0:0:5                                                     dev_disk
114 3:0:0:6                                                     dev_disk
115 3:0:0:7                                                     dev_disk
116 2:0:0:0                                                     none
117 4:0:0:0                                                     none
118 4:0:0:5                                                     dev_disk
119 4:0:0:6                                                     dev_disk
120 4:0:0:7                                                     dev_disk
121 4:0:0:8                                                     dev_disk
122 4:0:0:9                                                     dev_disk
123 4:0:1:0                                                     dev_disk
124 4:0:1:1                                                     dev_disk
125 4:0:1:2                                                     dev_disk
126 4:0:1:3                                                     dev_disk
127 4:0:1:4                                                     dev_disk
128 5:0:0:0                                                     none
129 5:0:0:5                                                     dev_disk
130 5:0:0:6                                                     dev_disk
131 5:0:0:7                                                     dev_disk
132 5:0:0:8                                                     dev_disk
133 5:0:0:9                                                     dev_disk
134 5:0:1:0                                                     dev_disk
135 5:0:1:1                                                     dev_disk
136 5:0:1:2                                                     dev_disk
137 5:0:1:3                                                     dev_disk
138 5:0:1:4                                                     dev_disk
139
140 LUN masking.
141
142 SCST defines security groups. For each group, you can add LUNs. 
143
144 If you want to have all LUNs available for all targets, just add them to
145 the "Default" group:
146
147 # echo "add 5:0:0:8 0" >/proc/scsi_tgt/groups/Default/devices
148 # cat /proc/scsi_tgt/groups/Default/devices
149 Device (host:ch:id:lun or name)                             Virtual lun  Options
150 5:0:0:8                                                        0
151
152 Now, the LUN "5:0:0:8" was added to the "Default" group as LUN #0.
153
154 Note, that you must have LUN 0. That's a SCSI requirement (documented in SCST's README).
155
156 Defining LUN masking
157
158 In order to associate specific LUNs with specific targets, do the following:
159
160    * Create a group for the target:
161
162 echo "add_group Default_iqn.2007-05.com.example:storage.iscsi-scst-1" >/proc/scsi_tgt/scsi_tgt
163
164    * Add LUNs to the group:
165
166 echo "add 4:0:0:8 0" > /proc/scsi_tgt/groups/Default_iqn.2007-05.com.example\:storage.iscsi-scst-1/devices
167
168 This will assign the LUN "4:0:0:8" to the target iqn.2007-05.com.example:storage.iscsi-scst-1.
169 Again, you must have LUN 0 for each group.
170
171 Deleting a LUN from a group
172
173 Run the following command:
174
175 echo "del 4:0:0:8 0" > /proc/scsi_tgt/groups/Default_iqn.2007-05.com.example\:storage.iscsi-scst-1/devices
176
177 This will remove the LUN "4:0:0:8" from the target iqn.2007-05.com.example:storage.iscsi-scst-1.
178
179 Deleting a group.
180
181 Run the following command:
182
183 echo "del_group Default_iqn.2007-05.com.example:storage.iscsi-scst-1" >/proc/scsi_tgt/scsi_tgt
184
185 For more information about LUN masking, refer to SCST README, section
186 "Access and devices visibility management (LUN masking)".
187
188 Creating targets using iscsi-scstd.conf.
189
190 The easiest way to create targets is to define them in
191 /etc/iscsi-scstd.conf. An example can be found in etc/iscsi-scstd.conf.
192 You need to have this file under /etc/ before starting iSCSI-SCST.
193
194 Assigning targets to specific initiators
195
196 In order to assign targets to specific initiators, you need to have
197 /etc/initiators.allow  and /etc/initiators.deny. You can find
198 example files in etc/initiators.allow and etc/initiators.deny.
199
200 Note that all targets are allowed to all initiators by default, so if
201 you want to use /etc/initiators.allow, you will need to have
202 /etc/initiators.deny that looks like this:
203
204 ALL ALL
205
206 This will deny all initiators expect for those defined in /etc/initiators.allow.
207
208 Useful examples of iscsi-scst-adm:
209
210 Show a specific target:
211
212 # iscsi-scst-adm --op show --tid=1
213 QueuedCommands=0
214
215 Show the configured parameters for a specific target:
216
217 # iscsi-scst-adm --op show --tid=1 --sid=0
218 InitialR2T=No
219 ImmediateData=
220 MaxConnections=0
221 MaxRecvDataSegmentLength=4269849632
222 MaxXmitDataSegmentLength=10933
223 MaxBurstLength=4294967295
224 FirstBurstLength=32767
225 DefaultTime2Wait=4203042
226 DefaultTime2Retain=5
227 MaxOutstandingR2T=0
228 DataPDUInOrder=No
229 DataSequenceInOrder=Yes
230 ErrorRecoveryLevel=0
231 HeaderDigest=
232 DataDigest=CRC32C
233 OFMarker=
234 IFMarker=No
235 OFMarkInt=Reject
236 IFMarkInt=Reject
237
238
239 Bart Van Assche
240 Erez Zilber
241 Vladislav Bolkhovitin