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
28         domain  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
40              details
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
46              --define,  even  if  the VM is running. To update the running VM
47              configuration,  add   the   --update   option   (but   not   all
48              options/devices 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.
109              Example: '--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
145              optimal 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
160              operation. 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 requeseted changes. If com‐
181              bined with --no-define, this will create transient VM boot  with
182              the 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
191              option is specified, all other output options are  disabled  and
192              no 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
203              increase  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
210              automatically.
211
212              Use the command  "osinfo-query  os"  to  get  the  list  of  the
213              accepted OS variants.
214
215              See   virt-install(1)   documentation  for  more  details  about
216              --os-variant
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       · --watchdog
290
291       · --video
292
293       · --smartcard
294
295       · --redirdev
296
297       · --memballoon
298
299       · --tpm
300
301       · --rng
302
303       · --panic
304
305       · --memdev
306
307       These options alter the XML for a single class of  XML  elements.  More
308       complete documentation is found in virt-install(1).
309
310       Generally  these  options  map  pretty straightforwardly to the libvirt
311       XML, documented at https://libvirt.org/formatdomain.html
312
313       Option strings are in the  format  of:  --option  opt=val,opt2=val2,...
314       example: --disk path=/tmp/foo,shareable=on. Properties can be used with
315       '--option opt=,', so to clear a  disks  cache  setting  you  could  use
316       '--disk cache=,'
317
318       For  any  option,  use  --option=?  to  see a list of all available sub
319       options, example: --disk=?  or  --boot=?
320
321       --help output also lists a few general examples. See the EXAMPLES  sec‐
322       tion below for some common examples.
323

MISCELLANEOUS OPTIONS

325       -h, --help
326              Show the help message and exit
327
328       --version
329              Show program's version number and exit
330
331       -q, --quiet
332              Avoid verbose output.
333
334       -d, --debug
335              Print debugging information
336

EXAMPLES

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

CAVEATS

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

BUGS

435       Please see https://virt-manager.org/bugs
436

COPYRIGHT

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