virt-xml(1)

1VIRT-XML(1)                 Virtualization Support                 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 docu‐
15       ment 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
23       • --remove-device: Remove an existing device definition
24
25       • --edit: Edit an existing XML block
26
27       • --build-xml: Just build the requested XML block and print it. No  do‐
28         main  or  input  are  required  here, but it's recommended to provide
29         them, so virt-xml can fill in optimal defaults.
30
31       An XML change is one instance of any of the  XML  options  provided  by
32       virt-xml, for example --disk or --boot.
33
34       virt-xml  only  allows  one  action and XML pair per invocation. If you
35       need to make multiple edits, invoke the command multiple times.
36

OPTIONS

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

XML ACTIONS

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

OUTPUT OPTIONS

152       These options decide what action to take after altering the XML. In the
153       common case these do not need to be specified, as  'XML  actions'  will
154       imply  a  default  output  action, described in detail above. These are
155       only needed if you want to modify the default output.
156
157       --update
158              If the specified domain is running, attempt to alter the running
159              VM configuration. If combined with --edit, this is an update op‐
160              eration. If combined with --add-device, this is  a  device  hot‐
161              plug.  If combined with --remove-device, this is a device hotun‐
162              plug.
163
164              Keep in mind, most XML properties and  devices  do  not  support
165              live  update  operations,  so  don't expect it to succeed in all
166              cases.
167
168              By default this also implies --define.
169
170       --define
171              Define the requested XML change. This is typically  the  default
172              if  no  output  option  is specified, but if a --print option is
173              specified, --define is required to force the change.
174
175       --no-define
176              Explicitly do not define the XML. For example if you  only  want
177              to alter the runtime state of a VM, combine this with --update.
178
179       --start
180              Start the VM after performing the requested changes. If combined
181              with --no-define, this will create transient VM  boot  with  the
182              requested changes.
183
184       --print-diff
185              Print  the  generated XML change in unified diff format. If only
186              this output option is specified, all other  output  options  are
187              disabled and no persistent change is made.
188
189       --print-xml
190              Print the generated XML in its entirety. If only this output op‐
191              tion is specified, all other output options are disabled and  no
192              persistent change is made.
193
194       --confirm
195              Before  defining  or updating the domain, show the generated XML
196              diff and interactively request confirmation.
197

GUEST OS OPTIONS

199       --os-variant, --osinfo OS_VARIANT
200              Optimize the guest configuration for a specific operating system
201              (ex.   'fedora29', 'rhel7', 'win10'). While not required, speci‐
202              fying this options is HIGHLY RECOMMENDED, as it can greatly  in‐
203              crease  performance  by  specifying  virtio  among  other  guest
204              tweaks.
205
206              If the guest has been installed using virt-manager version 2.0.0
207              or newer, providing this information should not be necessary, as
208              the OS variant will have been stored in the guest  configuration
209              during installation and virt-xml will retrieve it from there au‐
210              tomatically.
211
212              Use the command virt-xml --osinfo list to get the  list  of  the
213              accepted OS variants. See osinfo-query os for even more output.
214
215              See   virt-install(1)   documentation  for  more  details  about
216              --os-variant/--osinfo
217

XML OPTIONS

219       • --disk
220
221       • --network
222
223       • --graphics
224
225       • --metadata
226
227       • --memory
228
229       • --vcpus
230
231       • --cpu
232
233       • --iothreads
234
235       • --seclabel
236
237       • --keywrap
238
239       • --cputune
240
241       • --numatune
242
243       • --memtune
244
245       • --blkiotune
246
247       • --memorybacking
248
249       • --features
250
251       • --clock
252
253       • --pm
254
255       • --events
256
257       • --resources
258
259       • --sysinfo
260
261       • --xml
262
263       • --qemu-commandline
264
265       • --launchSecurity
266
267       • --boot
268
269       • --idmap
270
271       • --controller
272
273       • --input
274
275       • --serial
276
277       • --parallel
278
279       • --channel
280
281       • --console
282
283       • --hostdev
284
285       • --filesystem
286
287       • --sound
288
289       • --audio
290
291       • --watchdog
292
293       • --video
294
295       • --smartcard
296
297       • --redirdev
298
299       • --memballoon
300
301       • --tpm
302
303       • --rng
304
305       • --panic
306
307       • --shmem
308
309       • --memdev
310
311       These options alter the XML for a single class of  XML  elements.  More
312       complete documentation is found in virt-install(1).
313
314       Generally  these  options  map  pretty straightforwardly to the libvirt
315       XML, documented at https://libvirt.org/formatdomain.html
316
317       Option strings are in the  format  of:  --option  opt=val,opt2=val2,...
318       example: --disk path=/tmp/foo,shareable=on. Properties can be used with
319       '--option opt=,', so to clear a  disks  cache  setting  you  could  use
320       '--disk cache=,'
321
322       For  any  option, use --option=? to see a list of all available sub op‐
323       tions, example: --disk=?  or  --boot=?
324
325       --help output also lists a few general examples. See the EXAMPLES  sec‐
326       tion below for some common examples.
327
328       virt-xml  specifically  has  some operations that don't really apply to
329       virt-install Examples:
330
331       --boot refresh-machine-type=yes
332              Refresh the XML <os><type machine=X></os> value  to  the  latest
333              one  that  qemu  provides. For example, if your VM has a machine
334              type value pc-q35-4.0, this will reset the  value  to  q35,  and
335              works similarly with other versioned machine types. Occasionally
336              this is necessary to get enable qemu bug  fixes,  or  when  qemu
337              deprecates and removes old machine type values.
338

