README

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