OpenBSD Upgrade Guide: 6.5 to 6.6

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

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.

Alternatively, a new unattended upgrade method has been introduced. The sysupgrade(8) program is available as a syspatch(8) for OpenBSD 6.5 on the i386, amd64, and arm64 platforms. Once installed, the upgrade can be performed by running sysupgrade.

Another option is using the manual upgrade process (although this is not recommended).

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 rebooting into the install kernel

• 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.

• Get and verify bsd.rd. Download the ramdisk kernel and the cryptographically signed checksum file for your architecture.

  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-66-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

• acme-client(1). acme-client(1) has been updated to implement the recently published RFC 8555. Users must change the api url in /etc/acme-client.conf from

    https://acme-v01.api.letsencrypt.org/directory

  to

    https://acme-v02.api.letsencrypt.org/directory

  The staging api url should also be changed from

    https://acme-staging.api.letsencrypt.org/directory

  to

    https://acme-staging-v02.api.letsencrypt.org/directory

  The -A and -D flags have been removed from acme-client(1). The private keys are now created automatically if missing. If you were using either of these flags on your regular command lines, remove them.

• bgpctl(8). The bgpctl(8) irrfilter command has been removed. People interested in generating prefix- and as-sets from IRR data should use bgpq3 from ports.

• bgpd(8). The config keyword route-collector is deprecated and will cause bgpd(8) to fail parsing the config. Instead disable the route evaluation process on the Loc-RIB with

    rde rib Loc-RIB no evaluate

• bootloader for OpenBSD/octeon. OpenBSD/octeon now comes with a bootloader. U-Boot must be configured to load the file boot instead of bsd. For example, the following kernel launch command

    fatload usb 0 ${loadaddr} bsd; bootoctlinux rootdev=8e309909c27040dd numcores=4

  would need to change to

    fatload usb 0 ${loadaddr} boot; bootoctlinux rootdev=8e309909c27040dd numcores=4

  See INSTALL.octeon for the details on how to configure U-Boot. (Search for "OpenBSD/octeon bootloader").

• doas(1). The environment variable handling in doas(1) has been changed. In particular HOME and PATH are now reset to the target user.

• IPv6 link-local address change. It has been discovered that some hosting providers route customer IPv6 prefixes to link-local addresses derived from Ethernet MAC addresses (RFC 2464). This leads to hard to debug IPv6 connectivity issues with the RFC 7217-style random but stable link-local addresses that OpenBSD used. Link-local addresses are again formed from Ethernet MAC addresses.

• vmctl(8). The order of the arguments in the create, start, and stop commands of vmctl(8) has been changed to match a commonly expected style. Manual usage or scripting with vmctl must be adjusted to use the new syntax. For example, the old syntax looked like this:

    # vmctl create disk.qcow2 -s 50G

  The new syntax specifies the command options before the argument:

    # vmctl create -s 50G disk.qcow2

Files to remove

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

    rm -f /usr/share/man/man3p/carp.3p \
          /usr/share/man/man3p/Tie::ExtraHash.3p \
          /usr/share/man/man3p/Tie::StdHash.3p \
          /usr/share/man/man3p/Tie::StdScalar.3p \
          /usr/share/man/man3p/basename.3p \
          /usr/share/man/man3p/cluck.3p \
          /usr/share/man/man3p/confess.3p \
          /usr/share/man/man3p/croak.3p \
          /usr/share/man/man3p/dirname.3p \
          /usr/share/man/man3p/fileparse.3p \
          /usr/share/man/man3p/getopt.3p \
          /usr/share/man/man3p/getopts.3p \
          /usr/share/man/man3p/inet_aton.3p \
          /usr/share/man/man3p/inet_ntoa.3p \
          /usr/share/man/man3p/longmess.3p \
          /usr/share/man/man3p/look.3p \
          /usr/share/man/man3p/open2.3p \
          /usr/share/man/man3p/open3.3p \
          /usr/share/man/man3p/pod2usage.3p \
          /usr/share/man/man3p/podchecker.3p \
          /usr/share/man/man3p/podselect.3p \
          /usr/share/man/man3p/shortmess.3p \
          /usr/share/man/man3p/sockaddr_in.3p \
          /usr/share/man/man3p/sockaddr_un.3p \
          /usr/share/man/man3p/writemain.3p

