DEBOPS.ETCKEEPER(5)

NAME
debops.etckeeper - Put /etc under version control using etckeeper

SYNOPSIS

debops service/etckeeper [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.etckeeper Ansible role will install etckeeper <https://etckeeper.branchable.com/>, which puts the /etc directory under version control. To do this, etckeeper hooks into the package management and from now on automatically will commit changes to a local git repository under /etc/.git/ directory. This makes it easy to see which changes are applied on a specific host and quickly revert them, if something breaks.

The role will install a special Ansible local fact which will commit any changes in the /etc directory as well, usually at the moment the Ansible facts are gathered.

GETTING STARTED

  Initial configuration

By default git is used as VCS. This can be changed via the etckeeper__vcs variable through Ansible inventory.

The role is designed with etckeeper being already installed on a host in mind. This can be done for example via Debian Preseeding or LXC template installing and pre-configuring etckeeper; the role will keep the already existing configuration without any changes if the variables are not overwritten through the Ansible inventory. Any changes in the /etc/ directory will be automatically committed by Ansible local facts before Ansible role execution.

  Example inventory

The debops.etckeeper role is part of the default DebOps playbook and run on all hosts which are part of the [debops_all_hosts] group. To use this role with DebOps it's therefore enough to add your host to the mentioned host group (which most likely it is already):

[debops_all_hosts]
hostname

  Example playbook

Here's an example playbook that uses the debops.etckeeper role:

---
- name: Put /etc under version control using etckeeper
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_etckeeper' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ etckeeper__apt_preferences__dependent_list }}'
    - role: etckeeper
      tags: [ 'role::etckeeper', 'skip::etckeeper' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::etckeeper
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

DEFAULT VARIABLE DETAILS

Some of debops.etckeeper default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  etckeeper__gitignore

The etckeeper__*_gitignore variables configure the contents of a section in the /etc/.gitignore file managed by the debops.etckeeper role. This file specifies which paths (directories, files) should be ignored by etckeeper and git. You can check the gitignore(5) <https://manpages.debian.org/gitignore(5)> manual page for the allowed syntax.

Each entry in the list defined in the variables is a YAML dictionary with specific parameters:

name
    Required. Name of a given entry. If the ignore parameter is not specified, the name parameter is used as-is, otherwise it's not included in the file.

comment
    Optional. A string or YAML text block with a comment that describes a given entry.

ignore
    Optional. String or YAML text block that contains the paths which should be present in the /etc/.gitignore file, it will be added in the file as-is.

state
    Optional. If not specified or present, a given entry will be included in the generated section. If absent, and entry will be removed from the generated section.

  Examples

Don't include /etc/shadow and /etc/shadow- files in etckeeper repository:

etckeeper__gitignore:
  - name: 'ignore-shadow'
    ignore: |
      shadow
      shadow-
    comment: "Don't track shadow database"

AUTHOR
Robin Schneider, Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others