Chapter 23. Manipulating the Domain XML

This chapter explains in detail the components of guest virtual machine XML configuration files, also known as domain XML. In this chapter, the term domain refers to the root <domain> element required for all guest virtual machines. The domain XML has two attributes: type and id. type specifies the hypervisor used for running the domain. The allowed values are driver-specific, but include KVM and others. id is a unique integer identifier for the running guest virtual machine. Inactive machines have no id value. The sections in this chapter will describe the components of the domain XML. Additional chapters in this manual may see this chapter when manipulation of the domain XML is required.

Important

Use only supported management interfaces (such as virsh and the Virtual Machine Manager) and commands (such as virt-xml) to edit the components of the domain XML file. Do not open and edit the domain XML file directly with a text editor. If you absolutely must edit the domain XML file directly, use the virsh edit command.

Note

This chapter is based on the libvirt upstream documentation.

23.1. General Information and Metadata

This information is in this part of the domain XML:

<domain type='kvm' id='3'>
  <name>fv0</name>
  <uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
  <title>A short description - title - of the domain</title>
  <description>A human readable description</description>
  <metadata>
    <app1:foo xmlns:app1="http://app1.org/app1/">..</app1:foo>
    <app2:bar xmlns:app2="http://app1.org/app2/">..</app2:bar>
  </metadata>
  ...
</domain>

Figure 23.1. Domain XML metadata

The components of this section of the domain XML are as follows:

Table 23.1. General metadata elements

Element Description
<name> Assigns a name for the virtual machine. This name should consist only of alpha-numeric characters and is required to be unique within the scope of a single host physical machine. It is often used to form the file name for storing the persistent configuration files.
<uuid> Assigns a globally unique identifier for the virtual machine. The format must be RFC 4122-compliant, for example 3e3fce45-4f53-4fa7-bb32-11f34168b82b. If omitted when defining or creating a new machine, a random UUID is generated. It is also possible to provide the UUID using a sysinfo specification.
<title> Creates space for a short description of the domain. The title should not contain any new lines.
<description> Different from the title, this data is not used by libvirt. It can contain any information the user chooses to display.
<metadata> Can be used by applications to store custom metadata in the form of XML nodes/trees. Applications must use custom name spaces on XML nodes/trees, with only one top-level element per name space (if the application needs structure, they should have sub-elements to their name space element).