overcfg
Licensing and disclaimer
This software is licensed under the GNU General Public License version 2. It 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 COPYING file included in the distribution for more information.
Info
overcfg
=======
overcfg is a simple configuration file management utility designed to
complement the Gentoo Linux package manager: Portage.
overcfg was originally developed at Brontes Technologies, a 3M ESPE subsidiary.
It has been released to the community under the terms of the GNU General Public
License version 2. See the COPYING file for more information.
Although overcfg was written specifically for Portage, and does parse some of
Portage's database, it should be possible to modify it for similar uses on
other systems.
overcfg is written in python and has no special requirements other than a
portage-style /var/db/pkg package tree.
Homepage: http://www.brontes3d.com/opensource
The problem
===========
Many packages install configuration files which can optionally be modified by
the user. When a newer version of the same package is installed, it attempts
to install the configuration file again.
The new configuration file may be identical the the one in the previous version,
or it may have changed. The user may have added their own customizations to
the installed copy, and would like those customizations to persist across
updates.
By default, Portage hands this problem off to the user: Portage does not
overwrite configuration files. Instead, it installs them in a special location
and notifies the user that some configuration files need to be reprocessed. The
user then uses portage-supplied tools to manage merging in the new changes.
In an embedded product environment, the user never goes near the console, so
the above system is not appropriate.
The solution
============
As input, overcfg takes a specially formatted directory tree of configuration
files ("the store"). All of these configuration files are your custom versions
of the files, indexed by package that owns the original copy and version of
the package which your modified version applies to.
You configure Portage to ALWAYS overwrite configuration files. Then, at the
end of every update session, you run overcfg.
overcfg iterates over the store, comparing each configuration file to the one
on-disk. If the on-disk copy is different, overcfg overwrites it with the one
from the store. This way, your own modifications are put back in place.
It's designed to simple and not to limit you, and as such, overcfg is only
really useful for frozen package trees, where introduction of new versions is
tightly controlled. As files in the store are indexed by version, you need to
have the opportunity to update the store on all your target systems before you
ship the new package version.
Usage
=====
You first need to set up a store at /usr/share/overcfg. It makes sense to
maintain the contents of this store in an ebuild, so that you can push out
updates at will. We'll assume your configurations are owned by a package named
"app-admin/my-overcfg-configs".
Put your custom configuration files in the store under the following path
format:
/usr/share/overcfg/pkg/<CAT>/<PKG>/<VER>/<TARGET PATH>/<FILENAME>
TARGET PATH can be multiple directories, e.g. you might have "etc/conf.d"
For example, my-overcfg-configs would install a file/directory tree as follows:
/usr/share/overcfg/pkg/app-admin/sudo/1.6.8_p9/etc/sudoers
/usr/share/overcfg/pkg/sys-apps/baselayout/2.0.0_alpha3/etc/conf.d/rc
The above files correspond to:
1. /etc/conf.d/rc to overwrite the /etc/conf.d/rc file shipped in
sys-apps/baselayout-2.0.0_alpha3
2. /etc/sudoers to overwrite the /etc/sudoers file shipped in
app-admin/sudo-1.6.8_p9
Next, disable Portage's configuration file protection. This is important so
that other configuration files shipped by sudo and baselayout (which you do
not modify) get overwritten when newer versions are installed. The same also
applies to configuration files owned by separate packages (of which you modify
0).
To do this, put the following line in /etc/make.conf:
CONFIG_PROTECT="-*"
And that's about it, configuration wise. Here are some situations where
overcfg becomes useful:
When you emerge sudo-1.6.8_p9, it puts it's own default /etc/sudoers file in
place. Then, at the end of the emerge, you run overcfg-update. overcfg
realises a difference in the /etc/sudoers file and the one in the store, so
overwrites /etc/sudoers with your own version.
Later on, a user modifies /etc/sudoers and screws it up. Actually, users should
never modify files which are indexed in your store, so let's say a script
screwed up your sudoers file instead. Run overcfg-update. overcfg will restore
the sudoers file from the store.
Someone or something deletes your sudo binary. To fix it, you reinstall the sudo
package, which puts the default /etc/sudoers back in place (remember, you
disabled configuration file protection). After you reinstall sudo, you run
overcfg-update, which puts your customised sudoers back in place.
sudo-1.6.8_p10 comes out. You want to upgrade, but the above considerations of
losing your own configuration apply. You first create a new file in your store:
/usr/share/overcfg/pkg/app-admin/sudo/1.6.8_p10/etc/sudoers
This file is exactly the same as the _p9 version.
Next, you do a new my-overcfg-configs release, and distribute it to all your
target systems. Then, you ship the new sudo version to those systems, and
install it, overwriting your sudoers file. Finally, you run overcfg, and your
own modifications are put back in place.
sudo-2.0.0 comes out. It has a new /etc/sudoers file format which is
incompatible with the old one. You want to support both 1.6.8 and 2.0.0 for
a while. You create a new file in your store:
/usr/share/overcfg/pkg/app-admin/sudo/2.0.0/etc/sudoers
This file is your customised version of sudoers, in the 2.0.0 file format. You
also leave the 1.6.8 versions in your store, untouched. You do a new
my-overcfg-configs release and distribute it. Then, on all target systems, no
matter which sudo version you install, overcfg puts the right configuration
file in place.
So, if we are to devise some 'rules' for using overcfg correctly:
1. Disable config file protection
2. Use a frozen package tree, where you tightly control introduction of new
package versions.
3. Roll out new my-overcfg-configs package releases to all your target
systems BEFORE shipping them new versions of packages
4. If a new package version comes out, even a -r release, remember to copy
all existing configuration files in your store to a directory
corresponding to the new version number.
5. Run overcfg at the end of every emerge
6. Don't allow use of the system while updates are taking place, to avoid any
potential issues in the time window where the default configuration has
overwritten your customised configs, and overcfg has not yet been run.
Additional features
===================
1. Metadata
By default, all files are owned by user root, group root, with 644 permissions.
If you want to change these, adjusting permissions and/or ownership of the
files within the store will NOT have an effect.
Instead, create a metadata file in your store, with the same name as the
configuration file but with "%metadata" on the end. The format for this file is:
user myuser
group users
mode 755
You do not have to specify all 3 lines, only the parts you want to customise.
In the sudoers example above, you must ensure that /etc/sudoers has 440
permissions, otherwise sudo will refuse to operate. So, you would create a file:
/usr/share/overcfg/pkg/app-admin/sudo/1.6.8_p9/etc/sudoers%metadata
with this line:
mode 440
2. Logging
overcfg creates per-session logs in /var/log/overcfg. It logs the operations
it has performed and the files that it has modified.
3. Backups
When overcfg does overwrite a configuration file, it backs up the old one to
/var/lib/overcfg/backups/<DATE>-<TIME>/<PATH>/<FILE>
and compresses the backup.
In the above example, we would have e.g.:
/var/lib/overcfg/backups/20070622-162431/etc/sudoers.gz
4. Misc file syncing
overcfg can also sync files that are not part of any package. You put them
under the "misc" directory in your store. For example:
/usr/share/overcfg/misc/usr/sbin/foobar
would install /usr/sbin/foobar and synchronize in the same fashion that it
handles configuration files. All other considerations such as backup and
metadata also apply to these files.
The intended use of this feature is to allow you to ship scripts in the same
tarball as your configuration files, which are often somewhat paired.
5. Sanity checking
overcfg runs some sanity checks on your store directory. It detects stray files
in your store which it doesn't recognise, for example all of the following:
/usr/share/overcfg/pkg/app-admin/sudo/foo
/usr/share/overcfg/pkg/app-admin/foo
/usr/share/overcfg/pkg/foo
If it finds a file in one of these locations, it will log a message.
The other checking it does is presence of versions. There is always the danger
that in the above example, sudo-1.6.8_p10 comes out but you totally forget
about the configuration customisation. You install the new version, you lose
your sudoers file, overcfg doesn't restore it, and you have a broken system.
To help you avoid forgetting this, overcfg will produce a warning if all of
the following conditions are true:
1. sudo-1.6.8_p10 is installed on your system
2. /usr/share/overcfg/pkg/app-admin/sudo/ exists
3. /usr/share/overcfg/pkg/app-admin/sudo/1.6.8_p10/ does not exist
The above check is useful, but a situation may arise where you no longer need
to ship customised configurations for later versions of sudo, in which case
you have no requirement to put anything in your store.
To make the warnings go away in such a situation, add empty directories for
each new version to your store. overcfg will stop complaining. Then, when you
are ready to stop supporting all the older versions of the package, delete the
whole pkg/app-admin/sudo directory structure.