Kunterbunt

etckeeper tutorial

## tutorial

A quick walkthrough of using etckeeper.

Note that the default VCS is git, and this tutorial assumes you're using
it. Using other VCSes should be broadly similar.

The `etckeeper init` command initialises an /etc/.git/ repository.
If you installed etckeeper from a package, this was probably automatically
performed during the package installation. If not, your first step is to
run it by hand:

        etckeeper init

The `etckeeper init` command is careful to never overwrite existing files
or directories in /etc. It will create a `.gitignore` if one doesn't
already exist (or update content inside a "managed by etckeeper" comment
block), sets up pre-commit hooks if they don't already exist, and so on. It
does *not* commit any files, but does `git add` all interesting files for
an initial commit later.

Now you might want to run `git status` to check that it includes all
the right files, and none of the wrong files. And you can edit the
`.gitignore` and so forth. Once you're ready, it's time to commit:

        cd /etc
        git status
        git commit -m "initial checkin" 
        git gc # pack git repo to save a lot of space

After this first commit, you can use regular git commands to handle
further changes:

        passwd someuser
        git status
        git commit -a -m "changed a password" 

Rinse, lather, repeat. You might find that some files are changed by
daemons and shouldn't be tracked by git. These can be removed from git:
        git rm --cached printcap # modified by CUPS
        echo printcap >> .gitignore
        git commit -a -m "don't track printcap" 

etckeeper hooks into apt (and similar systems) so changes to interesting
files in /etc caused by installing or upgrading packages will automatically
be committed. Here "interesting" means files that are not ignored by
`.gitignore`.

You can use any git commands you like, but do keep in mind that, if you
check out a different branch or an old version, git is operating directly
on your system's /etc. If you do decide to check out a branch or tag,
make sure you run "etckeeper init" again, to get any metadata changes:

        git checkout april_first_joke_etc
        etckeeper init

Often it's better to clone /etc to elsewhere and do potentially dangerous
stuff in a staging directory. You can clone the repository using git clone,
but be careful that the directory it's cloned into starts out mode 700, to
prevent anyone else from seeing files like shadow, before `etckeeper init`
fixes their permissions:

        mkdir /my/workdir
        cd /my/workdir
        chmod 700 .
        git clone /etc
        cd etc
        etckeeper init -d .
        chmod 755 ..

Another common reason to clone the repository is to make a backup to a
server. When using git push to create a new remote clone, make sure the new
remote clone is mode 700! (And, obviously, only push over a secure
transport like ssh, and only to a server you trust.)

        ssh server 'mkdir /etc-clone; cd /etc-clone; chmod 700 .; git init'
        git push ssh://server/etc-clone master

If you have several machine's using etckeeper, you can start with a
etckeeper repository on one machine, then add another machine's etckeeper
repository as a git remote. Then you can diff against it, examine its
history, merge with it, and so on. It would probably not, however, be wise
to "git checkout" the other machine's branch! (And if you do, make sure to
run "etckeeper init" to update file permissions.)

        root@kodama:/etc>git remote add dodo ssh://dodo/etc
        root@kodama:/etc>git fetch dodo
        root@kodama:/etc>git diff dodo/master group |head
        diff --git a/group b/group
        index 0242b84..b5e4384 100644
        --- a/group
        +++ b/group
        @@ -5,21 +5,21 @@ sys:x:3:
        adm:x:4:joey
        tty:x:5:
        disk:x:6:
        -lp:x:7:cupsys
        +lp:x:7:

Incidentially, this also means I have a backup of dodo's /etc on kodama.
So if kodama is compromised, that data could be used to attack dodo
too. On the other hand, if dodo's disk dies, I can restore it from this
handy hackup.

Of course, it's also possible to pull changes from a server onto client
machines, to deploy changes to /etc. Once /etc is under version control, the
sky's the limit..