external/bsd/iscsi/dist/src/target/targets.5

   1 .\" $NetBSD: targets.5,v 1.1 2009/06/21 21:20:31 agc Exp $
   2 .\"
   3 .\" Copyright © 2006 Alistair Crooks.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. The name of the author may not be used to endorse or promote
  14 .\"    products derived from this software without specific prior written
  15 .\"    permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
  18 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  19 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  21 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  23 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  25 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  26 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  27 .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd December 18, 2007
  30 .Dt TARGETS 5
  31 .Os
  32 .Sh NAME
  33 .Nm targets
  34 .Nd configuration file for iSCSI targets
  35 .Sh SYNOPSIS
  36 .Nm targets
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 file describes the iSCSI storage which is presented to iSCSI
  41 initiators by the
  42 .Xr iscsi-target 8
  43 service.
  44 A description of the iSCSI protocol can be found in
  45 .%T "Internet Small Computer Systems Interface \\*(tNRFC\\*(sP 3720" .
  46 .Pp
  47 Each line in the file
  48 (other than comment lines that begin with a
  49 .Sq # )
  50 specifies an extent, a device (made up of extents or other devices),
  51 or a target to present to the initiator.
  52 .Pp
  53 Each definition, an extent, a device, and a target, is specified
  54 on a single whitespace delimited line.
  55 .Pp
  56 The
  57 .Ar extent
  58 definition specifies a piece of storage that will be used
  59 as storage, and presented to initiators.
  60 It is the basic definition for an iSCSI target.
  61 Each target must contain at least one extent definition.
  62 The first field in the definition is the extent name, which must
  63 begin with the word
  64 .Dq extent
  65 and be followed by a number.
  66 The next field is the file or
  67 .Nx
  68 device which will be used as persistent storage.
  69 The next field is the offset (in bytes) of the start of the extent.
  70 This field is usually 0.
  71 The fourth field in the definition is the size of the extent.
  72 The basic unit is bytes, and the shorthand
  73 .Ar KB ,
  74 .Ar MB ,
  75 .Ar GB ,
  76 and
  77 .Ar TB
  78 can be used for kilobytes (1024 bytes),
  79 megabytes (1024 kilobytes), gigabytes
  80 (1024 megabytes), and
  81 terabytes (1024 gigabytes) respectively.
  82 It is possible to use the word
  83 .Dq size
  84 to use the full size of the pre-existing regular file
  85 given in the extent name.
  86 .Pp
  87 The
  88 .Ar device
  89 definition specifies a LUN or device, and is made up of extents
  90 and other devices.
  91 It is possible to create hierarchies of devices using the device definition.
  92 The first field in the definition is the device name, which must
  93 begin with the word
  94 .Dq device
  95 and be followed by a number.
  96 The next field is the type of resilience that is to be provided
  97 by the device.
  98 For simple devices,
  99 .Ar RAID0
 100 suffices.
 101 Greater resilience can be gained by using the
 102 .Ar RAID1
 103 resilience field.
 104 Following the resilience field is a list of extents or other devices.
 105 Large devices can be created by using multiple RAID0 extents,
 106 in which case each extent will be concatenated.
 107 Resilient devices can be created by using multiple RAID1 devices
 108 or extents, in which case data will be written to each of the
 109 devices or extents in turn.
 110 If RAID1 resilience is used, all the extents or sub-devices must
 111 be the same size.
 112 Please note that RAID1 recovery is not yet supported by the
 113 .Xr iscsi-target 8
 114 utility.
 115 An extent or sub-device may only be used once.
 116 .Pp
 117 The
 118 .Ar target
 119 definition specifies an iSCSI target, which is presented to the iSCSI
 120 initiator.
 121 Multiple targets can be specified.
 122 The first field in the definition is the target name, which must
 123 begin with either of the words
 124 .Dq target
 125 or
 126 .Dq lun
 127 and be followed by a number.
 128 Optionally, if a target is followed by an
 129 .Dq =
 130 sign and some text,
 131 the text is taken to be that of the iSCSI Qualified Name
 132 of the target.
 133 This IQN is used by the initiator to connect to the appropriate target.
 134 The next field is a selector for whether the storage should be presented
 135 as writable, or merely as read-only storage.
 136 The field of
 137 .Dq rw
 138 denotes read-write storage,
 139 whilst
 140 .Dq ro
 141 denotes read-only storage.
 142 The next field is the device or extent name that will be used as persistent storage
 143 for this target.
 144 The fourth field is a slash-notation netmask which will be used, during the
 145 discovery phase, to control the network addresses to which targets will
 146 be presented.
 147 The magic values
 148 .Dq any
 149 and
 150 .Dq all
 151 will expand to be the same as
 152 .Dq 0/0 .
 153 If an attempt is made to discover a target which is not allowed
 154 by the netmask, a warning will be issued using
 155 .Xr syslog 3
 156 to make administrators aware of this attempt.
 157 The administrator can still use
 158 tcp wrapper functionality, as found in
 159 .Xr hosts_access 5
 160 and
 161 .Xr hosts.deny 5
 162 to allow or deny discovery attempts from initiators as
 163 well as using the inbuilt netmask functionality.
 164 .Sh FILES
 165 .Bl -tag -width /etc/iscsi/targets -compact
 166 .It Pa /etc/iscsi/targets
 167 the list of exported storage
 168 .Nm
 169 .El
 170 .Sh SEE ALSO
 171 .Xr syslog 3 ,
 172 .Xr hosts.deny 5 ,
 173 .Xr hosts_access 5 ,
 174 .Xr iscsi-target 8
 175 .Sh HISTORY
 176 The
 177 .Nm
 178 file first appeared in
 179 .Nx 4.0 .