rename file, since it is a markdown file

Hmm

1 files changed, 272 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d9fd4cd
--- /dev/null
+++ b/README.md
@@ -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>