1.\" $NetBSD: targets.5,v 1.3 2013/03/28 22:54:25 njoly 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 38The 39.Nm 40file describes the iSCSI storage which is presented to iSCSI 41initiators by the 42.Xr iscsi-target 8 43service. 44A description of the iSCSI protocol can be found in 45.%T "Internet Small Computer Systems Interface RFC 3720" . 46.Pp 47Each line in the file 48(other than comment lines that begin with a 49.Sq # ) 50specifies an extent, a device (made up of extents or other devices), 51or a target to present to the initiator. 52.Pp 53Each definition, an extent, a device, and a target, is specified 54on a single whitespace delimited line. 55.Pp 56The 57.Ar extent 58definition specifies a piece of storage that will be used 59as storage, and presented to initiators. 60It is the basic definition for an iSCSI target. 61Each target must contain at least one extent definition. 62The first field in the definition is the extent name, which must 63begin with the word 64.Dq extent 65and be followed by a number. 66The next field is the file or 67.Nx 68device which will be used as persistent storage. 69The next field is the offset (in bytes) of the start of the extent. 70This field is usually 0. 71The fourth field in the definition is the size of the extent. 72The basic unit is bytes, and the shorthand 73.Ar KB , 74.Ar MB , 75.Ar GB , 76and 77.Ar TB 78can be used for kilobytes (1024 bytes), 79megabytes (1024 kilobytes), gigabytes 80(1024 megabytes), and 81terabytes (1024 gigabytes) respectively. 82It is possible to use the word 83.Dq size 84to use the full size of the pre-existing regular file 85given in the extent name. 86.Pp 87The 88.Ar device 89definition specifies a LUN or device, and is made up of extents 90and other devices. 91It is possible to create hierarchies of devices using the device definition. 92The first field in the definition is the device name, which must 93begin with the word 94.Dq device 95and be followed by a number. 96The next field is the type of resilience that is to be provided 97by the device. 98For simple devices, 99.Ar RAID0 100suffices. 101Greater resilience can be gained by using the 102.Ar RAID1 103resilience field. 104Following the resilience field is a list of extents or other devices. 105Large devices can be created by using multiple RAID0 extents, 106in which case each extent will be concatenated. 107Resilient devices can be created by using multiple RAID1 devices 108or extents, in which case data will be written to each of the 109devices or extents in turn. 110If RAID1 resilience is used, all the extents or sub-devices must 111be the same size. 112Please note that RAID1 recovery is not yet supported by the 113.Xr iscsi-target 8 114utility. 115An extent or sub-device may only be used once. 116.Pp 117The 118.Ar target 119definition specifies an iSCSI target, which is presented to the iSCSI 120initiator. 121Multiple targets can be specified. 122The first field in the definition is the target name, which must 123begin with either of the words 124.Dq target 125or 126.Dq lun 127and be followed by a number. 128Optionally, if a target is followed by an 129.Dq = 130sign and some text, 131the text is taken to be that of the iSCSI Qualified Name 132of the target. 133This IQN is used by the initiator to connect to the appropriate target. 134The next field is a selector for whether the storage should be presented 135as writable, or merely as read-only storage. 136The field of 137.Dq rw 138denotes read-write storage, 139whilst 140.Dq ro 141denotes read-only storage. 142The next field is the device or extent name that will be used as persistent storage 143for this target. 144The fourth field is a slash-notation netmask which will be used, during the 145discovery phase, to control the network addresses to which targets will 146be presented. 147The magic values 148.Dq any 149and 150.Dq all 151will expand to be the same as 152.Dq 0/0 . 153If an attempt is made to discover a target which is not allowed 154by the netmask, a warning will be issued using 155.Xr syslog 3 156to make administrators aware of this attempt. 157The administrator can still use 158tcp wrapper functionality, as found in 159.Xr hosts_access 5 160and 161.Xr hosts.deny 5 162to allow or deny discovery attempts from initiators as 163well as using the inbuilt netmask functionality. 164.Sh FILES 165.Bl -tag -width /etc/iscsi/targets -compact 166.It Pa /etc/iscsi/targets 167the 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 176The 177.Nm 178file first appeared in 179.Nx 4.0 . 180