Installing SimpleVirt

SimpleVirt ships as two bootable installer ISOs:

• simplevirt-hypervisor.iso — installs a SimpleVirt-Hypervisor host. A bare-metal KVM hypervisor that runs virtual machines and is managed entirely from a web browser.
• simplevirt-command.iso — installs SimpleVirt-Command, the controller that manages a fleet of Hosts grouped into Clusters. SimpleVirt-Command runs as a virtual machine (typically on a SimpleVirt-Hypervisor host) and bundles its own PostgreSQL database for controller state.

A working deployment is at least one SimpleVirt-Hypervisor host plus one SimpleVirt-Command controller. You install the hosts first, install the controller, then add the hosts to the controller and group them into a Cluster.

flowchart TD
    Op["Operator's browser"] -->|HTTPS 443| Cmd["SimpleVirt-Command<br/>(controller VM)"]
    Cmd -->|manages over HTTPS| H1["SimpleVirt-Hypervisor<br/>host01.example.local"]
    Cmd -->|manages over HTTPS| H2["SimpleVirt-Hypervisor<br/>host02.example.local"]
    Cmd -->|manages over HTTPS| H3["SimpleVirt-Hypervisor<br/>host03.example.local"]
    H1 --- Cl(("Cluster"))
    H2 --- Cl
    H3 --- Cl

Both ISOs share one installer engine, so the install flow — disk selection, management network, time, and (for a fresh install) the first account — is the same on each; only the branding and the account it creates differ.

Prerequisites

Hardware and virtualization

SimpleVirt-Hypervisor host (bare metal):

• A 64-bit x86 CPU with hardware virtualization enabled in firmware (Intel VT-x or AMD-V). SimpleVirt uses KVM acceleration when /dev/kvm is present.
• Enough RAM and CPU cores for the virtual machines you intend to run, plus headroom for the host itself.
• A dedicated disk for the appliance. The target disk is repartitioned and erased during a fresh install. VM disks and pooled storage live on separate capacity described below.
• One or more wired network interfaces. Wi-Fi is not used by a host.
• For SimpleVirt HCI (pooled, resilient cluster storage), plan one or more additional data disks per host beyond the appliance/system disk. SimpleVirt HCI presents pooled capacity as a Datastore reachable from every Cluster member.

SimpleVirt-Command controller (a virtual machine):

• Runs as a guest VM. You can host it on one of your SimpleVirt-Hypervisor hosts or on separate infrastructure.
• A modest allocation of vCPU, RAM, and a single virtual disk is sufficient; the controller stores fleet state in its bundled PostgreSQL database. The controller's disk is separate from the hosts' storage and should be protected (snapshots/backups) like any management system.

Hardware minimums

Before it writes anything to disk, the installer runs a hardware preflight and shows you the result. A check is one of two kinds, and the difference matters:

• A hard floor blocks the install. There is no override, because every hard floor describes a machine that cannot run what it is being asked to run.
• A recommendation warns and lets you continue. You acknowledge it and proceed. This is what makes evaluation on modest or nested hardware possible.

Why the numbers are not round. They are stated as the kernel reports them, which puts them slightly below the figure a vendor quotes. A nominal 4 GB machine reports about 3.8 GiB of usable memory once firmware has taken its reservation, and a "16 GB" disk is 14.9 GiB. A floor set at the round number would refuse the very hardware it was meant to allow. In practice: a 4 GB machine clears the hypervisor's memory floor, a 16 GB machine clears its recommendation, and a 2 GB controller VM clears the controller's floor with a 4 GB VM clearing its recommendation.

What the floors are for. They size the appliance, not your workload. The hypervisor recommendation of 15 GiB assumes the host itself, its virtualization stack, and — if you enable SimpleVirt HCI — a storage daemon that wants about 4 GiB of its own, all before a single guest gets any memory. Add the memory and cores your virtual machines need on top of this. The controller's floor is lower because it runs no workloads: only itself and its bundled database.

The disk figures are the same for both appliances. The installed system is small, but an appliance also holds its ISO library, its journal and audit log, and a complete staged release image while an in-place upgrade is applied. 12 GiB is the point below which an upgrade has no safe headroom; 32 GiB is the recommendation. VM disks do not live here — they live on datastores.

Other preflight checks.

