README
1
2---------------------------------------
3Intel iSCSI v20 Reference Implementation
4---------------------------------------
5
6This is a software implementation of iSCSI v20. Included in this distribution
7are both host and target mode drivers with built in conformance and performance
8tests, and sockets tests that can be used to simulate TCP traffic identical to
9that generated between a real iSCSI host and target.
10
11See PERFORMANCE for information regarding the expected performance of this
12distribution.
13
14This code has been successfully compiled and tested on Redhat 8.0
15(kernel version 2.4.18-14) and Redhat 9.0 (kernel version 2.4.20)
16with UP and SMP configurations.
17
18-------------------
19Starting the System
20-------------------
21
221a) Modify the array in initiator.c to contain your target ip addresses and port
23 numbers. If you specify a TargetName there will be no discovery process. For
24 example, targets 0 and 2 below will first be discovered. Target 1 will not.
25 ISCSI_PORT is the default port defined in iscsi.h and currently set to 3260.
26
27 static INITIATOR_TARGET_T g_target[CONFIG_INITIATOR_NUM_TARGETS] = {
28 {"192.168.10.10", ISCSI_PORT, "", NULL, 0},
29 {"192.168.10.11", ISCSI_PORT, "iqn.com.intel.abc123", NULL, 0},
30 {"192.168.10.12", ISCSI_PORT, "", NULL, 0}};
31
32 The initiator currently only connects to one of the discovered targets. If
33 multiple TargetNames and TargetAddresses are returned, all but 1 are ignored.
34
351b) Alternately for the kernel mode driver you may specify ip addresses
36 in a file in the local directory called "./intel_iscsi_targets". This
37 file will also be looked for in the /etc directory or you may specify
38 the file name as a module parameter to the insmod command using the
39 "gfilename" argument, (insmod intel_iscsi.o gfilename="./targets").
40 The format for the contents of of the file is:
41 ip=192.168.10.10
42 ip=192.168.10.11 name=iqn.com.intel.abc123 port=3260
43 ip=192.168.10.12
44 The name and port fields are optional. If name is not specified, there
45 will be a discovery process. If port is not specified, the default port
46 of 3260 will be used.
47
481c) For the user mode intiator, if the first entry of the g_target array has ip
49 address "151.0.1.1", the initiator will prompt the user to enter the number
50 of targets and their ip addresses.
51
522) Modify the following constant in initiator.h accordingly:
53
54 #define CONFIG_INITIATOR_NUM_TARGETS 3
55
563) Run "make" to build each of:
57
58 intel_iscsi.o - kernel mode iSCSI initiator
59 kramdisk.o - kernel mode iSCSI target ramdisk
60 ufsdisk - user mode iSCSI target (disk stored as file in /tmp)
61 ufsdisk_mmap - same as ufsdisk, but uses mmap
62 uramdisk - user mode iSCSI ramdisk
63 utest - user mode iSCSI test suite
64 ktest - invokes same tests as utest, but from within device driver
65 usocktest - user mode sockets test that simulates iSCSI traffic
66
674) Start a user level target (uramdisk, ufsdisk, ufsdisk_mmap) on each target
68 machine:
69
70 Usage: -t <name> iSCSI TargetName (dflt "iqn.com.intel.abc123")
71 -p <port> Port Number (dflt 3260)
72 -b <block len> Block Length (dflt 512)
73 -n <num blocks> Number of Blocks (dflt 204800)
74
75
76 Or start the kernel level target (kramdisk.o):
77
78 Usage: insmod kramdisk.o port=<port>
79 block_len=<block length>
80 num_blocks=<number of blocks>
81
82
83 With ufsdisk and ufsdisk_mmap you can directly access a device in /dev by
84 creating a symbolic link in /tmp to point to the appropriate device. For
85 example:
86
87 "ln -s /dev/sdd /tmp/iqn.com.intel.abc123_3260_iscsi_disk_lun_0"
88
89 And kramdisk.o only operates in ramdisk mode.
90
915) Run utest. If you did not successfully connect to each target machine you
92 specified in initiator.c, then there was a problem. Make sure initiator.h
93 and initiator.c were correctly edited and all your targets had been started.
94
956) As root, run "insmod ./intel_iscsi.o." You should see output similar to the
96 following when either viewing /var/log/messages or running dmesg:
97
98 *********************************************
99 * PARAMETERS NEGOTIATED *
100 * *
101 * InitiatorName: Intel *
102 * InitiatorAlias: Intel *
103 * SessionType: normal *
104 * TargetName: iqn.com.intel.abc12 *
105 *********************************************
106 *********************************************
107 * LOGIN SUCCESSFUL *
108 * *
109 * CID: 0 *
110 * ISID: 0 *
111 * TSID: 1 *
112 * CmdSN: 0 *
113 * MaxCmdSN: 0 *
114 * ExpStatSN: 0 *
115 *********************************************
116 Vendor: Intel Model: Intel Labs iSCSI Rev: 2
117 Type: Direct-Access ANSI SCSI revision: 02
118 Detected scsi disk sdb at scsi2, channel 0, id 0, lun 0
119 SCSI device sdb: 204800 512-byte hdwr sectors (105 MB)
120 sdb: unknown partition table
121
122 You can now use the device as you would any other SCSI device. You can also
123 view driver statistics by viewing the file in /proc/scsi/iscsi. Writing to
124 the file (e.g. echo reset > /proc/scsi/iscsi/1) will reset all counters.
125
126------------------
127Testing the System
128------------------
129
130Once your targets and host have been started, you can test the installation
131using either a single target, or by creating a RAID volume over multiple
132targets.
133
134To test a single target you can either directly read and write the device by
135opening, for example, /dev/sdd. Or you can create a filesystem on the device:
136
137 fdisk /dev/sdd
138 mkfs /dev/sdd1
139 mount -t ext2 /dev/sdd1 /mnt/iscsi_fs
140
141To test a multiple target installation, you can create a RAID volume,
142virtualizing multiple targets as one SCSI device. The Linux RAID modules
143will either need to be installed or compiled into the kernel. The file
144/etc/raidtab must be created to reflect your targets. For example,
145
146 raiddev /dev/md0
147 raid-level 0
148 nr-raid-disks 5
149 persistent-superblock 0
150 chunk-size 64
151
152 device /dev/sdd
153 raid-disk 0
154 device /dev/sde
155 raid-disk 1
156 device /dev/sdf
157 raid-disk 2
158 device /dev/sdg
159 raid-disk 3
160 device /dev/sdh
161 raid-disk 4
162
163
164After initialized the raid device with "mkraid /dev/md0," you can use /dev/md0
165as though it were a normal SCSI device. For example,
166
167 mkfs /dev/md0
168 mount -t ext2 /dev/md0 /mnt/iscsi_fs
169
170--------------------
171When Things Go Wrong
172--------------------
173
174Check the kernel error messages /var/log/messages or run the dmesg command to
175see any errors reported from the host driver. The targets will report target
176errors to standard output.
177
178If you need more fine grained debugging, modify the Makefile to turn on the
179compilation flag CONFIG_ISCSI_DEBUG. Then run "make clean," and then "make."
180You can select which type of debugging statements get printed by modifying
181iscsiutil.h
182
183-------------------------------------
184Interoperability with Cisco Initiator
185-------------------------------------
186
187The target is tested to be interoperable with Cisco Initiator release
1883.4.1.1
189
README_OSD
1
2-------------------------
3Installing the OSD System
4-------------------------
5
6 1. Build kernel version 2.4 w/ SMP mode disabled and make sure the
7 directory /usr/src/linux points to this build.
8 2. Modify initiator.h and initiator.c (as per the README) to point to
9 your intended target.
10 3. Run 'make osd' to build all the OSD executables. In particular,
11 you need uosd, so.o, intel_iscsi.o and osdfs.o.
12 4. Run 'make all' to build the remaining executables.
13 5. Select a machine as the target and run "uosd -f" as root on this
14 machine. This will create files and directories in /tmp.
15
16----------------------
17Testing the OSD System
18----------------------
19
20 6. Run utest to make sure the target is working OK.
21 7. Do an "insmod ./so.o" to install the Linux SCSI upper layer driver for OSD.
22 8. Do an "insmod ./intel_iscsi.o" to install the kernel mode iSCSI initiator.
23 9. Do an "insmod ./osdfs.o" to install the file system.
2410. Make the OSD device with "mknod /dev/so0 b 232 0".
2511. Do a "mount -t osdfs /dev/so0 /mnt" to mount the filesystem.
2612. Go to /mnt and run "echo Hello, World! > foo" to create an object
27 on the OSD.
2813. Do a "cat foo" to read the object. you should see "Hello, world!"
29
30From here you should be able to use /mnt as you would any filesystem.
31
32--------------------
332.4.18 Modifications
34--------------------
35
36include/scsi/scsi.h:143
37 #define TYPE_OSD 0x0e
38
39drivers/scsi/scsi.h:92:
40 #define MAX_SCSI_DEVICE_CODE 15
41
42drivers/scsi/scsi.h:354:
43 #define MAX_COMMAND_SIZE 256
44
45drivers/scsi/scsi.c:145:
46 "OSD ",
47
48drivers/scsi/scsi_dma.c:248:
49 SDpnt->type == TYPE_DISK || SDpnt->type == TYPE_MOD || SDpnt->type == TYPE_OSD) {
50
51drivers/scsi/scsi_scan.c:644:
52 case TYPE_OSD:
53
54----------
55Hints/Tips
56----------
57
58-Field testing on some workstations resulted in compiling errors if highmem support in the kernel as enabled
59