Projects : sysutils/etcmerge

BSDforge™

Following, are FreeBSD ports, or other *BSD related projects, hosted, or worked on at BSDforge in the sysutils category.

ETCMERGE(1) FreeBSD General Commands Manual ETCMERGE(1)

NAME

etcmerge -- 3-way merge of /etc with updates from /usr/src

SYNOPSIS

etcmerge init etcmerge install

DESCRIPTION

WARNING: ETCMERGE HAS NOT UNDERGONE EXTENSIVE PRODUCTION USE, SO USE AT YOUR OWN RISK. Making a backup of /etc before making alterations to /etc is always good practice. Even when not using etcmerge
etcmerge is a tool for keeping your /etc up to date as you update your system. It fills the same niche as mergemaster(8), with the primary difference being, that etcmerge requires much less manual work. This is because etcmerge merges two sets of changes instead of two copies of /etc; The changes you have done locally are merged with the changes done by FreeBSD. etcmerge does this by tracking three instead of two copies of etc - the active /etc (the one you are running your system on), the new etc distributed from FreeBSD (generated from /usr/src by etcmerge ), and a reference copy of the etc that was originally distributed from FreeBSD and which you have changed to get the active /etc.
The use of all three copies allows etcmerge to find the two sets of changes - changes by you (the difference from reference to installed etc) and changes by FreeBSD (the difference from reference etc to new etc).
A three way merge is usually fully automated - no user interaction is needed for the merge itself. However, sometimes conflicting changes have been made - you have done one change, and FreeBSD has done a different change to the same part of /etc.

ROUGH DESCRIPTION OF USE

First, ensure you have a copy of the /etc distributed by FreeBSD (BEFORE you or sysinstall(8) started modifying it) stored in /var/db/etc. There are two easy ways to do this:

  1. Download a copy matching your installation from http://BSDforge.com/projects/source/sysutils/etcmerge/etc/ and extract this in /var/db/.
  2. Run mergemaster(8) one last time to get your /etc up to date. Then rerun mergemaster(8) with the -v option, exit after it creates /var/tmp/temproot, and copy /var/tmp/temproot/etc to /var/db/etc.

When you have /var/db/etc initialized, start a merge with etcmerge init (as root). etcmerge will run for a while, and start printing out information about what operations it does, prefixed with ETCMERGE:. When it is finished, it will print out a line saying which work directory it has worked in (by default, ${HOME}/etc-work/<date>). Change to this directory, and check if you have any .conflicts files there. If you do, check through them, and resolve the conflicts. The conflicts will be recorded in different ways depending on what kind of conflicts they are. Under the directory etc-merged you'll find a replacement for /etc, including both changes done by you and FreeBSD. Any files that have normal change conflicts (you and FreeBSD have made different changes) will have conflict markers ("<<<<<<<<", "=====" and ">>>>>>>") indicating where the conflict is. See merge(1) for details. The files with this kind of conflict will be listed in 7.conflicts. Other forms of conflicts will be listed in other .conflict files; see below for details if you get any of these.
When you are finished with resolving conflicts, type etcmerge install to make the present etc-merged directory replace /etc, and make etc-new (newly generated etc, based on the present /usr/src) the new reference etc.

INTERNAL DESCRIPTION

In order to do its work, etcmerge divides the files it operate in into different classes, and do different operations depending on which class the files belong in. This division makes a difference for how each file is treated. The exact treatment of each class will be printed out by etcmerge when you run it, along with how many files is in each class, and how many conflicts occur. Each conflict is registered in <class-number>.conflicts - e.g. 7.conflicts for conflicts in class 7 (3-way merged files).

CLASSES

The following table define what the class numbers refer to. The headings Reference, New, and Active refers to various copies of etc - the one generated from /usr/src (New), the one stored as a Reference copy (basically the one generated from /usr/src the last time you ran etcmerge or the one distributed with the FreeBSD you installed), and the one presently Active (ie, the one stored in /etc when you run etcmerge ).
Class Reference New Active 1 Absent Absent Present 2 Absent Present Absent 3 Absent Present Present 4 Present Absent Absent 5 Present Absent Present 6 Present Present Absent 7 Present Present Present
Depending on what class each file (and I'm talking flat files here) is in, it will be handled differently. (See separate description for handling of directories and special files.) The following table describes how each class of files are handled when there are no conflicts in the file.
Class File merge handling 1 Copy from Active 2 Copy from New 3 Copy from New 4 Drop file 5 Drop file (store in conflict dir if diffs) 6 Drop file (store in conflict dir) 7 Do a 3-way merge between all variant, and store result in etc-merged
Depending on what class a file is in, conflicts will be detected differently, and handled differently. The below table detail how conflicts are detected and handled for each class.
Class File conflict handling 1 Cannot be a conflict 2 Cannot be a conflict 3 If there are differences between New and Active, store a diff file in merged-changed. 4 Cannot be a conflict 5 If there are differences between New and Active, store a diff file in merged-removed. 6 Store file in merged-conflicts, with a diff file if there are diffs between Reference and New 7 Conflicts are indicated inside the file, using <<<<<<<<<, =======, and >>>>>>>>> as markers. See merge(1).
Directories and special files are also handled by etcmerge. Empty directories and special files are handled by class (see the tables below). Directories with content is handled alongside files. When a file is copied over to the merged etc (the one etcmerge generates), all prefix directories will be copied too, using permissions either from the active (if available) or the new etc. Ie, if etcmerge decide to copy etc/ssh/ssh_config from /etc, then merged-etc/ssh will get the same permissions as /etc/ssh. This table details how special files (symlinks, device nodes, pipes, etc) and empty directories are handled. etcmerge does not look for conflicts for these, but just copies them as appropriate.
Class Directory/special file handling 1 Copy from Active 2 Copy from New 3 Copy from Active 4 Ignore dir/special file 5 Ignore dir/special file 6 Ignore dir/special file 7 Copy from Active

DIRECTORIES USED

etc-merged Merged etc directory, based on etc-new but customized with on your changes. etc-new New etc directory, as distributed by FreeBSD. Created based on /usr/src. classes Data about what goes in what class merged-removed Files that have been removed, along with .diff files if the active file was different from the reference file. merged-changed Files that have been replaced by the update, along with .diff files saying what changes this has resulted in. merged-conflicts Files that are present in new and reference, but not in the active etc. If these are changed, a .diff is also stored here.

REFERENCES

mergemaster(8), merge(1).

AUTHOR

Eivind Eklund <eivind@FreeBSD.org>
July 5, 2003
See also: etcmerge