<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<RefEntry id="metche">
<refmeta>
<refentrytitle>metche</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>metche</refname>
<refpurpose>reducing root bus factor</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>metche</command>
<arg>-h <replaceable>vserver</replaceable></arg>
<group choice="req">
<arg>report
<arg choice="opt">
<group choice="req">
<arg>stable</arg>
<arg>testing</arg>
<arg>unstable</arg>
</group>-<replaceable>YYYYMMDDHHMM</replaceable>
</arg>
</arg>
<arg>list</arg>
<arg>stabilize <arg choice="opt">testing-<replaceable>YYYYMMDDHHMM</replaceable></arg></arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>DESCRIPTION</title>
<Para>metche is a tool meant to ease collective system administration by
monitoring changes in the system configuration.</Para>
<Para>metche basic usage is to monitor changes in a directory, usually
<filename>/etc</filename> ; optionally, metche can also
monitor:</Para>
<ItemizedList>
<ListItem>
<Para>one or more user maintained changelog files,</Para>
</ListItem>
<ListItem>
<Para>the state of Debian packages and versions.</Para>
</ListItem>
</ItemizedList>
<Para>metche should be installed with a cronjob that regularly runs to
automatically save the system state as needed. These states are saved in a
way similar to the Debian development model:</Para>
<ItemizedList>
<ListItem>
<Para><emphasis>unstable</emphasis> states are saved as soon as
a change is detected. They are kept until a new
<emphasis>testing</emphasis> state appears.</Para>
</ListItem>
<ListItem>
<Para><emphasis>testing</emphasis> states is created from the last
<emphasis>unstable</emphasis> state that has not been changed
after a short amount of time (by default, one hour). Old
<emphasis>unstable</emphasis> states are deleted afterwards.</Para>
</ListItem>
<ListItem>
<Para><emphasis>stable</emphasis> states are created from the last
<emphasis>testing</emphasis> state, either manually, or after a
long amount of time (by default, 3 days). Old <emphasis
>testing</emphasis> states are deleted afterwards.</Para>
</ListItem>
</ItemizedList>
<Para>When a new <emphasis>testing</emphasis> state is saved, an email is
sent to a configurable address, giving an overwiew of
the differences with the previous <emphasis>testing</emphasis>.
A notification is also sent when a new <emphasis>stable</emphasis> state is
saved.</Para>
<Para>metche's configuration is read from
<filename>/etc/metche.conf</filename>. Various settings like changelog
monitoring or time between system state switches are described
there.</Para>
</refsect1>
<refsect1 id="options">
<title>OPTIONS</title>
<Para>If <command>-h</command> <emphasis>VSERVER</emphasis> is specified,
the VServer <emphasis>VSERVER</emphasis> is operated on instead of
the host system. This, along with the <envar>VSNAMES</envar> option,
allows to monitor several VServers running on the system.</Para>
<Para>One of the following commands must be specified on the
command line:</Para>
<VariableList>
<VarListEntry><Term><command>report</command></Term>
<ListItem>
<Para>When run with the <command>report</command> command, metche
displays a report against the specified saved state, or if unspecified,
against the latest testing state. This is useful when you
have broken your system and want to know which changes have been made
since a given, known working, system state.</Para>
</ListItem>
</VarListEntry>
<VarListEntry><Term><command>list</command></Term>
<ListItem>
<Para>When run with the <command>list</command> command, metche
displays a list of all the saved states.</Para>
</ListItem>
</VarListEntry>
<VarListEntry><Term><command>stabilize</command></Term>
<ListItem>
<Para>When run with the <command>stabilize</command> command, metche
turns a "testing state" into a "stable state". By default, it will
use the last "testing state", but this can be overriden by giving
a specific state as argument.</Para>
</ListItem>
</VarListEntry>
<VarListEntry><Term><command>cron</command></Term>
<ListItem>
<Para>This command should not be called manually, but used from
a cronjob. When called, it can perform various operations like:
saving "unstable", "testing" or "stable" states as needed and
sending reports and notification if configured to do so. This command
does not support the <command>-h</command> option.</Para>
</ListItem>
</VarListEntry>
</VariableList>
</refsect1>
<refsect1 id="files"><title>FILES</title>
<Para><filename>/etc/metche.conf</filename> contains metche configuration.
</Para>
<Para>When configured to monitor one changelog,
<envar>CHANGELOG_FILE</envar> (default:
<filename>/root/Changelog</filename>).
</Para>
<Para>When configured to monitor multiple changelogs,
<filename>CHANGELOG_DIR/*/Changelog</filename>
(default: <filename>/root/changelogs</filename>).</Para>
<Para>System states are saved in
<envar>BACKUP_DIR</envar> (default:
<filename>/var/lib/metche)</filename>.</Para>
</refsect1>
<refsect1 id="security"><title>SECURITY</title>
<Para>metche is able to use GnuPG to encrypt the email it sends, but does
not by default; just enable the <envar>ENCRYPT_EMAIL</envar> configuration
option, and make sure <envar>EMAIL_ADDRESS</envar>' public key is in root's
keyring, trusted enough to be used blindly by metche.
If <envar>EMAIL_ADDRESS</envar> is an email alias or mailing-list's address,
you probably want to use the <envar>group</envar> option
in <filename>/root/.gnupg/gpg.conf</filename> so that metche reports are
encrypted for every person subscribed to this alias or mailing-list; for
more information, see <literal>gpg</literal>(1).</Para>
<Para>When <envar>DO_DETAILS</envar> is enabled and
<envar>ENCRYPT_EMAIL</envar> is disabled, metche sends in <emphasis>clear
text email</emphasis> the changes made to the watched directory... either
make sure that the <envar>EXCLUDES</envar> configuration variable prevents
it to send sensitive information, or triple check that secure connections
will be used end-to-end on the email path. If unsure, set
<envar>EMAIL_ADDRESS</envar> configuration variable to a local mailbox.
Please note that <envar>EMAIL_ADDRESS</envar> is not used for VServers:
a VServer's report messages are sent to its root email address.</Para>
<Para>metche stores, in <envar>BACKUP_DIR</envar> (default :
<filename>/var/lib/metche</filename>), various backups of
<envar>WATCHED_DIR</envar>. Make sure that this backup place is at least as
secured as the source.</Para>
</refsect1>
<refsect1 id="bugs"><title>BUGS</title>
<Para>See <ulink url="https://labs.riseup.net/code/projects/metche/issues">metche's
ticket system</ulink> for known bugs, missing features, and the development
road-map.</Para>
</refsect1>
<refsect1 id="author"><title>AUTHOR</title>
<Para>metche and this manual page were written by the boum.org collective,
and are now maintained by the metche developers collective
<email>metche@lists.riseup.net</email>.</Para>
</refsect1>
</RefEntry>