.\" $NetBSD: targets.5,v 1.3 2013/03/28 22:54:25 njoly Exp $
.\"
.\" Copyright © 2006 Alistair Crooks.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote
.\"    products derived from this software without specific prior written
.\"    permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 18, 2007
.Dt TARGETS 5
.Os
.Sh NAME
.Nm targets
.Nd configuration file for iSCSI targets
.Sh SYNOPSIS
.Nm targets
.Sh DESCRIPTION
The
.Nm
file describes the iSCSI storage which is presented to iSCSI
initiators by the
.Xr iscsi-target 8
service.
A description of the iSCSI protocol can be found in
.%T "Internet Small Computer Systems Interface RFC 3720" .
.Pp
Each line in the file
(other than comment lines that begin with a
.Sq # )
specifies an extent, a device (made up of extents or other devices),
or a target to present to the initiator.
.Pp
Each definition, an extent, a device, and a target, is specified
on a single whitespace delimited line.
.Pp
The
.Ar extent
definition specifies a piece of storage that will be used
as storage, and presented to initiators.
It is the basic definition for an iSCSI target.
Each target must contain at least one extent definition.
The first field in the definition is the extent name, which must
begin with the word
.Dq extent
and be followed by a number.
The next field is the file or
.Nx
device which will be used as persistent storage.
The next field is the offset (in bytes) of the start of the extent.
This field is usually 0.
The fourth field in the definition is the size of the extent.
The basic unit is bytes, and the shorthand
.Ar KB ,
.Ar MB ,
.Ar GB ,
and
.Ar TB
can be used for kilobytes (1024 bytes),
megabytes (1024 kilobytes), gigabytes
(1024 megabytes), and
terabytes (1024 gigabytes) respectively.
It is possible to use the word
.Dq size
to use the full size of the pre-existing regular file
given in the extent name.
.Pp
The
.Ar device
definition specifies a LUN or device, and is made up of extents
and other devices.
It is possible to create hierarchies of devices using the device definition.
The first field in the definition is the device name, which must
begin with the word
.Dq device
and be followed by a number.
The next field is the type of resilience that is to be provided
by the device.
For simple devices,
.Ar RAID0
suffices.
Greater resilience can be gained by using the
.Ar RAID1
resilience field.
Following the resilience field is a list of extents or other devices.
Large devices can be created by using multiple RAID0 extents,
in which case each extent will be concatenated.
Resilient devices can be created by using multiple RAID1 devices
or extents, in which case data will be written to each of the
devices or extents in turn.
If RAID1 resilience is used, all the extents or sub-devices must
be the same size.
Please note that RAID1 recovery is not yet supported by the
.Xr iscsi-target 8
utility.
An extent or sub-device may only be used once.
.Pp
The
.Ar target
definition specifies an iSCSI target, which is presented to the iSCSI
initiator.
Multiple targets can be specified.
The first field in the definition is the target name, which must
begin with either of the words
.Dq target
or
.Dq lun
and be followed by a number.
Optionally, if a target is followed by an
.Dq =
sign and some text,
the text is taken to be that of the iSCSI Qualified Name
of the target.
This IQN is used by the initiator to connect to the appropriate target.
The next field is a selector for whether the storage should be presented
as writable, or merely as read-only storage.
The field of
.Dq rw
denotes read-write storage,
whilst
.Dq ro
denotes read-only storage.
The next field is the device or extent name that will be used as persistent storage
for this target.
The fourth field is a slash-notation netmask which will be used, during the
discovery phase, to control the network addresses to which targets will
be presented.
The magic values
.Dq any
and
.Dq all
will expand to be the same as
.Dq 0/0 .
If an attempt is made to discover a target which is not allowed
by the netmask, a warning will be issued using
.Xr syslog 3
to make administrators aware of this attempt.
The administrator can still use
tcp wrapper functionality, as found in
.Xr hosts_access 5
and
.Xr hosts.deny 5
to allow or deny discovery attempts from initiators as
well as using the inbuilt netmask functionality.
.Sh FILES
.Bl -tag -width /etc/iscsi/targets -compact
.It Pa /etc/iscsi/targets
the list of exported storage
.Nm
.El
.Sh SEE ALSO
.Xr syslog 3 ,
.Xr hosts.deny 5 ,
.Xr hosts_access 5 ,
.Xr iscsi-target 8
.Sh HISTORY
The
.Nm
file first appeared in
.Nx 4.0 .