Virtual Machines

The Virtual Machines panel allows you to control the lifecycle of guest operating systems, manage configuration files, and clone resources.

A. Basic State Operations

• From the primary VM list, you can filter by current execution states: All States, Running, Stopped, Paused, or Suspended.
• Action shortcuts allow administrators to execute quick power state commands: Start, Stop (Graceful), Force Stop, Restart, or Force Restart.

B. Accessing Guest Consoles

• Selecting a running virtual machine allows you to launch an interactive VNC Console directly within the web browser.
• This provides low-level graphical or command-line operating system login control (tty1), ideal for initial setups, networking fixes, or checking hostnames.

C. Modifying Virtual Hardware Configurations (Edit & XML Editing)

When a virtual machine needs resource adjustments, navigate to the Edit action panel:

• Compute Options (Basic & Advanced): Adjust settings for Maximum Memory, Max vCPUs, CPU Pinning Configurations, Sockets, Cores, and Threads. You can also define the CPU Mode (e.g., host-passthrough) and specify advanced flags (e.g., enabling UEFI, Secure Boot, or TPM features).
• Direct XML Editing: For precise adjustments beyond standard toggle menus, choose Edit XML. This grants direct text-based access to the guest's libvirt XML domain definition mapping blocks (such as modifying <domain type='kvm'>, <vcpu>, <memory>, or backing file definitions directly).

D. Templates, Cloning, and Snapshots

• Cloning VMs: Create duplicates by initiating the Clone action. Enter a unique name for the new clone, select a target destination storage pool, and choose the Guest identity (see section E). A clone is always a full, independent copy of every disk image of the source VM: it does not depend on the source afterwards, and the larger the disks, the longer the clone takes. Linked (copy-on-write) clones are not available, and the source's snapshots are not copied to the clone. A host block device attached directly to the source, read-only disks, and ISO images are not copied: the clone uses the same device or file as the source, so do not run both VMs at the same time while they share a writable device.
• Snapshots: Take point-in-time recovery images by selecting Create Snapshot. Provide a unique snapshot name (e.g., snap-01) and optional descriptive notes. You can choose whether to include active runtime memory inside the snapshot state.
• Templates: Convert an existing structured virtual machine deployment into a static baseline template configuration via the Convert to Template feature, or deploy new machines from previously captured templates. Deploying from a template offers the same Guest identity choice as cloning. See Snapshots & Templates.

E. Guest Identity of a Clone

A plain disk copy also copies everything the guest operating system uses to tell itself apart from other machines. When the source and an exact copy run at the same time, you typically see:

• both VMs getting the same IP address from DHCP;
• a clone of a VM built from a cloud image starting with no network at all;
• both VMs showing the same hostname, and SSH clients unable to tell them apart by host key.

The Guest identity setting in the Clone dialog decides what happens:

Option	What you get
Reset guest identity (recommended)	A clone with its own identity. Vapor edits the copied disks before the clone is started for the first time. The source VM is never changed.
Keep an exact copy	A byte-for-byte copy of the source's disks. Use it for restore tests, for a copy you keep for investigation, or for appliances whose licence is bound to the machine ID.

Reset guest identity is selected by default when the host can reset identities. When it cannot, Keep an exact copy is selected and the dialog shows why (see Host requirement).

What Reset guest identity changes

• Machine ID: /etc/machine-id (and /var/lib/dbus/machine-id when it is a separate file) gets a new random ID. DHCP servers that recognise clients by this ID then give the clone its own address. A machine ID set to uninitialized (a template prepared for first boot) is left as it is.
• SSH host keys: every host key is replaced by a new key of the same type and size. Clients that connected to the source see a different host key on the clone. An old DSA key is removed when the VM also has a newer key type. RSA keys larger than 4096 bits are replaced by 4096-bit keys, and the result includes a note about it.
• Network MAC bindings: the clone's network interfaces get new MAC addresses. Network configuration that names the source's MAC addresses (netplan, NetworkManager, ifcfg files, systemd-networkd, udev rules, /etc/network/interfaces) is updated to the clone's addresses, so the interfaces come up.
• DHCP leases: leases saved by the source are removed, so the clone asks for its own.
• Random seed: the saved random seed is replaced with new random data.
• Hostname: set from the clone name, in lowercase. Every character other than ASCII letters, digits, and hyphens becomes a hyphen, repeated hyphens are merged into one, leading and trailing hyphens are removed, and the result is cut to 63 characters. The domain of the source's hostname is kept when it is a valid DNS domain: web01.example.com cloned as web02 becomes web02.example.com. Matching names on the loopback lines of /etc/hosts are updated too. If nothing usable remains of the clone name, or the guest has no /etc/hostname, the hostname is left as it is.

