summaryrefslogtreecommitdiffstats
path: root/man/virt-xml.pod
blob: d383177127f4a7556e1b45c89e9ddea4bbc9ef3b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
=pod

=head1 NAME

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

=head1 SYNOPSIS

B<virt-xml> DOMAIN XML-ACTION XML-OPTION [OUTPUT-OPTION] [MISC-OPTIONS] ...

=head1 DESCRIPTION

B<virt-xml> is a command line tool for editing libvirt XML using explicit command line options. See the EXAMPLES section at the end of this document to jump right in.

Each B<virt-xml> invocation requires 3 things: name of an existing domain to alter (or XML passed on stdin), an action to on the XML, and an XML change to make. actions are one of:

--add-device: Append a new device definition to the XML
--remove-device: Remove an existing device definition
--edit: Edit an existing XML block
--build-xml: Just build the requested XML block and print it (no domain or input XML are required here).

An XML change is one instance of any of the XML options provided by virt-xml, for example --disk or --boot.

B<virt-xml> only allows one action and XML pair per invocation. If you need to make multiple edits, invoke the command multiple times.



=head1 OPTIONS

=over 4

=item B<-c> URI

=item B<--connect>=URI

Connect to a non-default hypervisor. See L<virt-install(1)> for details

=item B<domain>

domain is the name, UUID, or ID of the existing VM. This can be omitted if
using --build-xml, or if XML is passed on stdin.

When a domain is specified, the default output action is --define, even if the VM is running. To update the running VM configuration, add the --update option (but not all options/devices support updating the running VM configuration).

If XML is passed on stdin, the default output is --print-xml.

=back



=head1 XML ACTIONS

=over 4

=item B<--edit> [EDIT-OPTIONS]

Edit the specified XML block. EDIT-OPTIONS tell B<virt-xml> which block to edit. The type of XML that we are editing is decided by XML option that is passed to B<virt-xml>. So if --disk is passed, EDIT-OPTIONS select which <disk> block to edit.

Certain XML options only ever map to a single XML block, like --cpu, --security, --boot, --clock, and a few others. In those cases, B<virt-xml> will not complain if a corresponding XML block does not already exist, it will create it for you.

Some XML option support a special value 'clearxml=yes'. When combined with --edit, it will completely blank out the XML block being edited before applying the requested changes. This allows completely rebuilding an XML block. See EXAMPLES for some usage.

EDIT-OPTIONS examples:

=over 4

=item B<--edit>

--edit without any options implies 'edit the first block'. So '--edit --disk DISK-OPTIONS' means 'edit the first <disk>'.

For the single XML block options mentioned above, plain '--edit' without any options is what you always want to use.

=item B<--edit> #

Select the specified XML block number. So '--edit 2 --disk DISK-OPTS' means 'edit the second <disk>'. This option only really applies for device XML.

=item B<--edit> all

Modify every XML block of the XML option type. So '--edit all --disk DISK-OPTS' means 'edit ever <disk> block'. This option only really applies for device XML.

=item B<--edit> DEVICE-OPTIONS

Modify every XML block that matches the passed device options. The device options are in the same format as would be passed to the XML option.

So '--edit path=/tmp/foo --disk DISK-OPTS' means 'edit every <disk> with path /tmp/foo'. This option only really applies for device XML.

=back

=item B<--add-device>

Append the specified XML options to the XML <devices> list. Example: '--add-device --disk DISK-OPTIONS' will create a new <disk> block and add it to the XML.

This option will error if specified with a non-device XML option (see --edit section for a partial list).

=item B<--remove-device>

Remove the specified device from the XML. The device to remove is chosen by the XML option, which takes arguments in the same format as --edit. Examples

=over 4

=item B<--remove-device> --disk 2

Remove the second disk device

=item B<--remove-device> --network all

Remove all network devices

=item B<--remove-device> --sound pcspk

Remove all sound devices with model='pcspk'

=back

This option will error if specified with a non-device XML option (see --edit section for a partial list).

=item B<--build-xml>

Just build the specified XML, and print it to stdout. No input domain or input XML is required. Example: '--build-xml --disk DISK-OPTIONS' will just print the new <disk> device.

This option will error if specified with an XML option that does not map cleanly to a specific XML block, like --vcpus or --memory.

=back




=head1 OUTPUT OPTIONS

These options decide what action to take after altering the XML. In the common case these do not need to be specified, as 'XML actions' will imply a default output action, described in detail above. These are only needed if you want to modify the default output.

=over 4

=item B<--update>

If the specified domain is running, attempt to alter the running VM configuration. If combined with --edit, this is an update operation. If combined with --add-device, this is a device hotplug. If combined with --remove-device, this is a device hotunplug.

