SimpleVirt Administrator Guide

This guide is for administrators operating a SimpleVirt environment day to day. It covers getting around SimpleVirt-Command, running virtual machines, managing hosts and clusters, networking, storage, the Stretched Cluster, health and events, users, and lifecycle updates.

SimpleVirt has two appliances:

• SimpleVirt-Hypervisor — the host. It runs your virtual machines. Each host exposes an agent that SimpleVirt-Command talks to; a host also has an on-console text UI for break-glass access.
• SimpleVirt-Command — the controller. It manages a fleet of hosts grouped into clusters, and is where you spend almost all of your time. This guide is written against the SimpleVirt-Command web console.

You sign in to SimpleVirt-Command in a browser at your controller address (for example, https://command.example.local).

1. Getting around SimpleVirt-Command

The console is a single workspace with three regions:

• Inventory rail (left) — your whole environment, projected through one of four lenses.
• Object detail (center) — a tabbed page for whatever object you selected.
• Recent Tasks dock (bottom) — what the fleet is doing right now, drawn from the controller's own task log so it shows work started by you, by another operator, or by SimpleVirt-Command itself.

The top bar holds Home (fleet dashboard), the Health Center, Kubernetes, the content Library, and — next to your signed-in name — Administration, which is SimpleVirt-Command's own settings.

The four lenses

The same objects, organized four ways. Switch lenses at the top of the inventory rail:

Switching a lens changes how the tree is organized, not what you are looking at. Every object links to its neighbors through its Connections — from a host you can jump to a datastore it mounts, from a VM to its host, and so on — so you are never more than a click from a related object even when it lives in another lens.

The object spine

Every object page uses the same tab order, so you learn it once:

Overview → Health → Settings → (relation tabs) → (type actions)

• Overview — what this object is and its current state.
• Health — values that change on their own over time (utilization, live health, events).
• Settings — configuration, which changes only because someone changed it. Some Settings panels are read-only and simply state how a value is set and why it is fixed.
• Relation tabs — one per relationship (a host's VMs, a datastore's hosts).
• Type actions — what only this type can do (a VM's Console, a datastore's Files).

Object-level actions (power operations, migrate, maintenance, delete) live in the Actions menu on the object header and also on the tree's right-click menu.

Finding things fast

Use Quick Find to jump to any host, VM, cluster, or datastore by name. The Datacenter page (top of the Hosts and Clusters lens) gives a fleet roll-up with tabs for Overview, Health, Hosts, VMs, Datastores, and Networks.

2. Virtual machines

Create a VM

From the Datacenter's VMs tab or a cluster, choose New VM. The wizard steps are:

1. Placement — which cluster/host the VM runs on.
2. Compute — vCPUs and memory (with optional CPU topology).
3. Storage & network — a disk on a datastore, and a network (port group). A network is required.
4. Guest customization — hostname and cloud-init, applied on first boot.
5. Advanced — boot order, CPU pinning, PCI passthrough, and a static MAC address.
6. Review — confirm and create.

You can also create from a base image or template in the content Library, which clones a prepared disk instead of installing from ISO.

Power and lifecycle

From a VM's page (or its right-click menu) you can Start, Shut down (clean guest shutdown where the guest agent is present), Restart, Reset, Suspend, and Force stop. Force stop is confirmed because it is an abrupt power-off.

Edit a VM from Settings → Hardware: CPU and memory, attach/detach NICs, CD-ROM (mount/eject ISO), and disks. You can also take and manage snapshots.

Folders group VMs so a large fleet is easier to scan. They are managed from the Virtual Machines list — + New folder, then the Folder picker on each VM's row — not from the VM's own page, and they are a flat set of named groups rather than a nested tree. A folder is a Command-side view and nothing more: it moves no VM and changes nothing on any host, membership follows the VM by its identity when it migrates between hosts, and deleting a folder unfiles its VMs without deleting any of them.

A snapshot is a short-term undo, not a backup. It is crash-consistent (the guest is not quiesced), it lives on the same datastore as the VM, it is not available on SimpleVirt HCI storage, and it does not survive a migration or an HA recovery. SimpleVirt does not back up VM data — see Backup responsibility.

Delete removes the VM and is confirmed; deleting a running VM warns you first.

Console

Open Console on a VM's page for a web VNC session — no plugin, in the browser. Copy/paste and power controls are available inline.

Migrate a VM

Migration is one wizard, launched from Migrate…. Step 1 chooses what to move:

• Change compute resource only — move the VM to another host; its disks stay on storage both hosts share.
• Change storage only — keep the host, move the disk(s) to another datastore. This is live storage migration for a running VM, or an offline copy for a stopped one.
• Both — move the VM to another host and relocate its disks.

Step 2 picks the destination and runs a compatibility precheck before it lets you commit. The precheck catches a destination host that lacks the VM's port group, or that carries it on the wrong VLAN, so a move never silently strands a VM off its network. A running (or paused/suspended) VM is live-migrated with no downtime; a stopped VM is cold-migrated.

Destinations must be online, not merely reachable — SimpleVirt will not migrate into a degraded host.

A live move rides the cluster's migration network. If the destination has no migration adapter, SimpleVirt refuses the move rather than quietly sending guest memory across the management LAN; you can override that for a single move in the dialog. Guest data is encrypted and mutually authenticated in flight by default (qemu+tls / VIR_MIGRATE_TLS); the isolated migration VLAN is still required because the libvirt control listener on TCP 16509 is unauthenticated — see Migration network.

3. Hosts

Open a host from the Hosts and Clusters lens. A host's status (online / degraded / unreachable) is authoritative from the host itself.

Host tabs

• Overview — identity, cluster, VM counts, key resources.
• Health — Issues, Utilization (CPU/memory/storage over time), Physical adapters, Services (host daemons, with restart where offered), and Events.
• Settings — Networking, Storage, Time, Security (host certificate, host-local users), Hardware (inventory), and Licensing.

Host state and maintenance

From the host's Actions menu:

• Enter / Exit maintenance — Entering maintenance stops new VM placement on the host and shuts down its running VMs (a clean guest shutdown where possible) so it can be serviced or rebooted safely. Before you commit, a read-only preview shows exactly what entering maintenance would do. Exiting maintenance simply re-admits placement and takes effect at once.
• Evacuate host… — the no-downtime alternative for a clustered host: live-migrate every running VM off onto other cluster members (disks stay put on shared storage; only memory moves), leaving the host empty to reboot or service.
• Reboot host… and power operations.

When you enter maintenance on a clustered host with running VMs, SimpleVirt also offers Evacuate (keep VMs running) as the alternative, so you can choose downtime-free servicing.

Host networking and storage

Manage both centrally from the host's Settings tab — you never have to log in to the host itself. Networking and storage changes are proxied to the owning host. See sections 4 and 5.

4. Networking

SimpleVirt networking is identity-first and organized around a few clear terms.

Logical Switch (per host)

On Host → Settings → Networking, each Logical Switch is a card: its physical uplink sits in the header, its Networks (port groups) nest inside it, and each service adapter shows on the network it rides. Read a card top to bottom and the whole path — network → switch → uplink — is legible at a glance. Free (unused) physical adapters are listed below, so spare uplinks are obvious.

With two or more uplinks a switch teams them. Teaming modes:

• Active / standby failover — one active, the rest hot spare. No physical-switch configuration.
• Load-balance, adaptive — no physical-switch configuration.
• Load-balance by MAC/IP hash — requires a matching static link aggregation on the physical switch.
• LACP (802.3ad) — requires a matching port-channel on the physical switch.

Logical Distributed Switch (per cluster)

Declare a distributed switch once on a cluster's Networks tab; SimpleVirt realizes it on every member. Its Networks/port groups, uplink slots, and VLANs stay consistent across the cluster. On an individual host, a switch or port group that came from a distributed switch is marked Distributed and is read-only there — you manage it from the cluster, not the host — because SimpleVirt-Command owns it.

The cluster's networking view rolls up network and VLAN health across members and surfaces mismatches, so a port group that is missing or on the wrong VLAN on one host is visible before it strands a migration.

Service adapters and the migration network

A service adapter is the host's own IP address on one of its networks, created from Host → Settings → Networking → Add service adapter. Beyond management, the one that matters most is Migration: live migration, host evacuation, and the workload distributor all move guest memory between hosts over each host's Migration adapter.

Give every member of a cluster a Migration adapter on the same, dedicated, isolated migration VLAN. That VLAN is a deployment prerequisite, not a tuning option: guest data is encrypted and mutually authenticated in flight by default (qemu+tls / VIR_MIGRATE_TLS), but the libvirt control listener on TCP 16509 is unauthenticated, and the network is what protects it. See Migration network for what "isolated" has to mean.

Port group details

A port group's Settings tab states its VLAN and its switch and is read-only: port groups are created and deleted, not edited in place. To change a VLAN, create the network you want and move VMs to it.

5. Storage

SimpleVirt presents storage as Datastores, each a first-class object with tabs Overview │ Health │ Settings │ Hosts │ VMs │ Files │ Reclaim. The Storage lens lists every datastore and the hosts that mount it.

Add a datastore

From a host's Settings → Storage, choose Add datastore and pick a type. For an NFS share on a cluster, you also choose Availability:

• Shared across the cluster — SimpleVirt mounts the share on every member, so a VM on it can run on, and migrate to, any host.
• This host only — mounted on the one host.

Non-shared types are host-local by nature. A datastore carries a stable storage identity, so the same shared datastore reported by several hosts is grouped into one object rather than appearing many times.

Browse and manage

• Files — browse the datastore's contents (ISOs, disks).
• Hosts — which hosts mount it, and whether each mount is active.
• Health — capacity and health, including warnings when a host cannot read the datastore (an unreadable host contributes zero VMs, which can make a datastore look emptier — and safer to remove — than it is; the page says so).

Unmount a datastore from a single host from its row menu; the action names the host so you always know what you are detaching.

SimpleVirt HCI — pooled resilient cluster storage

SimpleVirt HCI turns the local disks across a cluster's hosts into one pooled, replicated datastore that every member can reach. A VM on SimpleVirt HCI storage keeps a resilient copy of its data across hosts, so a single host or disk failure does not take the data offline.

Set it up from the cluster's SimpleVirt HCI tab, which walks you through selecting hosts and disks and configuring the storage network. Once running, the tab is a live console:

• Overview — protection status and available capacity, in plain terms.
• Hosts & Disks — the disks contributing to the pool and their state.
• Datastores — the one datastore SimpleVirt HCI presents (VM disks and files together).
• Virtual Objects — every virtual disk, how many copies it keeps, and where they physically live.
• Data & Resync, Health, Performance, Network, Advanced — live operational detail.

SimpleVirt HCI speaks in outcomes — protection, resilience, available capacity — rather than storage internals. See SimpleVirt HCI: one datastore, health and virtual objects for how maintenance is reflected in health and how to read where your data lives. Destroying the pool is deliberately hard: it lives in a Danger zone and requires typing the exact cluster name.

6. Clusters

A cluster groups hosts for shared placement, availability, and pooled storage. Open one from the Hosts and Clusters lens.

Membership

From the Datacenter or a cluster page you can Create cluster, Add hosts, Move a host between clusters, and Remove a host or cluster. When you add hosts you enter each host's address and a shared admin sign-in once; SimpleVirt-Command connects to each host and pairs with it automatically. The admin credentials are used once and never stored. Hosts are paired one at a time, so one bad host never blocks the rest, and a failed row can be retried in place.

Cluster tabs

• Overview — health and roll-up.
• Settings — General, Datastores (cluster-wide declarations), High availability, and SimpleVirt Workload Distributor.
• Hosts, VMs, Datastores — membership and roll-ups.
• SimpleVirt HCI — pooled storage (section 5).
• Networks — the cluster's distributed switches (section 4).
• Stretched Cluster — two-site protection (section 7).

High availability

SimpleVirt HA restarts a failed host's VMs on surviving hosts. Configure it on the cluster's High availability tab.

• The tab renders a readiness checklist: every requirement, what SimpleVirt observed, and what to do about anything failing. A cluster that is not ready cannot arm HA.
• Failover mode:
  • Automatic — SimpleVirt-Command restarts a failed host's VMs itself.
  • Ask me first — SimpleVirt proposes the failover and waits for your approval; pending approvals appear on this tab.
• The tab lists the failover actions SimpleVirt has actually taken on the cluster.

HA is honest about state: an enabled, automatic cluster is told plainly that SimpleVirt will restart a failed host's VMs; an enabled cluster whose readiness is currently failing is told it is not active. HA fires only on a genuine host death, not a brief reboot blip, and it never claims protection it cannot deliver.

Admission control — an HA reserve — keeps enough spare capacity to restart a failed host's VMs. When the reserve is configured, SimpleVirt rejects a power-on or create that would consume the headroom needed for failover.

Two boundaries to plan for: HA requires VM storage on NFSv4.1 or SimpleVirt HCI — it will not arm on NFSv3 — and failover is driven by SimpleVirt-Command, so the controller must be reachable when a host dies. See Known limitations.

Workload Distributor (load balancing)

The SimpleVirt Workload Distributor balances VMs across a cluster's members. Configure it on its tab:

• Recommend — SimpleVirt computes balancing moves and lets you apply them. The safe default.
• Automatic — SimpleVirt applies balancing moves itself, one at a time, each gated by the migration precheck.

You can also set host-affinity rules per VM (pin a VM to, or keep it off, specific hosts). Every move SimpleVirt makes still runs the same compatibility precheck as a manual migration.

7. Stretched Cluster

A Stretched Cluster spans two datacenters so that workloads survive the loss of an entire site. Configure and operate it from a cluster's Stretched Cluster tab.

Status: validated in simulation and single-site lab; full two-datacenter hardware validation is pending. The feature has graduated out of the experimental preview gate, so its tab and endpoints need no flag — but graduation did not relax any safety check. Configuration records your intent; enabling activates stretch mode only when the fail-closed readiness checks pass, so a cluster that is not a genuine two-site topology with a Witness can never be activated. Treat a first activation on real two-site hardware as a carefully monitored change, not a routine one. See SIMPLEVIRT_STRETCHED_CLUSTER.md.

Topology

• Site A and Site B — the two datacenters, each holding hosts.
• Witness — a tiebreaker at a third location that decides which site keeps running if the two sites lose contact.

Storage protection

SimpleVirt supports two storage backends for a Stretched Cluster:

• SimpleVirt HCI (stretched) — SimpleVirt owns a resilient copy of your data across both sites and requires a Witness to arbitrate. This backend gives you site-level data protection managed by SimpleVirt.
• External shared datastore — a datastore reachable from both sites. Here SimpleVirt owns compute failover and fencing; it does not claim the external storage array itself survives the loss of a storage site. Use this only when your storage is already stretched by other means.

Readiness — is it safe to enable?

The tab answers, in administrator language, three questions: what is my state, what do I do next, is it safe to enable. It validates and reports:

• Site placement — hosts assigned to Site A and Site B.
• Storage protection — data protected across both sites.
• Witness arbitration — the Witness role is present and healthy.
• Inter-site networking — the sites can reach each other.
• Failover capacity — each site can absorb the other's workload.

Any fact SimpleVirt has not yet validated reads Not validated — never a false green. A guided Next steps list walks you to a state where enabling is safe, and Enable is offered only when the cluster is ready. Storage/monitor internals stay under Advanced readiness; the primary surface is plain-language.

Operating

Once enabled, the tab is a protected dashboard showing each site's status, the Witness, and per-site failover readiness. If a site is lost, it shows a controlled degraded view rather than a false all-clear. A non-destructive preview lets you review every lifecycle and failure state without touching the live cluster.

8. Health, Tasks, and Events

Health Center

The Health Center (top bar) is one page that answers "what is wrong in my environment?" — grouped by subsystem (Compute & Hosts, Virtual Machines, Storage, SimpleVirt HCI, Networking, and more). Every item links straight to the affected object. Subsystems SimpleVirt does not yet evaluate are shown honestly as not-yet-monitored rather than a green OK it cannot back.

Tasks

The Recent Tasks dock (bottom) streams what the fleet is doing live, and reflects the controller's own task log — so you see work started by anyone, or by SimpleVirt-Command itself. The full history lives under Administration → Tasks & Events.

Events and Alarms

Objects carry an Events view (a host's Health → Events, the fleet event log on Home). Alarms surface conditions that need attention and roll up into the Health Center. Together, Tasks tell you what was done, Events tell you what happened, and Alarms tell you what is wrong.

9. Users and access

Open Administration (top bar, next to your name). This is SimpleVirt-Command's own settings — who can sign in to the controller and which directory authenticates them. A host's own local users live on that host's page, because break-glass access to a host is a host-local decision. A host signs in local accounts only: a directory never authenticates directly to a host, so directory sign-in always comes through SimpleVirt-Command, where per-capability access control applies.

• Users — the accounts that can sign in to SimpleVirt-Command.
• Directory (LDAP / Active Directory) — connect an external directory so your organization's accounts and groups sign in. Access is default-deny.
• Access control — roles and per-capability permissions that gate what an account can do.
• Certificates — the controller's certificate: keep the self-signed default, upload a signed certificate, or generate a signing request (CSR) and install the issued certificate.
• Backup & Restore — back up the controller's own state (an audited archive) and restore it.
• Tasks & Events — the full activity history.
• About — build information.

10. Lifecycle and updates

Update SimpleVirt from Administration → Lifecycle & Updates.

SimpleVirt is updated from a single artifact: the signed SimpleVirt installer .iso, the same image that installs an appliance. It is verified before it is applied, so an update either arrives intact and trusted or is refused — there is no unsigned side path, and no second file format to keep track of. The flow is upload → verify → stage → apply. Update hosts and the controller from this one place; there is no other supported install or upgrade artifact.

Quick reference