##(see the SpecSpec for an explanation)

 * '''Launchpad Entry''': UbuntuSpec:server-lucid-puppet-etckeeper-integration
 * '''Created''': MathiasGug
 * '''Contributors''': 
 * '''Packages affected''':

== Summary ==

## This should provide an overview of the issue/functionality/change proposed here. Focus here on what will actually be DONE, summarising that so that other people don't have to read the whole spec. See also CategorySpec for examples.

Puppet leverages a VCS when it creates and modifies (configuration) files.

== Release Note ==

## This section should include a paragraph describing the end-user impact of this change.  It is meant to be included in the release notes of the first release in which it is implemented.  (Not all of these will actually be included in the release notes, at the release manager's discretion; but writing them is a useful exercise.)

## It is mandatory.

Puppet leverages the bzr version control system to keep track of changes made to files under its control. Local changes are now taken into account and puppet can decide what to do in this case.

== Rationale ==

## This should cover the _why_: why is this change being proposed, what justifies it, where we see this justified.

The use of a VCS for configuration files has been a best practice for system administration for some time as it helps in tracking changes made to the system and debugging. Since puppet can create and update text files using a VCS for tracking purposes is useful.

Puppet could also take advantage of client-side VCS to differentiate between puppet master configuration has changed and local changes on the client.

== User stories ==
 * Patrice, a system administrator, uses puppet to manage his infrastructure. After pushing an update, the mail service fails to restart. In a hurry he can log into the production system via ssh and look at the changes made to the actual configuration files lately. 
 * Cid, a junior system administrator, is asked to update the mail aliases file on the mail server. He logs into the server and manually edit the alias file. Next time puppet runs on the system, it detects that the alias has been modified locally and aborts by emitting a warning message.

== Design ==

## You can have subsections that better describe specific parts of the issue.

=== VCS integration in puppet ===

Whenever puppet is about to create or modify a text file it uses a VCS to:
  1. Detect local changes
  1. If a local change is made puppet relies on a policy to take an action:
     i. Always overwrite
     i. Always abort with reporting of an error message (and the diff)
  1. If the file is going to be updated the client records the new version of the file in the local VCS and updates the file.

{{{
WI: Write a design document outlining the changes required to the puppet client to support a VCS (upstream): TODO
WI: Implement VCS support in puppet client: TODO
WI: Integrate bzr as the VCS for puppet client: TODO
}}}

VCS support for meta-data file:

https://bugs.launchpad.net/ubuntu/+source/etckeeper/+bug/322327

https://bugs.launchpad.net/ubuntu/+source/etckeeper/+bug/322339

=== etckeeper ===
{{{
WI: etckeeper: fix .bazaar/ owned as root bug: TODO
WI: move etckeeper into main: TODO
WI: implement new features/commands - diff, log, status: TODO
WI: discuss proper meta-data (file permissions, user/group, acls, selinux, ...) support for the underlying VCS (bzr): TODO
WI: implement proper file permissions and ownership support in bzr: TODO
WI: implement proper acls support in bzr: TODO
WI: implement proper selinux in bzr: TODO
}}}

== Implementation ==

## This section should describe a plan of action (the "how") to implement the changes discussed. Could include subsections like:
See the Work Items in the [[UbuntuSpec:server-lucid-puppet-etckeeper-integration|blueprint]] 

== 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 http://testcases.qa.ubuntu.com/Coverage/NewFeatures 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 ==

## Use this section to take notes during the BoF; if you keep it in the approved spec, use it for summarising what was discussed and note any options that were rejected.

=== UDS Session notes ===

Puppet should use etckeeper to keep track of the configuration files it generates. It should also leverage etckeeper (and the underlying vcs) to detect local changes to files it manages and report any differences.

==== puppet integration ====
* integration with puppet template engine: 1. VCS? 2. etckeeper?
* etckeeper/vcs support to puppet reporting engine

==== etckeeper ====
* candidate for main / install during installation
* bug to solve: .bazaar created as root (bug 376388)
* integration of permissions/ownership in bzr diff/revert

==== puppet overview ====
 * configuration management framework
 * puppet currently uses a backing filesystem for revision control (like git?)
 * file contents stored by md5 sum, would like to replace backend with a real revision control system
   - only 2-3 places where to hook the vcs: 
     * one single commit for the whole run ( – lose meta data)
     * individual commits (per ressource)
etckeeper integration: give a new version of the file (content, path), etckeeper decides by policy what needs to be done (overwriting).
replacing backup system with etckeeper/vcs.
 * capistrano, symlinks?

==== etckeeper overview ====
 * revision control over /etc
 * configuration changes committed to revision control, hooked into apt/dpkg installs
 * maintains history of configuration file changes
 * can install and "forget about it"
 
==== approach ====

2 options:
 * ensure that puppet integrates with etckeeper for change control of /etc
 * general integration of puppet with a VCS so that all of its changes are in
   revision control
   
 * dpkg conffile integration?

==== detecting local changes in puppet ====

 * could take advantage of client-side VCS to differentiate between
  * puppet master configuration has changed
  * local changes on the client
 * puppet cannot tell the difference today
 * this would be useful to trigger different conflict handling (e.g. human mediation)
 
 
==== etckeeper ====
* move into main:
  - a few bugs to fix: .bazaar/ owned as root
* support in the installer:
  - when to install it? as early as possible
  - use of dpkg triggers?
* new features/commands: diff, log, status
* files outside /etc?
* proper files permissions

Design document: by the end of the month
----
CategorySpec