Everything else stays as it was in the source: user accounts and passwords, users' SSH authorized keys, installed software and drivers, application data, and static IP addresses.

Static IP addresses

A static IP address is kept, so the clone has the same address as the source. The clone completes with a warning and is created with autostart turned off. Change the address before both VMs run on the same network, for example: keep the source stopped, start the clone, change its address from the VNC console, then start the source again.

Other things to check on a completed clone

The clone is created, and the result lists a warning or a note when:

• The source is joined to an Active Directory or Kerberos domain: the clone still uses the source's machine account, which can lock the source out of the domain. Remove the clone from the domain and join it again under its new name before connecting it to the network.
• cloud-init manages the hostname: cloud-init may set the source's hostname again on every boot. If the clone keeps showing the source's name, change the hostname in the clone's cloud-init configuration.
• Registration and management agents are configured (Red Hat Subscription Manager, Ubuntu Pro, Puppet, Salt, Chef): the clone still presents the source's registration. Register the clone again.

When the identity cannot be reset

When you chose Reset guest identity and the identity cannot be reset, the clone fails with the reason and no VM is created. Vapor checks the source VM before copying, so most of these cases are reported right away; the others are found on the copies before they are changed, and the copies are removed. Choose Keep an exact copy instead, then change the identity inside the guest before running both VMs:

Situation	What to do
Windows or another non-Linux guest	Keep an exact copy, then generalize the guest (on Windows, with Sysprep).
Encrypted disks (for example LUKS or BitLocker)	Keep an exact copy and change the identity inside the guest.
No operating system found on the disks, or more than one	Keep an exact copy.
A file system the host cannot modify, for example the XFS file system of RHEL 9 and its rebuilds (Rocky Linux, AlmaLinux) on hosts with an older kernel	Keep an exact copy and change the identity inside the guest.
Part of the guest's system, such as /var, is on a disk that is not copied with the clone (a host block device attached directly, or a read-only disk)	Move that part of the system to a disk image in the source VM, then clone again. An exact copy would still share that device with the source.
The VM has more than one network interface, and its network configuration names a MAC address that none of the source's network interfaces has	Remove or correct the stale entry in the source VM, then clone again. With guest_identity set to auto, this is only a warning and the reset still completes.
The only SSH host key is a DSA key	Add a current key type in the source VM (sudo ssh-keygen -A), then clone again.

To change the identity of a Linux clone yourself, run inside the clone:

sudo rm -f /etc/machine-id /var/lib/dbus/machine-id
sudo systemd-machine-id-setup
sudo hostnamectl set-hostname <new-name>
sudo rm -f /etc/ssh/ssh_host_*
sudo ssh-keygen -A
sudo systemctl restart ssh    # the service is named sshd on RHEL-family guests

If something goes wrong while Vapor is editing the copied disks, the clone fails as a whole: the copies are removed and no VM is created. The source VM is not affected.

Guest agent

A clone keeps the source's QEMU guest agent connection, so features that rely on the agent (filesystem quiescing for snapshots and backups, guest IP reporting) work on the clone as they do on the source.

Host requirement

Resetting the identity needs guestfish (part of libguestfs) on the Vapor host. Install it as root:

# Debian 12 and later, Ubuntu 22.04 and later
sudo apt-get install guestfish libguestfs-xfs

# Debian 11, Ubuntu 20.04
sudo apt-get install libguestfs-tools libguestfs-xfs

# RHEL 9 and rebuilds (Rocky Linux, AlmaLinux)
sudo dnf install libguestfs libguestfs-xfs

