OpenBSD Upgrade Guide: 6.3 to 6.4

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.

Start by performing the pre-upgrade steps. Next, boot from the install kernel, bsd.rd: use bootable install media, or place the 6.4 version of bsd.rd in the root of your filesystem and instruct the boot loader to boot this kernel. Once this kernel is booted, choose the (U)pgrade option and follow the prompts. Apply the configuration changes and finish up by upgrading the packages: pkg_add -u.

Alternatively, you can use the manual upgrade process.

You may wish to check the errata page or upgrade to the stable branch to get any post-release fixes.

Before rebooting into the install kernel

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

bsd.rd

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

SHA256.sig

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

Verify them using signify(1):
```
  $ signify -C -p /etc/signify/openbsd-64-base.pub -x SHA256.sig bsd.rd
  Signature Verified
  bsd.rd: OK
```
Read configuration and syntax changes. There were several configuration changes that may require planning before starting the upgrade, most notably bgpd.conf(5), pf.conf(5) and smtpd.conf(5). Moreover, rtadvd(8) was replaced with the new rad(8).
_rad reuses the _btd uid/gid. The new _rad user recycles the user and group ids of the "Bluetooth Daemon" user (_btd) which was removed in 2013. If you upgraded your system from all the way back then and never deleted the user and group, delete them:
```
  # userdel _btd
  # groupdel _btd
```
If you do not delete them before upgrading, sysmerge(8) will fail and will need to be re-run manually after deleting them.

Configuration and syntax changes

