1 etckeeper is a collection of tools to let /etc be stored in a git,
2 mercurial, or bazaar repository. It hooks into apt to automatically commit
3 changes made to /etc during package upgrades. It tracks file metadata that
4 git does not normally support, but that is important for /etc, such as the
5 permissions of `/etc/shadow`. It's quite modular and configurable, while
6 also being simple to use if you understand the basics of working with
11 First, a big warning: By checking /etc into revision control, you are
12 creating a copy of files like /etc/shadow that must remain secret. Anytime
13 you have a copy of a secret file, it becomes more likely that the file
14 contents won't remain secret. etckeeper is careful about file permissions,
15 and will make sure that repositories it sets up don't allow anyone but root
16 to read their contents. However, you *also* must take care when cloning
17 or copying these repositories, not to allow anyone else to see the data.
19 Since git mushes all the files into packs under the .git directory, the
20 whole .git directory content needs to be kept secret. (Ditto for mercurial
21 and .hg as well as bazaar and .bzr)
23 Also, since revision control systems don't keep track of the mode of files
24 like the shadow file, it will check out world readable, before etckeeper
25 fixes the permissions. The tutorial has some examples of safe ways to avoid
26 these problems when cloning an /etc repository.
28 Also note that `etckeeper init` runs code stored in the repository.
29 So don't use it on repositories from untrusted sources.
32 ## what etckeeper does
34 etckeeper has special support to handle changes to /etc caused by
35 installing and upgrading packages. Before apt installs packages,
36 `etckeeper pre-install` will check that /etc contains no uncommitted changes.
37 After apt installs packages, `etckeeper post-install` will add any new
38 interesting files to the repository, and commit the changes.
40 Revsion control systems are designed as a way to manage source code, not as
41 a way to manage arbitrary directories like /etc. This means there are a few
42 limitations that etckeeper has to work around. These include file metadata
43 storage, empty directories, and special files.
45 Most VCS, including git, mercurial and bazaar have only limited tracking of
46 file metadata, being able to track the executable bit, but not other
47 permissions or owner info. So file metadata storage is stored separately.
48 Among other chores, `etckeeper init` sets up a `pre-commit` hook that stores
49 metadata about file owners and permissions into a `/etc/.metadata` file.
50 This metadata is stored in version control along with everything else, and
51 can be applied if the repo should need to be checked back out.
53 git and mercurial cannot track empty directories, but they can be
54 significant sometimes in /etc. So the `pre-commit` hook also stores
55 information that can be used to recreate the empty directories in a
56 `/etc/.etckeeper` file.
58 Most VCS, including git, mercurial, and bazaar don't support several
59 special files that you _probably_ won't have in /etc, such as unix
60 sockets, named pipes, hardlinked files (but softlinks are fine), and
61 device files. The `pre-commit` hook will warn if your /etc contains
67 A quick walkthrough of using etckeeper.
69 First, edit `/etc/etckeeper/etckeeper.conf` to select which version control
70 system to use. The default is git, and this tutorial assumes you're using
71 it. Mercurial and bazaar are similar.
73 The `etckeeper init` command initialises an /etc/.git/ repository. This
74 command is careful to never overwrite existing files or directories in
75 /etc. It will create a `.gitignore` if one doesn't already exist, sets up
76 pre-commit hooks if they don't already exist, and so on. It does *not*
77 commit any files, but does `git add` all interesting files for an initial
82 Now you might want to run `git status` to check that it includes all
83 the right files, and none of the wrong files. And you can edit the
84 `.gitignore` and so forth. Once you're ready, it's time to commit:
88 git commit -m "initial checkin"
89 git gc # pack git repo to save a lot of space
91 After this first commit, you can use regular git commands to handle
96 git commit -a -m "changed a password"
98 Rinse, lather, repeat. You might find that some files are changed by
99 daemons and shouldn't be tracked by git. These can be removed from git:
101 git rm --cached printcap # modified by CUPS
102 echo printcap >> .gitignore
103 git commit -a -m "don't track printcap"
105 etckeeper hooks into apt so changes to interesting files in /etc caused by
106 installing or upgrading packages will automatically be committed. Here
107 "interesting" means files that are not ignored by `.gitignore`.
109 You can use any git commands you like, but do keep in mind that, if you
110 check out a different branch or an old version, git is operating directly
111 on your system's /etc. If you do decide to check out a branch or tag,
112 make sure you run "etckeeper init" again, to get any metadata changes:
114 git checkout april_first_joke_etc
117 Often it's better to clone /etc to elsewhere and do potentially dangerous
118 stuff in a staging directory. You can clone the repository using git clone,
119 but be careful that the directory it's cloned into starts out mode 700, to
120 prevent anyone else from seeing files like shadow, before `etckeeper init`
121 fixes their permissions:
131 Another common reason to clone the repository is to make a backup to a
132 server. When using git push to create a new remote clone, make sure the new
133 remote clone is mode 700! (And, obviously, only push over a secure
134 transport like ssh, and only to a server you trust.)
136 ssh server 'mkdir /etc-clone; cd /etc-clone; chmod 700 .; git init'
137 git push ssh://server/etc-clone master
139 If you have several machine's using etckeeper, you can start with a
140 etckeeper repository on one machine, then add another machine's etckeeper
141 repository as a git remote. Then you can diff against it, examine its
142 history, merge with it, and so on. It would probably not, however, be wise
143 to "git checkout" the other machine's branch! (And if you do, make sure to
144 run "etckeeper init" to update file permissions.)
146 root@kodama:/etc>git remote add dodo ssh://dodo/etc
147 root@kodama:/etc>git fetch dodo
148 root@kodama:/etc>git diff dodo/master group |head
149 diff --git a/group b/group
150 index 0242b84..b5e4384 100644
153 @@ -5,21 +5,21 @@ sys:x:3:
160 Incidentially, this also means I have a backup of dodo's /etc on kodama.
161 So if kodama is compromised, that data could be used to attack dodo
162 too. On the other hand, if dodo's disk dies, I can restore it from this
165 Of course, it's also possible to pull changes from a server onto client
166 machines, to deploy changes to /etc. Once /etc is under version control, the
171 The main configuration file is `/etc/etckeeper/etckeeper.conf`
173 etckeeper runs the executable files in `/etc/etckeeper/$command.d/`. (It
174 ignores the same ones that run-parts(1) would ignore.) You can modify these
175 files, or add your own custom files. Each individual file is short, simple,
176 and does only one action.
178 For example, here's how to configure it to run `git gc` after each apt run,
179 which will save a lot of disk space:
181 cd /etc/etckeeper/post-install.d
182 (echo '#!/bin/sh' ; echo 'exec git gc') > 99git-gc
185 git commit -m "run git gc after each apt run"
187 Here's how to disable the automatic commits after each apt run, while still
188 letting it git add new files and git rm removed ones:
190 chmod -x /etc/etckeeper/commit.d/50vcs-commit
195 Two blog posts provided inspiration for techniques used by etckeeper:
196 * http://www.jukie.net/~bart/blog/20070312134706
197 * http://bryan-murdock.blogspot.com/2007/07/put-etc-under-revision-control-with-git.html
199 [isisetup][2] has some of the same aims as etckeeper, however, unlike it,
200 etckeeper does not aim to be a git porcelain with its own set of commands
201 for manipulating the /etc repository. Instead, etckeeper provides a simple
202 setup procedure and hooks for setting up an /etc repository, and then gets
203 out of your way; you manage the repository using regular VCS commands.
205 [2]: http://www.isisetup.ch/
210 etckeeper is licensed under version 2 or greater of the GNU GPL.
215 Joey Hess <joey@kitenet.net>