Skip to content

Manual

hv version 0.0.0

Hosts and pools

A Pool groups Hosts under an xapi coordinator. Each Host retains its agent, physical devices and local storage. Add Hosts to increase capacity or provide migration destinations; joining alone does not make local disks shared. Before joining, prepare compatible Hosts, working management connectivity and an administrator login for the coordinator.

Add a host

A newly installed Host begins in its own Pool. Public-profile admission uses a short-lived join code so that otherwise restricted xapi connections can be opened for joining.

  1. On the new Host's console, run hv-agent pool join-code. Keep the returned code private; it is valid for 15 minutes and usable once.
  2. On the coordinator, open System, Pools, select the Pool and choose Add host.
  3. Supply the joining Host's address and login, the join code for a public Host, and the coordinator login requested by the sheet.
  4. Review the certificate trust choice and the Host identity. Submit the join and inspect the result.
  5. Confirm that the Host appears in the intended Pool, its agent is reachable, its Networks and SR connections are correct and the mesh has reconciled where enabled.

Private-profile joins do not need the public join code. Joining a NATed Host through mesh management uses a different enrollment path; it is not interchangeable with the ordinary public-address sheet. Resolve that deployment before trying a normal join.

Add capacity to a first pool

For example, hv-01 already runs the production workloads and you want hv-02 to receive VMs during maintenance. Install hv-02 using the installation procedure and check its management connection before joining. Record the two Host identities and addresses; a join request must target the new server, not the existing coordinator under another name.

Keep both Host consoles available. Generate the public join code only when you are ready to submit the join, because it expires. Enter the new Host's reachable address and the requested login details in Add host, then verify its certificate identity. If the code expires while you are resolving connectivity, generate a new one and submit the corrected request. Do not distribute the code in a general support log.

After the join, check that the intended Pool lists both Hosts. Inspect agent reachability and the new Host's physical interfaces. Compare the SR connections and Networks with those required by web-01. A Host can appear in inventory while still lacking a storage connection needed for a particular VM. Resolve that missing connection before scheduling maintenance on hv-01.

Finally, test moving an appropriate noncritical VM using live migration. Check the resulting placement and the guest's access to disks and services. Adding CPU and memory is useful, but the destination is ready for this workload only when all its dependencies are available. Keep that test separate from the first production maintenance operation so that a configuration problem does not become an unexpected outage.

Maintain a host

Maintenance disables new placement and attempts to evacuate resident VMs. Ensure other Hosts can receive their memory, storage and Networks, or shut the VMs down in a planned outage.

hv host maintenance enter HOST --pool POOL
hv host show HOST --pool POOL
hv host reboot HOST --pool POOL
hv host maintenance exit HOST --pool POOL

Run the reboot only after confirming evacuation and readiness; run the final command only after the Host returns healthy. A failed evacuation may leave the Host disabled with VMs still resident. The normal power operation refuses a Host with resident VMs even when its enabled-state check is forced.

For a planned reboot of hv-01, first review every resident VM. Ensure hv-02 can receive them, including their storage and Network attachments. Check for assigned devices that tie a VM to its current Host. If one workload cannot migrate, agree a shutdown with its owner before beginning the maintenance operation.

Enter maintenance and inspect the resulting Tasks and Host state. Disabling placement prevents new workloads arriving, but does not prove that all existing workloads have left. Confirm that no VM remains resident before rebooting. If evacuation stops on web-01, leave the Host's power unchanged while you inspect that VM's migration error.

After the Host returns, check its Pool membership, agent, SR connections and Networks. Exit maintenance only when those checks pass. Verify the applications that were moved as well as the rebooted Host. A successful boot is not the same result as restored workload availability, especially when shared storage or physical switching was also maintained.

Coordinator and dom0 mode

Member dashboards normally redirect to the coordinator. Changing the coordinator is a deliberate Pool operation; inspect connectivity and state before using hv pool designate-master. A Host behind NAT is refused as coordinator with mesh management.

PVH is the normal requested dom0 mode. PCI/GPU passthrough and SR-IOV require PV and an active IOMMU. hv host dom0-mode HOST pv --pool POOL schedules PV for the next boot; it does not transform the running control domain.

GRUB records a PVH boot attempt. If the agent never confirms it and the machine reboots, the next boot tries PV; after two consecutive failures it remains on PV until PVH is explicitly selected again. Without an IOMMU, PV lets ordinary operation continue. This fallback handles failed boots followed by reboot, not an indefinitely hung system. Inspect the Host's fallback indication and boot diagnostics rather than repeatedly selecting PVH.

Remove and troubleshoot

Before hv pool eject, evacuate the Host, inspect storage dependencies and ensure it is not the active coordinator. Read the command's confirmation and the resulting membership. Ejection is not a data-backup operation.

For join refusals, preserve the xapi error name, confirm time, login, certificate identity and admission-code validity. For inaccessible members, check management routing and agent trust before changing coordinator state. For maintenance failures, follow live migration and inspect the individual blocked VM.