etcmanage is used to update configuration files (typically in /etc)
automatically.  The essential concept is that a file which was
installed automatically and has not been changed will be updated with
new versions, and modified files will not be changed.

WARNING - ETCMANAGE MAY RENDER YOUR SYSTEM UNUSABLE

Before starting, back up all of etc (e.g., tar up and leave tarball on
/), and ensure that you can boot from another root (e.g. floppy, cd,
etc.).  etcmanage is alpha code and comes with no sanity checks; it is
possible to remove most of /etc.

At this time, etcmanage should be used only by those who have backups
and are very familiar with system administration and recovery from
trashed root filesystems.


USAGE

To generate a manifest:
  cd /usr/src/etc && make DESTDIR=$HOME/DESTDIR distrib-dirs distribution
  # note that this is $HOME/DESTDIR, not $HOME/DESTDIR/etc
  etcmanage --generate-manifest $HOME/DESTDIR > $HOME/manifest-version

To import a manifest:
  etcmanage --import < $HOME/manifest-version

To update from source:
  cd /usr/src/etc && make DESTDIR=$HOME/DESTDIR distrib-dirs distribution
  # note that this is DESTDIR, not DESTDIR/etc
  etcmanage --update $HOME/DESTDIR

Note that the argument to --update is a DESTDIR, not a copy of /etc.
If $1 is the argument, then e.g. $1/etc/services should exist.

To get the list of unmanaged files

  etcmanage --unmanaged

To put a file in /etc (or anywhere else) under etcmanage's control:

  etcmanage --add FILE

To put a file back under manual control:

  etcmanage --remove FILE

or:

  etcmanage --manual FILE

Differences between '--remove' and '--manual':

  * The '--remove' command deletes the file's entry from the etcmanage
    database.  Because the file is no longer in the database, a future
    '--update' command will cause that file to become managed again if
    upstream still has a copy of that file but the local copy of the
    file has been deleted (etcmanage will think that the upstream file
    is a brand new config file).  The '--manual' command marks the
    file's entry in the database as "manually managed" to prevent
    'etcmanage --update' from causing the file to become managed.

  * Using the '--manual' command on a file causes '--update' to use an
    alternate log message when processing the file.  The alternate
    message includes the string "MANUAL" to remind the user that the
    file is marked as manually managed.  All "MANUAL" messages are
    written to standard output (stdout) instead of standard error
    (stderr)---even when the upstream file is different or
    withdrawn---because differences are expected, not unusual.


MANAGED VS. UNMANAGED

Each file is considered to be in one of two states:  managed or
unmanaged.  etcmanage tries to take care of managed files for you,
while unmanaged files are your responsibility.

When a file is managed, 'etcmanage --update' will automatically update
the local copy of a config file to match the current upstream version
if the local copy has not changed.  (This includes deleting the local
copy if the file no longer exists upstream.)

All files are unmanaged by default.  A file can become managed in the
following ways:
  * you run 'etcmanage --add' on the file
  * you run 'etcmanage --import-manifest' and the hash in the manifest
    matches the hash of the file
  * you run 'etcmanage --update' and the following are true:
      - the file exists in the directory passed to '--update'
      - the file does not exist in your local system
      - the file is not in the etcmanage database
    This behavior causes etcmanage to automatically manage new
    upstream config files.

A file can become unmanaged in the following ways:
  * you run 'etcmanage --clear' (but a later 'etcmanage --update' will
    cause the file to become managed again if you delete your local
    copy)
  * you run 'etcmanage --remove' on the file (but a later 'etcmanage
    --update' will cause the file to become managed again if you
    delete your local copy of the file)
  * you run 'etcmanage --manual' on the file
  * you run 'etcmanage --update' and the following are true:
      - the file does not exist in the directory passed to '--update'
      - the file does exist in your local system
      - the hash stored in the database matches the hash of your local
        version of the file
      - the file is not marked as manually managed in the database
        (via the '--manual' command)
    This behavior allows etcmanage to forget about obsolete config
    files.


DESIGN

etcmanage keeps a database of files and md5sums in
/var/db/etcmanage.db.  If the database does not contain an entry for a
file, then that file is considered to be unmanaged (although it may
automatically become managed after running 'etcmanage --update').  If
the database does have an entry for the file, but the value stored in
the md5 field is "manual", then the file is considered to be unmanaged
and it will never automatically become managed.  An entry in the
database with a value in the md5 field other than "manual" means that
the file is managed.  The md5sum is that of the version of the file
that was declared to be automatically managed.  The filename in the
database is absolute, e.g. "/etc/services".

Manual operations are provided to print the database, remove a file,
and add a file.  Adding will record the current md5sum.

etcmanage can produce a "standard manifest" (space-separated line with
filename and md5sum) from a etc tree (such as would appear in DESTDIR
with a make install).  This database then contains md5sums of files
that might have been automatically installed, and are therefore not
customized.

etcmanage can read a standard manifest and mark files automatically
managed if they match.  This can be used to seed the database for
systems not installed with etcmanage in the first place.  This
operation is effected by examining all files in /etc, and for those
not in the database, computing their md5sum and comparing to the
standard manifest.

One might produce standard databases for NetBSD 1.5, 1.5.1, 1.5.2,
1.5.3 and 1.6, and cat them together.  Manifests need not be sorted.

etcmanage can update /etc from another tree.  For each file that is in
the database and unmodified, if the file exists in the new tree it is
updated (and the new md5sum stored).  If it does not exist in the new
tree, it is removed from the filesystem and the database.  Files that
are in the new tree but not present are installed in /etc (and the
md5sum stored).


TIPS

The MANIFESTS/ directory in this release directory contains recent
manifests for several versions of NetBSD.  To put /etc under control
of etcmanage for the first time, it's easiest to --import the provided
manifest file corresponding to your version of NetBSD, then use
--unmanaged to find stray files and --add them.


BUGS

etcmanage does not understand METALOG files in DESTDIR.  Thus it
cannot be used with UNPRIVed builds (or rather, when used with
UNPRIVed builds results in incorrect ownership of files in /etc).

etcmanage lacks a man page and invocation help.
