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><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@xxxxxxxxxxxxxxx> + </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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
