Use item-prefixed options for specifying what device to act on

This makes the configuration files slighty more readable and also
cleans up the API somewhat.

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

2 files changed, 125 insertions, 45 deletions

diff --git a/doc/stc-sections.txt b/doc/stc-sections.txt
index 057c036..db7c608 100644
--- a/doc/stc-sections.txt
+++ b/doc/stc-sections.txt
@@ -25,7 +25,6 @@ StcItemState
 stc_item_get_id
 stc_item_get_item_type
 stc_item_get_comment
-stc_item_get_target
 stc_item_get_option
 stc_item_get_option_keys
 stc_item_get_dependencies
diff --git a/doc/stc.conf.xml b/doc/stc.conf.xml
index a32fc1f..6dfbb78 100644
--- a/doc/stc.conf.xml
+++ b/doc/stc.conf.xml
@@ -91,7 +91,7 @@ MyData_LV_PV1     MyData_LV_PV2         MyData_LV_PV3
   </para>
 <programlisting>
 [Filesystem MyDisk]
-Device=/dev/disk/by-uuid/1234:5678
+FilesystemDevice=/dev/disk/by-uuid/1234:5678
 FilesystemMountPath=/mnt/somewhere
 </programlisting>
   <para>
@@ -117,17 +117,6 @@ FilesystemMountPath=/mnt/somewhere
 
   <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>Comment</literal></term>
       <listitem>
         <para>
@@ -178,15 +167,64 @@ FilesystemMountPath=/mnt/somewhere
   <title>Filesystem Items</title>
   <para>
     Items of type <literal>Filesystem</literal> are used to mount
-    block devices into the filesystem tree — you can use keys
-    <literal>Device</literal>, <literal>UUID</literal> and
-    <literal>Label</literal> to refer to the device. The option
-    <literal>FilesystemMountPath</literal> is mandatory and is used to
-    specify the path where the device should be mounted. The option
-    <literal>FilesystemOptions</literal> is optional and is a
-    comma-separated list of options to pass to the
-    <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    command.
+    block devices into the filesystem tree. The follow options are
+    supported:
+  </para>
+
+  <variablelist>
+    <varlistentry>
+      <term><literal>FilesystemDevice</literal></term>
+      <listitem>
+        <para>
+          The block device to mount.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>FilesystemLabel</literal></term>
+      <listitem>
+        <para>
+          The label of the filesystem to mount.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>FilesystemUUID</literal></term>
+      <listitem>
+        <para>
+          The UUID of the filesystem to mount.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>FilesystemMountPath</literal></term>
+      <listitem>
+        <para>
+          The filesystem path where the filesystem is mounted. This option is mandatory.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>FilesystemOptions</literal></term>
+      <listitem>
+        <para>
+          A comma-separated list of options to pass to the
+          <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+          command. This option is optional.
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+  <para>
+    Exactly one of the <literal>FilesystemDevice</literal>,
+    <literal>FilesystemUUID</literal> or
+    <literal>FilesystemLabel</literal> options must be set to specify
+    what filesystem to mount.
   </para>
 
   <refsect2>
@@ -195,25 +233,25 @@ FilesystemMountPath=/mnt/somewhere
 # Mount by label
 #
 [Filesystem id1]
-Label=Some Label
+FilesystemLabel=Some Label
 FilesystemMountPath=/mnt/id1
 
 # Mount by UUID
 #
 [Filesystem id2]
-UUID=4e057fd9-bae5-4a12-83b5-2f654d42edb1
+FilesystemUUID=4e057fd9-bae5-4a12-83b5-2f654d42edb1
 FilesystemMountPath=/mnt/id2
 
 # Mount by device (in this case, a persistent device name)
 #
 [Filesystem id3]
-Device=/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0-part1
+FilesystemDevice=/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0-part1
 FilesystemMountPath=/mnt/id3
 
 # Specify filesystem options
 #
 [Filesystem id4]
-Label=EOS_DIGITAL
+FilesystemLabel=EOS_DIGITAL
 FilesystemMountPath=/media/My Photos
 FilesystemOptions=umask=0022,noatime
 </programlisting>
@@ -224,14 +262,38 @@ FilesystemOptions=umask=0022,noatime
   <title>Luks Items</title>
   <para>
     Items of type <literal>Luks</literal> are used to unlock an
-    encrypted device. The key <literal>UUID</literal> can be used to
-    refer to the device.  The option <literal>LuksPassphrase</literal>
-    is <emphasis>optional</emphasis> and if set, contains the
-    passphrase used to unlock the device. If the
-    <literal>LuksPassphrase</literal> option is not set, then the user
-    is asked for the passphrase when starting the device.
+    encrypted device. The following options are supported:
   </para>
 
+  <variablelist>
+    <varlistentry>
+      <term><literal>LuksUUID</literal></term>
+      <listitem>
+        <para>
+          The UUID of the cryptotext device. This option is mandatory.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>LuksMappingName</literal></term>
+      <listitem>
+        <para>
+          The name to use for the unlocked <literal>dm-crypt</literal> device. This option is optional.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>LuksPassphrase</literal></term>
+      <listitem>
+        <para>
+          The passphrase used to unlock the device. This option is optional.
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
   <note>
     <title>Security Note</title>
     <para>
@@ -244,19 +306,13 @@ FilesystemOptions=umask=0022,noatime
     </para>
   </note>
 
-  <para>
-    The option <literal>LuksMappingName</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
+LuksUUID=5b2aeadf-7f10-4df9-92f2-0bc13123d6e5
 LuksPassphrase=xyz123
 LuksMappingName=sekrit
 
@@ -267,7 +323,7 @@ LuksMappingName=sekrit
 # tandem when running stc(8).
 #
 [Filesystem sekrit]
-UUID=9639-06F4
+FilesystemUUID=9639-06F4
 FilesystemMountPath=/mnt/sekrit
 Depends=sekrit_Luks
 </programlisting>
@@ -279,9 +335,34 @@ Depends=sekrit_Luks
   <para>
     Items of type <literal>Raid</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.
+    aka Linux Software Raid devices. The following options are
+    supported:
+  </para>
+
+  <variablelist>
+    <varlistentry>
+      <term><literal>RaidUUID</literal></term>
+      <listitem>
+        <para>
+          The UUID of the RAID array.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><literal>RaidName</literal></term>
+      <listitem>
+        <para>
+          The name of the RAID array.
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+  <para>
+    Exactly one of the <literal>RaidUUID</literal> or
+    <literal>RaidName</literal> options must be set to specify what
+    RAID array to assemble.
   </para>
 
   <refsect2>
@@ -290,12 +371,12 @@ Depends=sekrit_Luks
 # Refer to array by UUID
 #
 [Raid BigStorage]
-UUID=a4a5646e:933c7856:23bfc059:6e17b7ec
+RaidUUID=a4a5646e:933c7856:23bfc059:6e17b7ec
 
 # Refer to array by name (typically in the homehost:name format)
 #
 [Raid MyRaid]
-Name=x61:MyRaid
+RaidName=x61:MyRaid
 </programlisting>
   </refsect2>
 </refsect1>