path: root/README

etckeeper is a collection of tools to let /etc be stored in a git
repository. It hooks into apt to automatically commit changes made to /etc
during package upgrades. It uses [metastore][1] to track file metadata
that git does not normally support, but that is important for /etc, such as
the permissions of `/etc/shadow`. It's quite modular and configurable,
while also being simple to use if you understand the basics of working with
git.

   [1]: http://david.hardeman.nu/software.php

## security warnings

First, a big warning: By checking /etc into revision control, you are
creating a copy of files like /etc/shadow that must remain secret. Anytime
you have a copy of a secret file, it becomes more likely that the file
contents won't remain secret. etckeeper is careful about file permissions,
and will make sure that repositories it sets up don't allow anyone but root
to read their contents. However, you *also* must take care when cloning
or copying these repositories, not to allow anyone else to see the data.

Since git mushes all the files into packs under the .git directory, the
whole .git directory content needs to be kept secret. Also, since git
doesn't keep track of the mode of files like the shadow file, it will check
it out world readable, before etckeeper fixes the permissions. The tutorial
has some examples of safe ways to avoid these problems when cloning an /etc
repository.

Also note that `etckeeper init` runs code stored in the git repository.
So don't use it on git repositories from untrusted sources.


## what etckeeper does

etckeeper has special support to handle changes to /etc caused by
installing and upgrading packages. Before apt installs packages,
`etckeeper pre-install` will check that /etc contains no uncommitted changes.
After apt installs packages, `etckeeper post-install` will add any new
interesting files to the repository, and commit the changes.

git is designed as a way to manage source code, not as a way to manage
arbitrary directories like /etc. This means it has a few limitations that
etckeeper has to work around. These include file metadata storage,
empty directories, and special files.

git has only limited tracking of file metadata, being able to track the
executable bit, but not other permissions or owner info. So file metadata
storage is handled by `metastore`. Amoung other chores, `etckeeper init`
sets up a `pre-commit` hook that uses `metastore` to store metadata about
file owners, permissions, and even extended attributes into a
`/etc/.metadata` file. This metadata is stored in git along with everything
else, and can be applied if the repo should need to be checked back out.

git cannot track empty directories, but they can be significant sometimes
in /etc. So the `pre-commit` hook also stores information that can be used
to recreate the empty directories in a `/etc/.etckeeper` file.

git doesn't support several special files that you _probably_ won't have in
/etc, such as unix sockets, named pipes, hardlinked files (but softlinks
are fine), and device files. The `pre-commit` hook will warn if your /etc
contains such special files.


## tutorial

A quick walkthrough of using etckeeper. The `etckeeper init` command
initialises an /etc/.git/ repository. This command is careful to never
overwrite existing files or directories in /etc. It will create a `.gitignore`
if one doesn't already exist, sets up git hooks if they don't already exist,
and so on. It does *not* commit any files into to git, but does `git-add` all
interesting files for an initial commit.

	etckeeper init

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

Of course, it's also possible to pull changes from a server onto client
machines, to deploy changes to /etc. You might even set up branches for
each machine and merge changes between them. Once /etc is under version
control, the sky's the limit..


## configuration

etckeeper uses `run-parts` to run the executable files in
`/etc/etckeeper/$command.d/`. You can modify these files, or add your own
custom files. Each individual file is short, simple, and does only one
action.

For example, here's how to configure it to run `git gc` after each apt run,
which will save a lot of disk space:

	cd /etc/etckeeper/post-install.d
	(echo '#!/bin/sh' ; echo 'exec git-gc') > 99git-gc
	chmod +x 99git-gc
	git add .
	git-commit -m "run git-gc after each apt run"

Here's how to disable the automatic commits after each apt run, while still
letting it git-add new files and git-rm removed ones:

	chmod -x /etc/etckeeper/post-install.d/75git-commit

Note that the etckeeper commands are careful to not hardcode anything about
git. If you want to use some other revision control system, that's
theoretically possible to accomplish by just changing the files in
/etc/etckeeper/. If you do this, please let me know.


## inspiration

Two blog posts provided inspiration for techniques used by etckeeper:
* http://www.jukie.net/~bart/blog/20070312134706
* http://bryan-murdock.blogspot.com/2007/07/put-etc-under-revision-control-with-git.html

[isisetup][2] has some of the same aims as etckeeper, however, unlike it,
etckeeper does not aim to be a git porcelain with its own set of commands
for manipulating the /etc repository. Instead, etckeeper provides a simple
setup procedure and hooks for setting up an /etc repsository, and then gets
out of your way; you manage the repository using regular git commands.

   [2]: http://www.isisetup.ch/


## license

etckeeper is licensed under version 2 or greater of the GNU GPL.


## author

Joey Hess <joey@kitenet.net>