• Hardware virtualization is checked twice on a hypervisor install: the CPU must report the vmx (Intel) or svm (AMD) flag, and /dev/kvm must actually open. Both fail when virtualization is switched off in firmware — a common factory default. Enable Intel VT-x / AMD-V in the BIOS/UEFI setup (it may be listed as Virtualization Technology or SVM Mode) and reboot. Neither check applies to the SimpleVirt-Command installer, which runs as a guest VM and needs no virtualization of its own.
• Installing nested (SimpleVirt-Hypervisor inside another hypervisor) warns but is allowed. It is supported for evaluation and lab use; nested virtualization is markedly slower and its timing is not what a production workload should sit on. Install on bare metal for production.
• The medium you booted from is never an install target, however large it is. A machine whose only sizeable disk is the installer USB stick has no install target, and the preflight says so rather than presenting an empty disk picker later.
• A machine with no wired interface a driver has bound to cannot be installed. SimpleVirt is managed entirely over the network; there is no local administration UI beyond the console. If this fails on hardware that does have network ports, the image does not carry a driver for that card.
• Disks the installer cannot use are shown with the reason, rather than hidden — a disk visible in the firmware and absent from the picker is a support call.

Networking

• Management network. Each appliance needs a management IP on a reachable network. During install you pick the management interface and choose DHCP or a static address; you can also set a management VLAN if the port is a trunk carrying tagged management traffic. Static addressing is recommended for anything long-lived.
• DNS. Provide forward and reverse DNS for every appliance's management address (for example command.example.local, host01.example.local). SimpleVirt resolves management names by unicast DNS. Configure a DNS search domain during install if you use short names. Consistent, resolvable names make pairing and clustering straightforward.
• NTP. A virtual appliance's clock drifts, and clustering, HA, and TLS all depend on agreement about time. The installer asks for one or more NTP servers (for example pool.ntp.org). Point every host and the controller at the same time source.
• Connectivity and ports. SimpleVirt serves its UI and API over HTTPS on port 443 only — there is no plaintext HTTP listener. The controller reaches each host over HTTPS. Live migration between hosts uses libvirt's own transport: a control channel on TCP 16509 and guest memory/disk traffic on TCP 49152–49215. The guest data on those data ports is encrypted and mutually authenticated by default (qemu+tls / VIR_MIGRATE_TLS, using short-lived per-host leaf certificates the controller auto-issues); the control channel on 16509 is still plaintext and unauthenticated, so migration must run on a dedicated, isolated migration network — see Migration network below. Ensure the controller can reach every host on 443, and that hosts can reach each other on the migration ports.

Migration network (required)

Live migration, host evacuation, and the workload distributor all move a running VM's memory from one host to another over libvirt's migration transport. Guest data on that transport is encrypted and mutually authenticated by default (qemu+tls / VIR_MIGRATE_TLS), but the libvirt control channel on 16509 remains plaintext and unauthenticated, so plan a dedicated, isolated migration VLAN before you build a cluster.

• Control channel — libvirtd on TCP 16509 with libvirt authentication disabled (auth_tcp = "none"). This channel is not protected by the migration TLS: whatever can open a TCP connection to that port can drive libvirt on that host, which is equivalent to administrative control of the host and every VM on it. This is why the isolated VLAN is required regardless of the encryption setting.
• Data channel — TCP 49152–49215, carrying guest RAM (and, for a storage or cold move, disk contents). By default this is a mutually authenticated TLS channel: the controller auto-issues a short-lived migration leaf certificate to each host (at startup, on host-add, and on renewal), and the handler refuses to migrate rather than fall back to cleartext if a peer lacks a leaf. Cleartext on these ports exists only as an explicit encryption-off opt-out.

Because reaching the port is the access, give every host in a cluster a migration adapter on a network that carries nothing else. Concretely, "isolated" means:

• A separate VLAN (or separate physical network) carrying only the hosts' migration adapters — no VMs, no user devices, no general server traffic.
• Not routed to your general-purpose or user networks, and with no default gateway of its own. It should not be reachable from any network a person or a guest VM sits on.
• The same migration VLAN on every member of a cluster: a host that cannot reach the others on it cannot be a migration target, and evacuation will have nowhere to place its VMs.
• Sized for the traffic — 10 GbE or better is recommended, because a live migration moves a VM's entire memory footprint, repeatedly, until it converges.

What SimpleVirt enforces on its own. Each host keeps the migration ports closed by default with an nftables rule set: they are opened only on a configured migration adapter and to the fleet peer addresses the controller pushes; every other packet to them is dropped. The listener is ordered after — and requires — the firewall, so if the firewall ever fails to load, port 16509 is never opened at all: a firewall failure disables migration instead of exposing it. SimpleVirt also refuses to run a migration over the management network unless you explicitly choose that in the Migrate dialog.

