Skip to content

Manual

hv version 0.0.0

Installation

Installation turns a physical machine into an hv Host, with an initial Pool, local SR and management services. It destroys the selected disk. Before starting, identify that disk, preserve any required data, record network settings and arrange console access that survives a management-network outage.

Prepare the installation medium

Obtain the release ISO and its checksum from your release operator. Download the image for the version you intend to install, then compare its checksum with the published value. If they differ, stop and obtain a matching image before writing any medium. Keep the release details with your installation notes so that you can identify the installed version later.

You can write the ISO to a USB stick or mount it as virtual media at a bare-metal provider or through the server's BMC. Virtual media is useful when you cannot reach the server physically. In either case, select UEFI boot and keep the console available through the first restart.

Write a USB stick on Linux

Writing the image destroys all contents of the selected device. Identify the USB by its model and capacity, and unmount its mounted partitions before writing. Use the whole device, not a partition. In this example, hv-release.iso is the downloaded image and /dev/sdX is a placeholder for the USB device. Replace both after checking them; selecting the workstation's system disk would destroy it.

sudo dd if=hv-release.iso of=/dev/sdX bs=4M conv=fsync
sync

Wait for dd to finish successfully and for sync to return before removing the stick. An error or interrupted write means the medium is not ready. Check the destination and image, then repeat the write only to the confirmed USB device. The CLI reference explains the arguments and the distinction between workstation and Host commands.

Write a USB stick on macOS

Use the disk listing to identify the USB's disk number. Unmount the whole USB disk before writing; keep it connected. /dev/diskN and /dev/rdiskN below refer to the same USB, with N replaced by the verified disk number. These are placeholders, not a suggested destination.

diskutil list
diskutil unmountDisk /dev/diskN
sudo dd if=hv-release.iso of=/dev/rdiskN bs=4m
sync
diskutil eject /dev/diskN

Proceed to the next command only if the preceding one succeeded. The write erases the entire selected device. Wait until writing and synchronization finish before ejecting. You can also use a graphical disk-image writer: select the ISO, check the whole USB destination, and write the image. Copying the ISO into a folder on the stick does not create the installation medium.

Mount virtual media

Open the provider's server console or the BMC console, select its virtual-media facility and attach the downloaded ISO. Select that virtual CD/DVD as the UEFI boot device. Keep the media attached while the installer reads it; disconnect it after installation, before booting the installed disk. If the server returns to the installer after restart, check boot order and virtual-media attachment before confirming anything that could erase the disk again.

Run the interactive installer

The interview appears on tty1. A serial console may show boot output without showing that interview; recovery logins are available on tty2 and the serial console.

  1. Select the disk, hostname and timezone.
  2. Select the management NIC by its listed number, name or MAC. Review its reported DHCP lease. Configure DHCP or static IPv4, an optional VLAN and optional IPv6.
  3. Supply the root credential. This is the dom0 login, separate from an hv Account.
  4. Choose public or private. Public is the default. Supply the first administrator details, or leave the e-mail empty for a setup token at first boot.
  5. Review the release repository and channel. Keeping the ISO's repository avoids a new trust decision. Another repository URL requires its root-key fingerprint and network access before disk changes.
  6. Review dom0 mode, local SR size and Pool creation or join settings. Confirm the disk erasure only after checking the complete selection.
  7. Wait for completion, detach the ISO or USB, and boot the installed disk. Continue with first boot.

A failed installation does not restore the disk's previous contents. Preserve the failing step and diagnostic, and do not run two installers against the same disk.

Unattended installation

Use an answer file prepared for the same hv release and reviewed for this specific Host. Keep a private copy and replace every demonstration value before use. The file needs the installation disk, hostname, timezone, root credential and network selection. The optional [admin] table seeds the first hv Account; omit it for the setup-token procedure. Do not copy the sample credentials into an installation.

An answer file is consent to erase its selected disk: unattended execution has no additional erase question. From the live recovery console, stop the automatic installer before running another instance:

rc-service hv-installer-live stop
hv-installer --answers /root/answers.toml --dry-run
hv-installer --answers /root/answers.toml

Run the final command only after reviewing the plan. Dry-run checks answers and prints steps; it does not prove NIC existence or real bootability. reboot defaults to false. If enabled, change boot order so the machine cannot reinstall itself from the same answers.

The installer also accepts hv.answers=SOURCE and hv.answers_sha256=HEX on the boot command line. Use a local file or trusted HTTPS source; never place credentials in a URL. Remote answer fetching needs networking in the live environment, which may not yet match the final Host's static network.

Single-NIC public servers and pool joins

Use the provider's assigned MAC and addressing. With static prefix 32 the gateway may be outside the address's subnet; the installed on-link gateway service supplies the necessary route. IPv6 is configured in addition to IPv4. Do not assume a guessed interface name or attach VM MAC addresses to a provider network that disallows them.

The public profile places administration on port 8443 by default. It does not complete edge NIC handover. For a new public server, installing its initial Pool and then using the console's join-code procedure is the documented route; see adding Hosts. The answer schema also supports [pool] mode = "join", coordinator address and login, but public admission still requires the join-code procedure. Use the interactive post-install join for public Hosts.

After boot, check the management address, route, service state, Pool membership and local SR. If the disk or NIC is missing, resolve driver or firmware support before repeating installation. If access fails, use the console and troubleshooting, not another disk wipe.

Check a completed installation

For example, after installing hv-01 at 192.0.2.10, use the management URL printed by that Host rather than guessing from another server's profile. Sign in, check that hv-01 belongs to its initial Pool, and inspect the local SR. The first-boot chapter covers Account setup and read-only service checks. Complete those checks before adding the server to an existing Pool or creating workloads.

The installation disk contains two root slots for platform updates, shared management state and local VM storage. Those areas have different recovery roles. A root rollback does not restore the original disk contents or roll back guest data. Plan backups after installation, before placing irreplaceable data on the Host.

If the management URL does not respond, return to the server console and inspect the address and route. Compare them with the recorded settings, including any management VLAN or provider-specific gateway. A reachable server with a failed sign-in needs Account recovery; an unreachable address needs network or service diagnosis. Neither problem calls for reinstalling first.