$Id$

etcmanage is used to update files in /etc on a BSD system
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
  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 under etcmanage's control, or put one back under
manual control:

  etcmanage --add FILE
  etcmanage --remove FILE


DESIGN

etcmanage keeps a database of files and md5sums in
/var/db/etcmanage.db.  An entry in the database means that the file
should be treated as automatically 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), and the file is removed in the
new tree.  If it does not exist in the new tree, it is removed from
the filesystem and the database (NOT FOR NOW - TOO SCARY).  Files that
are in the new tree but not present are installed in /etc.  In a later
version, directories can be marked as automatically managed, but
without md5sums.  If such a directory is empty and does not exist in
the new tree, it is removed.


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

The --update option modifies the database while walking the tree, and
this violates the database routine preconditions.  For now, simply rerun
'etcmanage --update /usr/DESTDIR' repeatedly until it produces no output.

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.

etcmanage --update lacks a check for an execssive number of deleted
files, and thus can remove most of /etc if invoked incorrectly.
