[PATCH 1/5] Split out configuration file docs to its own page

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxx>
---
 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>&lt;target &lt;IQN&gt;&gt;</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 "&lt;/target&gt;"
+	  </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>default-driver &lt;lld&gt;</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 &lt;path&gt;</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 &lt;port&gt;</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 &lt;addr&gt;</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 &lt;value&gt;</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 &lt;port&gt;</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 &lt;path&gt;</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 &lt;path&gt;</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 &lt;lld&gt;</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 &lt;addr&gt;</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 &lt;user&gt; &lt;userpassword&gt;</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 &lt;user&gt; &lt;userpassword&gt;</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 &lt;val&gt;</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">
+&lt;backing-store /dev/sdb1&gt;
+  # LUN directives go here
+&lt;/backing-store&gt;
+
+&lt;direct-store /dev/sdb1&gt;
+  # LUN directives go here
+&lt;/direct-store&gt;
+    </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 &lt;val&gt;</option></term>
+	<listitem>
+	  <para>
+	    "on" or "off", default on.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry><term><option>scsi_id &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>scsi_sn &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>vendor_id &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>product_id &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>product_rev &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>sense_format &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>removable &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>path &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>mode_page &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>readonly &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>device-type &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>bs-type &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>allow-in-use &lt;val&gt;</option></term>
+      </varlistentry>
+
+      <varlistentry><term><option>params &lt;vals&gt;</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:
+
+&lt;target iqn.2007-04.com.example:san.monitoring&gt;
+  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
+&lt;/target&gt;
+
+&lt;target iqn.2007-02.com.example:san.xen1&gt;
+  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
+&lt;/target&gt;
+
+&lt;target iqn.2007-02.com.example:san.xen2&gt;
+  backing-store /dev/san/xen2
+&lt;/target&gt;
+
+&lt;target iqn.2007-06.com.example:san.vmware1&gt;
+  backing-store /dev/san/vmware1
+&lt;/target&gt;
+	</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 &lt;stgt@xxxxxxxxxxxxxxx&gt;
+    </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:
-
-&lt;target iqn.2007-04.com.example:san.monitoring&gt;
-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
-&lt;/target&gt;
-
-&lt;target iqn.2007-02.com.example:san.xen1&gt;
-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
-&lt;/target&gt;
-
-&lt;target iqn.2007-02.com.example:san.xen2&gt;
-backing-store /dev/san/xen2
-&lt;/target&gt;
-
-&lt;target iqn.2007-06.com.example:san.vmware1&gt;
-backing-store /dev/san/vmware1
-&lt;/target&gt;
-	</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@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html


[Index of Archives]     [Linux SCSI]     [Linux RAID]     [Linux Clusters]     [Linux USB Devel]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]

  Powered by Linux