diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.mdwn | 272 | ||||
| -rw-r--r-- | doc/index.mdwn | 7 | ||||
| -rw-r--r-- | doc/install.mdwn | 4 | ||||
| -rw-r--r-- | doc/todo.mdwn | 6 | ||||
| -rw-r--r-- | doc/todo/done.mdwn | 4 | ||||
| -rw-r--r-- | doc/todo/origin_branch.mdwn | 15 | ||||
| -rw-r--r-- | doc/todo/split_the_repo.mdwn | 10 |
7 files changed, 315 insertions, 3 deletions
diff --git a/doc/README.mdwn b/doc/README.mdwn new file mode 100644 index 0000000..d9fd4cd --- /dev/null +++ b/doc/README.mdwn @@ -0,0 +1,272 @@ +etckeeper is a collection of tools to let /etc be stored in a git, +mercurial, bazaar or darcs repository. It hooks into apt to automatically +commit changes made to /etc during package upgrades. It tracks 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 version control. + + +## security warnings + +First, a big warning: By checking /etc into version 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. (Ditto for mercurial +and .hg as well as bazaar and .bzr) + +Also, since version control systems don't keep track of the mode of files +like the shadow file, it will check 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 repository. +So don't use it on 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. + +You can also run `etckeeper commit` by hand to commit changes. + +There is also a cron job, that will use etckeeper to automatically +commit any changes to /etc each day. + + +## VCS limitations + +Version Control Systems are designed as a way to manage source code, not as +a way to manage arbitrary directories like /etc. This means there are a few +limitations that etckeeper has to work around. These include file metadata +storage, empty directories, and special files. + +Most VCS, including git, mercurial and bazaar have only limited tracking of +file metadata, being able to track the executable bit, but not other +permissions or owner info. (darcs doesn't even track executable bits.) So +file metadata is stored separately. Among other chores, `etckeeper init` +sets up a `pre-commit` hook that stores metadata about file owners and +permissions into a `/etc/.etckeeper` file. This metadata is stored in +version control along with everything else, and can be applied if the repo +should need to be checked back out. + +git and mercurial 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 the +`/etc/.etckeeper` file. + +Most VCS don't support several special files that you _probably_ won't have +in /etc, such as unix sockets, named pipes, hardlinked files (but symlinks +are fine), and device files. The `pre-commit` hook will warn if your /etc +contains such special files. + +Darcs doesn't support symlinks, so they are also stored in +`/etc/.etckeeper`. + + +## 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 --bare' + git remote add backup ssh://server/etc-clone + git push backup --all + +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.. + + +## configuration + +The main configuration file is `/etc/etckeeper/etckeeper.conf` + +etckeeper runs the executable files in `/etc/etckeeper/$command.d/`. (It +ignores the same ones that run-parts(1) would ignore.) 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: + + rm /etc/etckeeper/commit.d/50vcs-commit + +Here's how to make it automatically push commits to a clone of the +repository as a backup (see instructions above to set up the clone safely): + + cd /etc/etckeeper/commit.d + (echo '#!/bin/sh' ; echo 'git push backup') > 99git-push + chmod +x 99git-push + git add . + git commit -m "automatically push commits to backup repository" + +## changing VCS + +By default, etckeeper uses git. This choice has been carefully made; +git is the VCS best supported by etckeeper and the VCS users are most +likely to know. + +[ It's possible that your distribution has chosen to modify etckeeper so + its default VCS is not git -- if they have please complain to them, + as they're making things unnecessarily difficult for you, and causing + unnecessary divergence of etckeeper installations. + You should only be using etckeeper with a VCS other than git if you're + in love with the other VCS. ] + +If you would like to use some other VCS, and `etckeeper init` has already +been run to set up a git repository, you have a decision to make: Is the +history recorded in that repository something you need to preserve, or can +you afford to just blow it away and check the current /etc into the new +VCS? + +In the latter case, you just need to follow three steps: + + etckeeper uninit # deletes /etc/.git! + vim /etc/etckeeper/etckeeper.conf + etckeeper init + +In the former case, you will need to convert the git repository to the +other VCS using whatever tools are available to do that. Then you can +run `etckeeper uninit`, move files your new VCS will use into place, +edit `etckeeper.conf` to change the VCS setting, and finally +`etckeeper init`. This procedure is clearly only for the brave. + + +## 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 had 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 repository, and then gets +out of your way; you manage the repository using regular VCS commands. + + +## license + +etckeeper is licensed under version 2 or greater of the GNU GPL. + + +## author + +Joey Hess <joey@kitenet.net> diff --git a/doc/index.mdwn b/doc/index.mdwn index 2d2da53..4fa66e1 100644 --- a/doc/index.mdwn +++ b/doc/index.mdwn @@ -7,15 +7,16 @@ 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 revision control. -etckeeper is available in git at `git://git.kitenet.net/etckeeper`, or -[in gitweb](http://git.kitenet.net/?p=etckeeper.git). It's packaged in -Debian, Ubuntu, Fedora, etc. +For details, see the [[README]]. ## News [[!inline pages="news/* and !*/Discussion" show="3"]] [[!sidebar content=""" +[[Install]] +[[Todo]] + <a href="http://flattr.com/thing/39940/etckeeper" target="_blank"> <img src="http://api.flattr.com/button/button-static-50x60.png" alt="Flattr this" title="Flattr this" border="0" /></a> """]] diff --git a/doc/install.mdwn b/doc/install.mdwn new file mode 100644 index 0000000..b4f332a --- /dev/null +++ b/doc/install.mdwn @@ -0,0 +1,4 @@ +etckeeper is available in git at `git://git.kitenet.net/etckeeper`, or +[in gitweb](http://git.kitenet.net/?p=etckeeper.git). + +It's packaged in Debian, Ubuntu, Fedora, etc. diff --git a/doc/todo.mdwn b/doc/todo.mdwn new file mode 100644 index 0000000..81cf3ed --- /dev/null +++ b/doc/todo.mdwn @@ -0,0 +1,6 @@ +This is etckeeper's todo list. Link items to [[todo/done]] when done. + +See also: [Debian BTS](http://bugs.debian.org/etckeeper). + +[[!inline pages="./todo/* and !./todo/done and !link(done) +and !*/Discussion" actions=yes postform=yes show=0 archive=yes]] diff --git a/doc/todo/done.mdwn b/doc/todo/done.mdwn new file mode 100644 index 0000000..e7c9808 --- /dev/null +++ b/doc/todo/done.mdwn @@ -0,0 +1,4 @@ +recently fixed [[todo]] items. + +[[!inline pages="./* and link(./done) and !*/Discussion" sort=mtime show=10 +archive=yes]] diff --git a/doc/todo/origin_branch.mdwn b/doc/todo/origin_branch.mdwn new file mode 100644 index 0000000..55c3a32 --- /dev/null +++ b/doc/todo/origin_branch.mdwn @@ -0,0 +1,15 @@ +keep an origin branch with the files debian ships + +Not sure quite how to do this yet, it seems it would need to clone +the repo, switch to origin, and commit, then push back to /etc, +and either merge origin or commit a second time. +And do this after apt runs only, of course. + +Alternatively, commit in /etc, then clone the repo, switch to origin, and +cherry pick the commit into origin? + +Of coure, unless etckeeper is installed by debootstrap or thereabouts, +you won't have a true pristine origin branch. + +etcgit manages this, maybe steal its method? +git://git.debian.org/git/users/jo-guest/etcgit.git diff --git a/doc/todo/split_the_repo.mdwn b/doc/todo/split_the_repo.mdwn new file mode 100644 index 0000000..ed57dd5 --- /dev/null +++ b/doc/todo/split_the_repo.mdwn @@ -0,0 +1,10 @@ +split the repo + +One way to split it would be to put private (non-world-readable) files +one one repo, and public in another. This would need either symlink +farming or git "fake bare" repos, both of which are not pleasant, yet. + +Another way would be to allow splitting out subdirs into their own repos. +This is already doable, would just need modifying the pre-install and +post-instlal stuff (ie, it needs to commit in the subdirs too). Using mr +would be a possibility.. |