Difference between revisions of "Etckeeper"

From ArchWiki
Jump to navigation Jump to search
(Add systemd section)
m (style: added Note template)
 
(68 intermediate revisions by 21 users not shown)
Line 1: Line 1:
[[Category:System administration]]
+
{{Lowercase title}}
Etckeeper lets you keep /etc under version control.
+
[[Category:Configuration management]]
 +
[[es:Etckeeper]]
 +
[[ja:Etckeeper]]
 +
{{Related articles start}}
 +
{{Related|Git}}
 +
{{Related|Cron}}
 +
{{Related articles end}}
  
== Install ==
+
[http://etckeeper.branchable.com/ Etckeeper] is a collection of tools to keep track of {{ic|/etc/}} in a repository ([[Git]], [[Mercurial]], [[Bazaar]] or [[Darcs]] are supported). A [[pacman hook]] auto-commits changes before a system-upgrade and file permissions are tracked, which version control does not normally support, but is important for files like [[:/etc/shadow]].
Get {{AUR|etckeeper}} from the [[AUR]].
 
  
== Configure ==
+
== Installation ==
The main config file is {{ic|/etc/etckeeper/etckeeper.conf}}.
+
[[Install]] the {{Pkg|etckeeper}} package.
You can set things such as the VCS to use in this file.
 
  
Once you've set your preferred VCS (the default is git),
+
== Configuration ==
you can initialize the /etc repository by running
+
 
 +
The preferred version control system (default is [[git]]) and other options are to be configured in {{ic|/etc/etckeeper/etckeeper.conf}}.
 +
 
 +
Etckeeper supports using [[pacman]] as a {{ic|LOWLEVEL_PACKAGE_MANAGER}} and {{ic|HIGHLEVEL_PACKAGE_MANAGER}} in {{ic|etckeeper.conf}}.
 +
 
 +
== Usage ==
 +
 
 +
After configuration the repository for the {{ic|/etc}} path has to be initialized:
 
  # etckeeper init
 
  # etckeeper init
  
== Usage ==
+
And perform a first commit to keep track of the changes, this is a necessary step for etckeeper to be able to work automatically:
 +
# etckeeper commit "first commit"
 +
 
 +
As of ''etckeeper'' version 1.18.3-1, pre-install and post-install [[pacman hooks]] are executed automatically on package installation, update and removal. A manual [[#Wrapper script]] is not required anymore.
 +
 
 +
To track other changes to the {{ic|/etc}} path, you need to either commit changes manually (see the {{man|8|etckeeper}} man page for commands) or use one of the stopgap solutions below.
 +
 
 +
=== systemd ===
 +
 
 +
Service and timer units are included in the package. Simply [[Systemd/Timers#Management|enable]] {{ic|etckeeper.timer}}.
  
Etckeeper supports using pacman as a {{ic|LOWLEVEL_PACKAGE_MANAGER}} in etckeeper.conf.
+
See [[Systemd/Timers]] for more information and [[Systemd#Editing provided units]] if you wish to edit the provided units.
Support for using pacman as a {{ic|HIGHLEVEL_PACKAGER_MANAGER}} is not yet added,
 
so you'll need to either commit changes manually or use one of the stopgap solutions below.
 
  
 
=== Cron ===
 
=== Cron ===
  
There is a cron script in the source distribution at {{ic|debian/cron.daily}}.
+
There is a {{ic|[https://git.joeyh.name/index.cgi/etckeeper.git/tree/debian/cron.daily cron script]}} in the source distribution.
 
You can use this script to automatically commit changes on a schedule.
 
You can use this script to automatically commit changes on a schedule.
To make it run daily, for example, make sure you have cron installed and enabled,
 
then simply copy the script from the srcdir where you built etckeeper to /etc/cron.daily
 
and make sure it's executable (e.g. {{ic|chmod +x /path/to/script}}).
 
  
=== systemd ===
+
For example, to make it run daily:
 +
# Have [[cron]] installed and enabled.
 +
# Put script as {{ic|/etc/cron.daily/''script_name''}}.
 +
# Permit execution of file for ''root'' ({{ic|# chmod u+x /etc/cron.daily/''script_name''}}).
  
Service and timer units are included in the AUR package.
+
See [[cron#Cronie]], [[cron]] for more information.
  
=== Wrapper script ===
+
=== Incron ===
 
 
In order to emulate the auto-commit functionality that etckeeper has on other systems,
 
you could place a script such as the one below somewhere in your PATH, make it executable,
 
and use it instead of {{ic|pacman -Syu}} to update your system.
 
  
#!/bin/bash
+
{{Note|This section applies only to incron version 5.10.}}
 
   
 
   
etckeeper pre-install
+
To automatically create commits on '''every''' file modification inside {{ic|/etc/}}, use {{Pkg|incron}}. It utilizes native filesystem signalling through {{man|7|inotify}}.
pacman -Syu
 
etckeeper post-install
 
 
 
Alternatively you can add a quick alias to {{ic|~/.bashrc}}:
 
  
  alias pkg-update='sudo etckeeper pre-install && sudo pacman -Syu && sudo etckeeper post-install'
+
After installing incron and initializing etckeeper, add root to the users allowed to run incron scripts:
 +
  # echo root | sudo tee -a /etc/incron.allow
  
or a function where it is possible to specify the arguments for pacman or pacman wrapper:
+
Then edit the incrontab with:
 +
# sudo incrontab -e
  
  Pacman () { sudo etckeeper pre-install && sudo pacman  "$@" && sudo etckeeper post-install; }
+
Add in the text:
 +
  # /etc IN_MODIFY,IN_NO_LOOP /bin/etckeeper commit "[message]"
  
To use the function, just run pacman as usual with flags as needed, but with a capital "P".
+
''IN_NO_LOOP'' is a flag that waits for the commit to finish before running the next command, and prevents an infinite loop.
For example:
 
Pacman -Syu
 
Pacman -R foo
 
  
{{Warning|Do not name your wrapper script "pacman" and rely on it appearing earlier in the PATH than {{ic|/usr/bin/pacman}}. One of the etckeeper pre-install hooks calls pacman without specifying its path, so your script will be invoked recursively without end.}}
+
Where ''[message]'' could be something like {{ic|"modified $#"}} where $# is a special incrontab wildcard expanded to the name of the file modified.
  
=== Incron ===
+
Do note that Incron is not capable of watching subdirectories. Only files within the path will be monitored. If you need subdirectories monitored, you must give them their own entry. However, commits when top-level files are modified will still commit all changes.
  
As an alternative to the above, you could set up incron to automatically commit changes using etckeeper
+
See: [http://inotify.aiken.cz/?section=incron&page=doc&lang=en], [https://linux.die.net/man/8/incrond]
whenever a file in /etc is modified.
 
  
 
=== Automatic push to remote repo ===
 
=== Automatic push to remote repo ===
 
{{Warning|Pushing your etckeeper repository to a publicly accessible remote repository can expose sensitive data such as password hashes or private keys. Proceed with caution.}}
 
{{Warning|Pushing your etckeeper repository to a publicly accessible remote repository can expose sensitive data such as password hashes or private keys. Proceed with caution.}}
Whilst having a local backup in {{ic|/etc/.git}} is a good first step, etckeeper can automatically push your changes on each commit to a remote repository such as Github. Create an executable file {{ic|/etc/etckeeper/commit.d/40github-push}}:
+
 
 +
Whilst having a local backup in {{ic|/etc/.git}} is a good first step, etckeeper can automatically push your changes on each commit to a remote repository such as Github.
 +
 
 +
First, edit {{ic|etc/.git}} and add your remote Github repository:
 +
 
 +
# git remote add origin ''<nowiki>https://github.com/user/repo.git</nowiki>''
 +
 
 +
Next, a hook must be used or configured to push.
 +
 
 +
==== Using etckeeper provided hook ====
 +
 
 +
Edit the {{ic|PUSH_REMOTE}} option in {{ic|/etc/etckeeper/etckeeper.conf}}, with the name of
 +
the remote repository you want etckeeper to push to. For example:
 +
 
 +
PUSH_REMOTE="''origin''"
 +
 
 +
Multiple remote repositories can be added separated with spaces.
 +
 
 +
==== Through a custom hook ====
 +
 
 +
Create an executable file {{ic|/etc/etckeeper/commit.d/40github-push}}:
  
 
  #!/bin/sh
 
  #!/bin/sh
Line 75: Line 104:
 
  fi
 
  fi
  
Change to {{ic|etc/.git}} and add your remote Github repository:
+
Now each time you run your wrapper script or alias from above, changes will be automatically commited to your Github repo.
 +
 
 +
=== Wrapper script ===
 +
 
 +
If you want to track changes of a frequently executed command (e.g. {{ic|''command''}}), a simple wrapper script can help to automate it. For example, create:
 +
 
 +
{{hc|/usr/local/bin/checketc.sh|2=
 +
#!/bin/bash
 +
 
 +
etckeeper pre-install
 +
''command''
 +
etckeeper post-install}}
  
# git remote add origin https://github.com/user/repo.git
+
and make it executable. Alternatively, you may call the Etckeeper commands via a bash alias or function, see [[Bash#Aliases]] for more information.  
  
Now each time you run your wrapper script or alias from above, changes will be automatically commited to your Github repo.
+
{{Note|Before Etckeeper version 1.18.3-1 such manual wrapper script was required for Pacman integration. Now the Pacman hooks perform the commands automatically.}}

Latest revision as of 20:30, 3 May 2019

Etckeeper is a collection of tools to keep track of /etc/ in a repository (Git, Mercurial, Bazaar or Darcs are supported). A pacman hook auto-commits changes before a system-upgrade and file permissions are tracked, which version control does not normally support, but is important for files like /etc/shadow.

Installation

Install the etckeeper package.

Configuration

The preferred version control system (default is git) and other options are to be configured in /etc/etckeeper/etckeeper.conf.

Etckeeper supports using pacman as a LOWLEVEL_PACKAGE_MANAGER and HIGHLEVEL_PACKAGE_MANAGER in etckeeper.conf.

Usage

After configuration the repository for the /etc path has to be initialized:

# etckeeper init

And perform a first commit to keep track of the changes, this is a necessary step for etckeeper to be able to work automatically:

# etckeeper commit "first commit"

As of etckeeper version 1.18.3-1, pre-install and post-install pacman hooks are executed automatically on package installation, update and removal. A manual #Wrapper script is not required anymore.

To track other changes to the /etc path, you need to either commit changes manually (see the etckeeper(8) man page for commands) or use one of the stopgap solutions below.

systemd

Service and timer units are included in the package. Simply enable etckeeper.timer.

See Systemd/Timers for more information and Systemd#Editing provided units if you wish to edit the provided units.

Cron

There is a cron script in the source distribution. You can use this script to automatically commit changes on a schedule.

For example, to make it run daily:

  1. Have cron installed and enabled.
  2. Put script as /etc/cron.daily/script_name.
  3. Permit execution of file for root (# chmod u+x /etc/cron.daily/script_name).

See cron#Cronie, cron for more information.

Incron

Note: This section applies only to incron version 5.10.

To automatically create commits on every file modification inside /etc/, use incron. It utilizes native filesystem signalling through inotify(7).

After installing incron and initializing etckeeper, add root to the users allowed to run incron scripts:

# echo root | sudo tee -a /etc/incron.allow

Then edit the incrontab with:

# sudo incrontab -e

Add in the text:

# /etc IN_MODIFY,IN_NO_LOOP /bin/etckeeper commit "[message]"

IN_NO_LOOP is a flag that waits for the commit to finish before running the next command, and prevents an infinite loop.

Where [message] could be something like "modified $#" where $# is a special incrontab wildcard expanded to the name of the file modified.

Do note that Incron is not capable of watching subdirectories. Only files within the path will be monitored. If you need subdirectories monitored, you must give them their own entry. However, commits when top-level files are modified will still commit all changes.

See: [1], [2]

Automatic push to remote repo

Warning: Pushing your etckeeper repository to a publicly accessible remote repository can expose sensitive data such as password hashes or private keys. Proceed with caution.

Whilst having a local backup in /etc/.git is a good first step, etckeeper can automatically push your changes on each commit to a remote repository such as Github.

First, edit etc/.git and add your remote Github repository:

# git remote add origin https://github.com/user/repo.git

Next, a hook must be used or configured to push.

Using etckeeper provided hook

Edit the PUSH_REMOTE option in /etc/etckeeper/etckeeper.conf, with the name of the remote repository you want etckeeper to push to. For example:

PUSH_REMOTE="origin"

Multiple remote repositories can be added separated with spaces.

Through a custom hook

Create an executable file /etc/etckeeper/commit.d/40github-push:

#!/bin/sh
set -e

if [ "$VCS" = git ] && [ -d .git ]; then
  cd /etc/
  git push origin master
fi

Now each time you run your wrapper script or alias from above, changes will be automatically commited to your Github repo.

Wrapper script

If you want to track changes of a frequently executed command (e.g. command), a simple wrapper script can help to automate it. For example, create:

/usr/local/bin/checketc.sh
#!/bin/bash

etckeeper pre-install
command
etckeeper post-install

and make it executable. Alternatively, you may call the Etckeeper commands via a bash alias or function, see Bash#Aliases for more information.

Note: Before Etckeeper version 1.18.3-1 such manual wrapper script was required for Pacman integration. Now the Pacman hooks perform the commands automatically.