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 are required here, but it's recommended to
25       provide them, so virt-xml can fill in optimal defaults.
26
27       An XML change is one instance of any of the XML options provided by
28       virt-xml, for example --disk or --boot.
29
30       virt-xml only allows one action and XML pair per invocation. If you
31       need to make multiple edits, invoke the command multiple times.
32

OPTIONS

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

XML ACTIONS

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

OUTPUT OPTIONS

133       These options decide what action to take after altering the XML. In the
134       common case these do not need to be specified, as 'XML actions' will
135       imply a default output action, described in detail above. These are
136       only needed if you want to modify the default output.
137
138       --update
139           If the specified domain is running, attempt to alter the running VM
140           configuration. If combined with --edit, this is an update
141           operation. If combined with --add-device, this is a device hotplug.
142           If combined with --remove-device, this is a device hotunplug.
143
144           Keep in mind, most XML properties and devices do not support live
145           update operations, so don't expect it to succeed in all cases.
146
147           By default this also implies --define.
148
149       --define
150           Define the requested XML change. This is typically the default if
151           no output option is specified, but if a --print option is
152           specified, --define is required to force the change.
153
154       --no-define
155           Explicitly do not define the XML. For example if you only want to
156           alter the runtime state of a VM, combine this with --update.
157
158       --start
159           Start the VM after performing the requeseted changes. If combined
160           with --no-define, this will create transient VM boot with the
161           requested changes.
162
163       --print-diff
164           Print the generated XML change in unified diff format. If only this
165           output option is specified, all other output options are disabled
166           and no persistent change is made.
167
168       --print-xml
169           Print the generated XML in its entirety. If only this output option
170           is specified, all other output options are disabled and no
171           persistent change is made.
172
173       --confirm
174           Before defining or updating the domain, show the generated XML diff
175           and interactively request confirmation.
176

GUEST OS OPTIONS

178       --os-variant OS_VARIANT
179           Optimize the guest configuration for a specific operating system
180           (ex.  'fedora29', 'rhel7', 'win10'). While not required, specifying
181           this options is HIGHLY RECOMMENDED, as it can greatly increase
182           performance by specifying virtio among other guest tweaks.
183
184           If the guest has been installed using virt-manager version 2.0.0 or
185           newer, providing this information should not be necessary, as the
186           OS variant will have been stored in the guest configuration during
187           installation and virt-xml will retrieve it from there
188           automatically.
189
190           Use the command "osinfo-query os" to get the list of the accepted
191           OS variants.
192

XML OPTIONS

194       --disk
195       --network
196       --graphics
197       --metadata
198       --memory
199       --vcpus
200       --cpu
201       --iothreads
202       --seclabel
203       --cputune
204       --numatune
205       --memtune
206       --blkiotune
207       --memorybacking
208       --features
209       --clock
210       --pm
211       --events
212       --resources
213       --sysinfo
214       --qemu-commandline
215       --launchSecurity
216       --boot
217       --idmap
218       --controller
219       --input
220       --serial
221       --parallel
222       --channel
223       --console
224       --hostdev
225       --filesystem
226       --sound
227       --watchdog
228       --video
229       --smartcard
230       --redirdev
231       --memballoon
232       --tpm
233       --rng
234       --panic
235       --memdev
236           These options alter the XML for a single class of XML elements.
237           More complete documentation is found in virt-install(1).
238
239           Generally these options map pretty straightforwardly to the libvirt
240           XML, documented at <https://libvirt.org/formatdomain.html>
241
242           Option strings are in the format of: --option opt=val,opt2=val2,...
243           example: --disk path=/tmp/foo,shareable=on. Properties can be used
244           with '--option opt=,', so to clear a disks cache setting you could
245           use '--disk cache=,'
246
247           For any option, use --option=? to see a list of all available sub
248           options, example: --disk=?  or  --boot=?
249
250           --help output also lists a few general examples. See the EXAMPLES
251           section below for some common examples.
252

MISCELLANEOUS OPTIONS

254       -h
255       --help
256           Show the help message and exit
257
258       --version
259           Show program's version number and exit
260
261       -q
262       --quiet
263           Avoid verbose output.
264
265       -d
266       --debug
267           Print debugging information
268

EXAMPLES

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

CAVEATS

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

BUGS

367       Please see <https://virt-manager.org/bugs>
368

COPYRIGHT

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