If your system is only lightly modified, you should see something like this:

===> Populating temporary root under /var/tmp/sysmerge.daiHKukKfE/temproot
===> Starting comparison
===> Updating /etc/inetd.conf
===> Updating /etc/login.conf
…

I haven’t changed these files, so sysmerge automatically updates them for me.

…
===> Installing /etc/nginx/fastcgi_params
===> Installing /etc/nginx/koi-utf
…

I didn’t have these files on my system, so sysmerge installs them for me.

These examples are easy cases. In cases where you’ve edited an /etc file, sysmerge will need your help.

Say you’ve edited a file, and the file version has changed. Does your local change reflect the update, does it conflict, or can the two coexist? sysmerge can’t tell if it should overwrite the installed file with a new version, leave it unchanged, or merge the two, so it displays the differences between the old and new files.

  ===> Displaying differences between ./etc/mail/aliases and installed version:
1 --- /etc/mail/aliases   Sun Jun  9 04:50:04 2013
2 +++ ./etc/mail/aliases  Wed Oct 23 17:06:02 2013
  @@ -1,5 +1,5 @@
   #
3 -#      $OpenBSD: aliases,v 1.36 2010/09/22 13:01:10 deraadt Exp $
4 +#      $OpenBSD: aliases,v 1.37 2012/10/13 07:42:39 dcoppa Exp $
   #
   #  Aliases in this file will NOT be expanded in the header from
   #  Mail, but WILL be visible over networks or from /usr/libexec/mail.local.
  @@ -32,6 +32,7 @@
   _identd: /dev/null
   _iked: /dev/null
   _isakmpd: /dev/null
5 +_iscsid: /dev/null
   _kadmin: /dev/null
   _kdc: /dev/null
   _ldapd: /dev/null
  @@ -69,7 +70,7 @@
   sshd:   /dev/null
   # Well-known aliases -- these should be filled in!
6 -root: [email protected]
7 +# root:
   # manager:
   # dumper:

If you’ve changed the file, sysmerge presents the differences between the old and new files with a few surrounding lines of context. In this example, the /etc/mail/aliases file on my system is dated June 9 at 1, and the new version is from October 23 at 2. Lines that exist in the new version of the file but not in the installed one are prefaced with a plus sign (+). Lines that exist in the installed file but not in the new one are prefaced with a minus sign (-).

This example shows that the OpenBSD version of this file changed from 1.36 at 3 to 1.37 at 4. That’s not terribly surprising, and for system administration purposes, not a terribly vital piece of information. But the new version has a new alias, directing email addressed to the user _iscsid to /dev/null at 5. This could be important, so I want the new alias on my system.

Next, we see a difference between the files, where I’ve forwarded email addressed to root to my personal email at 6, but the new version of the file has no such redirection at 7. I want the old version of this line but the new version of another line, and while I don’t particularly care about the OpenBSD version numbers, I would prefer the newer one. I could hand assemble an aliases file, but after sysmerge prints out the differences, it offers to help.

1 Use 'd' to delete the temporary ./etc/mail/aliases
2 Use 'i' to install the temporary ./etc/mail/aliases
3 Use 'm' to merge the temporary and installed versions
4 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] m

sysmerge offers the following choices:

To merge the old and new files, I enter m. Note that the merge function requires close attention to detail. A mistake here can make your system hang as it tries to go into multiuser mode.

When you merge, sysmerge takes your input and builds a combined file. Lines that are identical in both versions are automatically added to the new file. When lines differ, sysmerge walks you through the differences and lets you choose a version.

The new version of the line appears on the right, and the installed version is on the left. Enter l or 1 to choose the version on the left side, or r or 2 to choose the version on the right.

# $OpenBSD: aliases,v 1.36 2010/09/22 13:01:10 de | # $OpenBSD: aliases,v 1.37 2012/10/13 07:42:39 dc
%r

The version number has updated, though it’s in a comment, which won’t affect how the alias file updates. Still, as I’m merging the files anyway, I might as well get the new version number. I enter r to choose the version on the right.

                               > _iscsid: /dev/null
%r

There is no equivalent to this line in the installed file, as this alias exists only in the new file. Again, I choose r to include this line in my file.

root: [email protected]    | # root:
%l

Here, I want the entry from the installed file, on the left-hand side. I choose l.

Once I’ve gone through all of the entries, sysmerge offers me more choices. These include comparing the merged and installed files, comparing the merged and new files, starting over, viewing the merged file, redoing the merge, and installing the merged file.

  Use 'e' to edit the merged file
  Use 'i' to install the merged file
  Use 'n' to view a diff between the merged and new files
  Use 'o' to view a diff between the old and merged files
  Use 'r' to re-do the merge
  Use 'v' to view the merged file
  Use 'x' to delete the merged file and go back to previous menu
  Default is to leave the temporary file to deal with by hand
===> How should I deal with the merged file? [Leave it for later] i

I did everything correctly, so I install the merged file (although I should probably view the merged file first, and then install it).

My biggest difficulty with sysmerge comes in differentiating my left and my right. Worse, the L key is on the right side, and the R key is on the left. (Go ahead now, laugh, but just wait until you mix that up.)

When sysmerge finishes installing the files, it checks the permissions on the /etc files, and tells you where to find the log and that the system might need a reboot. A purist might tell you that you don’t need to reboot, but usually you should go ahead and do it. Rebooting after changing core system files prevents a variety of problems, and rebooting as part of an upgrade isn’t unreasonable. You can wait to reboot until after you upgrade your packages, as long as everything works.

…
===> Comparison complete
===> Checking directory hierarchy permissions (running mtree(8))
===> Output log available at /var/tmp/sysmerge.daiHKukKfE/sysmerge.log
        *** WARNING: some new/updated file(s) may require a reboot
# reboot

You now have an updated OpenBSD base system. Be aware that new or changed files can change system behavior, but usually you won’t notice. The Upgrade Guide usually notes any changes average users are likely to notice. Still, only you know what your system does and how you want it to behave.

Upgrading your installed packages is a separate task.