Ubuntu Manpage: virt-xml - Edit libvirt XML using command line options.

Provided by: virtinst_1.3.2-3ubuntu1.16.04.4_all

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

       -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.

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. 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
       --input
       --serial
       --parallel
       --channel
       --console
       --hostdev
       --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=,'

           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

       -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 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 --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

       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 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.