<!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>host</replaceable></arg>
      <group choice="req">
	<arg>cron</arg>
	<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 facilitate collective sysadmin by
    monitoring changes in the system configuration.</Para>
    
    <Para>At least, metche monitors one directory, usually
    <filename>/etc</filename> ; optionally, metche can also
    monitor:</Para>
    <ItemizedList>
      <ListItem>
	<Para>one ore more user maintained changelog files,
      </ListItem>
      <ListItem>
	<Para>Debian packages states and versions.</Para>
      </ListItem>
    </ItemizedList>

    <Para>metche should be installed with a cronjob regularly running to
    automatically save the system state as needed. These states are saved in a
    way looking like 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>

    <!-- XXX: add a CONFIGURATION section -->
    <Para><envar>WATCHED_DIR</envar> and <envar>CHANGELOG_DIR</envar> options
    can me customized in metche's configuration file, as well as a few other
    ones.</Para>

  </refsect1>
  <refsect1 id="options">

    <title>OPTIONS</title>

    <Para>If <command>-h</command> <emphasis>HOST</emphasis> is specified,
    <filename>/etc/metche/HOST.conf</filename> is used instead of
    <filename>/etc/metche.conf</filename>. This, along with the
    <envar>VSERVER_EXEC_PREFIX</envar> option, allows to monitor several
    vservers running on a 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 a given saved state, if specified, or
	  against the latest testing state, otherwise. 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.
	</ListItem>

      <VarListEntry><Term><command>list</command></Term>
	<ListItem>
	  <Para>When run with the <command>list</command> command, metche
	  displays the full saved states list.</Para>
	</ListItem>

      <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><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.</Para>
	</ListItem>

    </VariableList>

  </refsect1>

  <refsect1 id="files"><title>FILES</title>
    <Para><filename>/etc/metche.conf</filename> or
    <filename>/etc/metche/*.conf</filename> : configuration file(s)</Para>

    <Para><filename><envar>CHANGELOG_DIR</envar>/*/Changelog</filename>
    (default : <filename>/root/changelogs</filename>), if Changelog monitoring
    is enabled : Changelog files location</Para>

    <Para><filename><envar>BACKUP_DIR</envar></filename> : directory containing
    the backups</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.</Para>

    <Para>In its default setup (<envar>ENCRYPT_EMAIL</envar> configuration
    option disabled) metche sends in <emphasis>clear text email</emphasis> the
    changes made to the watched directory... either make sure that the
    <envar>TAR_OPTS</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.</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.
  </refsect1>

  <refsect1 id="bugs"><title>BUGS</title>
    <Para>See <ulink url="https://poivron.org/dev/metche/">metche's ticket
    system</ulink> to see the bugs, missing features, and development
    road-map.</Para> 
  </refsect1>

  <refsect1 id="author"><title>AUTHOR</title>
    <Para>This manual page was written by the boum collective 
    <email>boum@anargeek.net</email>.</Para>
  </refsect1>

</RefEntry>