OpenBSD Upgrade Guide: 6.6 to 6.7

[FAQ Index] | [6.5 -> 6.6] [6.7 -> 6.8]

Upgrades are only supported from one release to the release immediately following it.

Read through and understand this process before attempting it. For critical or physically remote machines, test it on an identical, local system first.

An unattended upgrade method was introduced in version 6.6 which provides the simplest method for performing this upgrade. The sysupgrade(8) program will download all install sets, verify their signatures, and reboot to do the upgrade. Using this method means sysupgrade does the download and verification of bsd.rd for you.

Another option is using the manual upgrade process (although this is not recommended and is the most error-prone method).

After upgrading the sets, apply the configuration changes and remove the old files. Finish up by upgrading the packages: pkg_add -u.

You may wish to check the errata page for any post-release fixes.

Before using any upgrade method

• Check diskspace of /usr. Verify that the /usr partition has a size of at least 1.1G. With less space the upgrade may fail and you should consider reinstalling the system instead.

• rpki-client(8). The new _rpki-client user recycles the user and group ids of the "named" daemon user (named, uid/gid 70) which was removed in 2014. If you have kept upgrading your system from that time and never deleted the user and group, delete them and the /var/named directory:

    # userdel named
    # groupdel named
    # rm -rf /var/named  # backup the data if still needed

  If you do not delete them before upgrading, sysmerge(8) will fail and will need to be re-run manually after deleting them.

Before rebooting into the install kernel

• Get and verify bsd.rd. Download the ramdisk kernel and the cryptographically signed checksum file for your architecture. (This may be skipped if using sysupgrade(8) since it verifies downloaded files).

  bsd.rd

  [alpha] [amd64] [arm64] [armv7] [hppa] [i386] [landisk] [loongson] [luna88k] [macppc] [octeon] [sparc64]

  SHA256.sig

  [alpha] [amd64] [arm64] [armv7] [hppa] [i386] [landisk] [loongson] [luna88k] [macppc] [octeon] [sparc64]

  Verify them using signify(1):

    $ signify -C -p /etc/signify/openbsd-67-base.pub -x SHA256.sig bsd.rd
    Signature Verified
    bsd.rd: OK

• Read configuration and syntax changes and the package upgrade instructions. There were several configuration changes and changes in packages that may require planning before starting the upgrade.

Configuration and syntax changes

• audio(4)/midi(4). Regular users cannot access /dev/audio* and /dev/rmidi* devices any longer. Regular users must use the sndioctl(1) utility in place of mixerctl(8) to adjust the volume, for instance:

    $ sndioctl output.level=0.5

  As access to MIDI devices is now provided by sndiod(8), programs must use midi/N instead of rmidi/N as MIDI port names.

  Note that audio devices continue to be configured with mixerctl(8) as sndioctl(1) doesn't expose all audio device controls. Furthermore, sndioctl(1) is not intended to be run as root.

  Accordingly, the /dev/mixer* devices are no longer used.

• iked(8). iked(8) no longer automatically blocks unencrypted outbound IPv6 packets. This feature was intended to avoid accidental leakage, but in practice was found to mostly be a cause of misconfiguration. Instead, if you would like to explicitly block these packets, add the following line to /etc/ipsec.conf (not iked.conf):

    flow esp out from ::/0 to ::/0 type deny

  and enable loading it with:

    # rcctl enable ipsec           # to load at boot
    # ipsecctl -f /etc/ipsec.conf  # to load immediately

  If you previously used iked(8)'s -6 flag to disable this feature, it is no longer needed and should be removed from /etc/rc.conf.local if used.

• iked(8)/isakmpd(8). The type of incoming ipsec(4) flows installed by iked(8) or isakmpd(8) was changed from "use" to "require". This means unencrypted traffic matching the flows will no longer be accepted. Flows of type "use" can still be set up manually in ipsec.conf(5).

• ip(4)/ip6(4). Packets with a destination address not matching an IP address of the receiving interface will now be dropped unless IP forwarding is enabled. IP forwarding can be enabled via sysctl.conf(5):

    net.inet.ip.forwarding=1
    net.inet6.ip6.forwarding=1

  Note that when forwarding is enabled, all local IP addresses can be reached from outside unless explicitly filtered with pf(4).

