README

   1 etckeeper is a collection of tools to let /etc be stored in a git
   2 repository. It hooks into apt to automatically commit changes made to /etc
   3 during package upgrades. It uses [metastore][1] to track file metadata
   4 that git does not normally support, but that is important for /etc, such as
   5 the permissions of `/etc/shadow`. It's quite modular and configurable,
   6 while also being simple to use if you understand the basics of working with
   7 git.
   8
   9    [1]: http://david.hardeman.nu/software.php
  10
  11 ## security warnings
  12
  13 First, a big warning: By checking /etc into revision control, you are
  14 creating a copy of files like /etc/shadow that must remain secret. Anytime
  15 you have a copy of a secret file, it becomes more likely that the file
  16 contents won't remain secret. etckeeper is careful about file permissions,
  17 and will make sure that repositories it sets up don't allow anyone but root
  18 to read their contents. However, you *also* must take care when cloning
  19 or copying these repositories, not to allow anyone else to see the data.
  20
  21 Since git mushes all the files into packs under the .git directory, the
  22 whole .git directory content needs to be kept secret. Also, since git
  23 doesn't keep track of the mode of files like the shadow file, it will check
  24 it out world readable, before etckeeper fixes the permissions. The tutorial
  25 has some examples of safe ways to avoid these problems when cloning an /etc
  26 repository.
  27
  28 Also note that `etckeeper init` runs code stored in the git repository.
  29 So don't use it on git repositories from untrusted sources.
  30
  31
  32 ## what etckeeper does
  33
  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.
  39
  40 git is designed as a way to manage source code, not as a way to manage
  41 arbitrary directories like /etc. This means it has a few limitations that
  42 etckeeper has to work around. These include file metadata storage,
  43 empty directories, and special files.
  44
  45 git has only limited tracking of file metadata, being able to track the
  46 executable bit, but not other permissions or owner info. So file metadata
  47 storage is handled by `metastore`. Amoung other chores, `etckeeper init`
  48 sets up a `pre-commit` hook that uses `metastore` to store metadata about
  49 file owners, permissions, and even extended attributes into a
  50 `/etc/.metadata` file. This metadata is stored in git along with everything
  51 else, and can be applied if the repo should need to be checked back out.
  52
  53 git cannot track empty directories, but they can be significant sometimes
  54 in /etc. So the `pre-commit` hook also stores information that can be used
  55 to recreate the empty directories in a `/etc/.etckeeper` file.
  56
  57 git doesn't support several special files that you _probably_ won't have in
  58 /etc, such as unix sockets, named pipes, hardlinked files (but softlinks
  59 are fine), and device files. The `pre-commit` hook will warn if your /etc
  60 contains such special files.
  61
  62
  63 ## tutorial
  64
  65 A quick walkthrough of using etckeeper. The `etckeeper init` command
  66 initialises an /etc/.git/ repository. This command is careful to never
  67 overwrite existing files or directories in /etc. It will create a `.gitignore`
  68 if one doesn't already exist, sets up git hooks if they don't already exist,
  69 and so on. It does *not* commit any files into to git, but does `git-add` all
  70 interesting files for an initial commit.
  71
  72         etckeeper init
  73
  74 Now you might want to run git status to check that it includes all
  75 the right files, and none of the wrong files. And you can edit the
  76 .gitignore and so forth. Once you're ready, it's time to commit:
  77
  78         cd /etc
  79         git commit -m "initial checkin"
  80         git gc # pack git repo to save a lot of space
  81
  82 After this first commit, you can use regular git commands to handle
  83 further changes:
  84
  85         passwd someuser
  86         git status
  87         git commit -a -m "changed a password"
  88
  89 Rinse, lather, repeat. You might find that some files are changed by
  90 daemons and shouldn't be tracked by git. These can be removed from git:
  91
  92         git rm --cached printcap # modified by CUPS
  93         echo printcap >> .gitignore
  94         git commit -a -m "don't track printcap"
  95
  96 etckeeper hooks into apt so changes to interesting files in /etc caused by
  97 installing or upgrading packages will automatically be committed. Here
  98 "interesting" means files that are not ignored by `.gitignore`.
  99
 100 You can use any git commands you like, but do keep in mind that, if you
 101 check out a different branch or an old version, git is operating directly
 102 on your system's /etc. But if you do decide to check out a branch or tag,
 103 make sure you run "etckeeper init" again, to get any metadata changes:
 104
 105         git checkout april_first_joke_etc
 106         etckeeper init
 107
 108 Often it's better to clone /etc to elsewhere and do potentially dangerous
 109 stuff in a staging directory. You can clone the repository using git-clone,
 110 but be careful that the directory it's cloned into starts out mode 700, to
 111 prevent anyone else from seeing files like shadow, before `etckeeper init`
 112 fixes their permissions:
 113
 114         mkdir /my/workdir
 115         cd /my/workdir
 116         chmod 700 .
 117         git clone /etc
 118         cd etc
 119         etckeeper init .
 120         chmod 755 ..
 121
 122 Another common reason to clone the repository is to make a backup to a
 123 server. When using git-push to create a new remote clone, make sure the new
 124 remote clone is mode 700! (And, obviously, only push over a secure
 125 transport like ssh, and only to a server you trust.)
 126
 127         ssh server 'mkdir /etc-clone; cd /etc-clone; chmod 700 .; git init'
 128         git push ssh://server/etc-clone master
 129
 130 Of course, it's also possible to pull changes from a server onto client
 131 machines, to deploy changes to /etc. You might even set up branches for
 132 each machine and merge changes between them. Once /etc is under version
 133 control, the sky's the limit..
 134
 135
 136 ## configuration
 137
 138 etckeeper uses `run-parts` to run the executable files in
 139 `/etc/etckeeper/$command.d/`. You can modify these files, or add your own
 140 custom files. Each individual file is short, simple, and does only one
 141 action.
 142
 143 For example, here's how to configure it to run `git gc` after each apt run,
 144 which will save a lot of disk space:
 145
 146         cd /etc/etckeeper/post-install.d
 147         (echo '#!/bin/sh' ; echo 'exec git-gc') > 99git-gc
 148         chmod +x 99git-gc
 149         git add .
 150         git-commit -m "run git-gc after each apt run"
 151
 152 Here's how to disable the automatic commits after each apt run, while still
 153 letting it git-add new files and git-rm removed ones:
 154
 155         chmod -x /etc/etckeeper/post-install.d/75git-commit
 156
 157 Note that the etckeeper commands are careful to not hardcode anything about
 158 git. If you want to use some other revision control system, that's
 159 theoretically possible to accomplish by just changing the files in
 160 /etc/etckeeper/. If you do this, please let me know.
 161
 162
 163 ## inspiration
 164
 165 Two blog posts provided inspiration for techniques used by etckeeper:
 166 * http://www.jukie.net/~bart/blog/20070312134706
 167 * http://bryan-murdock.blogspot.com/2007/07/put-etc-under-revision-control-with-git.html
 168
 169 [isisetup][2] has some of the same aims as etckeeper, however, unlike it,
 170 etckeeper does not aim to be a git porcelain with its own set of commands
 171 for manipulating the /etc repository. Instead, etckeeper provides a simple
 172 setup procedure and hooks for setting up an /etc repsository, and then gets
 173 out of your way; you manage the repository using regular git commands.
 174
 175    [2]: http://www.isisetup.ch/
 176
 177
 178 ## license
 179
 180 etckeeper is licensed under version 2 or greater of the GNU GPL.
 181
 182
 183 ## author
 184
 185 Joey Hess <joey@kitenet.net>