external/bsd/iscsi/dist/doc/FAQ

   1 iSCSI Frequently Asked Questions
   2 ================================
   3
   4 Q1. What is iSCSI?
   5 ==================
   6
   7 A1.  It's an IETF standard (RFC 3720) for remote access to block-level
   8 storage.  It can be thought of as similar to NFS, except that an NFS
   9 server exports files; the iSCSI target exports blocks to the iSCSI
  10 initiators, which are the clients.
  11
  12
  13 Q2. What's the difference between an initiator and a target?
  14 ============================================================
  15
  16 A2.  The target is the iSCSI server - it serves up blocks to the
  17 clients, which are called initiators.  Typically, initiators are part
  18 of the operating system, since the operating system manages block
  19 storage, presenting it to the user as file systems sitting on top of
  20 the storage.
  21
  22 Targets do not generally need to be part of the operating system,
  23 indeed there is some flexibility to be gained by having targets as
  24 part of the user-level daemons that are run. This means that
  25 security credentials need not be buried in the kernel.
  26
  27
  28 Q3. So how do I use it?
  29 =======================
  30
  31 A3.  Firstly, you need to set up the iSCSI target.  The target is
  32 simply sitting there, waiting for requests for blocks.  So we need to
  33 configure the target with an area of storage for it to present to the
  34 initiators.
  35
  36 To set up the target, you need to edit the /etc/iscsi/targets file.
  37 It has a certain layout, to provide a means of (a) mirroring and (b)
  38 combining multiple areas to present one large contiguous area of
  39 storage. This can be multiply-layered.
  40
  41 The basic unit of storage is an extent. This can be either a file
  42 or a device. The offset of the start of the extent to be presented
  43 must be given, and also the length of the extent.
  44
  45 A device is made up of one or more extents, and/or one or more
  46 other devices.
  47
  48 At the highest level, a target is what is presented to the initiator,
  49 and is made up of one or more devices, and/or one or more extents.
  50
  51 The simple example is as follows, consisting of one piece of storage
  52 presented by one target:
  53
  54         # extent        file or device          start           length
  55         extent0         /tmp/iscsi-target0      0               100MB
  56
  57 will produce an extent of storage which is based on one file,
  58 /tmp/iscsi-target0, which starts 0 bytes into the file, and is 100 MB
  59 in length.  The file will be created if it does not already exist.
  60
  61         # target        storage                 netmask
  62         target0         extent0                 0.0.0.0/0
  63
  64 That extent is then used in target0, and will be presented to an
  65 initiator running on any host.
  66
  67 Extents must be defined before they can be used, and extents cannot
  68 be used more than once.
  69
  70 Devices are used to combine extents or other devices.  Device
  71 definitions have the following format:
  72
  73         # devices
  74         device0 RAID1           extent0 extent1
  75
  76 A "RAID1" device behaves in much the same way that RAID1 devices work
  77 in the storage arena - they mirror the original storage.  There can be
  78 any number of devices or extents in a RAID1 device, not just 2, but
  79 each device or extent must be of the same size.
  80
  81 A "RAID0" device combines the storage, to produce a larger area of
  82 (virtually) "contiguous" storage.
  83
  84 Devices must be defined before they can be used, and devices may not
  85 be used more than once.
  86
  87 A more detailed example would be as follows:
  88
  89         # Complex file showing 3-way RAID1 (with RAID1 components),
  90         # also using local and (NFS) remote components
  91
  92         # extents
  93         extent0 /iscsi/extents/0                        0       100MB
  94         extent1 /imports/remote1/iscsi/extents/0        0       100MB
  95         extent2 /iscsi/extents/1                        0       100MB
  96         extent3 /imports/remote1/iscsi/extents/1        0       100MB
  97         extent4 /iscsi/extents/2                        0       100MB
  98         extent5 /imports/remote1/iscsi/extents/2        0       100MB
  99         extent6 /iscsi/extents/3                        0       100GB
 100
 101         # devices
 102         device0 RAID1           extent0 extent1
 103         device1 RAID1           extent2 extent3
 104         device2 RAID1           extent4 extent5
 105         device3 RAID1           device0 device1 device2
 106
 107         # targets
 108         target0 device3         10.4.0.0/16
 109
 110         # a target can be made from just an extent
 111         target1 extent6         127.0.0.0/8
 112
 113 which will make 7 extents, 3 of them 100 MB in length and remote (via
 114 NFS), and 3 of them 100 MB in length and local, and one of them large
 115 (100 GB) and local.  Three separate occurrences of a local and remote
 116 100 MB extent are combined to make three RAID1 devices, and then those
 117 three RAID1 devices are combined into another RAID1 device, and
 118 presented as target0.
 119
 120 The other extent is used to present a simple 100 GB of storage as
 121 target1.
 122
 123
 124 Q4.  What about security?
 125 =========================
 126
 127 A4.  A good question.  RFC 3720 specifies CHAP, SRM and Kerberos as
 128 methods of providing authentication and/or security.  In practice,
 129 it's whatever is provided by the initiator you are using which will
 130 determine what authentication or security is used.
 131
 132 If you want any form of security, it's probably best to use ssh port
 133 forwarding for all your traffic if you're worried about security.
 134 CHAP will only provide authentication, the other information will flow
 135 across the network in clear.
 136
 137
 138 Q5.  Using the Microsoft initiator, I can't login with CHAP
 139 ===========================================================
 140
 141 A5.  The 1.06 Microsoft initiator silently enforces a chap password
 142 length of at least 12 characters.  If you enter a password which is
 143 less than that, your Discovery login will silently fail.
 144
 145 Since CHAP provides very little authentication anyway, you are advised
 146 not to use it - ssh port forwarding, and the use of tcp wrappers,
 147 will do a much better job of protection.
 148
 149
 150 Q6. What initiators work with the NetBSD iSCSI target?
 151 ======================================================
 152
 153 A6. The NetBSD target has been tested at various times with the Microsoft
 154 iSCSI initiator, version 1.06 (which can be downloaded for free from
 155 www.microsoft.com, but needs Windows XP Pro to work), and also with the
 156 NetBSD test harness, which is provided, but not installed, in the same
 157 place as the target.
 158
 159
 160 Q7.  What is the difference between Discovery and Normal login?
 161 ===============================================================
 162
 163 A7.  On direct-attached storage, the kernel verifies what storage is
 164 available, and assigns a device node to it. With iSCSI, storage can
 165 come and go, and our proximity to the devices doesn't matter. So we
 166 need to find a different method of finding out what iSCSI storage is
 167 out there.
 168
 169 This is done by a "Discovery" iSCSI session - the initiator logs in
 170 to the target, finds out what storage is being presented, then logs
 171 back out. This can be seen by the syslog entries:
 172
 173         Feb  5 10:33:44 sys3 iscsi-target: > Discovery login from iqn.1991-05.com.microsoft:inspiron on 10.4.1.5
 174         Feb  5 10:33:44 sys3 iscsi-target: < Discovery logout from iqn.1991-05.com.microsoft:inspiron on 10.4.1.5
 175
 176 The initiator will then perform a "Normal" login session, which will
 177 establish a session between the initiator and target. This is denoted
 178 by the syslog entries:
 179
 180         Feb  5 00:00:28 sys3 iscsi-target: > Discovery login from iqn.1993-03.org.NetBSD.iscsi-initiator:agc on 127.0.0.1
 181         Feb  5 00:00:28 sys3 iscsi-target: < Discovery logout from iqn.1993-03.org.NetBSD.iscsi-initiator:agc on 127.0.0.1
 182         Feb  5 00:00:28 sys3 iscsi-target: > Normal login from iqn.1993-03.org.NetBSD.iscsi-initiator:agc on 127.0.0.1
 183         Feb  5 00:05:32 sys3 iscsi-target: < Normal logout from iqn.1993-03.org.NetBSD.iscsi-initiator:agc on 127.0.0.1
 184
 185
 186 Q8. So what do I do to try it?
 187 ==============================
 188
 189 A8. Perform the following steps:
 190
 191 a) define the storage that you want to present in /etc/iscsi/targets
 192 b) start the iSCSI target: /etc/rc.d/iscsi_target forcestart
 193 c) use an initiator to point it at the machine you started it on
 194
 195
 196 Q9. Why does the test harness not work properly?
 197 ================================================
 198
 199 A9. Firstly, you should be invoking the test harness as
 200
 201         iscsi-harness -n 3 -h localhost
 202
 203 where the 'n' option is the number of iterations to perform, and the
 204 'h' parameter is the name or address of the machine where the
 205 iscsi-target is running.
 206
 207 If the harness was invoked properly, check any error messages which
 208 the test harness sends:
 209
 210 If one of them looks like:
 211
 212         No matching user configuration entry for `agc' was found
 213         Please add an entry for `agc' to `/etc/iscsi/auths'
 214
 215 (where "agc" is substituted for the name of the user who was running
 216 the test harness), then please do as suggested. The iSCSI test harness
 217 tests, amongst other things, the CHAP authentication process, and so
 218 CHAP credentials for that user are needed.
 219
 220
 221
 222 Alistair Crooks
 223 agc@NetBSD.org
 224 Wed Feb  8 07:21:56 GMT 2006