# RHEL 8 and rebuilds
sudo dnf install libguestfs-tools-c libguestfs-xfs

You do not need to restart Vapor. Vapor looks for the tool again each time the Clone dialog opens and then checks it with a short self-test in the background. If Reset guest identity is not preselected or is disabled, close the dialog and open it again after a minute. If it is still unavailable, the reason in the dialog says what the host is missing or what the self-test reported.

Hosts with a kernel older than 5.15

Vapor resets the identity inside a small helper VM, the libguestfs appliance, which boots the host's own kernel. A clone of a running VM is a crash-consistent copy, and the file system of a modern guest such as Debian 13 is then in a state that a kernel older than 5.15 cannot mount for writing. On such a host the identity of that clone cannot be reset (reason unmountable): depending on the choice, the clone either fails or is created as an exact copy with a warning, and an exact copy usually starts with no network. Clones of a stopped VM are not affected.

This affects Ubuntu 20.04 (kernel 5.4) and Debian 11 (kernel 5.10). Since Vapor 3.3.2, a new installation on Ubuntu 20.04 gives the appliance a 5.15 kernel: it downloads the 5.15 HWE kernel and extracts it under /opt/vapor-guestfs-kernel/<release> without installing it, so the host's own kernel and boot are unchanged. A host upgraded in place does not get it. Do the same by hand, as root:

REL=$(apt-cache depends linux-image-generic-hwe-20.04 | grep -o 'linux-image-5\.15[^ ]*' | sed 's/linux-image-//')
D=/opt/vapor-guestfs-kernel/$REL; T=$(mktemp -d)
(cd $T && sudo apt-get download linux-image-$REL linux-modules-$REL)
for f in $T/*.deb; do sudo dpkg-deb -x $f $D; done; sudo depmod -b $D $REL
sudo mkdir -p /etc/systemd/system/vapor.service.d
printf '[Service]\nEnvironment=SUPERMIN_KERNEL=%s\nEnvironment=SUPERMIN_MODULES=%s\n' \
  "$D/boot/vmlinuz-$REL" "$D/lib/modules/$REL" | sudo tee /etc/systemd/system/vapor.service.d/guestfs-kernel.conf
# The appliance is cached; clear it so it is rebuilt with the new kernel.
sudo rm -rf /var/lib/vapor/guestfs-cache/.guestfs-0
sudo systemctl daemon-reload && sudo systemctl restart vapor

To undo it, remove /etc/systemd/system/vapor.service.d/guestfs-kernel.conf and restart Vapor. On Debian 11, a newer kernel comes from bullseye-backports, and the same steps apply with that kernel's packages. Without any of this, clone such VMs while they are stopped.

For API clients

The clone requests (POST /api/v1/virtualization/computes/{id}/clone and POST /api/v1/virtualization/computes/clone) and deploy from template (POST /api/v1/virtualization/computes/from-template) accept a guest_identity field:

Value	Behaviour
reset	Reset the identity. If it cannot be done, the request fails: 409 with IDENTITY_RESET_UNAVAILABLE (the host cannot reset identities) or IDENTITY_RESET_UNSUPPORTED_GUEST (the guest cannot be reset; the details carry a reason_code), or, once the copy has started, a failed clone with the same error_code in the progress events.
auto	Reset the identity when possible. If Vapor finds that it cannot before it changes anything on the copies, the clone is an exact copy and the result reports why as a warning.
keep	Make an exact copy.

If the reset tool itself fails or times out, the clone fails with IDENTITY_RESET_FAILED and the reason_code tool_error or timeout: deploy from template answers 500, and a clone reports the code as the error_code in its progress events.

When the field is omitted, the host default applies: clone_guest_identity_default in vapor.conf (or the VAPOR_CLONE_GUEST_IDENTITY_DEFAULT environment variable), either auto (the default) or keep. The final clone event (and, for deploy from template, the response) carries an identity_reset object with status (done, kept, or failed), reason_code, reason, the new hostname, and the warnings described above. GET /api/v1/virtualization/computes/clone/capabilities reports whether the host can reset identities and, if not, why.