Solusvm2
SolusVM Documentation

XML Patching

Overview

In some cases, SolusVM’s generated libvirt configuration requires additional modifications on a per-host or per-VM basis. XML patching allows you to adjust the generated domain XML for individual compute resources and VMs.

Important:

  • You can only use XML patches on KVM virtual servers.
  • This feature requires administrator-level access to the compute resource’s filesystem.
  • Make certain that you thoroughly test any XML patch customizations. WebPros is not responsible for any downtime or issues that custom files cause.

Add a patch

To add a patch, create a valid patch file and upload it to the appropriate location:

  • For host-wide patches, upload the file to the following location:
    /usr/local/solus/patches/kvm_domain_patch.xml
  • For VM-specific patches, upload the file to the following location, where VM_UUID is the target VM’s UUID:
    /usr/local/solus/patches/VM_UUID/domain.xml

After you add the patch file, SolusVM will automatically read and apply it during the next operation that updates the configuration.

  • For new VMs, SolusVM applies the patch during VM creation.
  • For existing VMs, SolusVM applies the patch during the next update, resize, reinstallation, or offline migration.
    • The patch takes effect after the VM restarts with the updated XML configuration.
    • To apply the patch immediately, trigger one of these operations after adding the patch file.

Note:

If a VM-specific patch and a host-wide patch both exist, the VM-specific patch will take precedence.

Patch files

The patch file must be a valid XML diff document that uses XPath sel expressions to select nodes in the domain XML.

To see the XML structure that your selectors should target, run the following command, where VM_UUID is the UUID for an existing VM:

virsh dumpxml VM_UUID --inactive

Note:

For more information about correct XML diff document formatting, read RFC 5261.

Supported operations

Patch files support the following XML diff operations:

OperationDescription
<replace sel="...">Replace an existing element.
<replace sel="...@attr">Replace an existing attribute value.
<add sel="...">Add a child element under the selected node.
<add sel="..." rejectsel="...">Add a child element under the selected node but avoid creating a duplicate if that child element already exists.

Unsupported operations

XML patching in SolusVM does not support:

  • The <remove> operation.
  • <add> operations that add attributes or namespace declarations.
  • Operations that replace namespaces, comments, processing instructions, or text nodes.

If you use any of these operations, the system will silently ignore them.

Examples

The following examples show some possible uses of XML patching:

Custom QEMU command-line argument

The following XML file would add a custom QEMU command-line argument to every VM on the compute resource:

<diff>
    <add sel="domain">
        <qemu:commandline xmlns:qemu="http://libvirt.org/schemas/domain/qemu/1.0">
            <qemu:arg value="-some-flag"/>
        </qemu:commandline>
    </add>
</diff>

Add AVIC settings

The following XML file would modify AVIC on a VM:

<diff>
  <!-- 1. Change vapic state from 'on' to 'off' (skipped if hyperv absent) -->
  <replace sel="domain/features/hyperv/vapic/@state">off</replace>

  <!-- 2. Add <avic state='on'/> inside <hyperv> (skipped if hyperv absent) -->
  <add sel="domain/features/hyperv" pos="after" type="element">
    <avic state='on'/>
  </add>

  <!-- 3. Add <feature policy='require' name='x2apic'/> inside <cpu> -->
  <add sel="domain/cpu" type="element">
    <feature policy='require' name='x2apic'/>
  </add>

  <!-- 4. Add <timer name='pit' tickpolicy='discard'/> inside <clock> -->
  <add sel="domain/clock" type="element">
    <timer name='pit' tickpolicy='discard'/>
  </add>
</diff>

Add a vmport state if it does not already exist

The following example would only add the vmport state if no vmport argument is already present:

<diff>
    <add sel="domain/features" rejectsel="domain/features/vmport">
        <vmport state="off"/>
    </add>
</diff>

Failures

If the patch file is invalid or it causes an invalid libvirt XML file, the operation will fail and previous VM definitions will remain.

Important:

For failures of host-wide patches, all VMs on that compute resource will fail until you update or remove the patch. For this reason, we strongly recommend extensive testing before deploying patches to production use.

Migrations

During both offline and live migrations, VM-specific patches migrate with their associated VMs.

For host-wide patches, migration behavior depends on the type of migration:

  • For offline migrations, the VM will migrate with an unpatched definition. After migration, the destination compute resource will apply its patch (if one exists).
  • For live migrations, the VM will migrate with its current (patched) configuration. However, migration will fail if the patched configuration is not compatible with the destination.

Remove a patch

To remove a patch from a VM or compute resource, delete the patch file. The patch removal will apply to each VM during the next defining operation.

Prev
Virtual Private Cloud
×