When we discussed ensuring a hassle-free upgrade recently, I casually mentioned one of the benefits of using version control to keep track of changes to the /etc/ configuration directory — the fact that it makes it easy to migrate your settings to a new machine. But there are other benefits, too, such as rolling back after accidents, and tracking down unintended changes made by overactive packages. Let’s take a look at how etckeeper can help.
Background
Debian developer Joey Hess starting writingetckeeper after unsatisfying experiments with other people’s attempts to shoehorn /etc/ into a Git repository. A few people had done so successfully, but ran into two major problems: what to do when a package installation made changes to the directory or a file (i.e., and the user could not enter the usual log entry), and what to do about metadata changes like file permissions. File permissions are pretty important for files like /etc/shadow, but most version control systems (VCS) are not set up to notice them, because VCS is designed primarily for software development.
Hess sought out to combine the home brewed solutions demonstrated by others into an easily-installable package. The result is etckeeper, a highly flexible revision control service for /etc/. It can use not only Git (the original option), but any of a long list of popular VCSes, including Mercurial, Darcs, and Bazaar. It tracks metadata changes on its own, and although you can manually enter changelogs whenever you edit a file, it also does automatic nightly checks to record any updates you’ve overlooked.
Etckeeper also hooks into all of the major package managers: Apt, YUM, and Pacman-G2. As a result, any changes that are triggered by pre-installation scripts, new packages, or post-installation scripts are automatically tagged in the log.
Installation & Configuration
Etckeeper is already packaged for most of the major distributions, including Debian, Ubuntu, Fedora, and OpenSUSE. If you use another distribution — or simply prefer to compile from source — you can grab the latest release from the etckeeper site. The most recent version is 0.57, from November of 2011. There are no major dependencies for the core package itself, however you do need to have at least one of the supported VCSes installed — etckeeper makes use of your VCS of choice, rather than implementing its own.
The main configuration file is located in /etc/etckeeper/etckeeper.conf, and the first option you need to check is the VCS line. Simply uncomment-out the VCS that you intend to use; most of the distributions will already have chosen a sensible default that works well with its other development tools (for example, Ubuntu defaults to Bazaar). Below this line is a set of COMMIT_OPTIONS lines, on which you can specify command-line options that etckeeper needs to pass to the VCS upon each logged change.
Next are two options for honing down etckeeper’s logging behavior. You can uncomment the AVOID_DAILYAUTOCOMMITS=1 line to tell etckeeper not to run a nightly check looking for unlogged changes. You can also uncomment the AVOID_COMMIT_BEFORE_INSTALL=1 line to keep etckeeper from running an extra autocommit before starting a package installation. This is safe to do, because if the autocommit is switched off, etckeeper will stop the installation process, warn you that there is an un-logged change in /etc that you need to worry about, and allow you to perform the commit (or roll it back) before proceeding.
The last two lines ask you to specify the high-level and low-level package managers used on your system — for instance, Apt and dpkg on a Debian-based system, or YUM and rpm on an RPM-based system. Here, too, the distro will probably have the default chosen correctly for you. You may need to initialize etckeeper after installation — but only if your distro’s package does not do so automatically. Check the documentation to be sure, but if you need to initialize the system, just run sudo etckeeper init.
Ready, /etc, Run
In practice, etckeeper will run in the background, and your main interaction with it will be through changelog messages you submit after each editing session where you modify a configuration file. Etckeeper needs root privileges to run, but you will also need them to edit the files in /etc/.
For example, if you change the contents of /etc/hosts, you can then log the reason for your change with etckeeper. Type: sudo etckeeper commit "Added new NAS box to hosts file.". Etckeeper will commit the changed file to the VCS, tagged with your commit message.
You can check the history of your changes using the raw VCS tools. For example, on a Debian-based system, type sudo bzr log --line /etc. Bazaar will replay back the date and log messages of each of your changes. You’re more likely to remember the details of the change if you made it yourself, but don’t forget that etckeeper logs changes triggered by package installations as well. To see the details of last change line-for-line, all you have to do is type sudo bzr diff /etc.
Etckeeper writes detailed log messages to the VCS when tracking package-triggered changes. You will see “committing changes in /etc after apt run” or a similar message, followed a list of the changed packages, with a + indicating an installation, and a - indicating a removal.
Commits made during etckeeper’s daily sweep are logged with “daily autocommit” as the message. Naturally, this is the least informative of the changelog messages, but etckeeper has no information to go on in these circumstances. In this case, it’s important to remember that the VCS commit logs the actual file alteration for rollback purposes as well. An unidentified change caught by the nightly sweep might not have a clear message, but at least you know it is logged, and you can revert it in the case of problems.
Metadata changes are logged in their own special file, /etc/.etckeeper. By writing the permissions and other metadata values to a flat file, etckeeper gets around the fact that most VCSes do not track file metadata at all. Permission changes are thus recorded in etckeeper’s logs as changes to the .etckeeper file. You can read the contents of the file on your own, or view its log with the normal VCS diff commands.
Keep it real
Of course, the principle limitation to etckeeper is that it only monitors the /etc/ directory, while there are other important locations you might want to keep track of, too. But etckeeper is not just a mechanism to use version control on a single directory; it hooks into package management and performs nightly scans for a reason. The /etc/ directory is where changes are supposed to go regularly; if you want to set up your VCS to watch other specific locations (such as $HOME or /var/www/), you are likely to need a lot of customization anyway.
It may still be a worthwhile exercise; if you are so interested, I recommend checking out the links that Hess provides on his initial etckeeper announcement. They are Git-centric, but apply equally well to other VCS choices; you can learn a lot by following the process that others have been down before.