• snmpctl(8) has been retired

    rm -f /usr/sbin/snmpctl \
          /usr/share/man/man8/snmpctl.8

• Remove files associated with client use of the X Font Service:

    rm -f /usr/X11R6/lib/pkgconfig/libfs.pc \
          /usr/X11R6/include/X11/fonts/FSlib.h
       rm -rf  /usr/X11R6/share/doc/libFS

• xman(1) has been retired

    rm -f /usr/X11R6/bin/xman \
          /usr/X11R6/lib/X11/xman.help \
          /usr/X11R6/man/man1/xman.1 \
          /usr/X11R6/share/X11/app-defaults/Xman

• Remove files associated with retired X11 drivers and man pages:

    rm -f /usr/X11R6/lib/pkgconfig/libfs.pc \
          /usr/X11R6/lib/modules/v10002d.uc \
          /usr/X11R6/lib/modules/v20002d.uc \
          /usr/X11R6/lib/modules/drivers/ark_drv.la \
          /usr/X11R6/lib/modules/drivers/ark_drv.so \
          /usr/X11R6/lib/modules/drivers/chips_drv.la \
          /usr/X11R6/lib/modules/drivers/chips_drv.so \
          /usr/X11R6/lib/modules/drivers/glint_drv.la \
          /usr/X11R6/lib/modules/drivers/glint_drv.so \
          /usr/X11R6/lib/modules/drivers/i128_drv.la \
          /usr/X11R6/lib/modules/drivers/i128_drv.so \
          /usr/X11R6/lib/modules/drivers/neomagic_drv.la \
          /usr/X11R6/lib/modules/drivers/neomagic_drv.so \
          /usr/X11R6/lib/modules/drivers/rendition_drv.la \
          /usr/X11R6/lib/modules/drivers/rendition_drv.so \
          /usr/X11R6/lib/modules/drivers/s3_drv.la \
          /usr/X11R6/lib/modules/drivers/s3_drv.so \
          /usr/X11R6/lib/modules/drivers/s3virge_drv.la \
          /usr/X11R6/lib/modules/drivers/s3virge_drv.so \
          /usr/X11R6/lib/modules/drivers/sis_drv.la \
          /usr/X11R6/lib/modules/drivers/sis_drv.so \
          /usr/X11R6/lib/modules/drivers/tdfx_drv.la \
          /usr/X11R6/lib/modules/drivers/tdfx_drv.so \
          /usr/X11R6/lib/modules/drivers/trident_drv.la \
          /usr/X11R6/lib/modules/drivers/trident_drv.so \
          /usr/X11R6/lib/modules/drivers/tseng_drv.la \
          /usr/X11R6/lib/modules/drivers/tseng_drv.so \
          /usr/X11R6/man/man4/chips.4 \
          /usr/X11R6/man/man4/glint.4 \
          /usr/X11R6/man/man4/i128.4 \
          /usr/X11R6/man/man4/neomagic.4 \
          /usr/X11R6/man/man4/rendition.4 \
          /usr/X11R6/man/man4/s3.4 \
          /usr/X11R6/man/man4/s3virge.4 \
          /usr/X11R6/man/man4/sis.4 \
          /usr/X11R6/man/man4/tdfx.4 \
          /usr/X11R6/man/man4/trident.4 \
          /usr/X11R6/man/man4/tseng.4 \
          /usr/X11R6/man/man3/XkbAllocGeomOverlayKey.3

