System Configurations

This page is about how to manage configuration files (like /etc/*) on your machine(s) using subversion.

Simple case

Let's start off simple. I assume you are root, as you are the one modifying the configuration files. You first create a repository:

svnadmin create /svn/configs

Then you can make your root directory a working copy of this (so far empty) repository:

svn checkout file:///svn/configs /

Now you can start adding things you want to keep under revision control. When adding directories, make sure to use the -N (= --non-recursive) flag to add only the directory itself and not all its contents. And add directories before any files therein, although you may add both in the same command.

svn add -N /etc /etc/fstab

Now we want to have a look at what we modified so far. A simple svn stat will tell you all the things that are not under revision control so far. When working with configuration files where you are not interested in many of them this is usually not what you want. Using the -q (= --quiet) flag suppresses those unmanaged files.

svn stat -q /

Now we are ready to commit our configurations to the repository. It is usually a good idea to add and commit files before you modify them for the first time. This way you can always compare any revision of the file to its "virgin" form supplied by your distribution. And always write informative messages so you can later figure out not only what was changed but also why you changed it. Remember to set EDITOR for the root account as well if you do not supply the comment from the command line.

svn commit / -m "vanilla files"

You may want to have a list of all the files under version control. Luckily you can combine the -q flag with -v (= --verbose) to get just that:

svn stat -qv /

The basic work cycle probably is like this:

1. if you modify file for the first time:
   1. add all parent dirs and the file itself
   2. commit
2. edit the file
3. check your modification works as expected, otherwise revert
4. list all modifications
5. commit modifications, including message about the reason for this change

Basic concepts for multiple administrators or machines

Maybe you are not the only one administrating the machine. Assume there are several people who can become root and tweak the config files. You would then want to know who changed what. If you are accessing the repository using the file:// scheme you can simply provide --username yourName to provide this name for the record. It does not even have to correspond to an existing system account.

svn --username john commit /

Maybe you decide to manage the configuration files for several machines in a single repository. For the moment I'll consider the machines rather independent from one another, so that you manage them in completely distinct trees of your repository. Having them in the same repository still helps when diffing them, applying changesets from one machine to another and so on, so it's preferable to rather have subtrees in a single repository than different repositories.

Now let's create a directory for a single machine in the above repository. Note that we create dir directly in the repository, not in any checked out working copy.

svn mkdir file:///svn/configs/macchina

If you start off like this, you can simply check out the empty directory to the root directory of your machine, instead of checking out the repository root as described above. In case you started like described above and only later thought about adding other machines, you'll need to move your existing contents to the new location:

svn move file:///svn/configs/etc file:///svn/configs/macchina/etc
svn switch file:///svn/configs/macchina /

Make sure to first move the contents in the repository and only then switch your working copy, because otherwise you might switch to an empty tree and all your versioned files would be deleted.

You can then create additinal directories for other machines and check them out to their root directory. Let's suppose you are working on a machine called maschine. You could do the following:

svn mkdir ssh svn://root@macchina/svn/configs/maschine
svn checkout ssh svn://root@macchina/svn/configs/maschine /

Advanced tricks for multiple administrators and machines

Note that the trick for logging the user by passing --username to each command only works reasonably well with the file:// scheme. It won't work with ssh access to another machine. And it is easy enough to forget to provide your name. We can solve all this and more by (ab)using the svn facility for defining tunnel applications.

On every machine where you want to manage the configuration using svn, first create the following file named /usr/local/bin/svn sysadmin

#!/bin/bash
# Taken from http://www.orcaware.com/svn/wiki/System_Configurations
if [[ -z $SYSADMIN ]]; then
  SYSADMIN=$(
    read -p "Your (non-root) login name: " NAME </dev/tty >/dev/tty