→ Applies to: Hyperion 9.x and above

By default, VMs created or converted for Hyperion may not include all available performance optimizations. syneto-vmtune allows you to audit and apply these optimizations in a few simple steps.

Step 1. Connect to Hyperion via SSH as admin

ssh admin@<your_ip_address_or_hostname>

Step 2. Get root privileges

sudo su -

Step 3. Download syneto-vmtune to the /tmp folder

wget -L -O /tmp/syneto-vmtune "https://files.syneto.eu/public.php/dav/files/YjKrGssMzHpGcqK"

Step 4. Make it executable

chmod +x /tmp/syneto-vmtune

Assessing Current VM State

assess reports each finding with a code (F = failure, W = warning, I = info). The section Understanding the Assessment Results explains each code and how to fix it.

Step 1. Check the current state of your VMs

/tmp/syneto-vmtune assess

Step 2 (Optional). View the full description of each optimization code

/tmp/syneto-vmtune assess --legend

IMPORTANT
The sections Installing Guest Agent Tools, Migrating the Storage Bus to VirtIO, Binding Data Disks, and Swapping the Emulated NIC to VirtIO are independent optional modules — apply only the ones relevant to your VM, based on what assess reported. They are not a strict sequence, but some have prerequisites:

• Migrating the Storage Bus to VirtIO requires Installing Guest Agent Tools to be done first — the VirtIO Guest Tools ISO must already be mounted.
• Binding Data Disks requires Migrating the Storage Bus to VirtIO first, but only if assess reports F1 (data disk still on SATA/IDE).
• Swapping the Emulated NIC to VirtIO is independent — no prerequisite on the other modules — but the virtio-net driver must already be installed inside the guest.

Understanding the Assessment Results

assess reports each finding with a code:

• F (FAIL): a configuration problem that affects how the VM works or performs.
• W (WARNING): a missing or suboptimal optimization.
• I (INFO): information only, no action needed.

The tables below explain each code and how it is fixed.

Fixed automatically by apply

These codes are fixed by the command in the Applying General Optimizations section.

NOTE
W20 is the only fix applied to the storage pool instead of the VM configuration. To skip it, add --skip-zfs-direct to the apply command.

IMPORTANT
If assess reports W15, suspend BitLocker inside the VM before running apply. Adding a TPM (W11) to a BitLocker-protected VM triggers a BitLocker recovery prompt at the next boot.

Optional fixes

These codes are not fixed by default. Apply them only when the conditions are met.

Fixed with migrate-bus

Manual fixes

These codes are reported but not fixed by syneto-vmtune.

Information only

Applying General Optimizations

Step 1. Apply general optimizations (replace <vm_name> with the correct information)

/tmp/syneto-vmtune apply <vm_name>

IMPORTANT
Ensure the VM is powered off before running this command.
A ZFS snapshot is automatically taken before any change is applied. All changes are fully reversible.

NOTE
If assess reports W15 (BitLocker), suspend BitLocker inside the VM before running apply. Otherwise the VM boots into BitLocker recovery.

Step 2. Disable nested virtualization (replace <vm_name> with the correct information)

/tmp/syneto-vmtune apply <vm_name> --only W21

IMPORTANT
Ensure the VM is powered off before running this command.
Skip this step if the VM uses WSL2, Windows Sandbox, Hyper-V, or Virtualization Based Security (VBS/Credential Guard).

Installing Guest Agent Tools (Optional — apply if the VM needs VirtIO drivers for storage or NIC migration)

Step 1. Login to SynetoOS GUI

Step 2. From Virtualization menu, click on Virtual machines

Step 3. Select the VM on which you want to apply the optimizations

Scroll down to the OS Details section until you see the Install button.

Step 4. Click on Install/Mount (next to the Guest agent tools entry)

Step 5. Click on Install

The VirtIO Guest Tools ISO will automatically mount to the VM's optical drive and any previously mounted ISOs will be ejected.

Migrating the Storage Bus to VirtIO (Optional — requires Guest Agent Tools installed first)

Migrate storage bus from SATA/IDE to VirtIO (replace <vm_name> with the correct information)

/tmp/syneto-vmtune migrate-bus <vm_name>

