VIRT-XML(1) Virtualization Support VIRT-XML(1)
NAME
virt-xml - Edit libvirt XML using command line options.
SYNOPSIS
virt-xml DOMAIN XML-ACTION XML-OPTION [OUTPUT-OPTION] [MISC-OPTIONS]
...
DESCRIPTION
virt-xml is a command line tool for editing libvirt XML using explicit
command line options. See the EXAMPLES section at the end of this docu-
ment to jump right in.
Each virt-xml 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:
• --add-device: Append a new device definition to the XML
• --remove-device: Remove an existing device definition
• --edit: Edit an existing XML block
• --build-xml: Just build the requested XML block and print it. No do-
main or input are required here, but it's recommended to provide
them, so virt-xml can fill in optimal defaults.
An XML change is one instance of any of the XML options provided by
virt-xml, for example --disk or --boot.
virt-xml only allows one action and XML pair per invocation. If you
need to make multiple edits, invoke the command multiple times.
OPTIONS
-c --connect URI
Connect to a non-default hypervisor. See virt-install(1) for de-
tails
domain 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.
When a domain is specified, the default output action is --de-
fine, even if the VM is running. To update the running VM con-
figuration, add the --update option (but not all options/devices
support updating the running VM configuration).
If XML is passed on stdin, the default output is --print-xml.
XML ACTIONS
--edit [EDIT-OPTIONS]
Edit the specified XML block. EDIT-OPTIONS tell virt-xml which
block to edit. The type of XML that we are editing is decided by
XML option that is passed to virt-xml . So if --disk is passed,
EDIT-OPTIONS select which <disk> block to edit.
Certain XML options only ever map to a single XML block, like
--cpu, --security, --boot, --clock, and a few others. In those
cases, virt-xml will not complain if a corresponding XML block
does not already exist, it will create it for you.
Most XML options support a special value 'clearxml=yes'. 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.
EDIT-OPTIONS examples:
•
--edit --edit without any options implies 'edit the first
block'. So '--edit --disk DISK-OPTIONS' means 'edit the
first <disk>'.
For the single XML block options mentioned above, plain
'--edit' without any options is what you always want to
use.
•
--edit #
Select the specified XML block number. So '--edit 2
--disk DISK-OPTS' means 'edit the second <disk>'. This
option only really applies for device XML.
•
--edit all
Modify every XML block of the XML option type. So
'--edit all --disk DISK-OPTS' means 'edit ever <disk>
block'. This option only really applies for device
XML.
•
--edit 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.
So --edit path=/tmp/foo --disk DISK-OPTS means 'edit every
<disk> with path /tmp/foo'. This option only really applies for
device XML.
--add-device
Append the specified XML options to the XML <devices> list. Ex-
ample: '--add-device --disk DISK-OPTIONS' will create a new
<disk> block and add it to the XML.
This option will error if specified with a non-device XML option
(see --edit section for a partial list).
--remove-device
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:
•
--remove-device --disk 2
Remove the second disk device
•
--remove-device --network all
Remove all network devices
•
--remove-device --sound pcspk
Remove all sound devices with model='pcspk'
This option will error if specified with a non-device XML option
(see --edit isection for a partial list).
--build-xml
Just build the specified XML, and print it to stdout. No input
domain or input XML is required. Example: '--build-xml --disk
DISK-OPTIONS' will just print the new <disk> device.
However if the generated XML is targeted for a specific domain,
it's recommended to pass it to virt-xml, so the tool can set op-
timal defaults.
This option will error if specified with an XML option that does
not map cleanly to a specific XML block, like --vcpus or --mem-
ory.
OUTPUT OPTIONS
These options decide what action to take after altering the XML. In the
common case these do not need to be specified, as 'XML actions' will
imply a default output action, described in detail above. These are
only needed if you want to modify the default output.
--update
If the specified domain is running, attempt to alter the running
VM configuration. If combined with --edit, this is an update op-
eration. If combined with --add-device, this is a device hot-
plug. If combined with --remove-device, this is a device hotun-
plug.
Keep in mind, most XML properties and devices do not support
live update operations, so don't expect it to succeed in all
cases.
By default this also implies --define.
--define
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.
--no-define
Explicitly do not define the XML. For example if you only want
to alter the runtime state of a VM, combine this with --update.
--start
Start the VM after performing the requested changes. If combined
with --no-define, this will create transient VM boot with the
requested changes.
--print-diff
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.
--print-xml
Print the generated XML in its entirety. If only this output op-
tion is specified, all other output options are disabled and no
persistent change is made.
--confirm
Before defining or updating the domain, show the generated XML
diff and interactively request confirmation.
GUEST OS OPTIONS
--os-variant, --osinfo OS_VARIANT
Optimize the guest configuration for a specific operating system
(ex. 'fedora29', 'rhel7', 'win10'). While not required, speci-
fying this options is HIGHLY RECOMMENDED, as it can greatly in-
crease performance by specifying virtio among other guest
tweaks.
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 au-
tomatically.
Use the command virt-xml --osinfo list to get the list of the
accepted OS variants. See osinfo-query os for even more output.
See virt-install(1) documentation for more details about
--os-variant/--osinfo
XML OPTIONS
• --disk
• --network
• --graphics
• --metadata
• --memory
• --vcpus
• --cpu
• --iothreads
• --seclabel
• --keywrap
• --cputune
• --numatune
• --memtune
• --blkiotune
• --memorybacking
• --features
• --clock
• --pm
• --events
• --resources
• --sysinfo
• --xml
• --qemu-commandline
• --launchSecurity
• --boot
• --idmap
• --controller
• --input
• --serial
• --parallel
• --channel
• --console
• --hostdev
• --filesystem
• --sound
• --audio
• --watchdog
• --video
• --smartcard
• --redirdev
• --memballoon
• --tpm
• --rng
• --panic
• --shmem
• --memdev
These options alter the XML for a single class of XML elements. More
complete documentation is found in virt-install(1).
Generally these options map pretty straightforwardly to the libvirt
XML, documented at https://libvirt.org/formatdomain.html
Option strings are in the format of: --option opt=val,opt2=val2,...
example: --disk path=/tmp/foo,shareable=on. Properties can be used with
'--option opt=,', so to clear a disks cache setting you could use
'--disk cache=,'
For any option, use --option=? to see a list of all available sub op-
tions, example: --disk=? or --boot=?
--help output also lists a few general examples. See the EXAMPLES sec-
tion below for some common examples.
virt-xml specifically has some operations that don't really apply to
virt-install Examples:
--boot refresh-machine-type=yes
Refresh the XML <os><type machine=X></os> value to the latest
one that qemu provides. For example, if your VM has a machine
type value pc-q35-4.0, this will reset the value to q35, 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.
MISCELLANEOUS OPTIONS
-h, --help
Show the help message and exit
--version
Show program's version number and exit
-q, --quiet
Avoid verbose output.
-d, --debug
Print debugging information
EXAMPLES
See a list of all suboptions that --disk and --network take
# virt-xml --disk=? --network=?
Change the <description> of domain 'EXAMPLE':
# virt-xml EXAMPLE --edit --metadata description="my new description"
# Enable the boot device menu for domain 'EXAMPLE':
# virt-xml EXAMPLE --edit --boot menu=on
Clear the previous <cpu> definition of domain 'winxp', change it to
'host-model', but interactively confirm the diff before saving:
# virt-xml winxp --edit --cpu host-model,clearxml=yes --confirm
Change the second sound card to model=ich6 on 'fedora19', but only out-
put the diff:
# virt-xml fedora19 --edit 2 --sound model=ich6 --print-diff
Update the every graphics device password to 'foo' of the running VM
'rhel6':
# virt-xml rhel6 --edit all --graphics password=foo --update
Remove the disk path from disk device hdc:
# virt-xml rhel6 --edit target=hdc --disk path=
Change all disk devices of type 'disk' to use cache=none, using XML
from stdin, printing the new XML to stdout.
# cat <xmlfile> | virt-xml --edit device=disk --disk cache=none
Change disk 'hda' IO to native and use startup policy as 'optional'.
# virt-xml fedora20 --edit target=hda \
--disk io=native,startup_policy=optional
Change all host devices to use driver_name=vfio for VM 'fedora20' on
the remote connection
# virt-xml --connect qemu+ssh://remotehost/system \
fedora20 --edit all --hostdev driver_name=vfio
Hotplug host USB device 001.003 to running domain 'fedora19':
# virt-xml fedora19 --update --add-device --hostdev 001.003
Add a spicevmc channel to the domain 'winxp', that will be available
after the next VM shutdown.
# virt-xml winxp --add-device --channel spicevmc
Create a 10G qcow2 disk image and attach it to 'fedora18' for the next
VM startup:
# virt-xml fedora18 --add-device \
--disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
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:
# virt-xml fedora18 --osinfo fedora18 --add-device \
--disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
Hotunplug the disk vdb from the running domain 'rhel7':
# virt-xml rhel7 --update --remove-device --disk target=vdb
Remove all graphics devices from the VM 'rhel7' after the next shut-
down:
# virt-xml rhel7 --remove-device --graphics all
Generate XML for a virtio console device and print it to stdout:
# virt-xml --build-xml --console pty,target_type=virtio
Add qemu command line passthrough:
# virt-xml f25 --edit --confirm --qemu-commandline="-device FOO"
Use boot device 'network' for a single transient boot:
# virt-xml myvm --no-define --start --edit --boot network
CAVEATS
Virtualization hosts supported by libvirt may not permit all changes
that might seem possible. Some edits made to a VM's definition may be
ignored. For instance, QEMU does not allow the removal of certain de-
vices once they've been defined.
BUGS
Please see https://virt-manager.org/bugs
COPYRIGHT
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 https://www.gnu.org/licenses/gpl.html. There is
NO WARRANTY, to the extent permitted by law.
SEE ALSO
virt-install(1), the project website https://virt-manager.org
VIRT-XML(1)
Generated by dwww version 1.15 on Tue Jun 25 22:38:20 CEST 2024.