.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "VIRT-XML" 1 "" "" "Virtualization Support"
.SH NAME
virt-xml \- Edit libvirt XML using command line options.
.SH SYNOPSIS
.sp
\fBvirt\-xml\fP DOMAIN XML\-ACTION XML\-OPTION [OUTPUT\-OPTION] [MISC\-OPTIONS] ...
.SH DESCRIPTION
.sp
\fBvirt\-xml\fP is a command line tool for editing libvirt XML using explicit command line options. See the EXAMPLES section at the end of this document to jump right in.
.sp
Each \fBvirt\-xml\fP invocation requires 3 things: name of an existing domain to alter (or XML passed on stdin), an action to on the XML, and an XML change to make. actions are one of:
.INDENT 0.0
.IP \(bu 2
\fB\-\-add\-device\fP: Append a new device definition to the XML
.IP \(bu 2
\fB\-\-remove\-device\fP: Remove an existing device definition
.IP \(bu 2
\fB\-\-edit\fP: Edit an existing XML block
.IP \(bu 2
\fB\-\-build\-xml\fP: Just build the requested XML block and print it. No domain or input are required here, but it\(aqs recommended to provide them, so virt\-xml can fill in optimal defaults.
.UNINDENT
.sp
An XML change is one instance of any of the XML options provided by virt\-xml, for example \-\-disk or \-\-boot.
.sp
\fBvirt\-xml\fP only allows one action and XML pair per invocation. If you need to make multiple edits, invoke the command multiple times.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-c\fP \fB\-\-connect\fP URI
Connect to a non\-default hypervisor. See virt\-install(1) for details
.TP
.B \fBdomain\fP
domain is the name, UUID, or ID of the existing VM. This can be omitted if
using \-\-build\-xml, or if XML is passed on stdin.
.sp
When a domain is specified, the default output action is \-\-define, even if the
VM is running. To update the running VM configuration, add the \-\-update option
(but not all options/devices support updating the running VM configuration).
.sp
If XML is passed on stdin, the default output is \-\-print\-xml.
.UNINDENT
.SH XML ACTIONS
.INDENT 0.0
.TP
.B \fB\-\-edit\fP [EDIT\-OPTIONS]
Edit the specified XML block. EDIT\-OPTIONS tell \fBvirt\-xml\fP which block
to edit. The type of XML that we are editing is decided by XML option that
is passed to \fBvirt\-xml\fP . So if \-\-disk is passed, EDIT\-OPTIONS select
which <disk> block to edit.
.sp
Certain XML options only ever map to a single XML block, like \-\-cpu,
\-\-security, \-\-boot, \-\-clock, and a few others. In those cases,
\fBvirt\-xml\fP will not complain if a corresponding XML block does not
already exist, it will create it for you.
.sp
Most XML options support a special value \(aqclearxml=yes\(aq. When combined
with \-\-edit, it will completely blank out the XML block being edited
before applying the requested changes. This allows completely rebuilding
an XML block. See EXAMPLES for some usage.
.sp
EDIT\-OPTIONS examples:
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fB\-\-edit\fP
\-\-edit without any options implies \(aqedit the first block\(aq. So
\(aq\-\-edit \-\-disk DISK\-OPTIONS\(aq means \(aqedit the first <disk>\(aq.
.sp
For the single XML block options mentioned above, plain
\(aq\-\-edit\(aq without any options is what you always want to use.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fB\-\-edit\fP #
Select the specified XML block number. So \(aq\-\-edit 2 \-\-disk DISK\-OPTS\(aq
means \(aqedit the second <disk>\(aq. This option only really applies for
device XML.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fB\-\-edit\fP all
Modify every XML block of the XML option type. So
\(aq\-\-edit all \-\-disk DISK\-OPTS\(aq means \(aqedit ever <disk> block\(aq.
This option only really applies for device XML.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fB\-\-edit\fP DEVICE\-OPTIONS
Modify every XML block that matches the passed device options.
The device options are in the same format as would be passed to
the XML option.
.UNINDENT
.UNINDENT
.sp
So \fI\-\-edit path=/tmp/foo \-\-disk DISK\-OPTS\fP means \(aqedit every <disk> with
path /tmp/foo\(aq. This option only really applies for device XML.
.TP
.B \fB\-\-add\-device\fP
Append the specified XML options to the XML <devices> list. Example:
\(aq\-\-add\-device \-\-disk DISK\-OPTIONS\(aq will create a new <disk> block and
add it to the XML.
.sp
This option will error if specified with a non\-device XML option
(see \-\-edit section for a partial list).
.TP
.B \fB\-\-remove\-device\fP
Remove the specified device from the XML. The device to remove is chosen
by the XML option, which takes arguments in the same format as \-\-edit.
Examples:
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fB\-\-remove\-device \-\-disk 2\fP
Remove the second disk device
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fB\-\-remove\-device  \-\-network all\fP
Remove all network devices
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fB\-\-remove\-device \-\-sound pcspk\fP
Remove all sound devices with model=\(aqpcspk\(aq
.UNINDENT
.UNINDENT
.sp
This option will error if specified with a non\-device XML option
(see \-\-edit isection for a partial list).
.TP
.B \fB\-\-build\-xml\fP
Just build the specified XML, and print it to stdout. No input domain or
input XML is required. Example: \(aq\-\-build\-xml \-\-disk DISK\-OPTIONS\(aq will
just print the new <disk> device.
.sp
However if the generated XML is targeted for a specific domain, it\(aqs
recommended to pass it to virt\-xml, so the tool can set optimal defaults.
.sp
This option will error if specified with an XML option that does not map
cleanly to a specific XML block, like \-\-vcpus or \-\-memory.
.UNINDENT
.SH OUTPUT OPTIONS
.sp
These options decide what action to take after altering the XML. In the common case these do not need to be specified, as \(aqXML actions\(aq will imply a default output action, described in detail above. These are only needed if you want to modify the default output.
.INDENT 0.0
.TP
.B \fB\-\-update\fP
If the specified domain is running, attempt to alter the running VM configuration. If combined with \-\-edit, this is an update operation. If combined with \-\-add\-device, this is a device hotplug. If combined with \-\-remove\-device, this is a device hotunplug.
.sp
Keep in mind, most XML properties and devices do not support live update operations, so don\(aqt expect it to succeed in all cases.
.sp
By default this also implies \fB\-\-define\fP\&.
.TP
.B \fB\-\-define\fP
Define the requested XML change. This is typically the default if no output option is specified, but if a \-\-print option is specified, \-\-define is required to force the change.
.TP
.B \fB\-\-no\-define\fP
Explicitly do not define the XML. For example if you only want to alter the runtime state of a VM, combine this with \fB\-\-update\fP\&.
.TP
.B \fB\-\-start\fP
Start the VM after performing the requested changes. If combined with \-\-no\-define, this will create transient VM boot with the requested changes.
.TP
.B \fB\-\-print\-diff\fP
Print the generated XML change in unified diff format. If only this output option is specified, all other output options are disabled and no persistent change is made.
.TP
.B \fB\-\-print\-xml\fP
Print the generated XML in its entirety. If only this output option is specified, all other output options are disabled and no persistent change is made.
.TP
.B \fB\-\-confirm\fP
Before defining or updating the domain, show the generated XML diff and interactively request confirmation.
.UNINDENT
.SH GUEST OS OPTIONS
.INDENT 0.0
.TP
.B \fB\-\-os\-variant\fP, \fB\-\-osinfo\fP OS_VARIANT
Optimize the guest configuration for a specific operating system (ex.
\(aqfedora29\(aq, \(aqrhel7\(aq, \(aqwin10\(aq). While not required, specifying this
options is HIGHLY RECOMMENDED, as it can greatly increase performance
by specifying virtio among other guest tweaks.
.sp
If the guest has been installed using virt\-manager version 2.0.0 or newer,
providing this information should not be necessary, as the OS variant will
have been stored in the guest configuration during installation and virt\-xml
will retrieve it from there automatically.
.sp
Use the command \fBvirt\-xml \-\-osinfo list\fP to get the list of the
accepted OS variants. See \fBosinfo\-query os\fP for even more output.
.sp
See virt\-install(1) documentation for more details about \fB\-\-os\-variant/\-\-osinfo\fP
.UNINDENT
.SH XML OPTIONS
.INDENT 0.0
.IP \(bu 2
\fB\-\-disk\fP
.IP \(bu 2
\fB\-\-network\fP
.IP \(bu 2
\fB\-\-graphics\fP
.IP \(bu 2
\fB\-\-metadata\fP
.IP \(bu 2
\fB\-\-memory\fP
.IP \(bu 2
\fB\-\-vcpus\fP
.IP \(bu 2
\fB\-\-cpu\fP
.IP \(bu 2
\fB\-\-iothreads\fP
.IP \(bu 2
\fB\-\-seclabel\fP
.IP \(bu 2
\fB\-\-keywrap\fP
.IP \(bu 2
\fB\-\-cputune\fP
.IP \(bu 2
\fB\-\-numatune\fP
.IP \(bu 2
\fB\-\-memtune\fP
.IP \(bu 2
\fB\-\-blkiotune\fP
.IP \(bu 2
\fB\-\-memorybacking\fP
.IP \(bu 2
\fB\-\-features\fP
.IP \(bu 2
\fB\-\-clock\fP
.IP \(bu 2
\fB\-\-pm\fP
.IP \(bu 2
\fB\-\-events\fP
.IP \(bu 2
\fB\-\-resources\fP
.IP \(bu 2
\fB\-\-sysinfo\fP
.IP \(bu 2
\fB\-\-xml\fP
.IP \(bu 2
\fB\-\-qemu\-commandline\fP
.IP \(bu 2
\fB\-\-launchSecurity\fP
.IP \(bu 2
\fB\-\-boot\fP
.IP \(bu 2
\fB\-\-idmap\fP
.IP \(bu 2
\fB\-\-controller\fP
.IP \(bu 2
\fB\-\-input\fP
.IP \(bu 2
\fB\-\-serial\fP
.IP \(bu 2
\fB\-\-parallel\fP
.IP \(bu 2
\fB\-\-channel\fP
.IP \(bu 2
\fB\-\-console\fP
.IP \(bu 2
\fB\-\-hostdev\fP
.IP \(bu 2
\fB\-\-filesystem\fP
.IP \(bu 2
\fB\-\-sound\fP
.IP \(bu 2
\fB\-\-audio\fP
.IP \(bu 2
\fB\-\-watchdog\fP
.IP \(bu 2
\fB\-\-video\fP
.IP \(bu 2
\fB\-\-smartcard\fP
.IP \(bu 2
\fB\-\-redirdev\fP
.IP \(bu 2
\fB\-\-memballoon\fP
.IP \(bu 2
\fB\-\-tpm\fP
.IP \(bu 2
\fB\-\-rng\fP
.IP \(bu 2
\fB\-\-panic\fP
.IP \(bu 2
\fB\-\-shmem\fP
.IP \(bu 2
\fB\-\-memdev\fP
.UNINDENT
.sp
These options alter the XML for a single class of XML elements. More complete documentation is found in virt\-install(1).
.sp
Generally these options map pretty straightforwardly to the libvirt XML, documented at \fI\%https://libvirt.org/formatdomain.html\fP
.sp
Option strings are in the format of: \-\-option opt=val,opt2=val2,...  example: \-\-disk path=/tmp/foo,shareable=on. Properties can be used with \(aq\-\-option opt=,\(aq, so to clear a disks cache setting you could use \(aq\-\-disk cache=,\(aq
.sp
For any option, use \-\-option=? to see a list of all available sub options, example: \-\-disk=?  or  \-\-boot=?
.sp
\-\-help output also lists a few general examples. See the EXAMPLES section below for some common examples.
.sp
virt\-xml specifically has some operations that don\(aqt really apply to virt\-install
Examples:
.INDENT 0.0
.TP
.B \fB\-\-boot refresh\-machine\-type=yes\fP
Refresh the XML \fB<os><type machine=X></os>\fP value to the latest one
that qemu provides. For example, if your VM has a machine type value
\fBpc\-q35\-4.0\fP, this will reset the value to \fBq35\fP, and works
similarly with other versioned machine types. Occasionally this is
necessary to get enable qemu bug fixes, or when qemu deprecates and
removes old machine type values.
.UNINDENT
.SH MISCELLANEOUS OPTIONS
.INDENT 0.0
.TP
.B \fB\-h\fP, \fB\-\-help\fP
Show the help message and exit
.TP
.B \fB\-\-version\fP
Show program\(aqs version number and exit
.TP
.B \fB\-q\fP, \fB\-\-quiet\fP
Avoid verbose output.
.TP
.B \fB\-d\fP, \fB\-\-debug\fP
Print debugging information
.UNINDENT
.SH EXAMPLES
.sp
See a list of all suboptions that \-\-disk and \-\-network take
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml \-\-disk=? \-\-network=?
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Change the <description> of domain \(aqEXAMPLE\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml EXAMPLE \-\-edit \-\-metadata description="my new description"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
# Enable the boot device menu for domain \(aqEXAMPLE\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml EXAMPLE \-\-edit \-\-boot menu=on
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Clear the previous <cpu> definition of domain \(aqwinxp\(aq, change it to \(aqhost\-model\(aq, but interactively confirm the diff before saving:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml winxp \-\-edit \-\-cpu host\-model,clearxml=yes \-\-confirm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Change the second sound card to model=ich6 on \(aqfedora19\(aq, but only output the diff:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml fedora19 \-\-edit 2 \-\-sound model=ich6 \-\-print\-diff
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Update the every graphics device password to \(aqfoo\(aq of the running VM \(aqrhel6\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml rhel6 \-\-edit all \-\-graphics password=foo \-\-update
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Remove the disk path from disk device hdc:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml rhel6 \-\-edit target=hdc \-\-disk path=
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Change all disk devices of type \(aqdisk\(aq to use cache=none, using XML from stdin, printing the new XML to stdout.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# cat <xmlfile> | virt\-xml \-\-edit device=disk \-\-disk cache=none
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Change disk \(aqhda\(aq IO to native and use startup policy as \(aqoptional\(aq.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml fedora20 \-\-edit target=hda \e
           \-\-disk io=native,startup_policy=optional
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Change all host devices to use driver_name=vfio for VM \(aqfedora20\(aq on the remote connection
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml \-\-connect qemu+ssh://remotehost/system \e
           fedora20 \-\-edit all \-\-hostdev driver_name=vfio
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Hotplug host USB device 001.003 to running domain \(aqfedora19\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml fedora19 \-\-update \-\-add\-device \-\-hostdev 001.003
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Add a spicevmc channel to the domain \(aqwinxp\(aq, that will be available after the next VM shutdown.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml winxp \-\-add\-device \-\-channel spicevmc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Create a 10G qcow2 disk image and attach it to \(aqfedora18\(aq for the next VM startup:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml fedora18 \-\-add\-device \e
  \-\-disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Same as above, but ensure the disk is attached to the most appropriate bus
for the guest OS by providing information about it on the command line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml fedora18 \-\-osinfo fedora18 \-\-add\-device \e
  \-\-disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Hotunplug the disk vdb from the running domain \(aqrhel7\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml rhel7 \-\-update \-\-remove\-device \-\-disk target=vdb
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Remove all graphics devices from the VM \(aqrhel7\(aq after the next shutdown:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml rhel7 \-\-remove\-device \-\-graphics all
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Generate XML for a virtio console device and print it to stdout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml \-\-build\-xml \-\-console pty,target_type=virtio
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Add qemu command line passthrough:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml f25 \-\-edit \-\-confirm \-\-qemu\-commandline="\-device FOO"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use boot device \(aqnetwork\(aq for a single transient boot:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# virt\-xml myvm \-\-no\-define \-\-start \-\-edit \-\-boot network
.ft P
.fi
.UNINDENT
.UNINDENT
.SH CAVEATS
.sp
Virtualization hosts supported by libvirt may not permit all changes that might seem possible. Some edits made to a VM\(aqs definition may be ignored. For instance, QEMU does not allow the removal of certain devices once they\(aqve been defined.
.SH BUGS
.sp
Please see \fI\%https://virt\-manager.org/bugs\fP
.SH COPYRIGHT
.sp
Copyright (C) Red Hat, Inc, and various contributors.
This is free software. You may redistribute copies of it under the terms
of the GNU General Public License \fI\%https://www.gnu.org/licenses/gpl.html\fP\&.
There is NO WARRANTY, to the extent permitted by law.
.SH SEE ALSO
.sp
virt\-install(1), the project website \fI\%https://virt\-manager.org\fP
.\" Generated by docutils manpage writer.
.
