KoaVM
Guide pages

Guide · For administrators

Customers and VPSs

Customers

In Clients & plans › Clients you create customers (name, company, email). For a new customer the panel generates a password to give them; you can also generate a new one there. Customers created through the API (WHMCS, KoaBilling) are created automatically, matched by email.

With self-service on, Self-service gives the customer a package of resources to create their own VPSs: see Self-service and hourly usage.

Customer teams and API keys

Since 0.13 every customer can invite other people into their account (the Team & API page of the customer area), each with their own email, password and a role: administrator (everything the customer does), technician (works on the VPSs but doesn't create or delete them) or read-only. The customer can also create API keys with a role for their scripts: they work on the panel API (/api/…), with the same permissions as the interface, not on /api/v1.

Since 1.13 the 2FA mark next to the name means the customer has two-step verification on; the shield button removes it if they lost their phone and recovery codes (see Two-step verification).

In the customer list, under the name, you see how many people and keys the customer has. The badge button opens Team, API keys and log: remove a person (signed out of every session right away), their two-step verification or a key, and read who did what in the customer's account. Each email joins one account only: a new customer can't use the email of a person in another customer's team.

Create a VPS

VPS › Create VPS:

  • customer and plan;
  • system, with icons: the ones that do not fit the plan stay disabled with the reason (minimum RAM or disk, allowed plans);
  • app to install on first boot (optional): only the apps that fit the system and the plan are shown;
  • hostname (e.g. web1.example.com);
  • node or zone (empty = the node with the most assignable RAM left);
  • root password (Administrator for Windows) or SSH key;
  • an ISO to mount (optional, in Boot from an ISO), for example to install by hand from the graphical console.

Creation is a queued job: in less than a minute a Linux VPS is running and reachable; Windows takes a few minutes more. An app installs afterwards, while the VPS is already running: its status is on the VPS page.

The panel checks there is room on the node: RAM and disk assigned with the node overbooking and the real-usage brake.

If the hostname is a full domain and the IP belongs to a connected provider, the panel also sets reverse DNS.

The VPS page

  • Start, Shut down, Restart, and Force stop if the system does not respond.
  • Console: serial or graphical (the real VM screen), in the browser. Windows and VPSs booting from an ISO open the graphical one straight away; Hetzner Cloud VPSs have the provider's graphical console.
  • Generate new password: new root password (the VPS must be running: the agent inside the VPS changes it). On Windows the password is changed from remote desktop.
  • Reinstall the OS: wipes the disk and the snapshots and starts from scratch with the same IP, also with another system or an app; confirm by typing the hostname. Backups stay.
  • App: install step, and at the end address, user and password, plus the log.
  • CD / ISO: mounts an ISO, also booting from the CD, and unmounts it.
  • Snapshots and backups: see Backups and snapshots.
  • Network: IPv4, IPv6, MAC, speed, reverse DNS; extra IPs can move to another VPS of the client.
  • Firewall: inbound traffic rules, applied by the node. See Firewall, volumes and floating IPs.
  • Charts: CPU, RAM, disk and monthly traffic.

For you only:

  • Change plan: CPU and RAM change at the next restart (you can restart right away), the disk grows immediately and the file system grows at restart. The disk cannot shrink. The disk and CPU limits of the new plan apply within 30 seconds, even while the VPS is running. Without a restart, if the main disk of the VPS is virtio-blk (almost all Linux VPSs) it grows right away but its size in the configuration is updated the first time the VPS is stopped (start or restart from the panel, or on its own within a few minutes if you shut it down): the task says so.
  • Custom resources: vCPU, RAM, disk (up only), speed and traffic of this VPS, without changing its plan. The panel checks there is room on the node (node overbooking and real-usage brake). «custom» appears next to the plan; a plan change puts the plan's values back. Since 1.14 also the disk and CPU limits: untick As in the plan and choose the ones for this VPS (they apply within 30 seconds, even while the VPS is running; see Plans and systems).
  • Extra disks (see below).
  • Suspend / Reactivate with a reason (administrator, billing, traffic, abuse): the VPS shuts down and the customer cannot start it.
  • Add IPv6 / Set up again.
  • Delete: deletes the VPS and its backups and frees the IPs.

Rescue mode

Boot into rescue mode (the client and their team admins and technicians can do it too) restarts the VPS into a Debian 13 system with its own network, SSH root access with a temporary password (shown once) and the VPS disk attached but not mounted. What the client sees is in Your VPS.

How it works on the node:

  • the first time on a node (and pool) the node downloads the Debian 13 “generic” cloud image from cloud.debian.org (checked with SHA512SUMS, kept in /var/lib/koavm-rescue) and the panel turns it into the base disk koavm-rescue-base-… on the default pool; it needs curl, qemu-img and sgdisk or sfdisk (node preparation installs them). The image boots with BIOS and with UEFI. The base disk has its own identifiers (new PARTUUID, grub looking for a marker file instead of the UUID): a client disk created from the same image is never mistaken for the rescue system;
  • for each rescue session a fast copy of the base disk (koavm-rescue-<id>, a clone on ZFS) where the panel writes the local NoCloud seed (new instance-id, password, keys, VPS network). The VPS shuts down, the copy is attached with the highest boot priority and the VPS starts again. The VPS cloud-init configuration does not change: on exit the client system does not run its first boot again;
  • Leave, or after 24 hours by itself: shuts down, detaches and deletes the copy, starts the VPS again. If the automatic exit fails, the panel tries again with growing waits (5 minutes, then 10, 20… up to 6 hours) and sends the Rescue mode: leaving failed alert. If the panel restarts halfway, or a rescue is left halfway without its job, the panel puts the VPS back as it was.

During rescue mode the VPS is in the In rescue state (in the VPS list too): no snapshots, backups (automatic ones are skipped), moves, reinstalls, plan or pool changes. It is not available for provider VPSs, suspended VPSs and load balancer and router machines. To prepare the base disk before it is needed (or redo it from a mirror): POST /api/admin/nodes/{id}/rescue-base with optional {"url": "https://…/trixie/latest"} (only https://, or file:// for an image already on the node; an image that refers to other files, backing file or data file, is refused); GET /api/admin/rescue-bases shows the state on each node. The previous base disk is deleted as soon as no rescue uses it any more. On non-thin LVM pools the part of the base disk after the image is zeroed.

Extra disks

In the VPS's Extra disks box: Add disk with its size in GB. The disk is attached right away, even while the VPS is running. If you leave Format it and mount it on, the panel prepares it through the agent (ext4) and mounts it on the chosen folder (usually /mnt/disco1, /mnt/disco2…), with a line in /etc/fstab that mounts it again after reboots. On Windows, prepare the disk from Disk Management.

  • Grow: the disk grows right away and, if the panel mounted it, so does the filesystem, without shutting down the VPS. A disk cannot shrink.
  • Mount: for a disk that isn't mounted yet (for example added while the VPS was stopped).
  • Detach: unmounts and detaches the disk without deleting it: it becomes a detached volume, which you can attach to another VPS of the same client on the same node (Volumes page). Clients can do this too, as well as Mount.
  • Remove: unmounts, detaches and deletes the disk. Confirm by typing the disk name (e.g. disk1).

Extra disks are included in snapshots and backups and count towards the node's space. After a reinstall the new system mounts them where they were. VPSs that arrived through migration show their extra disks automatically.

Jobs

Jobs lists everything the panel does, who asked, how long it took and any error. A failed job can be retried (Retry button). On each node heavy jobs (creations, migrations, backups, restores) run one at a time.