MISCELLANEOUS OPTIONS

340       -h, --help
341              Show the help message and exit
342
343       --version
344              Show program's version number and exit
345
346       -q, --quiet
347              Avoid verbose output.
348
349       -d, --debug
350              Print debugging information
351

EXAMPLES

353       See a list of all suboptions that --disk and --network take
354
355          # virt-xml --disk=? --network=?
356
357       Change the <description> of domain 'EXAMPLE':
358
359          # virt-xml EXAMPLE --edit --metadata description="my new description"
360
361       # Enable the boot device menu for domain 'EXAMPLE':
362
363          # virt-xml EXAMPLE --edit --boot menu=on
364
365       Clear  the  previous  <cpu>  definition of domain 'winxp', change it to
366       'host-model', but interactively confirm the diff before saving:
367
368          # virt-xml winxp --edit --cpu host-model,clearxml=yes --confirm
369
370       Change the second sound card to model=ich6 on 'fedora19', but only out‐
371       put the diff:
372
373          # virt-xml fedora19 --edit 2 --sound model=ich6 --print-diff
374
375       Update  the  every  graphics device password to 'foo' of the running VM
376       'rhel6':
377
378          # virt-xml rhel6 --edit all --graphics password=foo --update
379
380       Remove the disk path from disk device hdc:
381
382          # virt-xml rhel6 --edit target=hdc --disk path=
383
384       Change all disk devices of type 'disk' to  use  cache=none,  using  XML
385       from stdin, printing the new XML to stdout.
386
387          # cat <xmlfile> | virt-xml --edit device=disk --disk cache=none
388
389       Change disk 'hda' IO to native and use startup policy as 'optional'.
390
391          # virt-xml fedora20 --edit target=hda \
392                     --disk io=native,startup_policy=optional
393
394       Change  all  host  devices to use driver_name=vfio for VM 'fedora20' on
395       the remote connection
396
397          # virt-xml --connect qemu+ssh://remotehost/system \
398                     fedora20 --edit all --hostdev driver_name=vfio
399
400       Hotplug host USB device 001.003 to running domain 'fedora19':
401
402          # virt-xml fedora19 --update --add-device --hostdev 001.003
403
404       Add a spicevmc channel to the domain 'winxp', that  will  be  available
405       after the next VM shutdown.
406
407          # virt-xml winxp --add-device --channel spicevmc
408
409       Create  a 10G qcow2 disk image and attach it to 'fedora18' for the next
410       VM startup:
411
412          # virt-xml fedora18 --add-device \
413            --disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
414
415       Same as above, but ensure the disk is attached to the most  appropriate
416       bus  for  the guest OS by providing information about it on the command
417       line:
418
419          # virt-xml fedora18 --osinfo fedora18 --add-device \
420            --disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10
421
422       Hotunplug the disk vdb from the running domain 'rhel7':
423
424          # virt-xml rhel7 --update --remove-device --disk target=vdb
425
426       Remove all graphics devices from the VM 'rhel7' after  the  next  shut‐
427       down:
428
429          # virt-xml rhel7 --remove-device --graphics all
430
431       Generate XML for a virtio console device and print it to stdout:
432
433          # virt-xml --build-xml --console pty,target_type=virtio
434
435       Add qemu command line passthrough:
436
437          # virt-xml f25 --edit --confirm --qemu-commandline="-device FOO"
438
439       Use boot device 'network' for a single transient boot:
440
441          # virt-xml myvm --no-define --start --edit --boot network
442

CAVEATS

444       Virtualization  hosts  supported  by libvirt may not permit all changes
445       that might seem possible. Some edits made to a VM's definition  may  be
446       ignored.  For  instance, QEMU does not allow the removal of certain de‐
447       vices once they've been defined.
448

BUGS

450       Please see https://virt-manager.org/bugs
451

COPYRIGHT

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