Editing domain definition¶

Although not recommended it's sometimes needed (or easier to perform a task) to edit a domain XML file manually. Domain's XML can be edited with the following command:

# virsh edit dom

This command starts an editor with the current definition of the domain. After you finish your edits and save the changes, the XML is reloaded and parsed by libvirt. If the XML was correct, following message is displayed:

# virsh edit dom

Domain dom XML configuration edited.

Please note, that when using the "edit" command in virsh after incorrectly editing a XML, the changes are not saved. Consider saving your changes before exiting the editor.

Once you have saved the XML it is possible to use the virt-xml-validate command to check for usage problems:

# virt-xml-validate config.xml

If there are no errors then your description is well-formed from an XML point of view and matches the libvirt schema. The schema cannot catch all constraints, but fixing any reported errors will get you further along.

Passing XML documents to libvirt¶

Numerous API functions of libvirt (and their implementation in virsh) take XML documents as their arguments. This documents are passed to the XML parser, that detects syntax errors and then are processed internaly. Most errors

XML documents stored by libvirt¶

These documents contain definitions of domains, their states and configurations. All of those documents are automatically generated and should not be edited manually. Errors in these documents contain the file name of the broken document. The file name is valid only on the host machine defined by the URI. (It may be the machine the command is run on.)

Errors in files created by libvirt are very rare. One possible source of these errors is a downgrade of libvirt; newer versions of libvirt will always be able to read XML generated by older versions, but older versions of libvirt may be confused by XML elements added in newer libvirt.

Extra stray "<" in the document¶

This snippet of a domain XML contains an extra "<" in the document:

<domain type='kvm'>
  <name>domain</name><
  <memory>524288</memory>
  <vcpu>2</vcpu>
  ...

Symptom

Libvirt produces following message:

  error: (domain_definition):6: StartTag: invalid element name
  <vcpu>2</vcpu><
-----------------^

This error message describes that the parser expects a new element name after the '<' symbol on line 6 of a domain definition XML document that was provided as a string.

Solution

Remove the extra "<" or finish the new element.

Unterminated attribute¶

This snippet of a domain XML contains a unterminated element attribute value:

<domain type='kvm>
  <name>domain</name>
  ...

Symptom

Libvirt produces following less obvious message:

error: (domain_definition):2: Unescaped '<' not allowed in attributes values
  <name>domain</name>
--^

Solution

Close all attribute value strings. (quotation marks and apostrophes)

Forgotten "/" in unpaired tag, unended tag¶

Following snippet contains an unended pair tag:

<domain type='kvm'>
 ...
 <features>
   <acpi/>
   <pae/>
 ...
</domain>

This is a example of a similar problem with a extra closing tag:

<domain type='kvm'>
  </name>
  ...
</domain>

Unpaired tags have to be ended with "/>". The following snippet contains an example of a tag not following this rule:

<domain type='kvm'>
  ...
  <clock offset='utc'>

Symptom

All of the errors above create the same error message:

error: (domain_definition):61: Opening and ending tag mismatch: clock line 16 and domain
</domain>
---------^

Identifying the root of the error is a little bit tricky. The error message contains three hints to identify the offending tag. The message after the last colon clock line 16 and domain states that the offending tag is <clock ... on line 16 of the source documment. The last hint is the tag provided in the context part of the message, that identifies the second offending tag.

Solution

End tags properly.

Typos in tags¶

Following examples contain flawed XML tags by a whitespace or special character typo

<domain type 'kvm'>
  ...

<dom ain type='kvm'>
  ...

<dom#ain type='kvm'>
  ...

Symptom

All of the mistakes above produce the following error message:

error: (domain_definition):1: Specification mandate value for attribute ty
<domain ty pe='kvm'>
-----------^

Solution

To identify the problematic tag, follow the guide provided by the pointer and context of the file.

Vanishing parts¶

The symptom is that parts of the change you made have no effect and do not show up once after editing or defining the domain, the define or edit command works but if you dump the XML again the change you made disappeared. A classical error when writing XML for libvirt from scratch instead of getting it generated is to use a broken construct or making an error in some of the syntax, like a misplaced or wrong tag or attribute name. The problem is that libvirt will generally only look for constructs that it knows and ignore everything else. So some of your changes made to the XML may vanish after libvirt parsed your input. The best way to check against such problems is to validate the XML input before passing it to edit or define commands:

Validating XML against libvirt schemas¶

Libvirt developers maintain a set of XML schemas bundled with libvirt and defining as much as possible the constructs allowed in XML documents used by libvirt. You can validate libvirt XML files using the following command:

# virt-xml-validate libvirt.xml

If that passes then chances are that libvirt will understand all constructs from your XML, though that is not an absolute guarantee, for example the schemas cannot detect options which are valid only for a given hypervisor, but that should help pinpointing problems. Any XML generated by libvirt for example as a result of a virsh dump command should validate without error (and failure to do so should be reported to the developers for fixing, thanks !)

Incorrect drive device type¶

Add a new cdrom drive or modify a existing one with the following XML:

<disk type='block' device='cdrom'>
  <driver name='qemu' type='raw'/>
  <source file='/path/to/image.iso'/>
  <target dev='hdc' bus='ide'/>
  <readonly/>
</disk>

Symptom

Definition of the source image for the cd-rom virtual drive is not present despite being added:

# virsh dumpxml domain
<domain type='kvm'>
  ...
  <disk type='block' device='cdrom'>
    <driver name='qemu' type='raw'/>
    <target dev='hdc' bus='ide'/>
    <readonly/>
  </disk>
  ...
</domain>

Solution

A disk device of type block expects that the source is a physical device. To use the disk with a image file use type file instead.