KoaVM
Guide pages

Guide · For administrators

Updates and versions

What's new

The What's new page lists every version with its date and what changes, for you and for your customers. The same list is on koavm.com/en/changelog. Numbers follow the x.y.z rule: z changes for fixes and small additions, y for new features, x for big changes. From 1.0 on, the v1 API, the WHMCS and KoaBilling modules and the koavm commands stay compatible across all 1.x versions: anything incompatible only comes with a 2.0, announced in advance.

Updating from the panel

Every 6 hours the panel checks for a new version on the stable channel (https://koavm.com/releases/stable.json). When there is one, What's new shows the version, what changes and the Update now button. Once pressed:

  1. the panel downloads the version and checks its signature (only versions signed by Prime Software are accepted) and its SHA-256;
  2. the koavm-update system service repeats the same checks, makes a copy of the database (/var/lib/koavm/koavm-prima-VERSION.db) and replaces the binary, keeping the previous one;
  3. the panel restarts (a few seconds without the interface; VPSs keep running);
  4. if the new version does not start within 90 seconds, the previous one comes back on its own.

The page reloads by itself at the end. Go back to the previous version puts the previous version back (the database stays as it is now; the copy made before the update stays in the data folder).

The automatic check can be turned off on the same page.

From the command line

sudo koavm update --check      # tells whether there is a new version and what changes
sudo koavm update              # updates (same checks and same database copy)
sudo koavm update --rollback   # goes back to the previous version

Panel copy and restore

If the panel server is lost (broken disk, deleted server), customers, VPSs, plans, IPs, the certificate the nodes trust, the panel's SSH key and the keys of the incremental backup archives go with it. The VPSs keep running on the nodes, but without the panel they can't be managed. That's why the panel makes a copy of itself every night.

In Backups › Panel copy:

  1. Create the recovery key. You see it only once: download or copy it and keep it away from the panel server (password manager, USB stick, safe). The panel only keeps the public part: whoever gets into the destination, or even into the panel, can't read the copies.
  2. Choose the destination (one of the backup destinations, not on the panel server itself) and how many copies to keep (14 by default).
  3. From then on the copy runs every night at backup time; Make a copy now runs it right away. If a copy fails you get an alert.

The copy holds the database (without the chart history and the sessions), the node certificate and key, the panel's SSH key, the key of the two-step verification secrets (totp.key), the HTTPS certificates and the configurations of the migrated VMs. It's a koavm-DATE-VERSION.tar.gz.age file in the koavm-pannello/copie/ folder of the destination, encrypted with age: with the key it opens even without KoaVM (age -d -i key.txt copy.tar.gz.age | tar -xz).

Restoring on a new server

  1. Install KoaVM on the new server with the same panel name (see Installation) and point the name to the new server.
  2. Copy the panel copy (from the page while the old panel is still there, or straight from the destination) and the key file to the server.
  3. Restore:
sudo systemctl stop koavm
sudo koavm panel-restore --file koavm-…tar.gz.age --key key.txt --force
sudo systemctl start koavm

With --force the files of the freshly installed panel go to /var/lib/koavm/prima-del-ripristino-…. A copy from a newer KoaVM version than the installed one is not restored: update first. You log in with the old accounts.

The nodes trust the restored panel (same certificate). The license instead shows as "used by another panel", because the server is a different one: ask whoever sold it to you (Prime Software or your reseller) to unlock it, or it frees itself after 15 days. In the meantime the VPSs keep running and the trial limits apply to new nodes and VPSs.

If the panel was installed before 0.7.2

The koavm-update service is installed by install.sh. Update once with the script (see Installation) or with sudo koavm update: from then on updates are done from the panel.