etckeeper

From Gentoo Wiki
Jump to:navigation Jump to:search

From the etckeeper website:

etckeeper is a collection of tools to let /etc be stored in a git, mercurial, bazaar, or darcs repository. This lets you use git to review or revert changes that were made to /etc. Or even push the repository elsewhere for backups or cherry-picking configuration changes.
It hooks into package managers like 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.

Installation

USE flags

USE flags for sys-apps/etckeeper A collection of tools to let /etc be stored in a repository

cron Install cron script
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
Data provided by the Gentoo Package Database · Last update: 2021-09-13 10:34 More information about USE flags

Emerge

Install sys-apps/etckeeper

root #emerge --ask sys-apps/etckeeper

Additional software

etckeeper supports the following version control systems:

Configuration

Files

The main configuration file is /etc/etckeeper/etckeeper.conf. Following configuration options in the main configuration file need specific settings:

FILE /etc/etckeeper/etckeeper.conf
# The VCS to use.
VCS="git"

...

# Options passed to git commit when run by etckeeper.
GIT_COMMIT_OPTIONS=""

...

# Etckeeper includes both a cron job and a systemd timer, which each
# can commit exiting changes to /etc automatically once per day.
# To enable the systemd timer, run: systemctl enable etckeeper.timer
# The cron job is enabled by default; to disable it, uncomment this next line.
AVOID_DAILY_AUTOCOMMITS=1

...

# Uncomment to avoid etckeeper committing existing changes to
# /etc before installation. It will cancel the installation,
# so you can commit the changes by hand.
AVOID_COMMIT_BEFORE_INSTALL=1

...

# Gentoo specific:                                                                                                                                                                                          
# For portage this is emerge
# For paludis this is cave
HIGHLEVEL_PACKAGE_MANAGER=emerge

# Gentoo specific:
# For portage this is qlist
# For paludis this is cave
LOWLEVEL_PACKAGE_MANAGER=qlist

...

# To push each commit to a remote, put the name of the remote here.
# (eg, "origin" for git). Space-separated lists of multiple remotes
# also work (eg, "origin gitlab github" for git).
PUSH_REMOTE=""

Service

Cron

The cron job is enabled by default, to disable it, uncomment following configuration entry:

FILE /etc/etckeeper/etckeeper.conf
...
#AVOID_DAILY_AUTOCOMMITS=1
..

systemd

To enable the systemd timer, run:

root #systemctl enable etckeeper.timer

Usage

Note
Before configuring etckeeper further, inspect first the README file and read the "Security warnings" section.

First, it must be considered if sensitive files (such as private keys) shall be included in the repository. If there are concerns, it is suggested to create a .gitignore file before running the etckeeper initialization. This example below shows how to save explicit files to the etckeeper repository. The first entry * in the ignores ALL files in the /etc directory, following ! negated entries mark the interesting files that will be saved to the repository. Only following files will be saved in the repository

  • /etc/crontab
  • /etc/inittab
  • /etc/resolv.conf.
FILE /etc/.gitignore
# ignore everything
*
# now add interesting files
!crontab
!inittab
!resolv.conf

Using following syntax all files in the /etc/apache2/ directory will be saved in the repository:

FILE /etc/.gitignore
# ignore everything
* 
# now add interesting files and dirs
!apache2/
!apache2/*

Sometimes directories contain subdirectcories with interesting files. And in the /etc/apache2 directory, only one file is to save httpd.conf

  • /etc/apache2/httpd.conf
  • /etc/apache2/vhosts.d/
  • /etc/apache2/modules.d/

One file and 2 subdirectories will be saved in the repository:

FILE /etc/.gitignore
# ignore everything
* 
# now add interesting files and dirs
!apache2/
!apache2/httpd.conf
!apache2/modules.d/
!apache2/modules.d/*
!apache2/vhosts.d/
!apache2/vhosts.d/*
Note
Files targeted to be stored in the repository need to be listed in the .gitignore file. This approach is giving more control and granularity, and minimizes the risk of adding accidentally secret files without noticing it.

Initialization of the repository is done by running:

root #cd /etc
root #etckeeper init

When initialization is done through the sudo command, the author of the commit will be set to the corresponding user:

user $sudo etckeeper init

The command creates a .gitignore file in the /etc directory. If it already exist, then a "managed by etckeeper" comment block is added. It also sets up pre-commit hooks. This command does not yet commit files, but runs git add to ensure all interesting files are included in the initial commit later.

Note
In .gitignore, do not manually edit inside the "managed by etckeeper" comment blocks. Place your own additions outside these blocks.

When specific files shall be excluded, effectiveness of the .gitignore file can be verified by running git status. In the following example it is tested whether shadow files will be checked in. If any files that shall be excluded show up as a new file, then the .gitignore is not applied properly and needs fixing.

root #cd /etc
root #git status | grep shadow 
        new file:   gshadow
        new file:   gshadow-
        new file:   pam.d/shadow
        new file:   shadow
        new file:   shadow-

If not interesting files show up, it is suggested to undo the etckeeper initialization (as described later in the Removal section), fix the .gitignore and start again.

Finally commit all changes in /etc to the repository. A commit message can be specified. It is possible to use the underlying VCS to commit manually. Note that etckeeper commit will notice if a user has used sudo or su to become root, and record the original username in the commit. At this time it is recommended to use the git commit command.

root #cd /etc
root #git commit -a -m 'initial /etc commit'

If the initial version has been committed, from this time forward it is safe to use following command below to commit diffs:

user $sudo etckeeper commit new-changes

or:

root #etckeeper commit new-changes

Pack git repository to save disk space:

user $git gc

Troubleshooting

(Troubleshoot issues in this section. Separate issues by best describing the error with a new section name. Remove if no issues are known.)

Removal

Following commands deletes the /etc/.git directory:

root #etckeeper uninit 

** Warning: This will DESTROY all recorded history for /etc,
** including the git repository.

Are you sure you want to do this? [yN]

Uninstall etckeeper:

root #emerge --ask --depclean --verbose sys-apps/etckeeper

See also

  • Dispatch-conf — a utility included with Portage, used to safely manage configuration file updates.

External resources

Retrieved from "https://wiki.gentoo.org/index.php?title=Etckeeper&oldid=1018968"