From Gentoo Wiki
Jump to:navigation Jump to:search

dispatch-conf is a utility included with Portage, used to safely manage configuration file updates. It allows system administrators to review configuration file changes made by Portage, either by using the new configuration as-is, by rejecting changes, or by selectively merging modifications. Portage will indicate when config files need updating.

dispatch-conf permits rollback, so any mistakes can be reverted. Changes made to config files will be saved in the archive directory; alternatively it can integrate with rcs to allow for version-controlled configuration file management. dispatch-conf will automatically update config files that the user has never modified, or that differ from the current version only in CVS cruft, comments, or white space.

dispatch-conf will check all directories in the CONFIG_PROTECT environment variable for changes. Any config files found in paths in the CONFIG_PROTECT_MASK environment variable will not be protected and will automatically be overwritten.



The dispatch-conf configuration file is /etc/dispatch-conf.conf. The directory referenced by the archive-dir variable in this file may need to be created.

RCS (revision control system) integration

When configured to use RCS, read and execute permissions of archived files may be inherited from a file's first check-in. If the permissions of the working file have since changed, the permissions from the first check in may be kept - this could inadvertently cause security issues. Access to RCS files can be controlled by setting the permissions of the parent directory.

When dispatch-conf is configured to integrate with rcs, it will store all changes in /etc/config-archive.

Install revision control system:

root #emerge --ask dev-vcs/rcs

This process of configuration is as simple as editing the configuration file to include the following:

FILE /etc/dispatch-conf.conf

Administrators can then view the differences using the rcs utilities like rlog as well as roll-back changes using co. The rcs utilities work with file locking itself, so the moment you want to use it in your administrative tasks, understand that:

  • dispatch-conf only stores the changes made when the package suggests to alter the file. Changes you made afterwards are not registered yet
  • when you check out a file, rcs will want to write the file to the file system, so make sure you backup your existing file first, or work with standard output (see later)
  • if you want to check in a file, you first need to take a lock on said file. Also, make sure you opt not to remove the working file

To view the commit history on /etc/conf.d/udev:

user $rlog /etc/config-archive/etc/conf.d/udev,v
RCS file: /etc/config-archive/etc/conf.d/udev,v
Working file: udev
head: 1.1
locks: strict
access list:
symbolic names:
keyword substitution: kv
total revisions: 2;     selected revisions: 2
Archived config file.
revision 1.1
date: 2011/06/15 18:14:59;  author: root;  state: Exp;
branches:  1.1.1;
dispatch-conf update.
date: 2011/06/15 18:14:59;  author: root;  state: Exp;  lines: +3 -2
dispatch-conf update.

If you want to roll back to a particular version, a simple way to do so is to check out a previous version:

root #cp udev udev.orig
root #co -p -r1.1.1.1 /etc/config-archive/etc/conf.d/udev,v > udev
etc/config-archive/etc/conf.d/udev,v  -->  standard output
revision 1.1.1.

After making your final changes (you can use the backup udev.orig to merge any changes made later), check in the file again:

root #co -p -l /etc/config-archive/etc/conf.d/udev,v

Edit the file, and finally check in the changes:

root #ci -l /etc/config-archive/etc/conf.d/udev,v
/etc/config-archive/etc/conf.d/udev,v  <--  udev
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.' or end of file:
>> Merged changes for persistant rules
>> .

Changing diff or merge tools

Color diff output

Reading changes in all grey text can be a bit annoying. Fortunately, modern versions of sys-apps/diffutils have a --color switch, which displays the different types of changes in different colors. Configuration is simple - change the diff line in the config file to:

FILE /etc/dispatch-conf.conf
diff="diff --color=always -Nu '%s' '%s'"

Alternatively, the package app-misc/colordiff can be used. Install colordiff with:

root #emerge --ask app-misc/colordiff

Then change the config to use it:

FILE /etc/dispatch-conf.conf
diff="colordiff -Nu '%s' '%s'"

Use (g)vimdiff to merge changes

You may wish to try (g)vimdiff instead of the default method of merging files. To do this, modify the /etc/dispatch-conf.conf configuration file by changing the merge line:

FILE /etc/dispatch-conf.conf
merge="vimdiff -c'saveas %s' -c next -c'setlocal noma readonly' -c prev %s %s"

You can also use vimdiff (for gvimdiff use -f option moreover) to merge changes. If you want to use neovim, replace %s %s at the end with -d %s %s

The left pane will hold the original config file saved as the merge output, so make changes in the left pane and save that pane. To help you remember the right hand pane (containing the new config file) will be marked unmodifiable and read-only.

Some useful commands related to merge with vimdiff:

"]c" : jump to next change
"[c" : jump to previous change
"CTRL-W <Right>" or "CTRL-W <Left>" : go to the other window
"do" (diff obtain): get the text of the highlighted block from the other window
"dp" (diff put) : put the text of the highlighted block to the other window
"zo" : open fold under the cursor
"zc" : close fold under the cursor
"zr" : open all folds
":wqa" : write and exit

See the Vim documentation for further help.

Using imediff2 to merge changes

Another merge alternative is dev-util/imediff2. This simple tool allows using just a few keys to toggle between options. Primarily, this is done through the a or b keys. Also, the e key will open the user's favorite editor set by the EDITOR shell variable for manual merging.

To use with dispatch-conf, first install imediff2:

root #emerge --ask dev-util/imediff2

Then, configure /etc/dispatch-conf.conf:

FILE /etc/dispatch-conf.conf
merge="imediff2 -c -N --output='%s' '%s' '%s'"



dispatch-conf should be run as root, as configuration files are usually owned by root:

root #dispatch-conf

The AMD64 Handbook and the man page contain further information on usage:

user $man 1 dispatch-conf

See also