Mergemaster Tutorial

OpenBSD 4.2 is scheduled for release on November 1 and systems running releases prior to 4.2 should be upgraded. Mergemaster is a tool in ports included that minimizes upgrade headaches by merging system configuration files from OpenBSD 4.1 with the new 4.2 /etc and /var files.

Upgrade steps:

1. Buy a CD (EU link).
2. Backup the 4.1 system.
3. Upgrade the system using the "Upgrading a previously-installed OpenBSD System" section of INSTALL.$ARCH in the /4.2/$ARCH directory of the installation CD.
4. Upgrade installed packages with: pkg_add -ui -F update -F updatedepends
5. If necessary, install mergemaster: pkg_add mergemaster
6. Use mergemaster (details below).

Mergemaster uses a temporary root containing the 4.2 configuration files and "compares the cvs(1) version $OpenBSD strings for files that have them, deleting the temporary file if the strings match. If there is no $OpenBSD string, or if the strings are different it compares the files themselves" (from mergemaster(1)). If the files are different, mergemaster prompts for what action to take: delete, install, merge or leave it for later. All responses given to mergemaster require pressing the [Enter].

To get started with mergemaster, create a temporary directory (mkdir /var/tmp/temproot) for the 4.2 files. Extract etc42.tgz (and xetc42.tgz if using X) to the temporary directory (tar -xvzpf etc42.tgz -C /var/tmp/temproot; tar -xvzpf xetc42.tgz -C /var/tmp/temproot). Run: mergemaster -ir

In the mergemaster command, "-ir" could really be "-i -r". "-i" tells mergemaster to automatically install new files. "-r" directs mergemaster to use a pre-exising temporary root directory instead of making one from source in /var/tmp/temproot.

As mergemaster compares the new files with the old files, use "d" to keep the 4.1 file (deleting the temporary file), "i" to install the 4.2 file (overwriting the old one), "m" to merge the two files or press [Enter] to "leave the temporary file to deal with by hand":

   ======================================================================   

  *** Displaying differences between ./etc/group and installed version:

--- /etc/group  Tue Sep  4 15:34:23 2007
+++ ./etc/group Tue Aug 28 12:00:10 2007
@@ -1,4 +1,4 @@
-wheel:*:0:root,merdely
+wheel:*:0:root
 daemon:*:1:daemon
 kmem:*:2:root
 sys:*:3:root
@@ -57,4 +57,3 @@
 dialer:*:117:
 nogroup:*:32766:
 nobody:*:32767:
-merdely:*:1000:merdely

  Use 'd' to delete the temporary ./etc/group
  Use 'i' to install the temporary ./etc/group
  Use 'm' to merge the temporary and installed versions
  Use 'v' to view the diff results again

  Default is to leave the temporary file to deal with by hand

How should I deal with this? [Leave it for later]

In merge mode, mergemaster invokes sdiff(1), which prompts at each set of differences for which part should be kept. Press "l" to keep the left side (old file) or "r" to install the right side (new file). Sometimes there are local changes in a file that you want to merge with the official changes. To do this, enter "eb" and $EDITOR is launched allowing manual merging of that set of differences. When the merge process is done, choose "i" to install the merged file, "r" to redo the merge, "v" to view the merged file or "Leave it for later".

How should I deal with this? [Leave it for later] m

wheel:*:0:root,erdelym                                               | wheel:*:0:root
%h
e:      edit blank diff
eb:     edit both diffs concatenated
el:     edit left diff
er:     edit right diff
l | 1:  choose left diff
r | 2:  choose right diff
s:      silent mode--don't print identical lines
v:      verbose mode--print identical lines
q:      quit
%

When mergemaster is done, it asks whether or not to delete what is left in the temporary root. If "Leave it for later" was ever chosen, press [Enter] to choose "no". Otherwise, type "yes". If some files were left for later, manually upgrade the files left in the temporary root.

It's a good idea to ensure your directories and file permissions are correct by running something like:

mtree -qdef /etc/mtree/4.4BSD.dist -p / -u

At this point, the upgrade process is done. Reboot to ensure the new configuration files allow the system to start up properly.