virt-xml(1)

1VIRT-XML(1)                 Virtual Machine Manager                VIRT-XML(1)
2
3
4

NAME

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

SYNOPSIS

9       virt-xml DOMAIN XML-ACTION XML-OPTION [OUTPUT-OPTION] [MISC-OPTIONS]
10       ...
11

DESCRIPTION

13       virt-xml is a command line tool for editing libvirt XML using explicit
14       command line options. See the EXAMPLES section at the end of this
15       document to jump right in.
16
17       Each virt-xml invocation requires 3 things: name of an existing domain
18       to alter (or XML passed on stdin), an action to on the XML, and an XML
19       change to make. actions are one of:
20
21       --add-device: Append a new device definition to the XML
22       --remove-device: Remove an existing device definition --edit: Edit an
23       existing XML block --build-xml: Just build the requested XML block and
24       print it (no domain or input XML are required here).
25
26       An XML change is one instance of any of the XML options provided by
27       virt-xml, for example --disk or --boot.
28
29       virt-xml only allows one action and XML pair per invocation. If you
30       need to make multiple edits, invoke the command multiple times.
31

OPTIONS

33       -c URI
34       --connect=URI
35           Connect to a non-default hypervisor. See virt-install(1) for
36           details
37
38       domain
39           domain is the name, UUID, or ID of the existing VM. This can be
40           omitted if using --build-xml, or if XML is passed on stdin.
41
42           When a domain is specified, the default output action is --define,
43           even if the VM is running. To update the running VM configuration,
44           add the --update option (but not all options/devices support
45           updating the running VM configuration).
46
47           If XML is passed on stdin, the default output is --print-xml.
48

XML ACTIONS

50       --edit [EDIT-OPTIONS]
51           Edit the specified XML block. EDIT-OPTIONS tell virt-xml which
52           block to edit. The type of XML that we are editing is decided by
53           XML option that is passed to virt-xml. So if --disk is passed,
54           EDIT-OPTIONS select which <disk> block to edit.
55
56           Certain XML options only ever map to a single XML block, like
57           --cpu, --security, --boot, --clock, and a few others. In those
58           cases, virt-xml will not complain if a corresponding XML block does
59           not already exist, it will create it for you.
60
61           Most XML options support a special value 'clearxml=yes'. When
62           combined with --edit, it will completely blank out the XML block
63           being edited before applying the requested changes. This allows
64           completely rebuilding an XML block. See EXAMPLES for some usage.
65
66           EDIT-OPTIONS examples:
67
68           --edit
69               --edit without any options implies 'edit the first block'. So
70               '--edit --disk DISK-OPTIONS' means 'edit the first <disk>'.
71
72               For the single XML block options mentioned above, plain
73               '--edit' without any options is what you always want to use.
74
75           --edit #
76               Select the specified XML block number. So '--edit 2 --disk
77               DISK-OPTS' means 'edit the second <disk>'. This option only
78               really applies for device XML.
79
80           --edit all
81               Modify every XML block of the XML option type. So '--edit all
82               --disk DISK-OPTS' means 'edit ever <disk> block'. This option
83               only really applies for device XML.
84
85           --edit DEVICE-OPTIONS
86               Modify every XML block that matches the passed device options.
87               The device options are in the same format as would be passed to
88               the XML option.
89
90               So '--edit path=/tmp/foo --disk DISK-OPTS' means 'edit every
91               <disk> with path /tmp/foo'. This option only really applies for
92               device XML.
93
94       --add-device
95           Append the specified XML options to the XML <devices> list.
96           Example: '--add-device --disk DISK-OPTIONS' will create a new
97           <disk> block and add it to the XML.
98
99           This option will error if specified with a non-device XML option
100           (see --edit section for a partial list).
101
102       --remove-device
103           Remove the specified device from the XML. The device to remove is
104           chosen by the XML option, which takes arguments in the same format
105           as --edit. Examples
106
107           --remove-device --disk 2
108               Remove the second disk device
109
110           --remove-device --network all
111               Remove all network devices
112
113           --remove-device --sound pcspk
114               Remove all sound devices with model='pcspk'
115
116           This option will error if specified with a non-device XML option
117           (see --edit section for a partial list).
118
119       --build-xml
120           Just build the specified XML, and print it to stdout. No input
121           domain or input XML is required. Example: '--build-xml --disk
122           DISK-OPTIONS' will just print the new <disk> device.
123
124           This option will error if specified with an XML option that does
125           not map cleanly to a specific XML block, like --vcpus or --memory.
126

OUTPUT OPTIONS

128       These options decide what action to take after altering the XML. In the
129       common case these do not need to be specified, as 'XML actions' will
130       imply a default output action, described in detail above. These are
131       only needed if you want to modify the default output.
132
133       --update
134           If the specified domain is running, attempt to alter the running VM
135           configuration. If combined with --edit, this is an update
136           operation. If combined with --add-device, this is a device hotplug.
137           If combined with --remove-device, this is a device hotunplug.
138
139           Keep in mind, most XML properties and devices do not support live
140           update operations, so don't expect it to succeed in all cases.
141
142       --define
143           Define the requested XML change. This is typically the default if
144           no output option is specified, but if a --print option is
145           specified, --define is required to force the change.
146
147       --print-diff
148           Print the generated XML change in unified diff format. If only this
149           output option is specified, all other output options are disabled
150           and no persistent change is made.
151
152       --print-xml
153           Print the generated XML in its entirety. If only this output option
154           is specified, all other output options are disabled and no
155           persistent change is made.
156
157       --confirm
158           Before defining or updating the domain, show the generated XML diff
159           and interactively request confirmation.
160

