KoaVM
Guide pages

Guide · For administrators

New nodes and automatic purchasing

Since 0.9 the panel sets up nodes on its own. It starts from a server you already have or from one it orders for you from a provider. It installs ZFS and Incus 7.0 LTS, creates the pool for the VPSs and the network, then connects the server as a node. The node also joins the private network tunnels. Everything is in Nodes › Add node.

A server you already have

You need a freshly installed x86_64 server with Debian 12 or 13 (or Ubuntu 22.04 or 24.04), virtualization enabled and at least 4 GB of RAM. The VPSs also need one of these:

  • an empty disk, without partitions;
  • unpartitioned space on a GPT disk (at least 20 GB);
  • a partition mounted on /var/lib/koavm-data, which becomes the ZFS pool.

With two disks the pool is a mirror, with three or more it is raidz.

  1. Enter the server address, the SSH port and the user (root, or a user with passwordless sudo). On OVHcloud servers and cloud images the key added at installation works for debian or ubuntu, and root answers «Please login as the user…»: leave root, the panel notices and logs in with the right user.
  2. Give the password, or put the panel key in authorized_keys: you find it under "Without a password".
  3. Press Check the server. The panel logs in and reads system, CPU, RAM and disks without changing anything.
  4. Choose the node name (e.g. gra-02), the city on the map and the overbooking: RAM, disk and CPU ratios and whether RAM can use the disk (swap). See Nodes. Then press Set up the node.

The password is only used for the first login. The panel adds its own key right away and deletes the password as soon as the setup is done. It usually takes 5–10 minutes, because the ZFS module is built on the server. You can follow the log in Nodes being set up.

If something stops, for example because a reboot is needed or there is no room, the error is in the log. Retry resumes from the step that stopped: the setup can be repeated safely.

Secure Boot must be off: on Debian the ZFS module built on the server is not loaded with Secure Boot on. The check reports it before starting.

Ports. The panel talks to Incus on the node's port 8443 (TCP) and nodes connect to each other on 51888 (UDP) (private networks). With ufw or firewalld the setup opens 8443 by itself, only for the panel IP, plus 51888, the br-vps bridge and forwarding of VPS traffic (ufw blocks it by default and VPSs would have no internet). With another firewall (hand-written nftables, the provider's firewall) open them yourself: Check the server tries 8443 from the panel and warns if it doesn't answer.

The br-vps network

In the advanced options you choose how br-vps, the bridge for the node's IP blocks, is created:

  • Internal network with NAT (default): 10.89.x.1/24 with NAT for outgoing traffic. The panel creates the «node name (rete NAT)» block by itself, with addresses .10 to .250, so you can create VPSs right away.
  • Attached to a NIC: the bridge takes a server NIC without an address, for example a provider's private network.

Public IPs from connected providers (OVHcloud, Hetzner, Contabo, Scaleway) do not go through br-vps: the panel attaches them to the node's public interface on its own.

If the server has a public IPv6 address (OVHcloud and Hetzner give every dedicated server a /64), the panel also creates the «IPv6 node name» block with that /64: each VPS gets its own public IPv6. If your provider doesn't route the whole /64 to the server, remove the block in Network & IPs.

A server in your account

With an OVHcloud (dedicated), Hetzner Robot or Scaleway Dedibox account connected in Network & IPs › Providers, the Server in your account tab lists its dedicated servers. Choose the server, the node name and the city, then type the server name to confirm: the panel reinstalls it with Debian 13, its key and the node partitions (40 GB for the system, the rest for VPSs), waits for the installation at the provider to finish and prepares it as above. Usually 20–30 minutes.

Reinstalling wipes everything on the server. Servers that are already panel nodes can't be chosen.

A server to order

With an OVHcloud (dedicated), Hetzner Robot or Scaleway Dedibox account connected in Network & IPs › Providers, the Order a server tab shows the provider's catalog. For each server you see CPU, RAM, disks, available datacenters, monthly price, setup fee and delivery time. It covers OVHcloud's Kimsufi, So you Start, Rise and Advance, Hetzner's price list and auctions, and Dediboxes.

  1. Choose the server, the datacenter and the node name.
  2. Ask for the price: the panel prepares the order at the provider and reads the exact price, that is the monthly fee and the first payment.
  3. Tick the confirmation and press Order the server.

If the price changes in the meantime, the order does not go through and the panel shows the new one.

Payment uses the provider account's default method. Then the panel does everything on its own:

  • it waits for delivery;
  • it installs Debian with the partitions for the node (through the OVHcloud and Scaleway APIs; for Hetzner from the rescue system with installimage);
  • it sets up the node as above;
  • it links it to the provider account, so additional IPs and cancellation work right away.

For Hetzner, API orders must be enabled once in Robot (Settings › Web service › Ordering).

Capacity and automatic purchasing

The Capacity and automatic purchasing card in Nodes shows free RAM and disk per city, based on the resources assigned to VPSs against what each node can assign with its overbooking. A node over the real-usage brake counts as full. Nodes ordered by the panel get the default overbooking and swap from Settings › Nodes and overbooking. A rule says what to do when space runs out:

  • nodes watched: one city or all nodes;
  • thresholds: free RAM below N% or free disk below N%;
  • server to order: account, offer and datacenter;
  • when needed:
  • Propose and wait for my OK: the panel prepares the order and alerts you. You confirm it in Nodes being set up with the updated price.
  • Order on its own: the panel orders without waiting, but only within the monthly cap for automatic orders and the maximum nodes per month. Beyond the cap it goes back to proposing.

The cap starts at 0, and with the cap at 0 rules only propose. The check runs every 10 minutes. While a node for the rule is on its way it does not order another, and after a node is ready it waits a day. The Running out of space, Server ordered, Node ready and Setup stopped alerts go to the channels in Alerts.

Retiring a node

Retire removes an empty node from the panel: first use Drain node to move the VPSs away. The panel removes its certificate from the server and updates the private network tunnels. If the node is linked to a provider account you can also cancel the server:

  • OVHcloud: no renewal, the server is deleted at expiry;
  • Hetzner: cancellation at the earliest possible date;
  • Scaleway: the server is deleted.

To confirm, type the node name.