Upgrade Guide: 6.1 to 6.2

[FAQ Index] | [6.0 -> 6.1] [6.2 -> 6.3]

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

clean out /usr/share/man. To remove all outdated manuals, issue rm -rf /usr/share/man.
ksh plaintext history file. The ksh(1) history file (used when $HISTFILE is set) changed from a binary file format to plaintext. If you wish to retain your current ksh history, create a plaintext version of it before upgrading:
```
  $ fc -ln 1 | cut -f2- > ~/ksh_hist.txt 
```
After the upgrade, you can use ksh_hist.txt as your history file.
If you mount HOME via NFS, ensure that machines running 6.2 use a different HISTFILE than machines running 6.1 or earlier.
breaking change for nvme(4) users with GPT. If you are booting from an nvme(4) drive with a GPT disk layout, you are affected by an off-by-one in the driver with the consequence that the sector count in your partition table may be incorrect. The only way to fix this is to re-initialize the partition table. Backup your data to another disk before you upgrade. In the new bsd.rd, drop to a shell and re-initialize the GPT:
```
  # fdisk -iy -g -b 960 sdN 
```
Then do a fresh install and restore the data from the backup.
resize /usr/obj. If you build your own releases on the amd64 or i386 platforms, you need to make sure that you have at least 3G available on /usr/obj.
adjust group ownership of existing at(1) jobs. The cron(8) daemon requires at(1) files in the spool to be owned by group crontab.
```
  # chgrp -R crontab /var/cron/atjobs 
```

Configuration and syntax changes

hostname.if. The keyword rtsol is no longer supported in hostname.if(5). Replace it with inet6 autoconf.
install.site. The execution of the {install,upgrade}.site scripts in bsd.rd is postponed to the end of the installer script. If you use this feature, make sure your script still works as expected. The script will now run after these steps:
- make underlying device nodes for softraid devices
- install the boot-block on disk
- switch to MP kernel on multi-processor systems
- update kernel.SHA256 and relink kernel
- prepare execution of sysmerge(8), fw_update(8) and syspatch(8) on reboot.
- prepare mail with response file to root/admin user
ifconfig. The vlan(4) and svlan(4) specific configuration options in ifconfig(8) and hostname.if(5) have been deprecated in favour of the generic parent and vnetid handling.
The vlan, vlandev, and -vlandev options are now deprecated in favour of vnetid, -vnetid, parent, and -parent when using ifconfig(8) or in hostname.if(5) configuration files. Use of the vlan option must be replaced with vnetid. Because VLAN tag 0 is invalid according to the relevant VLAN specifications, the vnetid option does not accept 0 as a valid network identifier. To use VLAN tag 0 on the wire the vnetid can be unconfigured with -vnetid. Use of vlandev and -vlandev must be replaced with parent and -parent respectively.
Unlike vlan and vlandev, vnetid and parent do not implicitly bring the vlan interface up. Similarly, the vlan option is no longer implied by the interface's minor when it is not explicitly set.
ifconfig(8) no longer outputs a vlan specific status line, or separate vnetid and parent lines. The vnetid and parent lines have been merged into a single encap line containing the VLAN tag and parent information.
An example of the changes to a vlan(4) configuration file and the ifconfig(8) output is below. Before the changes:
```
  # cat /etc/hostname.vlan7
  vlandev em0 # vlan 7 and up are implied
  lladdr random
  # ifconfig vlan7
  vlan7: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
          lladdr 70:a7:3a:75:da:2d
          index 7 priority 0 llprio 3
          vlan: 7 parent interface: em0
          vnetid: 7
          parent: em0
          status: active 
```
After the changes:
```
  # cat /etc/hostname.vlan7
  vnetid 7 parent em0
  up
  lladdr random
  # ifconfig vlan7
  vlan7: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
          lladdr 60:e8:d7:0d:10:6d
          index 7 priority 0 llprio 3
          encap: vnetid 7 parent: em0
          groups: vlan
          status: active 
```
ksh. The emacs-usemeta ksh(1) flag is no longer useful and has been deprecated. Please adjust your shell config files.
pf.conf: IPv6 options header blocked. IPv6 packets that have a hop-by-hop options header or a destination options header are now blocked by pf(4). Thus, IPv6 options are handled like their counterparts in IPv4. Add allow-opts to your rule if you want to pass IP packets with options.
pf.conf: icmp6-type notnbr-unr removed. Nearly 20 years ago RFC 1885 was obsoleted. Catch up by no longer supporting notnbr-unr (ICMP6_DST_UNREACH_NOTNEIGHBOR). The correct type is beyond-unr (ICMP6_DST_UNREACH_BEYONDSCOPE). In pf.conf(5), notnbr-unr needs to be replaced with beyond-unr.
smtpd.conf. The secure keyword is not valid anymore in listen directives in smtpd.conf(5). Users are advised to replace existing listen secure directives with two separate tls and smtps listeners, i.e., a line like
```
  listen on $iface secure pki $pki 
```
has to be replaced with
```
  listen on $iface tls pki $pki
  listen on $iface smtps pki $pki 
```
Relaying syntax is not affected by this change.
bgpd.conf. The softreconfig (in|out) (yes|no) neighbor setting has been removed in bgpd.conf(5). softreconfig can no longer be disabled. Remove the instruction from the configuration.

Special packages

beat. filebeat and packetbeat were updated to 5.3.1 which significantly changed the configuration file layout from 1.x to 5.x. Please refer to the upstream documentation for migrating your configuration. Also take note of the breaking changes when upgrading to 5.3.1.
topbeat has been merged into metricbeat, a migration path is available.
borgmatic. The configuration file changed from INI (/etc/borgmatic/config) to YAML (/etc/borgmatic/config.yaml) formatting. Please upgrade your existing config after updating your package:
```
  # upgrade-borgmatic-config 
```
cups. The CUPS binaries (lpr, lpq, lprm) are no longer symlinked into /usr/bin. If you want to use CUPS commands from the command line, you must now use the absolute path, e.g.:
```
  $ /usr/local/bin/lpq 
```
Running lpq without an absolute path would invoke the base lpq(1).
Similarly, to view a CUPS manual, you would use:
```
  $ man -m /usr/local/man lpq 
```
If you consistently use CUPS, you can add the following to your .kshrc to avoid the need to type an absolute path:
```
  for i in lpq lpr lprm; do alias $i=/usr/local/bin/$i; done 
```
zarafa. Zarafa was replaced with Kopano and a manual update of configuration files is needed. Please read the Kopano pkg-readme as well as the official migration guide and the migration quick start for more details.

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 base62.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 xshare62.tgz
    tar -C / -xzphf xserv62.tgz
    tar -C / -xzphf xfont62.tgz
    tar -C / -xzphf xbase62.tgz
    tar -C / -xzphf man62.tgz
    tar -C / -xzphf game62.tgz
    tar -C / -xzphf comp62.tgz
    tar -C / -xzphf base62.tgz    # Install last!
    /sbin/oreboot

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

    cp /sbin/reboot /sbin/oreboot
    for _f in [!b]*62.tgz base62.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.0 -> 6.1] [6.2 -> 6.3]

$OpenBSD: upgrade62.html,v 1.15 2026/03/10 10:23:28 sthen Exp $