IMPORTANT

• Ensure that the QEMU Guest Agent and VirtIO drivers are installed inside the VM before running this command.
• The VM needs to be powered on during this operation. It will automatically reboot during the migration process.
• After migration, Windows may display the initial setup screen on first boot — ensure you have console or RDP access ready before proceeding.

NOTE
The VirtIO Guest Tools ISO needs to be mounted beforehand in order to migrate the storage bus.

Binding Data Disks (Multi-Disk VMs) (Optional — apply if the VM has multiple active disks)

Step 1. Sample the data disks to ensure they see meaningful traffic (replace <vm_name> with the correct information)

virsh domstats <vm_name> --block

Step 2. Bind data disks on a multi-disk VM (replace <vm_name> with the correct information)

/tmp/syneto-vmtune apply <vm_name> --only W18

Before applying:

VM shape	Without W18	With W18
1 disk	Optimal	No-op, nothing to bind
2 disks, data idle	Optimal	Wastes a kernel thread
2 disks, data hot (e.g. SQL log volume)	Data is the bottleneck	Likely +20–50% improvement
3+ active disks	Severe bottleneck	Big win

IMPORTANT
Ensure the VM is powered off before running this command.
W18 only works on virtio-blk disks. If assess reports F1 (data disk on SATA/IDE), migrate the storage bus first — see Migrating the Storage Bus to VirtIO. There is nothing for the iothread to bind to until the disk is on virtio.

Swapping the Emulated NIC to VirtIO (Optional — apply if assess reports F2)

Step 1. Swap an emulated NIC to virtio (replace <vm_name> with the correct information)

/tmp/syneto-vmtune apply <vm_name> --also F2

Three things can trigger F2, and one of them is invisible in the XML:

What “assess” sees	What the guest actually gets
<model type='e1000e'/>, e1000, rtl8139, ne2k_pci	That emulated NIC — usually a Windows install done with paravirt off
<model type='vmxnet3'/>, pcnet	Leftover from a VMware V2V import
No <model> element at all	QEMU's machine-type default — e1000e on q35, rtl8139 on i440fx

NOTE

• The third row is the one to watch — the XML looks clean, with nothing explicitly saying e1000e, yet the VM is still on an emulated NIC. assess names the model QEMU will actually pick, so the finding reflects what you truly have, not just what's written in the XML.
• SR-IOV passthrough interfaces (type='hostdev') are exempt — the guest sees the physical NIC directly, so there is no model to choose.
• The MAC address is preserved, so DHCP reservations and MAC-keyed firewall rules are not affected. However, Windows will still enumerate a new network adapter, since the underlying PCI device changes — this can affect static IP configurations, which will need to be reapplied to the new adapter.
• If the VM is still being installed (install ISO mounted with the guest agent disconnected — Syneto's standard paravirt-off installer flow), the fixer declines and reports "no change" for F2. Finish the OS installation first, then re-run this step.
• Use --only F2 instead if you want to change the NIC and nothing else.

IMPORTANT
Ensure the VM is powered off before running this command.
The virtio-net driver must already be installed inside the guest before running this command. A guest without the driver comes back from this change with no network at all — nothing in the XML tells the tool whether the driver is present.

Step 2. Verify the change (replace <vm_name> with the correct information)

virsh dumpxml --inactive <vm_name> | grep -A4 "<interface"

EXAMPLE OUTPUT

<interface type='network'>
  <mac address='52:54:00:91:f3:da'/>
  <source network='default'/>
  <model type='virtio'/>
  <link state='up'/>

The interface should now read <model type='virtio'/>.

Powering On and Verifying Results

Step 1. Power on the optimized VM

Step 2. Check network connectivity after VM has booted

virsh qemu-agent-command <vm_name> '{"execute":"guest-ping"}'

EXAMPLE OUTPUT

{"return":{}}

IMPORTANT
If the guest agent does not respond, or the VM has no network access after this change, the virtio-net driver was likely not actually present in the guest before the fix was applied. Roll back using the backup XML created.

Step 3. Check applied optimizations

/tmp/syneto-vmtune assess

The output should show no FAIL or WARNING codes for the optimizations applied in the previous steps.