TIP_dispatch-conf

Introduction

dispatch-conf is a script designed to ease /etc and other config file updates. Its claim to fame is that it can automatically update any scripts that have easy changes to comments, or that haven't been changed between updates. Unlike etc-update it also creates backups and has more advanced options for configuration file management.

If you want to know more about what the dispatch-conf and etc-update tools do, read emerge --help --config.

Setup

No installation is necessary, it comes with portage so you already have this great tool installed! All you have to do is configure it via the config file:

# Directory to archive replaced configs
archive-dir=/etc/config-archive

# Use rcs for storing files in the archive directory?
# (yes or no)
use-rcs=yes

# Diff for display
# %s old file
# %s new file
diff="diff -Nu %s %s"

# Automerge files comprising only CVS interpolations (e.g. Header or Id)
# (yes or no)
replace-cvs=yes

# Automerge files comprising only whitespace and/or comments
# (yes or no)
replace-wscomments=yes

# Automerge files that the user hasn't modified
# (yes or no)
replace-unmodified=yes

# Ignore a version that is identical to the previously merged version,
# even though it is different from the current user modified version
# (yes or no)
ignore-previously-merged=yes

Backup Directory

dispatch-conf keeps copies of changed files in a directory is specified in the config files. By default this is /etc/config-archive

Advanced Backups

dispatch-conf also has the ability to use the rcs (revision control system) version management tool (similar to, and precursor to, cvs or subversion) to create a log of all changes ever made to config files.

To enable rcs backups, install rcs with emerge -av rcs and set use-rcs=yes in /etc/dispatch-conf.conf.

rcs basically creates diffs of the changes between two files. You can find out more about diff on Wikipedia.

Some useful commands related to rcs :

• rcs log :

# rcs2log -v /etc/config-archive/etc/init.d/fail2ban,v

Use colordiff to view changes

Reading changes in all grey text can be a bit annoying. Fortunately there's an aternative called colordiff that displays the different types of changes in different colors. Configuration is simple, first install colordiff with emerge -av colordiff. Now change the diff line in the config file to:

diff="colordiff -Nu '%s' '%s' | less --no-init --QUIT-AT-EOF"

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:

merge="vimdiff -c \'saveas %s\' -c next -c \'setlocal noma readonly\' -c prev %s %s"

You can also use vimdiff (for gvimdiff use -f flag moreover) to merge changes.

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 also the Vim documentation for further help.

Use xxdiff to view and merge changes

A further alternative is to use a gui tool to view and merge changes, such as xxdiff. To do so, install xxdiff with: emerge -av xxdiff and alter the diff line and add a merge line to the config file:

# xxdiff for viewing differences:
diff="xxdiff %s %s"

# xxdiff for merging:
merge="xxdiff -X -m --resource 'Show.PaneMergedView:true' -O -M %s %s %s"

Note: -X alters error code responce to meet dispatch-conf requirements.

Usage

Auto Merging

Run dispatch-conf. If you have any config files that need updating the script will go through and see if it can automerge any of them for you. You will then see a diff of the first config it found that it could not auto-merge.

Manually Merging

If there are files that can't be auto merged, you will see an output like this, if using the default configuration:

--- /etc/portage/package.keywords       2006-01-23 16:10:44.000000000 -0600
+++ /etc/portage/._cfg0000_package.keywords     2006-01-22 13:52:51.000000000 -0600
@@ -7,4 +7,4 @@
 dev-util/intltool ~x86
-# sys-block/gparted ~x86
+sys-block/gparted ~x86
 www-client/prozilla ~x86
 www-client/mozilla-firefox ~x86
@@ -41,3 +41,3 @@
 x11-libs/pango ~x86
-gnome-extra/libgtkhtml ~x86
+gnome-extra/gtkhtml ~x86
 mail-client/evolution ~x86


>> (1 of 1) -- /etc/portage/package.keywords
>> q quit, h help, n next, e edit-new, z zap-new, u use-new
   m merge, t toggle-merge, l look-merge:

In the above example the file being updated is /etc/portage/package.keywords.

• The first 2 lines are the file names of the new and old files. The line starting with +++ is the new filename and the line starting with --- is the old filename.
• Lines beginning with @@ denote a snippet of a file. In the above, @@ -7,4 means that this snippet starts at line 7 of the original file and is 4 lines in length. Likewise, +7,4 @@ means that this same snippet starts at line 7 of the new file and is 4 lines in length.
• Within a snippet, lines beginning with - or + belong only to the original or new file respectively.

At this point you can:

• skip making a decision for now (n next)
• open the new file with the editor defined by the EDITOR env variable (e edit-new)
• delete the new file and use the old file (z zap-new)
• use the new file and archive the old (u use-new)
• manually merge the files (m merge)
• toggle between the two copies (t toggle-merge)
• look at the differences between the merged and pre-merged files (l look-merge)

The t and l options don't really come into play until the m option has been used.

If you choose to merge the files, pressing m will compare difference groups side by side, with the original file on the left and the new file on the right. At the prompt (%) press l to choose the left side as the section to keep or r to keep the right side (part from new file).

Changes will be placed in a new, merged, file. If you run out of changes or press q at the prompt you will return to above diff display, only this time the merged file you just created will be compared the original. Pressing t compares the original with the pre-merged file once again. This means that the use-new option picks either the merged or pre-merged file depending on which is displayed on the screen.

Working with dispatch-conf

The first time you update a config file with the new untouched config file, dispatch-conf will copy it to your archive directory in the corresponding location with a '.dist'. From this point on, it will compare 'current' and 'archive.dist'. If the files are the same (and replace-unmodified=yes in /etc/dispatch-conf.conf), it will auto-merge.

As the collection grows, dispatch-conf gets smarter; it will have to ask you about fewer and fewer files each time it runs.

Thus, if, for instance, you always wanted to auto-merge the files in /etc/init.d and your config archive directory is /etc/config-archive: for x in /etc/init.d/*; do cp "$x" "/etc/config-archive$x.dist"; done

Example Session

A user is merging the system package set, new /etc/bash/._cfg0000_bashrc file appears and the user needs update it into their /etc/bash/bashrc. Now the user runs dispatch-conf, which finds the new file to merge and displays the differences.

The first item displayed is the files being compared:

--- /etc/bash/bashrc    2005-08-11 22:29:36.000000000 +0200
+++ /etc/bash/._cfg0000_bashrc  2006-09-24 15:29:13.000000000 +0200

The user decides to select m to interactively change their config. The users selected editing method is run and they make the desired changes, which are saved to /etc/bash/._mrg0000_bashrc, which is now considered the new version. dispatch-conf now displays the new differences:

--- /etc/bash/bashrc    2005-08-11 22:29:36.000000000 +0200
+++ /etc/bash/._mrg0000_bashrc  2006-09-24 15:58:54.000000000 +0200

The user decides that they want to abandon the changes they made and go back to the original new file, so they select the t option. dispatch-conf will forget about ._mrg* and ._cfg* becomes considered as "new" again.

Once the user is happy with the changes, they select the u (use-new) option to update /etc/bash/bashrc. All the temporary files created are now removed and a backup of the changes is made to /etc/config-archive (either a full copy of the old file, or if the user has rcs installed and enabled as per this article, just the differences.

See also

• dispatch-conf MAN page
• HOWTO etc-update - a less functional alternative.