audio recording. Due to privacy concerns, audio recording has been disabled by default. It may be re-enabled system wide:
```
  # sysctl kern.audio.record=1 # enable at runtime
  # echo kern.audio.record=1 >> /etc/sysctl.conf # set at boot
```
Finer-grained controls are available using mixerctl(1): for each mixer device, record.enable can be set to off (always off), on (always on), or sysctl (default: follow state of the kern.audio.record sysctl).
bgpd.conf(5): Without explicit policy configuration, bgpd(8) will deny both incoming and outgoing UPDATES. See RFC 8212 for more information.
The following configuration directives are deprecated (but will be accepted for backwards compatibility): announce all, announce none, and announce default-route. Furthermore, the announce self directive was removed. Explicit use of announce self will result in a syntax error preventing bgpd(8) from starting. Users are advised to review and update /etc/bgpd.conf before upgrading.
It is possible to write configuration files that are valid and functionally the same both before and after the update.
Before updating:
1. Mimic the new behavior of the updated bgpd(8) by adding deny from any and deny to any to the top of the filter ruleset. (After the update these rules are implicitly added to the filter)
2. Replace all instances of announce self with announce all.
3. Ensure that the filter ruleset only allows correct announcements to and from EBGP neighbors by explicitly specifying the prefixes to be imported from and exported to EBGP neighbors using prefix-set and large-community (or community).
4. Add announce all to all neighbors for which neither announce none nor announce default-route is specified (the implicit default for EBGP peers was announce self). You can confirm that you haven't missed any:
```
  # bgpd -nvf /etc/bgpd.conf | grep -B4 'announce self'
```
The resulting config should now be ready for the upgrade. It is recommended to review /etc/examples/bgpd.conf for an example how BGP communities and prefix-set can be used in simple network designs.
After updating:
1. Remove all announce all directives from the configuration.
2. The deny from any and deny to any rules at the top of the ruleset filter are redundant after the update (and as such could be removed), but leaving those may improve readability of the configuration.
hostname.if(5) and wpakey. The ifconfig(8) utility encourages users of the wpakey keyword to use it on the same line as any join or nwid keywords. In particular, hostname.if(5) file should be adjusted:
```
  nwid mynwid wpakey mywpakey
```
httpd.conf(5): meaning of listen on * port 80 changed. The meaning of listen on * port 80 changed from "listen on all IPv4 addresses" to "listen on all IPv4 and all IPv6 addresses". If listen on * port 80 is present, listen on :: port 80 needs to be removed. For example,
```
  listen on * port 80
  listen on :: port 80
```
must be changed to:
```
  listen on * port 80
```
httpd.conf(5): root strip option renamed. To be semantically correct, the root strip option has been renamed to request strip. For example, the following configuration block is needed for acme-client(1):
```
  location "/.well-known/acme-challenge/*" {
	root "/acme"
	request strip 2
  }
```
installurl(5): OpenBSD has a new CDN for packages, syspatches, and other downloads. If you want to make of use of it, replace your current installurl(5) file like so:
```
  # echo "https://cdn.openbsd.org/pub/OpenBSD" > /etc/installurl
```
nsd(8): control socket moved from TCP/IP to unix domain socket. If nsd(8) is started with the old config file and then the config file is changed to use the unix domain socket, rc(8) and rcctl(8) cannot restart nsd since they try to communicate over the unix domain socket while nsd(8) still uses TCP/IP. In that case kill nsd(8) and start it again. One way to end up in this situation is when sysmerge needs to be run by hand.
pf.conf(5): error on invalid queue definitions. PF queues can only refer to a single interface, not an interface group. Previously, the pf.conf(5) parser accepted invalid queue definitions (either for an interface group, or for a non-existent interface) and mostly ignored them, though gave an error when displaying queues. These are now rejected and result in the entire ruleset failing to load.
Before updating, use pfctl -s queue. If you have no output or a list of queues, you should not be affected by this. If you see the following error, adjust your pf.conf(5) accordingly:
```
  # pfctl -s queue
  pfctl: DIOCGETQSTATS: Bad file descriptor
```
Normally, you can just specify the relevant interface name, but if you are trying to use interface groups to allow use of the same pf.conf file on multiple systems which have different interface types, you might like to define macros in a separate file that can be different on each system (sharing a common pf.conf):
```
  $ cat /etc/pf.conf.local
  egress_if = ix0

  $ cat /etc/pf.conf
  include "/etc/pf.conf.local"
  queue rootq on $egress_if bandwidth 1G default

  [...]
```
relayd.conf(5): new log options. The log options log updates and log all in relayd.conf(5) have been superseded by three new options:
```
  log state changes
  log host checks
  log connection [errors]
```
The first two set the logging of host checks to either changes in host state only or all check results, and replace log updates and log all. The third option controls connection logging in relays which, until now, was a side effect of log updates. The optional errors will cause only failed connections to be logged.
Use of the old options will result in a warning message and they will be removed in OpenBSD 6.5.
route(8): error on bad -netmask or -prefixlen usage. If you have specified these options before the address string in hostname.if(5) or some script, route(8) will now print an error message and exit. Make sure to change
```
  route add -inet6 -prefixlen 56 2001:db8:: ::1 -blackhole
```
to
```
  route add -inet6 2001:db8:: -prefixlen 56 ::1 -blackhole
```
or, better yet, use CIDR notation:
```
  route add -inet6 2001:db8::/56 ::1 -blackhole
```
Previously, a route for 2001:db8::/64 would have been installed as the address string comes last for which a default prefix length of 64 was implied.
route(8): implicit prefix length removed. Unless -prefixlen or CIDR notation is used, route(8) no longer interprets an IPv6 address as /64 subnet.
Previously, a route with prefixlen 64 would be installed:
```
  # route add 2001:db8:: ::1
  add net 2001:db8::: gateway ::1
  # route show -inet6 | grep 2001:db8
  2001:db8::/64      localhost          UGS        0        0 32768     8 lo0
```
This behavior was deprecated in 2003 by RFC 3587. The route(8) utility now takes a host address as-is:
```
  2001:db8::         localhost          UGHS       0        0 32768     8 lo0
```
route(8): stricter network syntax. Support for guessing an old-style class A, B, or C netmask from a bare dot-notation IPv4 address by counting trailing zero octets was dropped from route(8), and related option parsing is now stricter. To specify a destination network, use any of the following syntaxes:
```
  route add [-net] 192.0.2.0/24 ...
  route add [-net] 192.0.2.0 -netmask 255.255.255.0 ...
  route add -inet [-net] 192.0.2.0 -prefixlen 24 ...
```
If neither -net nor -netmask nor -prefixlen is given, -host is now assumed.
rtadvd(8) removed; replaced by rad(8). rtadvd(8) has been removed from the base system. If you are running rtadvd(8) for IPv6 router advertisements, please switch to rad(8). First create a /etc/rad.conf configuration file. For example, if you had rtadvd_flags=em0 in /etc/rc.conf.local, /etc/rad.conf would be:
```
  interface em0
```
For more advanced configurations consult rad.conf(5). With the /etc/rad.conf file in place you can stop rtadvd(8) and start rad(8):
```
  # rcctl stop rtadvd
  # rcctl disable rtadvd
  # rcctl enable rad
  # rcctl start rad
```
smtpd.conf(5) grammar has changed in smtpd(8). The smtpd.conf(5) file needs to be adapted to use the new grammar.
The change is mostly mechanical and requires splitting current rules into actions and matching patterns, examples are available in the man page.
Authenticated users are no longer considered as local users, if your configuration file allows remote users to authenticate and send mail, an explicit rule must be written to match these.
smtpd(8) supported LMTP both as a relaying protocol and as a local delivery method. The local delivery method was implemented within the daemon and not as an MDA, it no longer does and must be used through the 'mda' action:
```
  action lmtp-local mda "/usr/libexec/mail.lmtp [...]"
```
The mail.lmtp(8) MDA provides all the features that used to be supported internally by smtpd(8).
smtpd.conf(5): LMTP action introduced. With the recent grammar change, LMTP support was re-implemented as an external mail delivery agent and required being configured using the 'mda' action:
```
  action lmtp-local mda "/usr/libexec/mail.lmtp [...]"
```
The grammar has been extended to provide an LMTP action hiding the details behind the mail.lmtp(8) MDA. The LMTP action is documented in smtpd.conf(5) and looks as follow:
```
  action lmtp-local lmtp localhost:25
```
In addition, the unix: and inet: prefixes which were used in LMTP destinations to distinguish between a UNIX socket or a network socket have been removed.
smtpd.conf(5): set and limit removed as main keywords. The grammar allowed setting options of components with the set keyword:
```
  set queue compression
  set mta max-deferred 100
```
The keyword brought no value and was dropped in favor of component namespaces:
```
  queue compression
  mta max-deferred 100
```
In addition, the limit option which could be used with mta:
```
  limit mta session-transaction-delay 0
```
is now an option within the mta namespace:
```
  mta limit session-transaction-delay 0
```
smtpd.conf(5): relay host syntax changed. The syntax for the smarthost string in relay rules has been updated. It is documented in smtpd.conf(5). The changes are as follows:
- the +auth specifier has been removed: it is implied by the presence of an auth label in the rest of the string.
- secure:// has been removed: use smtp+tls:// or smtps:// explicitly.
- tls:// has been replaced by smtp+tls://.
- smtp:// becomes SMTP with opportunistic STARTTLS: use smtp+notls:// to disable TLS.
- smtp+tls:// becomes SMTP with mandatory STARTTLS: use smtp:// for opportunistic STARTTLS.
Running smtpd(8) without updating the configuration will result in mails being stuck in the queue if the smarthost string is not recognized, or mails being relayed with TLS instead of plain text, for non-updated smtp:// and smtp+tls:// relays.
sndio(7): session cookie path changed. The new sndio(7) session cookie path is ~/.sndio/cookie. If you allow access to your audio/MIDI hardware to other users or to remote systems, you may want to move your authorization cookie to the new location:
```
  $ mkdir -p ~/.sndio
  $ mv ~/.aucat_cookie ~/.sndio/cookie
```
This is probably simpler than deleting the old cookie, generating a new one and installing it to all appropriate locations.

