Home > Ubuntu, Ubuntu Server > The etckeeper chronicles, part 1

The etckeeper chronicles, part 1

February 23, 2009 Leave a comment Go to comments

One thing I have been working on in this cycle is beginning to integrate an easy solution to put /etc under revision control. I have found etckeeper, by Joey Hess, to be the right tool for the job. The version in Jaunty will feature better support of bzr as the underlying VCS, and a couple of improvements I pushed upstream. In this series of articles, I’ll present an overview of how this solution works in Jaunty and the future planned (post 9.04 release) improvements.

Why you want it

Putting /etc under revision control allows you to keep a precise history of the changes made to configuration files. This is a well-known best practice on server environments with multiple sysadmins, where being able to tell who changed what files, and when, is very useful. But this is also nice to have on home servers or on desktops ! And keeping a log is only the tip of the iceberg of possibilities that are available once you have those files under a DVCS. Think reversion to a previous revision, branching…


To install the etckeeper/bzr combination, you will simply run:

$ sudo apt-get install etckeeper bzr

Then to initialize the repository:

$ sudo etckeeper init
$ sudo etckeeper commit "Initial commit"
Committed revision 1

This will create a bzr repository for /etc, add all files below /etc (except etckeeper ignore list) to that repository and commit (save) the current contents as revision 1.

Use it

Using etckeeper is quite simple. Whenever you make a coherent change to your configuration files, you can commit it by calling etckeeper commit:

$ sudo vi /etc/hosts
$ sudo vi /etc/resolv.conf
$ sudo etckeeper commit "Change domain name"
Committing to: /etc/
modified hosts
modified resolv.conf
Committed revision 2.

Who did what when ?

To be able to get a nice history of changes, you’ll have to call the underlying VCS system, which in our Jaunty setup is bzr. For example, this will give you a nice one-revision-per-line history of the revisions present in the repository:

$ sudo bzr log --line /etc
2: thc 2009-02-22 Change domain name to mycompany.com
1: thc 2009-02-22 Initial commit

Here you go, a nice captain’s log of changes made to configuration files. One feature I recently pushed back upstream is sudo integration: the username shown (thc) is the one of the user running the ‘sudo etckeeper’ command, not an undetermined ‘root’.

Now suppose you want to see what changed in revision 2 ? Try:

$ sudo bzr diff -c2 /etc
=== modified file 'hosts'
--- hosts    2009-02-22 11:26:09 +0000
+++ hosts    2009-02-22 11:27:34 +0000
@@ -1,5 +1,5 @@ localhost
- jaunty-test.example.com jaunty-test
+ jaunty-test.mycompany.com jaunty-test

# The following lines are desirable for IPv6 capable hosts
::1 ip6-localhost ip6-loopback

=== modified file 'resolv.conf'
--- resolv.conf    2009-02-22 11:26:09 +0000
+++ resolv.conf    2009-02-22 11:27:34 +0000
@@ -1,2 +1,2 @@
-domain example.com
+domain mycompany.com

Neat, uh ? You can also check the differences between the current configuration and the last-committed revision using:

$ sudo bzr diff /etc

In next episode

In part 2 of the etckeeper chronicles, we’ll see how etckeeper autocommits help in getting the right picture with minimal effort. Stay tuned !

Categories: Ubuntu, Ubuntu Server
  1. February 23, 2009 at 23:57

    Nice roundup.

    sudo bzr diff -c2 /etc is easier to see the diff of revision/change 2 though.

  2. Thierry Carrez
    February 24, 2009 at 07:06

    Daniel: You’re right, it looks better than -r1..2 ! Fixed in article, thanks !

  3. February 24, 2009 at 09:00

    Great introduction, and what a nice tool !
    I hope that there is also a mecanism to track automatically changes after an apt-get upgrade (or by synaptic or other tool). Like a hook. You upgrade, apt system, at the end, call etckeeper, and etckeeper commit changes (with package names that have been installed->responsible of changes).

    • Thierry Carrez
      February 24, 2009 at 09:05

      @Kagou: there is such a feature, I’ll cover it in part 2 !

  4. February 24, 2009 at 15:33

    This is a great idea, and I have tried it for several months on a hardy setup (should try with a more recent etckeeper release). I’m looking forward your part 2, my main problem is that after years of editing configuration files, you almost forget to commit after changing :(.

  5. Michael
    March 1, 2009 at 22:01

    Thanks for the article. My compliments.

    I’ve got a question:
    After installing a gnome game with:
    sudo apt-get install gbrainy

    I got the following output:
    Processing triggers for menu …
    Created commit 50d53a5: committing changes in /etc after apt run
    2 files changed, 2 insertions(+), 0 deletions(-)

    When I tried the following statements:
    sudo bzr log –line /etc

    i’ve got the following output:
    bzr: ERROR: Not a branch: “/etc/”

    I suppose this is not correct.

    Any hints for what possibly is wrong with my configuration of etckeeper?

    All have taken all the mentioned step of your article and everything went very well (same output as mentioned in this blog).
    Can anyone please help me in the right direction ?
    Regards & respect,


  6. Thierry Carrez
    March 2, 2009 at 07:33

    etckeeper is apparently using another VCS than bzr. You are probably not running the Jaunty version of etckeeper so you are using VCS=git by default (in /etc/etckeeper/etckeeper.conf). So you have to run the git equivalent of “bzr log” instead. Or restart over with VCS=bzr in etckeeper.conf…

  7. Michael
    March 2, 2009 at 08:09

    Thanks Thierry Carrez. You are right. Because I am still using Intrepid git is indeed the default in the mentioned config file. Problem solved.

  8. george
    May 22, 2009 at 11:23

    After installed etckeeper in an ubuntu 9.04 server every time I run “apt-get” I get the following response and it is not possible to install or remove any packages from the server:

    Commit failed

    An attempt to commit /etc changes to bzr failed.

    You may manually resolve the issues with the uncommited changes before continuing.

    • Thierry Carrez
      May 22, 2009 at 12:07

      Could you file a bug on Launchpad about this ?

  9. The Doctor
    September 7, 2009 at 15:34

    Brilliant post.

    Any more chronicles coming? Would love to keep up w/ this series.

    • The Doctor
      September 7, 2009 at 15:37

      Note to self: Don’t post comments when awake 20+ hrs.

  10. nutznboltz
    March 26, 2010 at 18:27

    > $ sudo etckeeper commit “Change domain name”

    One thing that people overlook with version control is that the commentary should always be written to answer the question “why?” because the diff itself can answer the question “what?”

    sudo etckeeper commit “foobar.com has been deprecated”

  1. November 18, 2010 at 02:29
  2. August 21, 2011 at 08:59
  3. September 6, 2013 at 06:59

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s