OpenBSD Journal

Mergemaster Tutorial

Contributed by merdely on from the etc-etc-etc dept.

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.

(Comments are closed)


  1. By Bryan Brake (192.85.47.2) on

    This is so awesome. I have been afraid to try this. Having the how-to will embiggen me to try it...

    1. By Mark Carlson (dextromulous) on http://mcarlson.ca

      > This is so awesome. I have been afraid to try this. Having the how-to will embiggen me to try it...

      I have been using this cromulent utility on FreeBSD for a while now, I did not even know it was available for OpenBSD! I will also try it when I get my 4.2 CDs.

      1. By Anonymous Coward (208.191.177.19) on

        Even if it doesn't work that well, at least I've learned two new words in this thread alone ("embiggen" & "cromulent").

    2. By Darrin Chandler (dwc) on http://www.stilyagin.com/darrin/

      > This is so awesome. I have been afraid to try this. Having the how-to will embiggen me to try it...

      I haven't exactly been afraid, but every release I do without and think "before next release I really should learn mergemaster." Nice to have an easy path to start using it.

      1. By Bryan Brake (brakeb) on

        > > This is so awesome. I have been afraid to try this. Having the how-to will embiggen me to try it...
        >
        > I haven't exactly been afraid, but every release I do without and think "before next release I really should learn mergemaster." Nice to have an easy path to start using it.

        That was what I meant. Not afraid, I'd say "you know, mergemaster and pkg_add -ui -F update -F updatedepends would require less time than a full re-install". Never happens. I end up re-installing...

  2. By Joe Price (75.144.71.81) on

    Spare yourself headaches and use it. I try and make practice of using mergemaster every upgrade so I don't forget any settings. It's also nice if you are one of those people [like myself] that wants to know every single change in config files.

  3. By Eduardo Alvarenga (200.142.128.16) on

    Maybe iīm wrong, but isnīt mergemaster a package? Or is it builtin now?
    pkg_add mergemaster should be one more step in this guide.

    1. By Anonymous Coward (24.37.242.64) on

      > Maybe iīm wrong, but isnīt mergemaster a package? Or is it builtin now? > pkg_add mergemaster should be one more step in this guide.

      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.

      I find it to be one of those 'must have' utils - I don't know why it's not native in OpenBSD though.

    2. By Mike Erdely (merdely) on http://erdelynet.com/

      > Maybe iīm wrong, but isnīt mergemaster a package? Or is it builtin now?
      > pkg_add mergemaster should be one more step in this guide.

      How silly of me to have assumed that you had it installed already. :)

    3. By Anonymous Coward (74.59.88.115) on

      That would be Step 5.

      1. By Mike Erdely (merdely) on http://erdelynet.com/

        > That would be Step 5.

        I added step 5 after Eduardo's comment.

  4. By sthen (85.158.44.149) on

    > At this point, the upgrade process is done.

    Nearly, but it doesn't run mtree for you.

    1. By Mike Erdely (merdely) on http://erdelynet.com/

      >> At this point, the upgrade process is done.
      > Nearly, but it doesn't run mtree for you.

      Thanks. Story updated to include running mtree.

  5. By Jason Dixon (jason) jason@dixongroup.net on

    Someone should merge this into the FAQ. :)

    1. By Nick Holland (68.43.113.17) nick@holland-consulting.net on http://www.openbsd.org/faq/

      > Someone should merge this into the FAQ. :)

      Tell ya what...
      You put mergemaster in base, I'll have the upgradeXX.html process use it. Until then, no.

      It is nothing against mergemaster. I have little desire and great reluctance to put things into the FAQ that require third party packages, at least if there are alternative ways of doing things.

      Besides...if put in base, it might be possible to integrate it right into the bsd.rd upgrade process. Imagine just being DONE after the first boot after doing an upgrade, no extra steps.

  6. By Rich (195.212.199.56) on

    The problem I had with using Mergemaster (and I have to admit this was some time ago, so maybe things have changed since) is that the diffs are presented to the user, but it's not always easy to see the context and scope of the change. As a result, I lost confidence that the end result was actually correct.

    Since then, when I update, I put together a new /etc somewhere (take the base /etc from the new release and manually apply the required changes), and then come the right time in the update process, just dump this over the old /etc and away I go. It's probably "wrong" and some would say it's error-prone (though I seem to have survived so far), but it doesn't actually take that long to do and I don't have any doubts about what the end result is any more.

    I'm not knocking Mergemanster; I'm just imparting my experience.

    1. By dingo (68.29.43.2) on

      > The problem I had with using Mergemaster (and I have to admit this was some time ago, so maybe things have changed since) is that the diffs are presented to the user, but it's not always easy to see the context and scope of the change. As a result, I lost confidence that the end result was actually correct.

      being familiar with using diff's is good sysadmin practice u kno?

      > Since then, when I update, I put together a new /etc somewhere (take the base /etc from the new release and manually apply the required changes), and then come the right time in the update process, just dump this over the old /etc and away I go. It's probably "wrong" and some would say it's error-prone (though I seem to have survived so far), but it doesn't actually take that long to do and I don't have any doubts about what the end result is any more.

      when you forget something and lock yourself out of a remote machine you may change your mind

      1. By Rich (195.212.199.56) on

        > being familiar with using diff's is good sysadmin practice u kno?

        Is is really? I would never have guessed. Thanks for the tip :-)

        > when you forget something and lock yourself out of a remote machine you may change your mind

        Yes - I think I mentioned that there is a risk involved. But then there is always a risk in anything, no? And yes, I may change my mind back in the future. As I said, I was just relaying my experience.

Credits

Copyright © - Daniel Hartmeier. All rights reserved. Articles and comments are copyright their respective authors, submission implies license to publish on this web site. Contents of the archive prior to as well as images and HTML templates were copied from the fabulous original deadly.org with Jose's and Jim's kind permission. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]