Files to remove

Remove /dev/audio and /dev/audioctl. The /dev/audio and /dev/audioctl symbolic links are not used anymore and can be removed:

  rm /dev/audio /dev/audioctl

Remove rtadvd(8):

  rm /etc/rc.d/rtadvd /usr/sbin/rtadvd /usr/share/man/man5/rtadvd.conf.5 /usr/share/man/man8/rtadvd.8

Remove the _rtadvd user and group:

  userdel _rtadvd
  groupdel _rtadvd

As part of the update to xcb 1.13, two obsolete libxcb components (xevie and xprint) have been removed. The corresponding files can be removed:

  rm /usr/X11R6/lib/libxcb-xevie.*
  rm /usr/X11R6/lib/libxcb-xprint.*
  rm /usr/X11R6/lib/pkgconfig/xcb-xevie.pc
  rm /usr/X11R6/lib/pkgconfig/xcb-xprint.pc

Special packages

buildbot/buildslave. Both, buildbot and buildbot-worker are now using python3.
Upstream renamed buildslave to buildbot-worker a while ago. Accordingly, the buildslave rc script was renamed to buildbot_worker. You need to adjust the list of daemons:
```
  # rcctl disable buildslave
  # rcctl enable buildbot_worker
```
Make sure to stop any running buildslave instances before upgrading, otherwise rc.d(8) will lose track of the process.
PHP default version changed. With a few exceptions, most packages using PHP have switched to using PHP 7.0 dependencies by default. Because extension modules (now including PECL modules) are packaged for multiple PHP versions, most existing PHP programs will work as-is, but to avoid confusion and benefit from improvements to PHP you should switch your system across:
1. Merge local configuration changes from /etc/php-5.6.ini to /etc/php-7.0.ini. It may be useful to diff(1) against the original file in /usr/local/share/examples/php-5.6/php.ini-production.
2. Create new symlinks for extension modules as described in the "extension modules" section of /usr/local/share/doc/pkg-readmes/php-7.0*.
3. Switch to running the new version. If using php-fpm:
```
    # rcctl disable php56_fpm; rcctl enable php70_fpm
    # rcctl stop php56_fpm; rcctl start php70_fpm
```
  If using the module for Apache httpd, update the symlink for /var/www/conf/modules/php.conf as shown in the pkg-readme.
