virt-xml (1)

Leading comments

Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man1/virt-xml.1".)

NAME

virt-xml - Edit libvirt XML using command line options.

SYNOPSIS

virt-xml XML-ACTION XML-OPTION [] [] ...

DESCRIPTION

virt-xml is a command line tool for editing libvirt using explicit command line options. See the 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

passed on stdin), an action to on the and an change to make. actions are one of:

--add-device: Append a new device definition to the

--remove-device: Remove an existing device definition --edit: Edit an existing block --build-xml: Just build the requested block and print it (no domain or input are required here).

An

change is one instance of any of the options provided by virt-xml, for example --disk or --boot.

virt-xml only allows one action and

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 In the common case these do not need to be specified, as ' 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 <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 '

':

  # virt-xml EXAMPLE --edit --metadata description="my new description"

# Enable the boot device menu for domain '

':

  # 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

'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

from stdin, printing the new to stdout.

  # cat <xmlfile> | virt-xml --edit device=disk --disk cache=none

Change disk 'hda'

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

'fedora20' on the remote connection

  # virt-xml --connect qemu+ssh://remotehost/system \
             fedora20 --edit all --hostdev driver_name=vfio

Hotplug host

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

shutdown.

  # virt-xml winxp --add-device --channel spicevmc

Create a 10G qcow2 disk image and attach it to 'fedora18' for the next

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

'rhel7' after the next shutdown:

  # virt-xml rhel7 --remove-device --graphics all

Generate

for a virtio console device and print it to stdout:

  # virt-xml --build-xml --console pty,target_type=virtio

BUGS

Please see 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 General Public License "www.gnu.org/licenses/gpl.html". There is to the extent permitted by law.

SEE ALSO

virt-install(1), the project website "virt-manager.org"