What isolation you still have to provide. Two cases are worth understanding before you design the network:

• A migration adapter on a shared VLAN. The host firewall accepts migration traffic from any source address that arrives on a migration interface, so every device on that VLAN can open the unauthenticated control channel on 16509. This is the configuration to avoid: a shared migration VLAN is a shared control plane.
• No migration adapter, using the management-network opt-in. The firewall then admits only the fleet peer addresses the controller pushes. That is much narrower, but a source-address allowlist is not authentication, and guest memory still crosses the management LAN in the clear. Treat it as a break-glass path for a lab or a one-off move, not as a deployment model.

Configuring it in SimpleVirt. The migration VLAN is a network like any other: on Host → Settings → Networking, create the network (port group) for the migration VLAN on the switch whose uplink is cabled to it, then Add service adapter on that network with Service: Migration and the host's address on the VLAN. Repeat on every member of the cluster. Until a host has one, migrations to it are refused unless an operator explicitly opts into the management network.

Guest data is already encrypted and mutually authenticated in flight, but because the 16509 control channel is not, network isolation remains the control for that channel — design for it at install time, not afterwards.

Storage expectations

• The appliance/system disk you select during install is wiped and becomes the boot device. Do not place data you need on it.
• Datastores hold VM disks. SimpleVirt supports NFS datastores (an external shared export reachable from members) and SimpleVirt HCI (pooled resilient storage built from the hosts' own data disks). Decide which you will use before building Clusters, and provision the underlying disks or NFS exports accordingly.
• The controller keeps its state in bundled PostgreSQL on its own disk; back the controller up (SimpleVirt-Command includes a controller-state backup/restore facility) rather than relying on the hosts for controller recovery.

Install a SimpleVirt-Hypervisor host

Repeat these steps for each host.

1. Boot the installer

Write simplevirt-hypervisor.iso to a USB stick or attach it as virtual media, then boot the machine from it. The ISO boots straight into the full-screen SimpleVirt-Hypervisor Installer — there is no separate login. A root shell for pre-install diagnostics is always available from the installer (press S on the welcome screen, or F2 from any screen).

2. Work through the installer

The installer is a guided sequence:

1. Welcome — press Enter to begin.
2. Target Disk — choose the disk to install onto. Each disk is listed with its size and model. The disk you select is repartitioned and erased. If the installer detects an existing SimpleVirt install on the chosen disk, it offers Upgrade (keep all VMs, networks, and settings; refresh the OS in place) or Reinstall (wipe and install clean).
3. Management Network — choose the interface SimpleVirt is managed on. NICs are listed with link state and MAC address so you can pick the one that is cabled. Choose Automatic (DHCP on all interfaces) to defer the choice, or select a specific NIC and set a VLAN, DHCP, or a static address (CIDR), gateway, DNS servers, and DNS search domain.
4. Time — enter one or more NTP servers (space-separated). Leave blank only if you deliberately want no time sync.
5. Account — set the hostname and create the first administrator. The admin username defaults to admin; the password must be at least 12 characters and is entered twice. This account is both the web UI administrator and a full OS/SSH login on the appliance.
6. Install — review the summary (target disk, hostname, admin account, management network, time source), then confirm. A progress checklist streams as the disk is partitioned, the system is copied, and the bootloader is installed.
7. Finish — remove the installation media and reboot into the installed host.

For fleet or automated provisioning, the installer also supports an unattended mode driven by kernel command-line parameters; interactive install is the normal path.

3. First boot

The host boots to the SimpleVirt Console on its local screen (tty1). The console shows the management URL — Manage this host at https://host01.example.local — and offers a menu for management tasks: Configure/Test/Restart Management Network, Network Diagnostics, Set Hostname & Domain, Create Admin User (access recovery), SimpleVirt-Command pairing status, Toggle SSH, Enter Shell, Factory Reset, and restart/shutdown.

Browse to https://host01.example.local (or the host's management IP) and log in with the administrator account you created. On first connection your browser will warn about the certificate: the host generates a self-signed certificate on first start. You can replace it with your own signed certificate, or generate a signing request and install the result, from the host's UI once you are logged in.

You can run VMs directly on a standalone host, but the intended model is to add the host to SimpleVirt-Command and manage it as part of a Cluster.

Install the SimpleVirt-Command controller

SimpleVirt-Command runs as a virtual machine. A convenient path is to install your first SimpleVirt-Hypervisor host, create a small VM on it, and install the controller into that VM; you can also run the controller VM on separate infrastructure.

1. Create the controller VM and boot the installer

Provision a VM with a single system disk and a NIC on the management network, then boot it from simplevirt-command.iso (attach it as the VM's virtual CD/ISO). The ISO boots into the SimpleVirt-Command Installer.

2. Work through the installer

The flow matches the host installer:

1. Welcome → Target Disk — select the controller VM's disk (it is erased on a fresh install; an existing controller disk offers Upgrade, which preserves operator accounts, the host registry, and Clusters).
2. Management Network — set the controller's management interface. Use a static address and a resolvable name such as command.example.local; the controller is the address your operators and every host will talk to.
3. Time — set the same NTP servers your hosts use.
4. Account — set the hostname and create the first operator account (web UI login, minimum 12-character password). This account is also a full OS/SSH login on the controller.
5. Install → Finish — confirm, let it install, remove the media, and reboot.

The controller initializes its bundled PostgreSQL database on first boot and imports the first operator account into it automatically.

3. First login

The controller boots to the SimpleVirt-Command Console on tty1, which shows the controller's management URL and a menu for network configuration, hostname/domain, network diagnostics, operator-password recovery, SSH toggle, and restart/shutdown.

Browse to https://command.example.local and sign in with the operator account. As with the host, the controller presents a self-signed certificate on first start that you can replace from the UI. This controller is where you will manage all of your hosts, Clusters, VMs, storage, and networking from now on.

Add hosts to SimpleVirt-Command

With the controller up and one or more hosts installed and reachable, register each host with the controller.

1. In SimpleVirt-Command, go to the hosts view and choose Add Host.
2. Enter the host's management address (for example host01.example.local) and the administrator username and password you set when installing that host.
3. SimpleVirt-Command connects to the host, verifies it, and pairs it into the fleet. The controller thereafter reaches the host's management endpoints on your behalf — you do not need to log in to each host individually.

Repeat for every host. You can confirm the pairing from the host side at any time on its local SimpleVirt Console under SimpleVirt-Command (controller pairing status / disconnect).

Keep the host's administrator credentials safe: they are what authorizes the controller to manage the host, and re-pairing requires them again.

Create a Cluster

A Cluster groups hosts so they share networking, storage, and availability features (HA auto-restart, the workload distributor, and pooled SimpleVirt HCI storage all operate at the Cluster level).

1. In SimpleVirt-Command, create a new Cluster and give it a name.
2. Add your registered hosts to the Cluster as members. For consistent behavior, cluster hosts with compatible CPUs and matching network and storage layouts.
3. Attach storage the Cluster's VMs will use:
   • an NFS Datastore reachable from every member, or
   • SimpleVirt HCI, which pools the members' data disks into a resilient Datastore presented to every member. SimpleVirt HCI is configured from its guided setup in the Cluster's storage/HCI console.
4. Define networking with a Logical Distributed Switch — declared once for the Cluster and realized on each member host — with Networks (port groups) on trunked Uplinks. A single-host, non-clustered setup can instead use a per-host Logical Switch.
5. Enable Cluster features as needed — HA (auto-restart on host death, with an admission-control reserve), the workload distributor (load balancing in recommend or automatic mode), and host maintenance/evacuation — from the Cluster's configuration.

Once a Cluster has members, shared storage, and networking, you can create and run virtual machines on it, migrate them live between hosts, and let HA restart them automatically if a host fails.

After installation

• Certificates. Replace the default self-signed certificates on both the controller and the hosts with your own signed certificates, or generate a signing request and install the issued certificate, from each appliance's UI.
• Users and access. Add operator accounts and roles in SimpleVirt-Command (SimpleVirt uses default-deny, per-capability access control), and connect an LDAP/Active Directory directory if you use one.
• Backups. Configure controller-state backups in SimpleVirt-Command so you can restore the controller independently of the hosts.
• Updates. SimpleVirt is updated only from a signed SimpleVirt installer ISO — the same image you installed from; apply updates through the Lifecycle flow, which upgrades in place and preserves your VMs, settings, and controller state.

Next: the user guide for day-to-day use, operations for day-2 procedures, known limitations for what this release does not do, and backup responsibility for what you must protect yourself.