Keep in mind, most XML properties and devices do not support live update operations, so don't expect it to succeed in all cases.

=item B<--define>

Define the requested XML change. This is typically the default if no output option is specified, but if a --print option is specified, --define is required to force the change.

=item B<--print-diff>

Print the generated XML change in unified diff format. If only this output option is specified, all other output options are disabled and no persistent change is made.

=item B<--print-xml>

Print the generated XML in its entirety. If only this output option is specified, all other output options are disabled and no persistent change is made.

=item B<--confirm>

Before defining or updating the domain, show the generated XML diff and interactively request confirmation.

=back




=head1 XML OPTIONS

=over 4

=item B<--disk>

=item B<--network>

=item B<--graphics>

=item B<--metadata>

=item B<--memory>

=item B<--vcpus>

=item B<--cpu>

=item B<--security>

=item B<--numatune>

=item B<--features>

=item B<--clock>

=item B<--pm>

=item B<--boot>

=item B<--filesystem>

=item B<--controller>

=item B<--input>

=item B<--serial>

=item B<--parallel>

=item B<--channel>

=item B<--console>

=item B<--hostdev>

=item B<--sound>

=item B<--watchdog>

=item B<--video>

=item B<--smartcard>

=item B<--redirdev>

=item B<--memballoon>

=item B<--tpm>

=item B<--rng>

=item B<--panic>

These options alter the XML for a single class of XML elements. More complete documentation is found in L<virt-install(1)>.

Generally these options map pretty straightforwardly to the libvirt XML, documented at L<http://libvirt.org/formatdomain.html>

Option strings are in the format of: --option opt=val,opt2=val2,...  example: --disk path=/tmp/foo,shareable=on. Properties can be used with '--option opt=,', so to clear a disks cache setting you could use '--disk cache=,'

For any option, use --option=? to see a list of all available sub options, example: --disk=?  or  --boot=?

--help output also lists a few general examples. See the EXAMPLES section below for some common examples.


=back




=head1 MISCELLANEOUS OPTIONS

=over 4

=item B<-h>

=item B<--help>

Show the help message and exit

=item B<--version>

Show program's version number and exit

=item B<-q>

=item B<--quiet>

Avoid verbose output.

=item B<-d>

=item B<--debug>

Print debugging information

=back



=head1 EXAMPLES

See a list of all suboptions that --disk and --network take

  # virt-xml --disk=? --network=?

Change the <description> of domain 'example':

  # virt-xml example --edit --metadata description="my new description"

# Enable the boot device menu for domain 'example':

  # virt-xml example --edit --boot menu=on

Clear the previous <cpu> definition of domain 'winxp', change it to 'host-model', but interactively confirm the diff before saving:

  # virt-xml winxp --edit --cpu host-model,clearxml=yes --confirm

Change the second sound card to model=ich6 on 'fedora19', but only output the diff:

  # virt-xml fedora19 --edit 2 --sound model=ich6 --print-diff

Update the every graphics device password to 'foo' of the running VM 'rhel6':

  # virt-xml rhel6 --edit all --graphics password=foo --update

Remove the disk path from disk device hdc:

  # virt-xml rhel6 --edit target=hdc --disk path=

Change all disk devices of type 'disk' to use cache=none, using XML from stdin, printing the new XML to stdout.

  # cat <xmlfile> | virt-xml --edit device=disk --disk cache=none

Change disk 'hda' IO to native and use startup policy as 'optional'.

  # virt-xml fedora20 --edit target=hda --disk io=native,startup_policy=optional

Change all host devices to use driver_name=vfio for VM 'fedora20' on the remote connection

  # virt-xml --connect qemu+ssh://remotehost/system \
             fedora20 --edit all --hostdev driver_name=vfio

Hotplug host USB device 001.003 to running domain 'fedora19':

  # virt-xml f19 --add-device --hostdev 001.003 --update

Add a spicevmc channel to the domain 'winxp', that will be available after the next VM shutdown.

  # virt-xml winxp --add-device --channel spicevmc

Create a 10G qcow2 disk image and attach it to 'fedora18' for the next VM startup:

  # virt-xml fedora18 --add-device \
    --disk /var/lib/libvirt/images/newimage.qcow2,format=qcow2,size=10

Remove the disk vdb from the running domain 'rhel7':

  # virt-xml rhel7 --remove-device --disk target=vdb

Remove all graphics devices from the VM 'rhel7' after the next shutdown:

  # virt-xml rhel7 --remove-device --graphics all

Generate XML for a virtio console device and print it to stdout:

  # virt-xml --build-xml --console pty,target_type=virtio


=head1 BUGS

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

=head1 COPYRIGHT

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

=head1 SEE ALSO

L<virt-install(1)>, the project website C<http://virt-manager.org>

=cut