Wednesday, November 22, 2006

Mergemaster Tutorial

OpenBSDWith the recent release of OpenBSD 4.0, it's that time to upgrade your machines again! I used to just do clean installs, re-install all packages and manually upgrade /etc and /var. Since the pkg_* tools have improved so much in recent versions and I learned of mergemaster, I now do upgrades (more often).

I've posted in the past about how I used mergemaster ([1], [2], [3]), but only briefly. I decided it was time for a post specifically about mergemaster and how to use it.

In OpenBSD, when you do an upgrade, the etcXY.tgz install set is not extracted to your system. You wouldn't want to overwrite important configuration files like pf.conf or rc.local, right? So upgrading /etc and /var is done by hand or with a tool like mergemaster.

Mergemaster, at least in how I use it, works in one of two ways. It will either refer to /usr/src and build a pristine /etc & /var or it will refer to an install set file that's been extracted (which wasn't installed during the upgrade). To me, the second scenario is easier because you don't have to extract or download an entire source tree to create /etc, you just unpack an etcXY.tgz file.

Here's how to use mergemaster:

  1. Buy an OpenBSD CD and wait for it to arrive.

  2. Unwrap the new CD and enjoy it's OpenBSD-goodness.

  3. Upgrade your system by booting to the CD for your architecture and performing an upgrade.

  4. Reboot into your newly upgraded system.

  5. Mount the CD of your architecture:
    mount /dev/cd0c /mnt

  6. Create a temporary home for your etc "source":
    mkdir /var/tmp/foo

  7. Extract the etcXY.tgz to your temporary "source":
    tar -xvzpf /mnt/`uname -r`/`arch -s`/etc??.tgz -C /var/tmp/foo

  8. Make sure your PKG_PATH is set to something sane (mine is usually set to`uname -r`/packages/`arch -s`).

  9. Upgrade your packages by running: pkg_add -ui

  10. Install mergemaster, if necessary: pkg_add -r mergemaster

  11. Optional: Backup /etc and /var: cd /; tar -czvf config_backup.tgz ./etc ./var

  12. Run: mergemaster -r -t /var/tmp/foo

Mergemaster will loop through each file in your "source" etc and var and compare each file with those in /etc and /var. When it finds files in the "source" etc and var that don't exist in /etc and /var, you will be prompted to copy the new file to the proper destinations.

When mergemaster finds files in both locations, it compares them. If they're not different, it discards the one in your "source" directory and continues. If they ARE different, you're given four options: delete the file from the "source" directory, install the "source" file (overwriting your old file), merge the two files or save the "source" file for later (for manual upgrade).

For files that "you're not supposed to touch" like /etc/netstart, /etc/rc, /etc/rc.conf, ..., you almost always choose "i" for install. For files that you may have modified like /etc/master.passwd, /etc/group, /etc/rc.local, you can choose merge. Merge will then give you the option, difference by difference, to choose the line from the old file or the line from the new file. For example, in the /etc/group file, I always add my user account to the wheel group. Mergemaster, in merge mode, would then prompt me to choose the left difference or the right difference:
wheel:*:0:root,mike       | wheel:*:0:root
At the '%' prompt, you choose either the left or the right side (by pressing l or r, then enter). When you've gone through all differences, you're given the option to install the merged file, redo the merge or view the merged file.

After mergemaster is completely done, reboot again to make sure you upgraded system will boot properly from your new /etc.