• Remove retired include files:

    rm -f /usr/X11R6/include/X11/fonts/FSlib.h \
          /usr/include/dev/ic/dwc_gmac_reg.h \
          /usr/include/dev/ic/dwc_gmac_var.h \
          /usr/include/llvm/Analysis/IndirectCallSiteVisitor.h \
          /usr/include/llvm/CodeGen/GCs.h \
          /usr/include/llvm/DebugInfo/PDB/Native/NativeBuiltinSymbol.h \
          /usr/include/llvm/DebugInfo/PDB/Native/NativeEnumSymbol.h \
          /usr/include/llvm/IR/TypeBuilder.h \
          /usr/include/llvm/Transforms/Utils/OrderedInstructions.h

• Remove other retired man pages:

    rm -f /usr/share/man/man1/clang++.1 \
          /usr/share/man/man1/clang-cpp.1 \
          /usr/share/man/man1/diagnostics.1 \
          /usr/share/man/man3/SipHash24.3 \
          /usr/share/man/man3/bitstring.3 \
          /usr/share/man/man3/byteorder.3 \
          /usr/share/man/man3/directory.3 \
          /usr/share/man/man3/ethers.3 \
          /usr/share/man/man3/exec.3 \
          /usr/share/man/man3/fts.3 \
          /usr/share/man/man3/getcap.3 \
          /usr/share/man/man3/inet_net.3 \
          /usr/share/man/man3/md5.3 \
          /usr/share/man/man3/pcap-filter.3 \
          /usr/share/man/man3/pcap.3 \
          /usr/share/man/man3/pwcache.3 \
          /usr/share/man/man3/resolver.3 \
          /usr/share/man/man3/rmd160.3 \
          /usr/share/man/man3/sha1.3 \
          /usr/share/man/man3/sha2.3 \
          /usr/share/man/man3/stdarg.3 \
          /usr/share/man/man3/uucplock.3 \
          /usr/share/man/man3/uuid.3 \
          /usr/share/man/man3/ypclnt.3 \
          /usr/share/man/man4/i386/vmm.4 \
          /usr/share/man/man4/macppc/openprom.4 \
          /usr/share/man/man4/sparc64/openprom.4

Special packages

• databases/mariadb. MariaDB was upgraded to the 10.3 branch. Due to changes in redo logs, ensure that your previous version was shut down cleanly before upgrading. The /etc/my.cnf option innodb_additional_mem_pool_size, found in some old default configurations, is no longer supported — remove it if present. If the new version fails to start, review /var/mysql/(hostname).err. As usual, run mysql_upgrade(1) after the update.

• databases/postgresql. Default rc.d(8) flags for databases/postgresql have been changed from:

    daemon_flags="-w -l /var/postgresql/logfile"

  to

    daemon_flags="-D /var/postgresql/data -w -l /var/postgresql/logfile"

  If you defined postgresql_flags in /etc/rc.conf.local make sure that your entry includes -D /var/postgresql/data.

• games/gzdoom. gzdoom was updated to 4.1.2 which is incompatible with previously saved games. There is no upstream solution.

• mail/courier-imap. Full UTF-8 support has been enabled for courier-imap. If you are using imap folders with UTF-8 names you should check and/or convert them using the maildirmake(1) --checkutf8 and --convutf8 options.

• mail/rss2email. rss2email has been updated to a new major version with incompatible configuration. Before updating, save your feed list:

    r2e list > ~/r2e.txt
    r2e opmlexport > ~/r2e.opml

  After updating, see the notes in /usr/local/share/pkg-readmes/rss2email.

• net/exabgp. exabgp has been upgraded to a new major version (4.1.2) and configurations will need changing. See https://github.com/Exa-Networks/exabgp/wiki/Migration-from-3.4-to-4.0 for details.

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 and 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 base66.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 xshare66.tgz
      tar -C / -xzphf xserv66.tgz
      tar -C / -xzphf xfont66.tgz
      tar -C / -xzphf xbase66.tgz
      tar -C / -xzphf man66.tgz
      tar -C / -xzphf game66.tgz
      tar -C / -xzphf comp66.tgz
      tar -C / -xzphf base66.tgz    # Install last!
      /sbin/oreboot

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

      cp /sbin/reboot /sbin/oreboot
      for _f in [!b]*66.tgz base66.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.4 -> 6.5] [6.6 -> 6.7]