.TH METCHE 8 "June 5, 2011" "metche user manual"
.SH NAME
.PP
metche - reducing root bus factor
.SH SYNOPSIS
.IP
.nf
\f[C]
metche\ [-h\ VSERVER]\ report\ (stable|testing|unstable)-YYYYMMDDHHMM
metche\ [-h\ VSERVER]\ list
metche\ [-h\ VSERVER]\ stabilize\ testing-YYYYMMDDHHMM
\f[]
.fi
.SH DESCRIPTION
.PP
metche is a tool meant to ease collective system administration by
monitoring changes in the system configuration.
.PP
metche basic usage is to monitor changes in a directory, usually
\f[C]/etc\f[]; optionally, metche can also monitor:
.IP \[bu] 2
one or more user maintained changelog files,
.IP \[bu] 2
the state of Debian packages and versions.
.PP
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:
.IP \[bu] 2
\f[I]unstable\f[] states are saved as soon as a change is detected.
They are kept until a new \f[I]testing\f[] state appears.
.IP \[bu] 2
\f[I]testing\f[] states is created from the last \f[I]unstable\f[] state
that has not been changed after a short amount of time (by default, one
hour).
Old \f[I]unstable\f[] states are deleted afterwards.
.IP \[bu] 2
\f[I]stable\f[] states are created from the last \f[I]testing\f[] state,
either manually, or after a long amount of time (by default, 3 days).
Old \f[I]testing\f[] states are deleted afterwards.
.PP
When a new \f[I]testing\f[] state is saved, an email is sent to a
configurable address, giving an overwiew of the differences with the
previous \f[I]testing\f[].
A notification is also sent when a new \f[I]stable\f[] state is saved.
.PP
metche\[aq]s configuration is read from \f[C]/etc/metche.conf\f[].
Various settings like changelog monitoring or time between system state
switches are described there.
.SH OPTIONS
.PP
If \f[C]-h\ VSERVER\f[] is specified, the VServer \f[I]VSERVER\f[] is
operated on instead of the host system.
This, along with the \f[C]VSNAMES\f[] option, allows one to monitor
several VServers running on the system.
.PP
One of the following commands must be specified on the command line:
.TP
.B report
When run with the \f[I]report\f[] 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.
.RS
.RE
.TP
.B list
When run with the \f[I]list\f[] command, metche displays a list of all
the saved states.
.RS
.RE
.TP
.B stabilize
When run with the \f[I]stabilize\f[] command, metche turns a "testing
state" into a "stable state".
By default, it will use the last "testing state", but this can be
overridden by giving a specific state as argument.
.RS
.RE
.TP
.B cron
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 \f[C]-h\f[] option.
.RS
.RE
.SH FILES
.PP
\f[C]/etc/metche.conf\f[] contains metche configuration.
.PP
When configured to monitor one changelog, \f[C]CHANGELOG_FILE\f[]
(default: \f[C]/root/Changelog\f[]).
.PP
When configured to monitor multiple changelogs,
\f[C]CHANGELOG_DIR/*/Changelog\f[] (default: \f[C]/root/changelogs\f[]).
.PP
System states are saved in \f[C]BACKUP_DIR\f[] (default:
\f[C]/var/lib/metche\f[]).
.SH SECURITY
.PP
metche is able to use GnuPG to encrypt the email it sends, but does not
by default; just enable the \f[C]ENCRYPT_EMAIL\f[] configuration option,
and make sure \f[C]EMAIL_ADDRESS\f[]\[aq] public key is in root\[aq]s
keyring, trusted enough to be used blindly by metche.
If \f[C]EMAIL_ADDRESS\f[] is an email alias or mailing-list\[aq]s
address, you probably want to use the \f[C]group\f[] option in
\f[C]/root/.gnupg/gpg.conf\f[] so that metche reports are encrypted for
every person subscribed to this alias or mailing-list; for more
information, see \f[C]gpg(1)\f[].
.PP
When \f[C]DO_DETAILS\f[] is enabled and \f[C]ENCRYPT_EMAIL\f[] is
disabled, metche sends in \f[I]clear text email\f[] the changes made to
the watched directory...
either make sure that the \f[C]EXCLUDES\f[] 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 \f[C]EMAIL_ADDRESS\f[] configuration variable to a local
mailbox.
Please note that \f[C]EMAIL_ADDRESS\f[] is not used for VServers: a
VServer\[aq]s report messages are sent to its root email address.
.PP
metche stores, in \f[C]BACKUP_DIR\f[] (default:
\f[C]/var/lib/metche\f[]), various backups of \f[C]WATCHED_DIR\f[].
Make sure that this backup place is at least as secured as the source.
.SH BUGS
.PP
See metche\[aq]s ticket
system (https://labs.riseup.net/code/projects/metche/issues) for known
bugs, missing features, and the development road-map.
.SH AUTHORS
metche and this manual page were written by the boum.org collective, and
are now maintained by the metche developers collective
<metche@lists.riseup.net>.