Add a stc.conf(5) man page

Signed-off-by: David Zeuthen <davidz@redhat.com>

4 files changed, 293 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8ebf073..4702c30 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -58,11 +58,15 @@ EXTRA_DIST +=			\
 
 man_MANS =			\
 	stc.1			\
+	stc.conf.5		\
 	$(NULL)
 
 .xml.1:
 	xsltproc -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
 
+.xml.5:
+	xsltproc -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
 MAINTAINERCLEANFILES = $(man_MANS) $(BUILT_SOURCES)
 
 EXTRA_DIST += $(man_MANS)
diff --git a/doc/stc-docs.xml b/doc/stc-docs.xml
index 2a26fa0..ac00027 100644
--- a/doc/stc-docs.xml
+++ b/doc/stc-docs.xml
@@ -25,6 +25,7 @@
   <part>
     <title>Tools Reference</title>
     <xi:include href="stc.xml"/>
+    <xi:include href="stc.conf.xml"/>
   </part>
 
   <index>
diff --git a/doc/stc.conf.xml b/doc/stc.conf.xml
new file mode 100644
index 0000000..1ed592a
--- /dev/null
+++ b/doc/stc.conf.xml
@@ -0,0 +1,285 @@
+<refentry id="stc.conf" lang="en">
+<refmeta>
+  <refentrytitle>stc.conf</refentrytitle>
+  <manvolnum>5</manvolnum>
+  <refmiscinfo class="manual">Storage Configuration Files</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>stc.conf</refname>
+  <refpurpose>
+    Storage configuration files
+  </refpurpose>
+</refnamediv>
+
+<refsect1>
+  <title>Synopsis</title>
+  <para>
+    <filename>/etc/stc.conf</filename>
+    <filename>/etc/stc.conf.d/*.conf</filename>
+  </para>
+</refsect1>
+
+
+<refsect1>
+  <title>Description</title>
+  <para>
+    The <filename>/etc/stc.conf</filename> and
+    <filename>/etc/stc.conf.d/*.conf</filename> files contain
+    descriptive information about various file systems and
+    devices. These configuration files, collectively, contains a set
+    of <emphasis>storage items</emphasis>. Each storage item describes
+    how to mount a filesystem, how to assemble a RAID array, how to
+    unlock a LUKS device, how to activate a LVM Volume Group and so
+    on.
+  </para>
+  <para>
+    An item can either be running or not running. For example, for a
+    filesystem this corresponds to whether it is mounted in the
+    configured location or not. Similarly, for a RAID array it conveys
+    whether the RAID is currently assembled or not. Additionally,
+    items can depend on each other. This allows handling very complex
+    inter-subsystem storage trees such as:
+  </para>
+<programlisting>
+                   Filesystem
+                     MyData
+                       |
+                     LUKS
+                  MyData_LUKS
+                       |
+                   LVMVolume
+     +------------ MyData_LV ----------------+
+     |                 |                     |
+     |                 |                     |
+   MDRaid           MDRaid                 MDRaid
+MyData_LV_PV1     MyData_LV_PV2         MyData_LV_PV3
+     |                 |                     |
+(2 x Disks)        (2 x Disks)           (2 x Disks)
+</programlisting>
+  <para>
+    The above example shows that <literal>MyData</literal> depends on
+    <literal>MyData_LUKS</literal> that depends on
+    <literal>MyData_LV</literal>. Additionally,
+    <literal>MyData_LV</literal> depends on three RAID arrays,
+    <literal>MyData_LV_PV1</literal>, <literal>MyData_LV_PV2</literal>
+    and <literal>MyData_LV_PV3</literal> (that each happen to be on
+    two disks each). Given this level of information, it is possible
+    to start/stop all involved devices by simply running these two commands
+  </para>
+<programlisting>
+# stc start --id MyData
+# stc stop --id MyData
+</programlisting>
+</refsect1>
+
+<refsect1>
+  <title>Configuration Files</title>
+  <para>
+    Storage items are declared in the
+    <filename>/etc/stc.conf</filename> and
+    <filename>/etc/stc.conf.d/*.conf</filename>. Each file is a
+    <emphasis>key/value-file</emphasis> (also commonly known as
+    <emphasis>ini-files</emphasis>) — see the <ulink
+    url="http://freedesktop.org/wiki/Specifications/desktop-entry-spec">Desktop
+    Entry Specification</ulink> specification for the syntax of
+    key/value files. Each storage item is <emphasis>group</emphasis>
+    where the group name contains two words conveying the type
+    resp. the identifier for the item. A simple example of a storage
+    item is:
+  </para>
+<programlisting>
+[Filesystem MyDisk]
+Device=/dev/disk/by-uuid/1234:5678
+Options=Filesystem:mount_path=/mnt/somewhere
+</programlisting>
+  <para>
+    In the above example, the type of the item is
+    <literal>Filesystem</literal> while the identifier is
+    <literal>MyDisk</literal>. Additionally, the item conveys that the
+    device <filename>/dev/disk/by-uuid/1234:5678</filename> should be
+    mounted at <filename>/mnt/somewhere</filename>.
+  </para>
+  <para>
+    The order of entries is defined as follows: First, all files are
+    sorted and processed in lexical order (in the C locale) and for
+    each file, items appear in the order they are declared. If two
+    items have the same identifier, the last one wins.
+  </para>
+  <para>
+    Each item supports the following keys:
+  </para>
+  <variablelist>
+    <varlistentry>
+      <term><literal>Device, Label, UUID, Name</literal></term>
+      <listitem>
+        <para>
+          Exactly one of these keys can be used to refer to the device
+          in question. See each item type for what subset of these
+          keys can be used.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>NickName</literal></term>
+      <listitem>
+        <para>
+          A human-readable string describing the entry.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>Options</literal></term>
+      <listitem>
+        <para>
+          A list of options to use when starting the item. See each
+          item type what set of keys are supported and/or required.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>Depends</literal></term>
+      <listitem>
+        <para>
+          A list of item identifiers for items that the item depends
+          on. This information is used to ensure that all dependent
+          items are started when starting an item. Conversely, it is
+          used to stop dependent items if an item is stopped.
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+</refsect1>
+
+<refsect1>
+  <title>Filesystem Items</title>
+  <para>
+    Items of type <literal>Filesystem</literal> are used to mount a
+    device into the filesystem tree — you can use keys
+    <literal>Device</literal>, <literal>UUID</literal> and
+    <literal>Label</literal> to refer to the device.
+  </para>
+  <para>
+    The option <literal>Filesystem:mount_path</literal> is mandatory
+    and is used to specify the path where the device should be
+    mounted. The option <literal>Filesystem:options</literal> is
+    optional and is a comma-separated list of options passed to the
+    <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    command.
+  </para>
+
+  <refsect2>
+    <title>Examples</title>
+<programlisting>
+# Mount by label
+#
+[Filesystem id1]
+Label=Some Label
+Options=Filesystem:mount_path=/mnt/id1
+
+# Mount by UUID
+#
+[Filesystem id2]
+UUID=4e057fd9-bae5-4a12-83b5-2f654d42edb1
+Options=Filesystem:mount_path=/mnt/id2
+
+# Mount by device (in this case, a persistent device name provided by udev(7))
+#
+[Filesystem id3]
+Device=/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0-part1
+Options=Filesystem:mount_path=/mnt/id3
+
+# Specify filesystem options
+#
+[Filesystem id4]
+Label=EOS_DIGITAL
+Options=Filesystem:mount_path=/media/My Photos;Filesystem:options=umask=0022,noatime
+</programlisting>
+  </refsect2>
+</refsect1>
+
+<refsect1>
+  <title>LUKS Items</title>
+  <para>
+    Items of type <literal>LUKS</literal> are used to unlock an
+    encrypted device. The keys <literal>Device</literal> and
+    <literal>UUID</literal> can be used to refer to the device.
+  </para>
+  <para>
+    The option <literal>LUKS:passphrase</literal> is optional and if
+    set, contains the passphrase used to unlock the device (if not
+    set, then the user is asked for the passphrase when starting the
+    device). The option <literal>LUKS:mapping_name</literal> is
+    likewise optional and if set, then the given name will be used for
+    the resulting <literal>dm-crypt</literal> device.
+  </para>
+
+  <refsect2>
+    <title>Examples</title>
+<programlisting>
+# Passphrase and mapping name given
+#
+[LUKS sekrit_LUKS]
+UUID=5b2aeadf-7f10-4df9-92f2-0bc13123d6e5
+Options=LUKS:passphrase=xyz123;LUKS:mapping_name=sekrit
+
+# Example of a Filesystem item that depends on the LUKS item above.
+# This way the LUKS device and the Filesystem will be unlocked/mounted
+# respectively locked/unmounted in tandem when running stc(1).
+#
+[Filesystem sekrit]
+UUID=9639-06F4
+Options=Filesystem:mount_path=/mnt/sekrit
+Depends=sekrit_LUKS
+</programlisting>
+  </refsect2>
+</refsect1>
+
+<refsect1>
+  <title>MDRaid Items</title>
+  <para>
+    Items of type <literal>MDRaid</literal> are used to assemble
+    <citerefentry><refentrytitle>md</refentrytitle><manvolnum>4</manvolnum></citerefentry>
+    aka Linux Software Raid devices. The keys <literal>UUID</literal>
+    and <literal>Name</literal> can be used to refer to the RAID
+    array.
+  </para>
+
+  <refsect2>
+    <title>Examples</title>
+<programlisting>
+# Refer to array by UUID
+#
+[MDRaid BigStorage]
+UUID=a4a5646e:933c7856:23bfc059:6e17b7ec
+
+# Refer to array by name (typically in the homehost:name format)
+#
+[MDRaid MyRaid]
+Name=x61:MyRaid
+</programlisting>
+  </refsect2>
+</refsect1>
+
+<refsect1>
+  <title>Author</title>
+  <para>
+    Written by David Zeuthen <email>zeuthen@gmail.com</email> with
+    a lot of help from many others.
+  </para>
+</refsect1>
+
+<refsect1>
+  <title>See also</title>
+  <para>
+    <citerefentry><refentrytitle>stc</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>md</refentrytitle><manvolnum>4</manvolnum></citerefentry>
+  </para>
+</refsect1>
+
+</refentry>
diff --git a/doc/stc.xml b/doc/stc.xml
index 84ee572..b9f9a17 100644
--- a/doc/stc.xml
+++ b/doc/stc.xml
@@ -35,6 +35,9 @@
   <title>See also</title>
   <para>
     <citerefentry>
+      <refentrytitle>stc.conf</refentrytitle><manvolnum>5</manvolnum>
+    </citerefentry>,
+    <citerefentry>
       <refentrytitle>udisks</refentrytitle><manvolnum>1</manvolnum>
     </citerefentry>
   </para>