PHP packaging changes. The PHP module for Apache httpd has moved from the main PHP package into a separate "php-apache" package, and the PHP extensions for SQLite have moved into separate "php-sqlite3" and "php-pdo_sqlite" packages. If you use these, install the relevant package (e.g. pkg_add php-apache%7.0, pkg_add php-sqlite3%7.0, pkg_add php-pdo_sqlite%7.0 or similar for 5.6). For the SQLite extensions, create symbolic links to enable the modules as shown in the pkg-readme. FPM and CLI remain in the main PHP package.
security/kc storage format change. The storage format of keychains has changed in a backward incompatible way. Dump all your keychains to XML before updating:
```
  $ kc -k ~/.kc/default.kcd
  Password:
  <example_chain% > dump kcdump
  Dump OK
  <example_chain% > quit
```
After updating follow the instructions in /usr/local/share/doc/kc/Changelog.
sysutils/apcupsd has SMTP client removed. The ${PREFIX}/sbin/smtp was removed from apcupsd package in favor of smtp(1). The programs are not option-compatible, so any scripts using an smtp command require adjustment.
www/sogo updated to 4.x. SOGo has been updated to version 4.0.2. A database upgrade is needed for the software to work properly. Follow the instructions on ${PREFIX}/share/doc/pkg-readmes/sogo

Upgrade without the install kernel

This is NOT the recommended process. Use the install kernel method if at all possible!

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 base64.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 xshare64.tgz
    tar -C / -xzphf xserv64.tgz
    tar -C / -xzphf xfont64.tgz
    tar -C / -xzphf xbase64.tgz
    tar -C / -xzphf man64.tgz
    tar -C / -xzphf game64.tgz
    tar -C / -xzphf comp64.tgz
    tar -C / -xzphf base64.tgz    # Install last!
    /sbin/oreboot

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

    cp /sbin/reboot /sbin/oreboot
    for _f in [!b]*64.tgz base64.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.2 -> 6.3] [6.4 -> 6.5]

$OpenBSD: upgrade64.html,v 1.18 2021/03/15 10:18:43 jsg Exp $