• man.conf(5). The man.conf(5) _whatdb directive is no longer supported. If you have an /etc/man.conf file, change lines of the form:

    _whatdb /usr/share/man/whatis.db

  to this form:

    manpath /usr/share/man

  The _whatdb directive has been obsolete since 2015.

• npppd(8). Support for using tun(4) as an access concentrator with npppd(8) has been removed. This functionality has been moved into a dedicated pppac(4) network interface driver. To migrate to the new driver, replace use of the tun interfaces in npppd.conf(5) with pppac.

• rebound(8). rebound(8) has been removed. Users are advised to consider alternatives such as unwind(8).

• unwind(8). asr has been renamed to stub in unwind.conf(5)

  unwind(8) no longer uses http to detect captive portals. Existing captive portal sections must be removed from unwind.conf(5)

• usb(4)/uhid(4). The default permissions of the usb(4) and uhid(4) device nodes have been changed by restricting read-write access to the root user.

  Access to FIDO/U2F security keys is now provided by the fido(4) driver instead of uhid(4). Programs must use /dev/fido/N instead of /dev/uhidN for U2F/FIDO.

• weekly(8). TMPDIR is no longer propagated for locate.updatedb in weekly(8). Custom TMPDIR values for locate.updatedb set in root crontab or /etc/weekly.local should be moved into /etc/locate.rc.

Files to remove

• Remove files no longer included in the current release of perl(1):

  # rm -rf /usr/libdata/perl5/*/Storable \
         /usr/libdata/perl5/*/arybase.pm \
         /usr/libdata/perl5/*/auto/arybase \
         /usr/libdata/perl5/B/Debug.pm \
         /usr/libdata/perl5/Locale/{Codes,Country,Currency,Language,Script}* \
         /usr/libdata/perl5/Math/BigInt/CalcEmu.pm \
         /usr/libdata/perl5/unicore/To/_PerlWB.pl \
         /usr/libdata/perl5/unicore/lib/GCB/EB.pl \
         /usr/libdata/perl5/unicore/lib/GCB/GAZ.pl \
         /usr/share/man/man3p/B::Debug.3p \
         /usr/share/man/man3p/Locale::{Codes*,Country,Currency,Language,Script}.3p \
         /usr/share/man/man3p/Math::BigInt::CalcEmu.3p \
         /usr/share/man/man3p/arybase.3p

• dig(1), host(1), and nslookup(1) have been moved to /usr/bin so the old binaries should be removed.

    # rm -f /usr/sbin/{dig,host,nslookup}

Special packages

• databases/postgresql. There was a major update to PostgreSQL 12.1. Use pg_upgrade as described in the pkg-readme file or do a dump/restore.

• databases/redis. Redis was updated to 5.0.9. Users should have no problem migrating from 4.0 to 5.0. A list of backward incompatible changes is at the end of the detailed release notes. Please note that the database is automatically upgraded on first run and cannot be read by older versions - take a backup first if you are concerned about compatibility.

• devel/ipython. Python 2 support has been retired. /usr/local/bin/ipython-3 has been renamed to /usr/local/bin/ipython.

• net/isc-bind. Current BIND versions insist that a writable "working directory" is available. A simple fix for upgrading users is to add directory "/tmp"; to the options section of named.conf. If you use relative paths in your configuration they will also need updating as directory is used as the base for these. All paths in named.conf are relative to the chroot directory, /var/named.

• net/powerdns. The update to PowerDNS Authoritative Server 4.3.0 requires a DB schema change. For details see the upgrade notes and /usr/local/share/doc/pdns.

• www/jupyter-notebook. Jupyter-notebook has been updated to 6.0.3, which dropped support for Python 2. Existing notebooks should be checked if they work with Python 3. Please note that tools supplied by this package have been renamed, e.g. jupyter-notebook-3 has been renamed to jupyter-notebook.

