metche - reducing root bus factor
homepage: https://0xacab.org/metche/metche/
Git repository: https://0xacab.org/metche/metche.git
dev team: metche AT lists DOT riseup DOT net

,-------------------------------------------------------------------------------
| Copyright (C) 2004-2006 boum.org collective - property is theft !
| Copyright (C) 2009-2011 metche developers <metche@lists.riseup.net>
`-------------------------------------------------------------------------------

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.

,-------------------------------------------------------------------------------
| OVERVIEW
`-------------------------------------------------------------------------------

metche is a tool meant to ease collective system administration. It does
periodically :
   - save the "system state" of 
      . $WATCHED_DIR (default: /etc)
      . $CHANGELOG_FILE (default /root/Changelog)
        or $CHANGELOG_DIR/*/Changelog (default: /root/changelogs/*/Changelog)
      . Debian packages states and versions if $DO_PACKAGES is set to "yes"
        (default: no)
     to $BACKUP_DIR (default: /var/lib/metche).
   - send a nicely formatted email to a defined email address, listing the last
     changes that have been made to the system.
     See https://0xacab.org/metche/metche for an example.

,-------------------------------------------------------------------------------
| BASIC USAGE
`-------------------------------------------------------------------------------

When installed and configured, metche is run by a cron job. You just have to
read the report emails. Of course it's not useful at all if you don't:
   - set the $EMAIL_ADDRESS config variable to your sysadmins' collective 
     mailing-list or email address;
   - use the Changelog files in a rigorous way.

Note: It is dangerous to use metche without reading the SECURITY section
of the manpage before.

For further explanation of the way metche works, read the metche(8) manpage and
the FAQ file.

,-------------------------------------------------------------------------------
| REQUIREMENTS
`-------------------------------------------------------------------------------

   * Debian GNU/Linux and apt-show-versions (if Debian package monitoring is
     enabled)
   * mutt or mail or sendmail
   * bzip2
   * If you want metche to encrypt the email it sends: gnupg
   * If you want metche to monitor your vservers as well: util-vserver tools
   * If you want metche to monitor one manually written Changelog file,
     it must be located at $CHANGELOG_FILE.
_or_ If you want metche to monitor multiple manually written Changelog
     files, they must be located in $CHANGELOG_DIR/*/Changelog;
     for example this way:
        /root/
            changelogs/
                common/Changelog
                apache/Changelog
                postfix/Changelog

,-------------------------------------------------------------------------------
| INSTALLATION
`-------------------------------------------------------------------------------

Please see the included INSTALL file.

,-------------------------------------------------------------------------------
| CONFIGURATION
`-------------------------------------------------------------------------------

1. Copy metche.conf.default to /etc/metche.conf and edit it so that it suits
   your needs.
2. Read the next sections of this document and the metche(8) manpage.
3. Add to /etc/cron.d/metche something like:
     0-59/5 * * * * root test -x /usr/local/sbin/metche && \
                         /usr/local/sbin/metche cron
   See the cron (8) manpage for further explanations on how to create a cron 
   job.

,-------------------------------------------------------------------------------
| VSERVERS SUPPORT
`-------------------------------------------------------------------------------

Just add one (or more) VServer name to the VSNAMES configuration variable, and
metche will monitor it in addition to the host system:
   - the WATCHED_DIR, CHANGELOG_DIR and CHANGELOG_FILE paths are also used,
     relatively to your VServer's root directory;
   - the "system state" backups will be saved in sub-directory in BACKUP_DIR's,
     called the same as the VServer;
   - EMAIL_ADDRESS is not used for the VServers: the report messages will be
     sent to the root email address of the VServer; if you're using
     ENCRYPT_EMAIL to encrypt the report messages, make sure the relevant
     public key are in the host system root's keyring, trusted enough to be
     used blindly by metche;
   - all other configuration variables are used as it.

Most of metche commands (namely: list, report and stabilize) support a
'-h <VSERVER>' option:
   - if -h is specified, metche only operates on the VServer provided as an
     argument;
   - else, metche only operates on the host system.

Troubleshooting: in case you have a not-purely-Debianish VServer setup, you may
have to customize some of the VServers-related configuration variables. See the
comments in metche.conf for more details.

,-------------------------------------------------------------------------------
| SECURITY WARNING
`-------------------------------------------------------------------------------

Read the SECURITY section of metche(8). Really.