path: root/doc/stc.conf.xml

<refentry id="stc.conf" lang="en">
<refmeta>
  <refentrytitle>stc.conf</refentrytitle>
  <manvolnum>5</manvolnum>
  <refmiscinfo class="manual">Storage Configuration</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 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 encrypted device, how to activate a LVM Volume Group and
    so on. Additionally, items can depend on each other. This allows
    handling complex inter-subsystem storage trees such as:
  </para>
<programlisting>
                   Filesystem
                     MyData
                       |
                     Luks
                  MyData_Luks
                       |
                   LVMVolume
     +------------ MyData_LV ----------------+
     |                 |                     |
     |                 |                     |
    Raid             Raid                   Raid
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 running a simple command
    referencing the <literal>MyData</literal> item.
  </para>
  <para>
    The
    <citerefentry><refentrytitle>stc</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    command can be used to start/stop/enumerate items as well as
    inquire about the current item state. The configuration file
    format is intentionally extensible – item types to support
    emerging storage subsystems may be added in the future. The
    <citerefentry><refentrytitle>stcd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    system daemon is responsible for automatically starting items as
    well as cleaning up defunct items.
  </para>
</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]
FilesystemDevice=/dev/disk/by-uuid/1234:5678
FilesystemMountPath=/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>
    Identifiers can only contain alphanumeric characters as well as
    underscores (<literal>[a-zA-Z0-9_]</literal>).
  </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>Comment</literal></term>
      <listitem>
        <para>
          A human-readable string describing the entry.
        </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>

    <varlistentry>
      <term><literal>Auto</literal></term>
      <listitem>
        <para>
          If set to <literal>true</literal> then the
          <citerefentry><refentrytitle>stcd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
          system daemon will automatically start the item (including
          its dependencies) when all dependent devices are in
          place. Additionally, if the item ends up in a defunct state
          (by e.g. the dependent device disappearing) the system
          daemon will automatically stop the item. It is only
          necessary to use this option on top-level items (e.g. items
          that does not have any dependencies themselves) as
          starting/stopping an item includes starting/stopping its
          dependencies.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>

  <para>
    Additionally, items can have type-specific keys. See each item
    type for details.
  </para>
</refsect1>

<refsect1>
  <title>Filesystem Items</title>
  <para>
    Items of type <literal>Filesystem</literal> are used to mount
    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>
    <title>Examples</title>
<programlisting>
# Mount by label
#
[Filesystem id1]
FilesystemLabel=Some Label
FilesystemMountPath=/mnt/id1

# Mount by UUID
#
[Filesystem id2]
FilesystemUUID=4e057fd9-bae5-4a12-83b5-2f654d42edb1
FilesystemMountPath=/mnt/id2

# Mount by device (in this case, a persistent device name)
#
[Filesystem id3]
FilesystemDevice=/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0-part1
FilesystemMountPath=/mnt/id3

# Specify filesystem options
#
[Filesystem id4]
FilesystemLabel=EOS_DIGITAL
FilesystemMountPath=/media/My Photos
FilesystemOptions=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 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. If not used, then the user is asked for the
          passphrase when starting the device via e.g.
          <citerefentry><refentrytitle>stc</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>

  <note>
    <title>Security Note</title>
    <para>
      If using the <literal>LuksPassphrase</literal> option, the
      <literal>Luks</literal> item should be stored in a file that is
      not world-readable (for example, in a separate file in the
      <filename>/etc/stc.conf.d</filename> directory). Otherwise any
      unprivileged user with access to the system will be able to
      obtain the passphrase.
    </para>
  </note>

  <refsect2>
    <title>Examples</title>
<programlisting>
# Passphrase and mapping name given
#
[Luks sekrit_Luks]
LuksUUID=5b2aeadf-7f10-4df9-92f2-0bc13123d6e5
LuksPassphrase=xyz123
LuksMappingName=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(8).
#
[Filesystem sekrit]
FilesystemUUID=9639-06F4
FilesystemMountPath=/mnt/sekrit
Depends=sekrit_Luks
</programlisting>
  </refsect2>
</refsect1>

<refsect1>
  <title>Raid Items</title>
  <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 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>
    <title>Examples</title>
<programlisting>
# Refer to array by UUID
#
[Raid BigStorage]
RaidUUID=a4a5646e:933c7856:23bfc059:6e17b7ec

# Refer to array by name (typically in the homehost:name format)
#
[Raid MyRaid]
RaidName=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>8</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>stcd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>md</refentrytitle><manvolnum>4</manvolnum></citerefentry>
  </para>
</refsect1>

</refentry>