• www/mozilla-firefox. Previously, disabling pledge was done by modifying an entry in about:config but now it is done using files in /etc/firefox as explained in the pkg-readme file, /usr/local/share/doc/pkg-readmes/firefox. Unveil has been added to firefox to restrict filesystem access by default. To grant access to additional paths or disable unveil, see the pkg-readme file.

Upgrade without the install kernel

Sometimes, you need to do an upgrade of a machine for which the normal upgrade process is not possible. The most common case is a machine in a remote location where there is no easy access to the system console.

Preparation

• Place install files in a good location. Make sure you have sufficient space! Running out of space on a remote upgrade could be...unfortunate. Note that using softdeps can exaggerate the situation as deleted and overwritten files do not release their space immediately. Consider disabling the softdep mount option in /etc/fstab and rebooting before undertaking a manual upgrade. Having at least 500MB free on /usr would be recommended.

• Become root. While using doas(1) before each command is generally a good practice, the command will likely be broken by the last steps, so you should become root before starting this process. It might be good to verify your access to root using a method other than doas at this point, i.e., direct login or using su(1).

• Stop and/or disable any appropriate applications. During this process, all the userland applications will be replaced but may not be runnable, and strange things may happen as a result. You may also have issues with DNS resolution during the first reboot, so PF rules and NFS mounts dependent upon DNS may cause boot-up problems. There may be other applications which you wish to keep from running immediately after the upgrade; stop and disable them as well.

• Install new boot blocks. This should actually be done at the end of any upgrade. If this has been neglected, then failure to do this now may break serial console or other things, depending on your platform. Use installboot(8), assuming sd0 is your boot disk:

      installboot sd0

Upgrading manually

• Install new kernels. The extra steps for copying over the primary kernel are done to ensure that there is always a valid kernel on the disk.

  If using the multiprocessor kernel:

      cd /usr/rel    # where you put the release files
      ln -f /bsd /obsd && cp bsd.mp /nbsd && mv /nbsd /bsd
      cp bsd.rd /
      cp bsd /bsd.sp

  If using the single processor kernel:

      cd /usr/rel    # where you put the release files
      ln -f /bsd /obsd && cp bsd /nbsd && mv /nbsd /bsd
      cp bsd.rd bsd.mp /    # may give a harmless warning

• Enable KARL. Store the kernel's checksum:

      sha256 -h /var/db/kernel.SHA256 /bsd 

• Install new userland. Save a copy of reboot(8), extract and install the release tarballs, reboot. Install base67.tgz last, because the new base system, in particular tar(1), gzip(1) and reboot(8), will not work with the old kernel. Either untar the needed filesets manually:

      cp /sbin/reboot /sbin/oreboot
      tar -C / -xzphf xshare67.tgz
      tar -C / -xzphf xserv67.tgz
      tar -C / -xzphf xfont67.tgz
      tar -C / -xzphf xbase67.tgz
      tar -C / -xzphf man67.tgz
      tar -C / -xzphf game67.tgz
      tar -C / -xzphf comp67.tgz
      tar -C / -xzphf base67.tgz    # Install last!
      /sbin/oreboot

  or, if you use ksh(1), you can do:

      cp /sbin/reboot /sbin/oreboot
      for _f in [!b]*67.tgz base67.tgz; do tar -C / -xzphf "$_f" || break; done
      /sbin/oreboot

  Note that tar(1) can expand only one archive per invocation, so a simple glob won't work.

• After reboot, update /dev. Run MAKEDEV(8):

      cd /dev
      ./MAKEDEV all

• Update boot loader. Still assuming sd0 is your boot disk:

      installboot sd0

• Update system configuration files. Run sysmerge(8):

      sysmerge

• Update firmware. There may be new firmware for your system. Update it with fw_update(1):

      fw_update

• Finish up. Review the console output from boot (using dmesg -s) and correct any failures as necessary. All the steps following configuration changes above also apply to manual upgrades. Finally, remove /sbin/oreboot and update packages: pkg_add -u. Reboot once more to make sure you run on your own kernel generated by KARL.

[FAQ Index] | [6.5 -> 6.6] [6.7 -> 6.8]