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           Note that --update implies --define: it can't be used in isolation.
143
144       --define
145           Define the requested XML change. This is typically the default if
146           no output option is specified, but if a --print option is
147           specified, --define is required to force the change.
148
149       --print-diff
150           Print the generated XML change in unified diff format. If only this
151           output option is specified, all other output options are disabled
152           and no persistent change is made.
153
154       --print-xml
155           Print the generated XML in its entirety. If only this output option
156           is specified, all other output options are disabled and no
157           persistent change is made.
158
159       --confirm
160           Before defining or updating the domain, show the generated XML diff
161           and interactively request confirmation.
162

GUEST OS OPTIONS

164       --os-variant OS_VARIANT
165           Optimize the guest configuration for a specific operating system
166           (ex.  'fedora29', 'rhel7', 'win10'). While not required, specifying
167           this options is HIGHLY RECOMMENDED, as it can greatly increase
168           performance by specifying virtio among other guest tweaks.
169
170           If the guest has been installed using virt-manager version 2.0.0 or
171           newer, providing this information should not be necessary, as the
172           OS variant will have been stored in the guest configuration during
173           installation and virt-xml will retrieve it from there
174           automatically.
175
176           Use the command "osinfo-query os" to get the list of the accepted
177           OS variants.
178

XML OPTIONS

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

MISCELLANEOUS OPTIONS

230       -h
231       --help
232           Show the help message and exit
233
234       --version
235           Show program's version number and exit
236
237       -q
238       --quiet
239           Avoid verbose output.
240
241       -d
242       --debug
243           Print debugging information
244

EXAMPLES

246       See a list of all suboptions that --disk and --network take
247
248         # virt-xml --disk=? --network=?
249
250       Change the <description> of domain 'EXAMPLE':
251
252         # virt-xml EXAMPLE --edit --metadata description="my new description"
253
254       # Enable the boot device menu for domain 'EXAMPLE':
255
256         # virt-xml EXAMPLE --edit --boot menu=on
257
258       Clear the previous <cpu> definition of domain 'winxp', change it to
259       'host-model', but interactively confirm the diff before saving:
260
261         # virt-xml winxp --edit --cpu host-model,clearxml=yes --confirm
262
263       Change the second sound card to model=ich6 on 'fedora19', but only
264       output the diff:
265
266         # virt-xml fedora19 --edit 2 --sound model=ich6 --print-diff
267
268       Update the every graphics device password to 'foo' of the running VM
269       'rhel6':
270
271         # virt-xml rhel6 --edit all --graphics password=foo --update
272
273       Remove the disk path from disk device hdc:
274
275         # virt-xml rhel6 --edit target=hdc --disk path=
276
277       Change all disk devices of type 'disk' to use cache=none, using XML
278       from stdin, printing the new XML to stdout.
279
280         # cat <xmlfile> | virt-xml --edit device=disk --disk cache=none
281
282       Change disk 'hda' IO to native and use startup policy as 'optional'.
283
284         # virt-xml fedora20 --edit target=hda \
285                    --disk io=native,startup_policy=optional
286
287       Change all host devices to use driver_name=vfio for VM 'fedora20' on
288       the remote connection
289
290         # virt-xml --connect qemu+ssh://remotehost/system \
291                    fedora20 --edit all --hostdev driver_name=vfio
292
293       Hotplug host USB device 001.003 to running domain 'fedora19':
294
295         # virt-xml fedora19 --update --add-device --hostdev 001.003
296
297       Add a spicevmc channel to the domain 'winxp', that will be available
298       after the next VM shutdown.
299
300         # virt-xml winxp --add-device --channel spicevmc
301
302       Create a 10G qcow2 disk image and attach it to 'fedora18' for the next
303       VM startup:
304
305         # virt-xml fedora18 --add-device \
306           --disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
307
308       Same as above, but ensure the disk is attached to the most appropriate
309       bus for the guest OS by providing information about it on the command
310       line:
311
312         # virt-xml fedora18 --os-variant fedora18 --add-device \
313           --disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
314
315       Hotunplug the disk vdb from the running domain 'rhel7':
316
317         # virt-xml rhel7 --update --remove-device --disk target=vdb
318
319       Remove all graphics devices from the VM 'rhel7' after the next
320       shutdown:
321
322         # virt-xml rhel7 --remove-device --graphics all
323
324       Generate XML for a virtio console device and print it to stdout:
325
326         # virt-xml --build-xml --console pty,target_type=virtio
327
328       Add qemu command line passthrough:
329
330         # virt-xml f25 --edit --confirm --qemu-commandline="-device FOO"
331

CAVEATS

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

BUGS

339       Please see https://virt-manager.org/page/BugReporting
340

COPYRIGHT

342       Copyright (C) Red Hat, Inc, and various contributors.  This is free
343       software. You may redistribute copies of it under the terms of the GNU
344       General Public License "https://www.gnu.org/licenses/gpl.html".  There
345       is NO WARRANTY, to the extent permitted by law.
346