Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  ETCMERGE (8)


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




etcmerge init etcmerge install



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
.Fx . 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
.Fx (generated from /usr/src by etcmerge ), and a reference copy of the etc that was originally distributed from
.Fx and which you have changed to get the active /etc.

The use of all three copies allow etcmerge to find the two sets of changes - changes by you (the difference from reference to installed etc) and changes by
.Fx (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
.Fx has done a different change to the same part of /etc.


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 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.


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).


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
.Fx 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


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."


mergemaster(8), merge(1).


Eivind Eklund <>

Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.