XML OPTIONS

162       --disk
163       --network
164       --graphics
165       --metadata
166       --memory
167       --vcpus
168       --cpu
169       --security
170       --numatune
171       --features
172       --clock
173       --pm
174       --boot
175       --filesystem
176       --controller
177       --input
178       --serial
179       --parallel
180       --channel
181       --console
182       --hostdev
183       --sound
184       --watchdog
185       --video
186       --smartcard
187       --redirdev
188       --memballoon
189       --tpm
190       --rng
191       --panic
192       --memdev
193       --qemu-commandline
194           These options alter the XML for a single class of XML elements.
195           More complete documentation is found in virt-install(1).
196
197           Generally these options map pretty straightforwardly to the libvirt
198           XML, documented at <http://libvirt.org/formatdomain.html>
199
200           Option strings are in the format of: --option opt=val,opt2=val2,...
201           example: --disk path=/tmp/foo,shareable=on. Properties can be used
202           with '--option opt=,', so to clear a disks cache setting you could
203           use '--disk cache=,'
204
205           For any option, use --option=? to see a list of all available sub
206           options, example: --disk=?  or  --boot=?
207
208           --help output also lists a few general examples. See the EXAMPLES
209           section below for some common examples.
210

MISCELLANEOUS OPTIONS

212       -h
213       --help
214           Show the help message and exit
215
216       --version
217           Show program's version number and exit
218
219       -q
220       --quiet
221           Avoid verbose output.
222
223       -d
224       --debug
225           Print debugging information
226

EXAMPLES

228       See a list of all suboptions that --disk and --network take
229
230         # virt-xml --disk=? --network=?
231
232       Change the <description> of domain 'EXAMPLE':
233
234         # virt-xml EXAMPLE --edit --metadata description="my new description"
235
236       # Enable the boot device menu for domain 'EXAMPLE':
237
238         # virt-xml EXAMPLE --edit --boot menu=on
239
240       Clear the previous <cpu> definition of domain 'winxp', change it to
241       'host-model', but interactively confirm the diff before saving:
242
243         # virt-xml winxp --edit --cpu host-model,clearxml=yes --confirm
244
245       Change the second sound card to model=ich6 on 'fedora19', but only
246       output the diff:
247
248         # virt-xml fedora19 --edit 2 --sound model=ich6 --print-diff
249
250       Update the every graphics device password to 'foo' of the running VM
251       'rhel6':
252
253         # virt-xml rhel6 --edit all --graphics password=foo --update
254
255       Remove the disk path from disk device hdc:
256
257         # virt-xml rhel6 --edit target=hdc --disk path=
258
259       Change all disk devices of type 'disk' to use cache=none, using XML
260       from stdin, printing the new XML to stdout.
261
262         # cat <xmlfile> | virt-xml --edit device=disk --disk cache=none
263
264       Change disk 'hda' IO to native and use startup policy as 'optional'.
265
266         # virt-xml fedora20 --edit target=hda \
267                    --disk io=native,startup_policy=optional
268
269       Change all host devices to use driver_name=vfio for VM 'fedora20' on
270       the remote connection
271
272         # virt-xml --connect qemu+ssh://remotehost/system \
273                    fedora20 --edit all --hostdev driver_name=vfio
274
275       Hotplug host USB device 001.003 to running domain 'fedora19':
276
277         # virt-xml fedora19 --update --add-device --hostdev 001.003
278
279       Add a spicevmc channel to the domain 'winxp', that will be available
280       after the next VM shutdown.
281
282         # virt-xml winxp --add-device --channel spicevmc
283
284       Create a 10G qcow2 disk image and attach it to 'fedora18' for the next
285       VM startup:
286
287         # virt-xml fedora18 --add-device \
288           --disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
289
290       Hotunplug the disk vdb from the running domain 'rhel7':
291
292         # virt-xml rhel7 --update --remove-device --disk target=vdb
293
294       Remove all graphics devices from the VM 'rhel7' after the next
295       shutdown:
296
297         # virt-xml rhel7 --remove-device --graphics all
298
299       Generate XML for a virtio console device and print it to stdout:
300
301         # virt-xml --build-xml --console pty,target_type=virtio
302
303       Add qemu command line passthrough:
304
305         # virt-xml f25 --edit --confirm --qemu-commandline="-device FOO"
306

CAVEATS

308       Virtualization hosts supported by libvirt may not permit all changes
309       that might seem possible. Some edits made to a VM's definition may be
310       ignored. For instance, QEMU does not allow the removal of certain
311       devices once they've been defined.
312

BUGS

314       Please see http://virt-manager.org/page/BugReporting
315

COPYRIGHT

317       Copyright (C) Red Hat, Inc, and various contributors.  This is free
318       software. You may redistribute copies of it under the terms of the GNU
319       General Public License "http://www.gnu.org/licenses/gpl.html".  There
320       is NO WARRANTY, to the extent permitted by law.
321