File: [local] / www / faq / upgrade62.html (download) (as text)
Revision 1.14, Tue May 28 01:53:11 2019 UTC (5 years ago) by bentley
Branch: MAIN
CVS Tags: HEAD
Changes since 1.13: +2 -2 lines
Give FAQ pages their own HTML id, for future use.
|
<!doctype html>
<html lang=en id=faq>
<title>OpenBSD Upgrade Guide: 6.1 to 6.2</title>
<meta charset=utf-8>
<meta name="description" content="OpenBSD Upgrade Process for 6.1 -> 6.2">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="../openbsd.css">
<link rel="canonical" href="https://www.openbsd.org/faq/upgrade62.html">
<style>
ul { list-style: none; }
</style>
<h2 id=OpenBSD>
<a href="../index.html">
<i>Open</i><b>BSD</b></a>
Upgrade Guide: 6.1 to 6.2
</h2>
<hr>
<p>
<a href="index.html">[FAQ Index]</a> |
<a href="upgrade61.html">[6.0 -> 6.1]</a>
<a href="upgrade63.html">[6.2 -> 6.3]</a>
<p>
<blockquote><i>
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.
</i></blockquote>
Start by performing the <a href="#BeforeUpdate">pre-upgrade steps</a>.
Next, boot from the install kernel, <a href="faq4.html#bsd.rd">bsd.rd</a>:
use <a href="faq4.html#MkInsMedia">bootable install media</a>, or place the 6.2
version of <code>bsd.rd</code> in the root of your filesystem and instruct the boot
loader to boot this kernel.
Once this kernel is booted, choose the <code>(U)pgrade</code> option and follow the
prompts.
Apply the <a href="#ConfigChanges">configuration changes</a> and
<!-- <a href="#RmFiles">remove the old files</a>. -->
finish up by upgrading the packages: <code><b>pkg_add -u</b></code>.
<p>
Alternatively, you can use the <a href="#NoInstKern">manual upgrade process</a>.
<p>
You may wish to check the <a href="../errata62.html">errata page</a> or upgrade
to the <a href="../stable.html">stable branch</a> to get any post-release fixes.
<hr>
<h3 id="BeforeUpdate">Before rebooting into the install kernel</h3>
<ul>
<li><b>clean out <code>/usr/share/man</code>.</b>
To remove all outdated manuals, issue <code><b>rm -rf /usr/share/man</b></code>.
<p>
<li><b>ksh plaintext history file.</b>
The <a href="https://man.openbsd.org/OpenBSD-6.2/ksh">ksh(1)</a> history file
(used when <code>$HISTFILE</code> 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:
<blockquote><pre>
$ <b>fc -ln 1 | cut -f2- > ~/ksh_hist.txt</b> <!--
--></pre></blockquote>
After the upgrade, you can use <code>ksh_hist.txt</code> as your history file.
<p>
If you mount <code>HOME</code> via <code>NFS</code>, ensure that machines running
6.2 use a different <code>HISTFILE</code> than machines running 6.1 or earlier.
<p>
<li><b>breaking change for nvme(4) users with GPT.</b>
If you are booting from an <a href="https://man.openbsd.org/OpenBSD-6.2/nvme">nvme(4)</a>
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.
<a href="faq14.html#DupFS">Backup your data</a> to another disk
before you upgrade.
In the new <code>bsd.rd</code>, drop to a shell and re-initialize the GPT:
<blockquote><pre>
# <b>fdisk -iy -g -b 960 sdN</b> <!--
--></pre></blockquote>
Then do a fresh install and restore the data from the backup.
<p>
<li><b>resize <code>/usr/obj</code>.</b>
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 <code>/usr/obj</code>.
<p>
<li><b>adjust group ownership of existing at(1) jobs.</b>
The <a href="https://man.openbsd.org/OpenBSD-6.2/cron">cron(8)</a> daemon
requires <a href="https://man.openbsd.org/OpenBSD-6.2/at">at(1)</a> files
in the spool to be owned by group crontab.
<blockquote><pre>
# <b>chgrp -R crontab /var/cron/atjobs</b> <!--
--></pre></blockquote>
</ul>
<h3 id="ConfigChanges">Configuration and syntax changes</h3>
<ul>
<li><b>hostname.if.</b>
The keyword <code>rtsol</code> is no longer supported in
<a href="https://man.openbsd.org/OpenBSD-6.2/hostname.if">hostname.if(5)</a>.
Replace it with <code>inet6 autoconf</code>.
<p>
<li><b>install.site.</b>
The execution of the <code>{install,upgrade}.site</code> scripts in <code>bsd.rd</code>
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:
<ul>
<li>make underlying device nodes for softraid devices
<li>install the boot-block on disk
<li>switch to MP kernel on multi-processor systems
<li>update kernel.SHA256 and relink kernel
<li>prepare execution of
<a href="https://man.openbsd.org/OpenBSD-6.2/sysmerge">sysmerge(8)</a>,
<a href="https://man.openbsd.org/OpenBSD-6.2/fw_update">fw_update(8)</a> and
<a href="https://man.openbsd.org/OpenBSD-6.2/syspatch">syspatch(8)</a> on reboot.
<li>prepare mail with response file to root/admin user
</ul>
<p>
<li><b>ifconfig.</b>
The
<a href="https://man.openbsd.org/OpenBSD-6.2/vlan.4">vlan(4)</a> and
<a href="https://man.openbsd.org/OpenBSD-6.2/vlan.4">svlan(4)</a>
specific configuration options in
<a href="https://man.openbsd.org/OpenBSD-6.2/ifconfig.8">ifconfig(8)</a>
and
<a href="https://man.openbsd.org/OpenBSD-6.2/hostname.if.5">hostname.if(5)</a>
have been deprecated in favour of the generic parent and
vnetid handling.
<p>
The <code>vlan</code>, <code>vlandev</code>, and <code>-vlandev</code> options
are now deprecated in favour of <code>vnetid</code>, <code>-vnetid</code>,
<code>parent</code>, and <code>-parent</code> when using ifconfig(8) or
in hostname.if(5) configuration files.
Use of the <code>vlan</code> option must be replaced with <code>vnetid</code>.
Because VLAN tag 0 is invalid according to the relevant VLAN
specifications, the <code>vnetid</code> option does not accept 0 as a
valid network identifier.
To use VLAN tag 0 on the wire the vnetid can be unconfigured with
<code>-vnetid</code>.
Use of <code>vlandev</code> and <code>-vlandev</code> must be replaced with
<code>parent</code> and <code>-parent</code> respectively.
<p>
Unlike <code>vlan</code> and <code>vlandev</code>, <code>vnetid</code> and
<code>parent</code> do not implicitly bring the vlan interface up.
Similarly, the <code>vlan</code> option is no longer implied by the
interface's minor when it is not explicitly set.
<p>
<a href="https://man.openbsd.org/OpenBSD-6.2/ifconfig.8">ifconfig(8)</a>
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.
<p>An example of the changes to a vlan(4) configuration file and
the ifconfig(8) output is below. Before the changes:
<blockquote><pre>
# <b>cat /etc/hostname.vlan7</b>
vlandev em0 <em># vlan 7 and up are implied</em>
lladdr random
# <b>ifconfig vlan7</b>
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 <!--
--></pre></blockquote>
After the changes:
<blockquote><pre>
# <b>cat /etc/hostname.vlan7</b>
vnetid 7 parent em0
up
lladdr random
# <b>ifconfig vlan7</b>
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 <!--
--></pre></blockquote>
<p>
<li><b>ksh.</b>
The <code>emacs-usemeta</code>
<a href="https://man.openbsd.org/OpenBSD-6.2/ksh">ksh(1)</a> flag
is no longer useful and has been deprecated.
Please adjust your shell config files.
<p>
<li><b>pf.conf: IPv6 options header blocked.</b>
IPv6 packets that have a hop-by-hop options header or a destination options
header are now blocked by
<a href="https://man.openbsd.org/OpenBSD-6.2/pf">pf(4)</a>.
Thus, IPv6 options are handled like their counterparts in IPv4.
Add <code>allow-opts</code> to your rule if you want to pass IP packets
with options.
<p>
<li><b>pf.conf: icmp6-type notnbr-unr removed.</b>
Nearly 20 years ago RFC 1885 was obsoleted.
Catch up by no longer supporting notnbr-unr
(<code>ICMP6_DST_UNREACH_NOTNEIGHBOR</code>).
The correct type is beyond-unr (<code>ICMP6_DST_UNREACH_BEYONDSCOPE</code>).
In <a href="https://man.openbsd.org/OpenBSD-6.2/pf.conf">pf.conf(5)</a>,
<code>notnbr-unr</code> needs to be replaced with <code>beyond-unr</code>.
<p>
<li><b>smtpd.conf.</b>
The <code>secure</code> keyword is not valid anymore in <code>listen</code> directives
in <a href="https://man.openbsd.org/OpenBSD-6.2/smtpd.conf">smtpd.conf(5)</a>.
Users are advised to replace existing <code>listen secure</code> directives with
two separate <code>tls</code> and <code>smtps</code> listeners, i.e., a line like
<blockquote><pre>
listen on $iface secure pki $pki <!--
--></pre></blockquote>
has to be replaced with
<blockquote><pre>
listen on $iface tls pki $pki
listen on $iface smtps pki $pki <!--
--></pre></blockquote>
Relaying syntax is not affected by this change.
<p>
<li><b>bgpd.conf.</b>
The <code>softreconfig (in|out) (yes|no)</code> neighbor setting has been removed
in <a href="https://man.openbsd.org/OpenBSD-6.2/bgpd.conf">bgpd.conf(5)</a>.
<code>softreconfig</code> can no longer be disabled. Remove the instruction from
the configuration.
</ul>
<h3 id="SpecPkg">Special packages</h3>
<ul>
<li><b>beat.</b>
<code>filebeat</code> and <code>packetbeat</code> were updated to 5.3.1 which
significantly changed the configuration file layout from 1.x to 5.x.
Please refer to the
<a href="https://www.elastic.co/guide/en/beats/libbeat/5.0/upgrading-1-to-5.html">upstream documentation</a>
for migrating your configuration.
Also take note of the
<a href="https://www.elastic.co/guide/en/beats/libbeat/5.0/release-notes-5.0.0.html">breaking changes</a>
when upgrading to 5.3.1.
<br>
<code>topbeat</code> has been merged into <code>metricbeat</code>, a
<a href="https://www.elastic.co/guide/en/beats/libbeat/current/upgrading-1-to-5.html#_upgrading_topbeat_to_metricbeat">
migration path</a> is available.
<p>
<li><b>borgmatic.</b>
The configuration file changed from INI (<code>/etc/borgmatic/config</code>)
to YAML (<code>/etc/borgmatic/config.yaml</code>) formatting. Please
upgrade your existing config after updating your package:
<blockquote><pre>
# <b>upgrade-borgmatic-config</b> <!--
--></pre></blockquote>
<p>
<li><b>cups.</b>
The CUPS binaries (<code>lpr</code>, <code>lpq</code>, <code>lprm</code>) are no longer
symlinked into <code>/usr/bin</code>.
If you want to use CUPS commands from the command line, you must now use the
absolute path, e.g.:
<blockquote><pre>
$ <b>/usr/local/bin/lpq</b> <!--
--></pre></blockquote>
Running <code>lpq</code> without an absolute path would invoke the base
<a href="https://man.openbsd.org/OpenBSD-6.2/lpq">lpq(1)</a>.
<p>
Similarly, to view a CUPS manual, you would use:
<blockquote><pre>
$ <b>man -m /usr/local/man lpq</b> <!--
--></pre></blockquote>
If you consistently use CUPS, you can add the following to your
<code>.kshrc</code> to avoid the need to type an absolute path:
<blockquote><pre>
for i in lpq lpr lprm; do alias $i=/usr/local/bin/$i; done <!--
--></pre></blockquote>
<p>
<li><b>zarafa.</b>
Zarafa was replaced with Kopano and a manual update of configuration files
is needed.
Please read the Kopano
<a href="https://cvsweb.openbsd.org/ports/mail/kopano/core/pkg/README-main?rev=1.1">
pkg-readme</a> as well as the official
<a href="https://documentation.kopano.io/kopano_migration_manual/zcp_migration.html">
migration guide</a> and the
<a href="https://kb.kopano.io/display/WIKI/Migration+Quick+Start-Guide+-+ZCP+to+Kopano+Core">
migration quick start</a> for more details.
</ul>
<hr>
<h2 id="NoInstKern">Upgrade without the install kernel</h2>
<b style="color:#e00000">This is NOT the recommended process.
Use the install kernel method if at all possible!</b>
<p>
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.
<h3>Preparation</h3>
<ul>
<li><b>Place install files in a good location.</b>
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 <code>softdep</code> mount option in <code>/etc/fstab</code>
and rebooting before undertaking a manual upgrade.
Having at least 500MB free on <code>/usr</code> would be recommended.
<p>
<li><b>Become root.</b>
While using
<a href="https://man.openbsd.org/OpenBSD-6.2/doas">doas(1)</a>
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
<a href="https://man.openbsd.org/OpenBSD-6.2/su">su(1)</a>.
<p>
<li><b>Stop and/or disable any appropriate applications.</b>
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.
<p>
<li><b>Install new boot blocks.</b>
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 <a href="https://man.openbsd.org/OpenBSD-6.2/amd64/installboot">
installboot(8)</a>, assuming <code>sd0</code> is your boot disk:
<blockquote><pre>
<b>installboot sd0</b><!--
--></pre></blockquote>
</ul>
<h3>Upgrading manually</h3>
<ul>
<li><b>Install new kernels.</b>
The extra steps for copying over the primary kernel are done
to ensure that there is always a valid kernel on the disk.
<p>
If using the multiprocessor kernel:
<blockquote><pre>
<b>cd /usr/rel</b> # where you put the release files
<b>ln -f /bsd /obsd && cp bsd.mp /nbsd && mv /nbsd /bsd</b>
<b>cp bsd.rd /</b>
<b>cp bsd /bsd.sp</b></pre>
</blockquote>
If using the single processor kernel:
<blockquote><pre>
<b>cd /usr/rel</b> # where you put the release files
<b>ln -f /bsd /obsd && cp bsd /nbsd && mv /nbsd /bsd</b>
<b>cp bsd.rd bsd.mp /</b> # may give a harmless warning<!--
--></pre></blockquote>
<li><b>Enable KARL.</b>
Store the kernel's checksum:
<blockquote><pre>
<b>sha256 -h /var/db/kernel.SHA256 /bsd</b> <!--
--></pre></blockquote>
<li><b>Install new userland.</b>
Save a copy of reboot(8), extract and install the release tarballs, reboot.
Install <code>base62.tgz</code> last, because the new base system, in particular
<a href="https://man.openbsd.org/OpenBSD-6.2/tar">tar(1)</a>,
<a href="https://man.openbsd.org/OpenBSD-6.2/gzip">gzip(1)</a> and
<a href="https://man.openbsd.org/OpenBSD-6.2/reboot">reboot(8)</a>,
will not work with the old kernel.
Either untar the needed filesets manually
<blockquote><pre>
<b>cp /sbin/reboot /sbin/oreboot</b>
<b>tar -C / -xzphf xshare62.tgz</b>
<b>tar -C / -xzphf xserv62.tgz</b>
<b>tar -C / -xzphf xfont62.tgz</b>
<b>tar -C / -xzphf xbase62.tgz</b>
<b>tar -C / -xzphf man62.tgz</b>
<b>tar -C / -xzphf game62.tgz</b>
<b>tar -C / -xzphf comp62.tgz</b>
<b>tar -C / -xzphf base62.tgz</b> # Install last!
<b>/sbin/oreboot</b><!--
--></pre></blockquote>
or, if you use
<a href="https://man.openbsd.org/OpenBSD-6.2/ksh">ksh(1)</a>, you can do
<blockquote><pre>
<b>cp /sbin/reboot /sbin/oreboot</b>
<b>for _f in [!b]*62.tgz base62.tgz; do tar -C / -xzphf "$_f" || break; done</b>
<b>/sbin/oreboot</b><!--
--></pre></blockquote>
Note that <a href="https://man.openbsd.org/OpenBSD-6.2/tar">tar(1)</a>
can expand only one archive per invocation, so a simple glob won't work.
<p>
<li><b>After reboot, update <code>/dev</code>.</b>
Run
<a href="https://man.openbsd.org/OpenBSD-6.2/amd64/MAKEDEV">MAKEDEV(8)</a>:
<blockquote><pre>
<b>cd /dev</b>
<b>./MAKEDEV all</b><!--
--></pre></blockquote>
<li><b>Update boot loader.</b>
Still assuming <code>sd0</code> is your boot disk:
<blockquote><pre>
<b>installboot sd0</b><!--
--></pre></blockquote>
<li><b>Update system configuration files.</b>
Run <a href="https://man.openbsd.org/OpenBSD-6.2/sysmerge">sysmerge(8)</a>:
<blockquote><pre>
<b>sysmerge</b><!--
--></pre></blockquote>
<li><b>Update firmware.</b>
There may be new firmware for your system.
Update it with
<a href="https://man.openbsd.org/OpenBSD-6.2/fw_update">fw_update(1)</a>:
<blockquote><pre>
<b>fw_update</b><!--
--></pre></blockquote>
<li><b>Finish up.</b>
Review the console output from boot (using <code><b>dmesg -s</b></code>)
and correct any failures as necessary.
All the steps following <a href="#ConfigChanges">configuration changes</a>
above also apply to manual upgrades.
Finally, remove <code><b>/sbin/oreboot</b></code> and update packages:
<code><b>pkg_add -u</b></code>.
Reboot once more to make sure you run on your own kernel generated by KARL.
</ul>
<p>
<a href="index.html">[FAQ Index]</a> |
<a href="upgrade61.html">[6.0 -> 6.1]</a>
<a href="upgrade63.html">[6.2 -> 6.3]</a>
<hr>
<small>$OpenBSD: upgrade62.html,v 1.14 2019/05/28 01:53:11 bentley Exp $</small>
![[BACK]](/icons/back.gif){kind=icon}
Return to upgrade62.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / www / faq