Kunterbunt

etckeeper tutorial

<pre>

## 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..

</pre>