Korthveil checks the Korthveil update service for new versions and tells you what each one changes, what to do first, and whether it installs live (no restart, traffic keeps flowing) or needs one restart. Nothing installs until you press Install, unless you turn on an automatic window yourself. If an update does not work as it should for you, go back to the previous version in seconds.

At a glance:

How an update works

Most releases change only Korthveil itself: its services, the web console, the guides. Since 1.1.24, such a release is installed as a small Korthveil layer (about 35 MB instead of about 1.3 GB):

• The firewall downloads only Korthveil's own programs and checks them against the signed release list.
• Its services restart into them for about 15 seconds. The kernel keeps forwarding, with its rules, NAT, routes, VPN tunnels and open connections. Nothing is written to the spare slot and nothing is rebooted.
• The version before stays on the firewall as the way back.

System › Updates says which kind each update is: Only Korthveil itself changes: a 35 MB download, or the size of the whole system. The firewall decides by itself: a layer is used only when it was built for exactly the system this firewall runs (the same Debian packages, kernel and firmware). Otherwise the whole system is updated, as below.

Going back after such an update uses the same button as always, Previous version: the Korthveil from before the update is still on the firewall, so nothing is downloaded.

When the system underneath changes (two slots)

Korthveil keeps two system slots on the disk. The running version is in one; an update is written into the other while the firewall keeps working. Then:

• Live switch (same kernel): only Korthveil's own services restart (web console, DNS, DHCP, VPN servers) for about 15 seconds. The kernel keeps forwarding, with its rules, NAT, routes, VPN tunnels and open connections. Nothing is rebooted.
• One restart (the update brings a new kernel): the firewall restarts once into the new version, about one to three minutes.

Every way, the new version must pass its health check (its configuration applies, the internet route and SentinelOps work). If it does not, the firewall goes back to the previous version by itself: the previous slot, or for a Korthveil layer the previous layer. The check always runs from the system's own copy of the update program, so even a broken update cannot stop it from going back.

Step 1: Check for updates

The firewall checks every 6 hours. To check now: System › Updates › Check now. When a newer version exists, every page shows Update 1.x.y in the top bar.

The offer shows:

• Installs live: no restart or Needs one restart, and why;
• Before you install: measures to take (for example a backup);
• Release notes.

The release list is signed with the Korthveil release key built into your firewall: a changed or forged list, or an image that does not match it, is refused.

Step 2: Install

Press Install 1.x.y. A progress bar shows the download: about 35 MB when only Korthveil changes, about 1.3 GB when the whole system does. Then the firewall switches (after writing the spare slot, for a whole-system update). For a live update, the web console disconnects for about 15 seconds and comes back on the new version; the page shows the result under Last update.

Tip: turn on Download updates in advance (Step 4) and Install only switches: no waiting for the download.

Step 3: Going back to the previous version

If an update does not work as it should for you: System › Updates › Previous version › Go back to 1.x.y.

• The previous version is still in the other slot, so nothing is downloaded. It switches the same way (live when the kernel is the same) and gets the same health check; if it does not come up, the firewall returns to the newer version by itself.
• Your configuration is kept, including changes made since the update.
• Exception: if the update changed the configuration database format, going back puts back the configuration from just before the update: changes made since then are lost. Korthveil says so and asks you to confirm. Make a backup first if you want to keep them.

If the firewall no longer has the previous version in its other slot (for example after a fresh install), the update service keeps the previous release too: Install it from the same panel (only when it uses the same database format).

Step 4: Update settings

System › Updates › Update settings, then Save and commit:

• Check for updates: on by default; a check never installs anything.
• Channel: Stable for production, Preview to test new versions first.
• Check every (hours): default 6.
• Download updates in advance: off by default. A new version is downloaded and checked as soon as it is found (about 35 MB for a Korthveil layer, about 1.3 GB for the whole system), so Install only switches. It is still installed only when you press Install.
• Automatic installs: off unless you turn them on. Choose a one-hour window (start time and days). Only updates that install live keeps updates that need a restart waiting for you.

Installing from a file

System › Updates › Install from file takes either file a release ships: the update image korthveil-1.x.y-installer.img.zst (the whole system), or the Korthveil layer korthveil-1.x.y.layer.raw. A layer is installed only when it fits this firewall's system; otherwise the firewall says so and changes nothing.

Updating a failover pair

With two Korthveil firewalls in a failover pair (see Two firewalls with automatic failover), update one at a time:

1. Update the standby firewall (live). Wait until its top bar shows the new version and Failover · Standby is green.
2. On the active firewall: Network › High availability › Force failover. The standby takes over the gateway and the internet port; connections continue.
3. Update the first firewall (now standby). When it is done, Clear forced failover (or wait for the time you chose) so the primary takes the active role back.

Automatic installs in a pair: only the standby firewall installs by itself in the automatic window. The active firewall waits for you (steps 2 and 3), so the two never restart at the same time.

Troubleshooting