etckeeper is a great way of keeping /etc under revision control, however it doesn't come without any pitfalls. These are mostly due to lack of integration between the VCS used and the permissions/ownership metadata. This spec tries to address the most obvious issues so that etckeeper can be more widely used in Ubuntu in the future.

Release Note

etckeeper in 9.10 is easier than ever. Enabling it is just a apt-get command away and etckeeper integration with bzr allows to visualize and revert permissions/ownership changes.


The etckeeper features introduced in Jaunty (track by SUDO_USER, daily autocommit...) allow for a richer out-of-the-box experience in tracking changes in configuration for an Ubuntu system. However, it is still a little confusing (bzr diff) or potentially harmful (bzr revert) to use as far as permissions/ownership changes are concerned. By leveraging the extra control over VCS that the etckeeper-bzr plugin allows, we can make etckeeper/bzr a more integrated experience and target regular users in future releases.

User stories


The required bzr hooks to implement this functionality need to be accepted in Bazaar.


One-step install

etckeeper should be working once "sudo apt-get install etckeeper" completes. As of Jaunty you need to run "etckeeper init" and "etckeeper commit" before /etc is really put under revision control. Current upstream version does "etckeeper init" but still requires you to run "etckeeper commit". This should be done in one step.

Support for running bzr under sudo

bzr doesn't really support running under sudo. In particular, it creates (if missing) $HOME/.bazaar directories as owner root rather than as the $SUDO_USER. In order to work properly in the specific etckeeper use case, those issues in bzr need to be addressed.

The .bazaar issue is tracked in

Integration of ownership/permissions metadata in "bzr diff" output

With the current version, a change in permissions or ownership will be displayed as a change in the .etckeeper file rather than a change in the file itself. This leads to confusion, and lack of integration with other tools (lsdiff...) which show the difference in the wrong place.

So rather than having:

$ sudo bzr diff /etc
=== modified file '.etckeeper'
--- .etckeeper  2009-01-28 08:47:07 +0000
+++ .etckeeper  2009-06-08 11:49:08 +0000
@@ -5,2 +5,3 @@
maybe chgrp adm ./resolv.conf
+ maybe chmod 666 ./tomcat6/server.xml
maybe chgrp tomcat6 ./tomcat6/policy.d

We should have:

$ sudo bzr diff /etc
=== modified file 'tomcat6/server.xml' (permissions: 644 -> 666)

This requires at least two hooks in bzr:

Design discussion is tracked in

Integration of ownership/permissions metadata in bzr file restore operations

With the current version, running "bzr revert" to restore a previous version of a file (or any other command that restore another version of a file) doesn't take permissions/ownership metadata into account. The file is restored with default ownership/permissions, and you have to manually look up the metadata in .etckeeper and restore it accordingly. Given the importance of permissions/ownership in /etc contents, this can be misleading and source for errors.

Ideally we need to hook at file creation time to look up corresponding metadata and restore it as well. The difficulty is in trying to cover all file restoration cases. One option is to fix "merge" and then implement etckeeper's "revert" in terms of "merge".

Design discussion is tracked in


This section should describe a plan of action (the "how") to implement the changes discussed.

Test/Demo Plan

It's important that we are able to test new features, and demonstrate them to users. Use this section to describe a short plan that anybody can follow that demonstrates the feature is working. This can then be used during testing, and to show off after release. Please add an entry to for tracking test coverage.

This need not be added or completed until the specification is nearing beta.

Unresolved issues

This should highlight any issues that should be addressed in further specifications, and not problems with the specification itself; since any specification with problems cannot be approved.

BoF agenda and discussion

UDS discussion

Introduction: etckeeper in 9.04

Karmic plans

bzr directly (and the etckeeper plugin should make that work)

Discussion of etckeeper usage potential

Discussion of future improvements


EtckeeperBzrIntegrationSpec (last edited 2009-06-08 12:02:39 by ttx)