external/bsd/iscsi/dist/doc/README

   1
   2 ---------------------------------------
   3 Intel iSCSI v20 Reference Implementation
   4 ---------------------------------------
   5
   6 This is a software implementation of iSCSI v20.  Included in this distribution
   7 are both host and target mode drivers with built in conformance and performance
   8 tests, and sockets tests that can be used to simulate TCP traffic identical to
   9 that generated between a real iSCSI host and target.
  10
  11 See PERFORMANCE for information regarding the expected performance of this
  12 distribution.
  13
  14 This 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)
  16 with UP and SMP configurations.
  17
  18 -------------------
  19 Starting the System
  20 -------------------
  21
  22 1a) 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
  35 1b) 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
  48 1c) 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
  52 2) Modify the following constant in initiator.h accordingly:
  53
  54    #define CONFIG_INITIATOR_NUM_TARGETS 3
  55
  56 3) 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
  67 4) 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
  91 5) 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
  95 6) 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 ------------------
 127 Testing the System
 128 ------------------
 129
 130 Once your targets and host have been started, you can test the installation
 131 using either a single target, or by creating a RAID volume over multiple
 132 targets.
 133
 134 To test a single target you can either directly read and write the device by
 135 opening, 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
 141 To test a multiple target installation, you can create a RAID volume,
 142 virtualizing multiple targets as one SCSI device.  The Linux RAID modules
 143 will 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
 164 After initialized the raid device with "mkraid /dev/md0," you can use /dev/md0
 165 as 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 --------------------
 171 When Things Go Wrong
 172 --------------------
 173
 174 Check the kernel error messages /var/log/messages or run the dmesg command to
 175 see any errors reported from the host driver. The targets will report target
 176 errors to standard output.
 177
 178 If you need more fine grained debugging, modify the Makefile to turn on the
 179 compilation flag CONFIG_ISCSI_DEBUG. Then run "make clean," and then "make."
 180 You can select which type of debugging statements get printed by modifying
 181 iscsiutil.h
 182
 183 -------------------------------------
 184 Interoperability with Cisco Initiator
 185 -------------------------------------
 186
 187 The target is tested to be interoperable with Cisco Initiator release
 188 3.4.1.1