[stgt] [PATCH 1/5] Split out configuration file docs to its own page
Andy Grover
agrover at redhat.com
Thu Oct 27 03:20:59 CEST 2011
Add targets.conf.5.xml
Move documentation of configuration file syntax to targets.conf.5
Expand documentation of config file.
Add to Makefile
Signed-off-by: Andy Grover <agrover at redhat.com>
---
doc/Makefile | 11 +-
doc/targets.conf.5.xml | 387 ++++++++++++++++++++++++++++++++++++++++++++++++
doc/tgt-admin.8.xml | 98 +------------
3 files changed, 397 insertions(+), 99 deletions(-)
create mode 100644 doc/targets.conf.5.xml
diff --git a/doc/Makefile b/doc/Makefile
index 9762c62..c4ffe82 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -9,9 +9,10 @@ DOCS = README.iscsi README.iser \
XSLTPROC = /usr/bin/xsltproc
XMLMAN = manpages/tgtd.8 manpages/tgtadm.8 manpages/tgtimg.8 \
- manpages/tgt-admin.8
+ manpages/tgt-admin.8 manpages/targets.conf.5
XMLHTML = htmlpages/tgtd.8.html htmlpages/tgtadm.8.html \
- htmlpages/tgtimg.8.html htmlpages/tgt-admin.8.html
+ htmlpages/tgtimg.8.html htmlpages/tgt-admin.8.html \
+ htmlpages/targets.conf.5.html
.PHONY:all
all:
@@ -52,6 +53,12 @@ manpages/tgtimg.8: tgtimg.8.xml
htmlpages/tgtimg.8.html: tgtimg.8.xml
-test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $<
+manpages/targets.conf.5: targets.conf.5.xml
+ -test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+htmlpages/targets.conf.5.html: targets.conf.5.xml
+ -test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $<
+
xmlman: $(XMLMAN)
xmlhtml: $(XMLHTML)
diff --git a/doc/targets.conf.5.xml b/doc/targets.conf.5.xml
new file mode 100644
index 0000000..8610c3d
--- /dev/null
+++ b/doc/targets.conf.5.xml
@@ -0,0 +1,387 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<refentry id="targets.conf.5">
+
+<refmeta>
+ <refentrytitle>targets.conf</refentrytitle>
+ <manvolnum>5</manvolnum>
+</refmeta>
+
+
+<refnamediv>
+ <refname>targets.conf</refname>
+ <refpurpose>Linux SCSI Target Configuration File</refpurpose>
+</refnamediv>
+
+ <refsect1><title>DESCRIPTION</title>
+ <para>
+ tgt-admin uses /etc/tgt/targets.conf to initialize tgtd
+ configuration, by default. Its layout uses a HTML-like structure, with a
+ hierarchy of nested tags to define targets and LUNs.
+ </para>
+ </refsect1>
+
+ <refsect1><title>CONFIGURATION FILE SYNTAX</title>
+ <para>
+ Global directives configure options that are
+ global to tgtd's configuration, as well as defining exported
+ targets, via target sections.
+ </para>
+ <para>
+ Target sections contain directives specific to one target
+ device. They define each target's exported LUNs via "backing-store" and
+ "direct-store" directives, as well as other target-wide options.
+ </para>
+ <para>
+ LUN directives ("backing-store" and "direct-store") may contain
+ options specific to a single exported logical unit.
+ </para>
+
+ </refsect1>
+
+ <refsect1><title>GLOBAL DIRECTIVES</title>
+
+ <para>
+ With the exception of target directives, each of these should occur at most once.
+ </para>
+
+ <variablelist>
+
+ <varlistentry><term><option><target <IQN>></option></term>
+ <listitem>
+ <para>
+ Defines a the start of a target definition. IQN is an ISCSI Qualified
+ Name such as "iqn.2001-04.com.example:storage1". See "ISCSI" on
+ Wikipedia for more information on IQNs.
+ </para>
+ <para>
+ Within this block should be target-level directives, as
+ documented below.
+ </para>
+ <para>
+ The target definition ends with "</target>"
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>default-driver <lld></option></term>
+ <listitem>
+ <para>
+ Instead of specifying a driver type for each target,
+ default-driver defines a default low-level driver for all
+ exported targets. It may be overriden on a per-target
+ basis.
+ Valid lld values are "iscsi" or
+ "iser". Since iscsi is assumed if this directive
+ is not present, it is only generally needed if iser
+ is the desired default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>include <path></option></term>
+ <listitem>
+ <para>
+ Include the configuration from another configuration
+ file. Wildcards are allowed, so an example like "include
+ /etc/tgt/xen/*.conf" is allowed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>ignore-errors yes</option></term>
+ <listitem>
+ <para>
+ Errors from tgtadm will be ignored. Default is no.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>control-port <port></option></term>
+ <listitem>
+ <para>
+ Define a different local socket key for communicating with
+ tgtd. Defaults to 0. This is only generally useful if
+ multiple instances of tgtd are in use.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>iSNSServerIP <addr></option></term>
+ <listitem>
+ <para>
+ Define the address of the iSNS server in IPv4 dotted-quad
+ address format.
+ Required when using iSNS, otherwise ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>iSNSAccessControl <value></option></term>
+ <listitem>
+ <para>
+ Set iSNS access control. Valid values are "On" or "Off".
+ Required when using iSNS, otherwise ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>iSNSServerPort <port></option></term>
+ <listitem>
+ <para>
+ Set a different iSNS server port. Default is 3205.
+ Optional when using iSNS, otherwise ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>iSNS On</option></term>
+ <listitem>
+ <para>
+ Enable iSNS. Only valid value is "On". Default is off.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+ <refsect1><title>TARGET-LEVEL DIRECTIVES</title>
+
+ <para>
+ Each target may export multiple block devices, or logical units
+ (LUNs). For the purposes of LUN numbering, backing-store
+ directives are processed before direct-store directives.
+ </para>
+
+ <variablelist>
+
+ <varlistentry><term><option>backing-store <path></option></term>
+ <listitem>
+ <para>
+ Defines a logical unit (LUN) exported by the
+ target. This may specify either a regular file, or a block
+ device.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>direct-store <path></option></term>
+ <listitem>
+ <para>
+ Defines a direct mapped logical unit (LUN) with the same properties
+ as the physical device (such as VENDOR_ID, SERIAL_NUM, etc.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>driver <lld></option></term>
+ <listitem>
+ <para>
+ Define the low-level driver to use for this target, either
+ "iscsi" or "iser" (without quotes). This overrides the
+ "default-driver" global directive.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>initiator-address <addr></option></term>
+ <listitem>
+ <para>
+ Allows connections only from the specified IP
+ address. Defaults to ALL if no initiator-address directive is specified.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>incominguser <user> <userpassword></option></term>
+ <listitem>
+ <para>
+ Define iscsi incoming authentication setting. If no
+ "incominguser" is specified, it is not used. This
+ directive may be used multiple times per target.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>outgoinguser <user> <userpassword></option></term>
+ <listitem>
+ <para>
+ Define iscsi outgoing authentication setting. If no
+ "outgoinguser" is specified, it is not used. This
+ directive may be used multiple times per target.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>controller_tid <val></option></term>
+ <listitem>
+ <para>
+ Define the tid of the controller. Default is next
+ available integer.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1><title>LUN-LEVEL DIRECTIVES</title>
+
+ <para>
+ All of these may be listed at the target level (and apply to all
+ LUNs) or within an individual LUN's definition, if it is defined
+ using the container-style, multi-line definition, rather than
+ single-line definition format:
+ </para>
+ <screen format="linespecific">
+<backing-store /dev/sdb1>
+ # LUN directives go here
+</backing-store>
+
+<direct-store /dev/sdb1>
+ # LUN directives go here
+</direct-store>
+ </screen>
+
+ <para>
+ It is recommended to use either single-line or container-style
+ LUN definitions within a target. Mixing styles can cause parser
+ errors.
+ </para>
+
+ <variablelist>
+ <varlistentry><term><option>write-cache <val></option></term>
+ <listitem>
+ <para>
+ "on" or "off", default on.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>scsi_id <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>scsi_sn <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>vendor_id <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>product_id <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>product_rev <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>sense_format <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>removable <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>path <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>mode_page <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>readonly <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>device-type <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>bs-type <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>allow-in-use <val></option></term>
+ </varlistentry>
+
+ <varlistentry><term><option>params <vals></option></term>
+ <listitem>
+ <para>
+ Pass additional parameters to tgtadm.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+ <refsect1><title>CONFIGURATION FILE EXAMPLE</title>
+ <screen format="linespecific">
+Example configuration file:
+
+<target iqn.2007-04.com.example:san.monitoring>
+ backing-store /dev/san/monitoring
+
+ # if no "incominguser" is specified, it is not used
+ incominguser backup secretpass12
+
+ # defaults to ALL if no "initiator-address" is specified
+ initiator-address 192.168.1.2
+</target>
+
+<target iqn.2007-02.com.example:san.xen1>
+ backing-store /dev/san/xen1-disk1 # LUN1
+ direct-store /dev/san/xen1-disk2 # LUN2
+
+ initiator-address 192.168.1.2 # Allowed IP
+ initiator-address 192.168.5.6 # Allowed IP
+
+ incominguser user1 secretpass12
+ incominguser user2 secretpass23
+
+ outgoinguser userA secretpassA
+</target>
+
+<target iqn.2007-02.com.example:san.xen2>
+ backing-store /dev/san/xen2
+</target>
+
+<target iqn.2007-06.com.example:san.vmware1>
+ backing-store /dev/san/vmware1
+</target>
+ </screen>
+ </refsect1>
+
+
+ <refsect1><title>FILES</title>
+ <variablelist>
+
+ <varlistentry><term><option>/etc/tgt/targets.conf</option></term>
+ <listitem>
+ <para>
+ Configuration file for tgt-admin.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term><option>/usr/share/doc/tgt/targets.conf.example</option></term>
+ <listitem>
+ <para>
+ Example configuration file for tgt-admin.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+
+ <refsect1><title>SEE ALSO</title>
+ <para>
+ tgtd(8), tgtadm(8), tgtimg(8), tgt-setup-lun(8).
+ <ulink url="http://stgt.sourceforge.net/"/>
+ </para>
+ </refsect1>
+
+ <refsect1><title>REPORTING BUGS</title>
+ <para>
+ Report bugs to <stgt at vger.kernel.org>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/doc/tgt-admin.8.xml b/doc/tgt-admin.8.xml
index 640356b..0a0e806 100644
--- a/doc/tgt-admin.8.xml
+++ b/doc/tgt-admin.8.xml
@@ -212,102 +212,6 @@ Example usage:
</variablelist>
</refsect1>
- <refsect1><title>CONFIGURATION FILE SYNTAX</title>
- <para>
- The defualt configuration file is /etc/tgt/target.conf. It defines all
- the targets and their properties.
- The configuration file is in XML format and uses tags.
- Configuration file contains several target blocks, where each block
- contains target's properties such as storage devices,
- initator ACL and authorization information. You can include other
- config files using:
- include /etc/tgt/xen/*.conf.
- </para>
-
- <variablelist>
-
- <varlistentry><term><option>backing-store</option></term>
- <listitem>
- <para>
- Defines a virtual device on the target.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term><option>direct-store</option></term>
- <listitem>
- <para>
- Defines a direct mapped device with the same properties
- as the physical device (such as VENDOR_ID, SERIAL_NUM, etc.)
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term><option>initiator-address</option></term>
- <listitem>
- <para>
- Allows connections only from the specified IP
- address. Defaults to ALL if no "initiator-address" is specified.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term><option>incominguser</option></term>
- <listitem>
- <para>
- Define iscsi incoming authentication setting. If no
- "incominguser" is specified, it is not used.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term><option>outgoinguser</option></term>
- <listitem>
- <para>
- Define iscsi outgoing authentication setting. If no
- "outgoinguser" is specified, it is not used.
- </para>
- </listitem>
- <screen format="linespecific">
-Example configuration file:
-
-<target iqn.2007-04.com.example:san.monitoring>
-backing-store /dev/san/monitoring
-
-# if no "incominguser" is specified, it is not used
-incominguser backup secretpass12
-
-# defaults to ALL if no "initiator-address" is specified
-initiator-address 192.168.1.2
-</target>
-
-<target iqn.2007-02.com.example:san.xen1>
-backing-store /dev/san/xen1-disk1 # LUN1
-direct-store /dev/san/xen1-disk2 # LUN2
-
-initiator-address 192.168.1.2 # Allowed IP
-initiator-address 192.168.5.6 # Allowed IP
-
-incominguser user1 secretpass12
-incominguser user2 secretpass23
-
-outgoinguser userA secretpassA
-</target>
-
-<target iqn.2007-02.com.example:san.xen2>
-backing-store /dev/san/xen2
-</target>
-
-<target iqn.2007-06.com.example:san.vmware1>
-backing-store /dev/san/vmware1
-</target>
- </screen>
- </varlistentry>
-
- </variablelist>
- </refsect1>
-
-
<refsect1><title>FILES</title>
<variablelist>
@@ -333,7 +237,7 @@ backing-store /dev/san/vmware1
<refsect1><title>SEE ALSO</title>
<para>
- tgtd(8), tgtadm(8), tgtimg(8), tgt-setup-lun(8).
+ targets.conf(5), tgtd(8), tgtadm(8), tgtimg(8), tgt-setup-lun(8).
<ulink url="http://stgt.sourceforge.net/"/>
</para>
</refsect1>
--
1.7.1
--
To unsubscribe from this list: send the line "unsubscribe stgt" in
the body of a message to majordomo at vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
More information about the stgt
mailing list