From 544aef9dfa8c214ec1543815832e882f138b2af0 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Wed, 6 Oct 2010 17:57:11 -0400 Subject: Add a stc.conf(5) man page Signed-off-by: David Zeuthen --- doc/Makefile.am | 4 + doc/stc-docs.xml | 1 + doc/stc.conf.xml | 285 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/stc.xml | 3 + 4 files changed, 293 insertions(+) create mode 100644 doc/stc.conf.xml 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 @@ Tools Reference + 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 @@ + + + stc.conf + 5 + Storage Configuration Files + + + + stc.conf + + Storage configuration files + + + + + Synopsis + + /etc/stc.conf + /etc/stc.conf.d/*.conf + + + + + + Description + + The /etc/stc.conf and + /etc/stc.conf.d/*.conf files contain + descriptive information about various file systems and + devices. These configuration files, collectively, contains a set + of storage items. 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. + + + 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: + + + 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) + + + The above example shows that MyData depends on + MyData_LUKS that depends on + MyData_LV. Additionally, + MyData_LV depends on three RAID arrays, + MyData_LV_PV1, MyData_LV_PV2 + and MyData_LV_PV3 (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 + + +# stc start --id MyData +# stc stop --id MyData + + + + + Configuration Files + + Storage items are declared in the + /etc/stc.conf and + /etc/stc.conf.d/*.conf. Each file is a + key/value-file (also commonly known as + ini-files) — see the Desktop + Entry Specification specification for the syntax of + key/value files. Each storage item is group + where the group name contains two words conveying the type + resp. the identifier for the item. A simple example of a storage + item is: + + +[Filesystem MyDisk] +Device=/dev/disk/by-uuid/1234:5678 +Options=Filesystem:mount_path=/mnt/somewhere + + + In the above example, the type of the item is + Filesystem while the identifier is + MyDisk. Additionally, the item conveys that the + device /dev/disk/by-uuid/1234:5678 should be + mounted at /mnt/somewhere. + + + 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. + + + Each item supports the following keys: + + + + Device, Label, UUID, Name + + + 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. + + + + + + NickName + + + A human-readable string describing the entry. + + + + + + Options + + + A list of options to use when starting the item. See each + item type what set of keys are supported and/or required. + + + + + + Depends + + + 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. + + + + + + + + + Filesystem Items + + Items of type Filesystem are used to mount a + device into the filesystem tree — you can use keys + Device, UUID and + Label to refer to the device. + + + The option Filesystem:mount_path is mandatory + and is used to specify the path where the device should be + mounted. The option Filesystem:options is + optional and is a comma-separated list of options passed to the + mount8 + command. + + + + Examples + +# 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 + + + + + + LUKS Items + + Items of type LUKS are used to unlock an + encrypted device. The keys Device and + UUID can be used to refer to the device. + + + The option LUKS:passphrase 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 LUKS:mapping_name is + likewise optional and if set, then the given name will be used for + the resulting dm-crypt device. + + + + Examples + +# 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 + + + + + + MDRaid Items + + Items of type MDRaid are used to assemble + md4 + aka Linux Software Raid devices. The keys UUID + and Name can be used to refer to the RAID + array. + + + + Examples + +# 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 + + + + + + Author + + Written by David Zeuthen zeuthen@gmail.com with + a lot of help from many others. + + + + + See also + + stc1, + mount8, + md4 + + + + diff --git a/doc/stc.xml b/doc/stc.xml index 84ee572..b9f9a17 100644 --- a/doc/stc.xml +++ b/doc/stc.xml @@ -34,6 +34,9 @@ See also + + stc.conf5 + , udisks1 -- cgit v1.2.3