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 document 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 domain or input XML are
required here).
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¶
- -h, --help
- Show the help message and exit
- --version
- Show program's version number and exit
- -c URI, --connect=URI
- Connect to a non-default hypervisor. See virt-install(1) for
details
- 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 --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).
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.
Every XML option has 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. Example:
'--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
section 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.
This option will error if specified with an XML option that does not map
cleanly to a specific XML block, like --vcpus or --memory.
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 operation. If
combined with --add-device, this is a device hotplug. If combined with
--remove-device, this is a device hotunplug.
Keep in mind, most XML properties and devices do not support live update
operations, so don't expect it to succeed in all cases.
- --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.
- --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 option 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.
XML options¶
- --disk
- --network
- --graphics
- --metadata
- --memory
- --vcpus
- --cpu
- --security
- --numatune
- --features
- --clock
- --pm
- --boot
- --filesystem
- --controller
- --serial
- --parallel
- --channel
- --console
- --host-device
- --sound
- --watchdog
- --video
- --smartcard
- --redirdev
- --memballoon
- --tpm
- --rng
- --panic
- 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 <http://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=,'
Every XML option has 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.
For any option, use --option=? to see a list of all available sub options,
example: --disk=? or --boot=?
--help output also lists a few general examples. See the EXAMPLES section
below for some common examples.
Miscellaneous Options¶
- -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 bootmenu=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 output 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 --host-device driver_name=vfio
Hotplug host USB device 001.003 to running domain 'fedora19':
# virt-xml f19 --add-device --host-device 001.003 --update
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
Remove the disk vdb from the running domain 'rhel7':
# virt-xml rhel7 --remove-device --disk target=vdb
Remove all graphics devices from the VM 'rhel7' after the next shutdown:
# 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
BUGS¶
Please see
http://virt-manager.org/page/BugReporting
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 "
http://www.gnu.org/licenses/gpl.html". There is NO
WARRANTY, to the extent permitted by law.
SEE ALSO¶
virt-install(1), the project website
"
http://virt-manager.org"