File: virsh.pod

package info (click to toggle)
libvirt 0.8.3-5+squeeze5
  • links: PTS, VCS
  • area: main
  • in suites: squeeze
  • size: 77,288 kB
  • ctags: 30,516
  • sloc: ansic: 177,367; xml: 26,161; sh: 13,271; python: 4,929; makefile: 2,083; ml: 472; perl: 221; awk: 48; sed: 16
file content (1118 lines) | stat: -rw-r--r-- 36,907 bytes parent folder | download
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
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
=head1 NAME

virsh - management user interface

=head1 SYNOPSIS

virsh <subcommand> [args]

=head1 DESCRIPTION

The B<virsh> program is the main interface for managing virsh guest
domains. The program can be used to create, pause, and shutdown
domains. It can also be used to list current domains. Libvirt is a C
toolkit to interact with the virtualization capabilities of recent
versions of Linux (and other OSes). It is free software available
under the GNU Lesser General Public License. Virtualization of the
Linux Operating System means the ability to run multiple instances of
Operating Systems concurrently on a single hardware system where the
basic resources are driven by a Linux instance. The library aims at
providing a long term stable C API.  It currently supports Xen, QEmu,
KVM, LXC, OpenVZ, VirtualBox, OpenNebula, and VMware ESX.

The basic structure of most virsh usage is:

  virsh <command> <domain-id> [OPTIONS]

Where I<command> is one of the commands listed below, I<domain-id>
is the numeric domain id, or the domain name (which will be internally
translated to domain id), and I<OPTIONS> are command specific
options.  There are a few exceptions to this rule in the cases where
the command in question acts on all domains, the entire machine,
or directly on the xen hypervisor.  Those exceptions will be clear for
each of those commands.

The B<virsh> program can be used either to run one command at a time
by giving the command as an argument on the command line, or as a shell
if no command is given in the command line, it will then start a minimal
interpreter waiting for your commands and the B<quit> command will then exit
the program.

=head1 NOTES

Most B<virsh> operations rely upon the libvirt library being able to
connect to an already running libvirtd service.  This can usually be
done using the command B<invoke-rc.d libvirt-bin start>.

Most B<virsh> commands require root privileges to run due to the
communications channels used to talk to the hypervisor.  Running as
non root will return an error.

Most B<virsh> commands act synchronously, except maybe shutdown,
setvcpus and setmem. In those cases the fact that the B<virsh>
program returned, may not mean the action is complete and you
must poll periodically to detect that the guest completed the
operation.

=head1 GENERIC COMMANDS

The following commands are generic i.e. not specific to a domain.

=over 4

=item B<help> optional I<command>

This prints a small synopsis about all commands available for B<virsh>
B<help> I<command> will print out a detailed help message on that command.

=item B<quit>, B<exit>

quit this interactive terminal

=item B<version>

Will print out the major version info about what this built from.

=over 4

B<Example>

B<virsh> version

Compiled against library: libvir 0.0.6

Using library: libvir 0.0.6

Using API: Xen 3.0.0

Running hypervisor: Xen 3.0.0

=back

=item B<cd> optional I<directory>

Will change current directory to I<directory>.  The default directory
for the B<cd> command is the home directory or, if there is no I<HOME>
variable in the environment, the root directory.

This command is only available in interactive mode.

=item B<pwd>

Will print the current directory.

=item B<connect> I<URI> optional I<--readonly>

(Re)-Connect to the hypervisor. When the shell is first started, this
is automatically run with the I<URI> parameter requested by the C<-c>
option on the command line. The I<URI> parameter specifies how to
connect to the hypervisor. The documentation page at
L<http://libvirt.org/uri.html> list the values supported, but the most
common are:

=over 4

=item xen:///

this is used to connect to the local Xen hypervisor, this is the default

=item qemu:///system

connect locally as root to the daemon supervising QEmu and KVM domains

=item qemu:///session

connect locally as a normal user to his own set of QEmu and KVM domains

=item lxc:///

connect to a local linux container

=back

For remote access see the documentation page on how to make URIs.
The I<--readonly> option allows for read-only connection

=item B<uri>

Prints the hypervisor canonical URI, can be useful in shell mode.

=item B<hostname>

Print the hypervisor hostname.

=item B<nodeinfo>

Returns basic information about the node, like number and type of CPU,
and size of the physical memory.

=item B<capabilities>

Print an XML document describing the capabilities of the hypervisor
we are currently connected to. This includes a section on the host
capabilities in terms of CPU and features, and a set of description
for each kind of guest which can be virtualized. For a more complete
description see:
  L<http://libvirt.org/formatcaps.html>
The XML also show the NUMA topology information if available.

=item B<list> optional I<--inactive> I<--all>

Prints information about one or more domains.  If no domains are
specified it prints out information about running domains.

An example format for the list is as follows:

B<virsh> list
 Id Name                 State

----------------------------------

  0 Domain-0             running
  2 fedora               paused


Name is the name of the domain.  ID the domain numeric id.
State is the run state (see below).

B<STATES>

The State field lists 7 states for a domain, and which ones the
current domain is in.

=over 4

=item B<running>

The domain is currently running on a CPU

=item B<idle>

The domain is idle, and not running or runnable.  This can be caused
because the domain is waiting on IO (a traditional wait state) or has
gone to sleep because there was nothing else for it to do.

=item B<paused>

The domain has been paused, usually occurring through the administrator
running B<virsh suspend>.  When in a paused state the domain will still
consume allocated resources like memory, but will not be eligible for
scheduling by the hypervisor.

=item B<shutdown>

The domain is in the process of shutting down, i.e. the guest operating system
has been notified and should be in the process of stopping its operations
gracefully.

=item B<shut off>

The domain is not running.  Usually this indicates the domain has been
shut down completely, or has not been started.

=item B<crashed>

The domain has crashed, which is always a violent ending.  Usually
this state can only occur if the domain has been configured not to
restart on crash.

=item B<dying>

The domain is in process of dying, but hasn't completely shutdown or
crashed.

=back

=item B<freecell> optional I<cellno>

Prints the available amount of memory on the machine or within a
NUMA cell if I<cellno> is provided.

=item B<cpu-baseline> I<FILE>

Compute baseline CPU which will be supported by all host CPUs given in <file>.
The list of host CPUs is built by extracting all <cpu> elements from the
<file>. Thus, the <file> can contain either a set of <cpu> elements separated
by new lines or even a set of complete <capabilities> elements printed by
B<capabilities> command.

=item B<cpu-compare> I<FILE>

Compare CPU definition from XML <file> with host CPU. The XML <file> may
contain either host or guest CPU definition. The host CPU definition is the
<cpu> element and its contents as printed by B<capabilities> command. The
guest CPU definition is the <cpu> element and its contents from domain XML
definition. For more information on guest CPU definition see:
L<http://libvirt.org/formatdomain.html#elementsCPU>

=back

=head1 DOMAIN COMMANDS

The following commands manipulate domains directly, as stated
previously most commands take domain-id as the first parameter. The
I<domain-id> can be specified as an short integer, a name or a full UUID.

=over 4

=item B<autostart> optional I<--disable> I<domain-id>

Configure a domain to be automatically started at boot.

The option I<--disable> disables autostarting.

=item B<console> I<domain-id>

Connect the virtual serial console for the guest.

=item B<create> I<FILE> optional I<--console> I<--paused>

Create a domain from an XML <file>. An easy way to create the XML
<file> is to use the B<dumpxml> command to obtain the definition of a
pre-existing guest.  The domain will be paused if the I<--paused> option
is used and supported by the driver; otherwise it will be running.
If I<--console> is requested, attach to the console after creation.

B<Example>

 virsh dumpxml <domain-id> > domain.xml
 edit domain.xml
 virsh create < domain.xml

=item B<define> I<FILE>

Define a domain from an XML <file>. The domain definition is registered
but not started.

=item B<destroy> I<domain-id>

Immediately terminate the domain domain-id.  This doesn't give the domain
OS any chance to react, and it's the equivalent of ripping the power
cord out on a physical machine.  In most cases you will want to use
the B<shutdown> command instead.

=item B<domblkstat> I<domain> I<block-device>

Get device block stats for a running domain.

=item B<domifstat> I<domain> I<interface-device>

Get network interface stats for a running domain.

=item B<dommemstat> I<domain>

Get memory stats for a running domain.

=item B<domblkinfo> I<domain> I<block-device>

Get block device size info for a domain.

=item B<dominfo> I<domain-id>

Returns basic information about the domain.

=item B<domuuid> I<domain-name-or-id>

Convert a domain name or id to domain UUID

=item B<domid> I<domain-name-or-uuid>

Convert a domain name (or UUID) to a domain id

=item B<domjobabort> I<domain-id-or-uuid>

Abort the currently running domain job.

=item B<domjobinfo> I<domain-id-or-uuid>

Returns information about jobs running on a domain.

=item B<domname> I<domain-id-or-uuid>

Convert a domain Id (or UUID) to domain name

=item B<domstate> I<domain-id>

Returns state about a running domain.

=item B<domxml-from-native> I<format> I<config>

Convert the file I<config> in the native guest configuration format
named by I<format> to a domain XML format.

=item B<domxml-to-native> I<format> I<xml>

Convert the file I<xml> in domain XML format to the native guest
configuration format named by I<format>.

=item B<dump> I<domain-id> I<corefilepath>

Dumps the core of a domain to a file for analysis.

=item B<dumpxml> I<domain-id> optional I<--inactive> I<--security-info> I<--update-cpu>

Output the domain information as an XML dump to stdout, this format can be used
by the B<create> command. Additional options affecting the XML dump may be
used. I<--inactive> tells virsh to dump domain configuration that will be used
on next start of the domain as opposed to the current domain configuration.
Using I<--security-info> security sensitive information will also be included
in the XML dump. I<--update-cpu> updates domain CPU requirements according to
host CPU.

=item B<edit> I<domain-id>

Edit the XML configuration file for a domain.

This is equivalent to:

 virsh dumpxml domain > domain.xml
 edit domain.xml
 virsh define domain.xml

except that it does some error checking.

The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
variables, and defaults to C<vi>.

=item B<managedsave> I<domain-id>

Ask libvirt to save a running domain state in a place managed by libvirt.
If libvirt is asked to restart the domain later on it will resume it from
the saved domain state (and the state is discarded).

=item B<managedsave-remove> I<domain-id>

Remove the managed save file for a domain if it exists.  The next time the
domain is started it will not restore to its previous state but instead will
do a full boot.

=item B<migrate> optional I<--live> I<--suspend> I<domain-id> I<desturi> I<migrateuri>

Migrate domain to another host.  Add --live for live migration; --suspend
leaves the domain paused on the destination host. The I<desturi> is the
connection URI of the destination host, and I<migrateuri> is the
migration URI, which usually can be omitted.

=item B<migrate-setmaxdowntime> I<domain-id> I<downtime>

Set maximum tolerable downtime for a domain which is being live-migrated to
another host.  The I<downtime> is a number of milliseconds the guest is allowed
to be down at the end of live migration.

=item B<reboot> I<domain-id>

Reboot a domain.  This acts just as if the domain had the B<reboot>
command run from the console.  The command returns as soon as it has
executed the reboot action, which may be significantly before the
domain actually reboots.

The exact behavior of a domain when it reboots is set by the
I<on_reboot> parameter in the domain's XML definition.

=item B<restore> I<state-file>

Restores a domain from an B<virsh save> state file.  See I<save> for more info.

=item B<save> I<domain-id> I<state-file>

Saves a running domain to a state file so that it can be restored
later.  Once saved, the domain will no longer be running on the
system, thus the memory allocated for the domain will be free for
other domains to use.  B<virsh restore> restores from this state file.

This is roughly equivalent to doing a hibernate on a running computer,
with all the same limitations.  Open network connections may be
severed upon restore, as TCP timeouts may have expired.

=item B<schedinfo> optional I<--set> B<parameter=value> I<domain-id>

=item B<schedinfo> optional I<--weight> B<number> optional I<--cap> B<number> I<domain-id>

Allows you to show (and set) the domain scheduler parameters. The parameters available for each hypervisor are:

LXC, QEMU/KVM (posix scheduler): cpu_shares

Xen (credit scheduler): weight, cap

ESX (allocation scheduler): reservation, limit, shares

B<Note>: The cpu_shares parameter has a valid value range of 0-262144.

B<Note>: The weight and cap parameters are defined only for the
XEN_CREDIT scheduler and are now I<DEPRECATED>.

=item B<setmem> I<domain-id> B<kilobytes>

Change the current memory allocation in the guest domain. This should take
effect immediately. The memory limit is specified in
kilobytes.

For Xen, you can only adjust the memory of a running domain if the
domain is paravirtualized or running the PV balloon driver.

=item B<setmaxmem> I<domain-id> B<kilobytes>

Change the maximum memory allocation limit in the guest domain. This should
not change the current memory use. The memory limit is specified in
kilobytes.

=item B<setvcpus> I<domain-id> I<count>

Change the number of virtual CPUs active in the guest domain. Note that
I<count> may be limited by host, hypervisor or limit coming from the
original description of domain.

For Xen, you can only adjust the virtual CPUs of a running domain if
the domain is paravirtualized.

=item B<shutdown> I<domain-id>

Gracefully shuts down a domain.  This coordinates with the domain OS
to perform graceful shutdown, so there is no guarantee that it will
succeed, and may take a variable length of time depending on what
services must be shutdown in the domain.

The exact behavior of a domain when it shuts down is set by the
I<on_shutdown> parameter in the domain's XML definition.

=item B<start> I<domain-name> optional I<--console> I<--paused>

Start a (previously defined) inactive domain.  The domain will be paused
if the I<--paused> option is used and supported by the driver; otherwise
it will be running.
If I<--console> is requested, attach to the console after creation.

=item B<suspend> I<domain-id>

Suspend a running domain. It is kept in memory but won't be scheduled
anymore.

=item B<resume> I<domain-id>

Moves a domain out of the suspended state.  This will allow a previously
suspended domain to now be eligible for scheduling by the underlying
hypervisor.

=item B<ttyconsole> I<domain-id>

Output the device used for the TTY console of the domain. If the information
is not available the processes will provide an exit code of 1.

=item B<undefine> I<domain-id>

Undefine the configuration for an inactive domain. Since it's not running
the domain name or UUID must be used as the I<domain-id>.

=item B<vcpuinfo> I<domain-id>

Returns basic information about the domain virtual CPUs, like the number of
vCPUs, the running time, the affinity to physical processors.

=item B<vcpupin> I<domain-id> I<vcpu> I<cpulist>

Pin domain VCPUs to host physical CPUs. The I<vcpu> number must be provided
and I<cpulist> is a comma separated list of physical CPU numbers.

=item B<vncdisplay> I<domain-id>

Output the IP address and port number for the VNC display. If the information
is not available the processes will provide an exit code of 1.

=back

=head1 DEVICE COMMANDS

The following commands manipulate devices associated to domains.
The domain-id can be specified as an short integer, a name or a full UUID.
To better understand the values allowed as options for the command
reading the documentation at L<http://libvirt.org/formatdomain.html> on the
format of the device sections to get the most accurate set of accepted values.

=over 4

=item B<attach-device> I<domain-id> I<FILE>

Attach a device to the domain, using a device definition in an XML file.
See the documentation to learn about libvirt XML format for a device.
For cdrom and floppy devices, this command only replaces the media within
the single existing device; consider using B<update-device> for this usage.

=item B<attach-disk> I<domain-id> I<source> I<target> optional I<--driver driver> I<--subdriver subdriver> I<--type type> I<--mode mode>

Attach a new disk device to the domain.
I<source> and I<target> are paths for the files and devices.
I<driver> can be I<file>, I<tap> or I<phy> depending on the kind of access.
I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default,
although this use only replaces the media within the existing virtual cdrom or
floppy device; consider using B<update-device> for this usage instead.
I<mode> can specify the two specific mode I<readonly> or I<shareable>.

=item B<attach-interface> I<domain-id> I<type> I<source> optional I<--target target> I<--mac mac> I<--script script>

Attach a new network interface to the domain.
I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device.
I<source> indicates the source device.
I<target> allows to indicate the target device in the guest.
I<mac> allows to specify the MAC address of the network interface.
I<script> allows to specify a path to a script handling a bridge instead of
the default one.

=item B<detach-device> I<domain-id> I<FILE>

Detach a device from the domain, takes the same kind of XML descriptions
as command B<attach-device>.

=item B<detach-disk> I<domain-id> I<target>

Detach a disk device from a domain. The I<target> is the device as seen
from the domain.

=item B<detach-interface> I<domain-id> I<type> optional I<--mac mac>

Detach a network interface from a domain.
I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device.
It is recommended to use the I<mac> option to distinguish between the interfaces
if more than one are present on the domain.

=item B<update-device> I<domain-id> I<file> optional I<--persistent>

Update the characteristics of a device associated with I<domain-id>,
based on the device definition in an XML I<file>.  If the I<--persistent>
option is used, the changes will affect the next boot of the domain.
See the documentation to learn about libvirt XML format for a device.

=back

=head1 VIRTUAL NETWORK COMMANDS

The following commands manipulate networks. Libvirt has the capability to
define virtual networks which can then be used by domains and linked to
actual network devices. For more detailed information about this feature
see the documentation at L<http://libvirt.org/formatnetwork.html> . A lot
of the command for virtual networks are similar to the one used for domains,
but the way to name a virtual network is either by its name or UUID.

=over 4

=item B<net-autostart> I<network> optional I<--disable>

Configure a virtual network to be automatically started at boot.
The I<--disable> option disable autostarting.

=item B<net-create> I<file>

Create a virtual network from an XML I<file>, see the documentation to get
a description of the XML network format used by libvirt.

=item B<net-define> I<file>

Define a virtual network from an XML I<file>, the network is just defined but
not instantiated.

=item B<net-destroy> I<network>

Destroy a given virtual network specified by its name or UUID. This takes
effect immediately.

=item B<net-dumpxml> I<network>

Output the virtual network information as an XML dump to stdout.

=item B<net-edit> I<network>

Edit the XML configuration file for a network.

This is equivalent to:

 virsh net-dumpxml network > network.xml
 edit network.xml
 virsh net-define network.xml

except that it does some error checking.

The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
variables, and defaults to C<vi>.

=item B<net-list> optional I<--inactive> or I<--all>

Returns the list of active networks, if I<--all> is specified this will also
include defined but inactive networks, if I<--inactive> is specified only the
inactive ones will be listed.

=item B<net-name> I<network-UUID>

Convert a network UUID to network name.

=item B<net-start> I<network>

Start a (previously defined) inactive network.

=item B<net-undefine> I<network>

Undefine the configuration for an inactive network.

=item B<net-uuid> I<network-name>

Convert a network name to network UUID.

=back

=head1 STORAGE POOL COMMANDS

The following commands manipulate storage pools. Libvirt has the
capability to manage various storage solutions, including files, raw
partitions, and domain-specific formats, used to provide the storage
volumes visible as devices within virtual machines. For more detailed
information about this feature, see the documentation at
L<http://libvirt.org/formatstorage.html> . A lot of the commands for
pools are similar to the ones used for domains.

=over 4

=item B<find-storage-pool-sources> I<type> optional I<srcSpec>

Returns XML describing all storage pools of a given I<type> that could
be found.  If I<srcSpec> is provided, it is a file that contains XML
to further restrict the query for pools.

=item B<find-storage-pool-sources> I<type> optional I<host> I<port>

Returns XML describing all storage pools of a given I<type> that could
be found.  If I<host> and I<port> are provided, they control where the
query is performed.

=item B<pool-autostart> I<pool-or-uuid> optional I<--disable>

Configure whether I<pool> should automatically start at boot.

=item B<pool-build> I<pool-or-uuid>

Build a given pool.

=item B<pool-create> I<file>

Create and start a pool object from the XML I<file>.

=item B<pool-create-as> I<name> I<--print-xml> I<type> optional I<source-host>
I<source-path> I<source-dev> I<source-name> <target> I<--source-format format>

Create and start a pool object I<name> from the raw parameters.  If
I<--print-xml> is specified, then print the XML of the pool object
without creating the pool.  Otherwise, the pool has the specified
I<type>.

=item B<pool-define> I<file>

Create, but do not start, a pool object from the XML I<file>.

=item B<pool-define-as> I<name> I<--print-xml> I<type> optional I<source-host>
I<source-path> I<source-dev> I<source-name> <target> I<--source-format format>

Create, but do not start, a pool object I<name> from the raw parameters.  If
I<--print-xml> is specified, then print the XML of the pool object
without defining the pool.  Otherwise, the pool has the specified
I<type>.

=item B<pool-destroy> I<pool-or-uuid>

Destroy a given I<pool> object. Libvirt will no longer manage the
storage described by the pool object, but the raw data contained in
the pool is not changed, and can be later recovered with
B<pool-create>.

=item B<pool-delete> I<pool-or-uuid>

Destroy the resources used by a given I<pool> object. This operation
is non-recoverable.  The I<pool> object will still exist after this
command.

=item B<pool-dumpxml> I<pool-or-uuid>

Returns the XML information about the I<pool> object.

=item B<pool-edit> I<pool-or-uuid>

Edit the XML configuration file for a storage pool.

This is equivalent to:

 virsh pool-dumpxml pool > pool.xml
 edit pool.xml
 virsh pool-define pool.xml

except that it does some error checking.

The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
variables, and defaults to C<vi>.

=item B<pool-info> I<pool-or-uuid>

Returns basic information about the I<pool> object.

=item B<pool-list> optional I<--inactive> I<--all> I<--details>

List pool objects known to libvirt.  By default, only pools in use by
active domains are listed; I<--inactive> lists just the inactive
pools, and I<--all> lists all pools. The I<--details> option instructs
virsh to additionally display pool persistence and capacity related
information where available.

=item B<pool-name> I<uuid>

Convert the I<uuid> to a pool name.

=item B<pool-refresh> I<pool-or-uuid>

Refresh the list of volumes contained in I<pool>.

=item B<pool-start> I<pool-or-uuid>

Start the storage I<pool>, which is previously defined but inactive.

=item B<pool-undefine> I<pool-or-uuid>

Undefine the configuration for an inactive I<pool>.

=item B<pool-uuid> I<pool>

Returns the UUID of the named I<pool>.

=back

=head1 VOLUME COMMANDS

=over 4

=item B<vol-create> I<pool-or-uuid> I<FILE>

Create a volume from an XML <file>.
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
I<FILE> is the XML <file> with the volume definition. An easy way to create the
XML <file> is to use the B<vol-dumpxml> command to obtain the definition of a
pre-existing volume.

B<Example>

 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
 edit newvolume.xml
 virsh vol-create differentstoragepool newvolume.xml

=item B<vol-create-from> I<pool-or-uuid> I<FILE> [optional I<--inputpool>
I<pool-or-uuid>] I<vol-name-or-key-or-path>

Create a volume, using another volume as input.
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
I<FILE> is the XML <file> with the volume definition.
I<--inputpool> I<pool-or-uuid> is the name or uuid of the storage pool the
source volume is in.
I<vol-name-or-key-or-path> is the name or key or path of the source volume.

=item B<vol-create-as> I<pool-or-uuid> I<name> I<capacity> optional
I<--allocation> I<size> I<--format> I<string> I<--backing-vol>
I<vol-name-or-key-or-path> I<--backing-vol-format> I<string>

Create a volume from a set of arguments.
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume
in.
I<name> is the name of the new volume.
I<capacity> is the size of the volume to be created, with optional k, M, G, or
T suffix.
I<--allocation> I<size> is the initial size to be allocated in the volume, with
optional k, M, G, or T suffix.
I<--format> I<string> is used in file based storage pools to specify the volume
file format to use; raw, bochs, qcow, qcow2, vmdk.
I<--backing-vol> I<vol-name-or-key-or-path> is the source backing
volume to be used if taking a snapshot of an existing volume.
I<--backing-vol-format> I<string> is the format of the snapshot backing volume;
raw, bochs, qcow, qcow2, vmdk, host_device.

=item B<vol-clone> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path> I<name>

Clone an existing volume.  Less powerful, but easier to type, version of
B<vol-create-from>.
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
I<vol-name-or-key-or-path> is the name or key or path of the source volume.
I<name> is the name of the new volume.

=item B<vol-delete> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>

Delete a given volume.
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
I<vol-name-or-key-or-path> is the name or key or path of the volume to delete.

=item B<vol-wipe> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>

Wipe a volume, ensure data previously on the volume is not accessible to future reads.
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.

=item B<vol-dumpxml> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>

Output the volume information as an XML dump to stdout.
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
I<vol-name-or-key-or-path> is the name or key or path of the volume to output the XML of.

=item B<vol-info> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>

Returns basic information about the given storage volume.
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
I<vol-name-or-key-or-path> is the name or key or path of the volume to return information for.

=item B<vol-list> [optional I<--pool>] I<pool-or-uuid> optional I<--details>

Return the list of volumes in the given storage pool.
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool.
The I<--details> option instructs virsh to additionally display volume
type and capacity related information where available.

=item B<vol-pool> [optional I<--uuid>] I<vol-key-or-path>

Return the pool name or UUID for a given volume. By default, the pool name is
returned. If the I<--uuid> option is given, the pool UUID is returned instead.
I<vol-key-or-path> is the key or path of the volume to return the pool
information for.

=item B<vol-path> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key>

Return the path for a given volume.
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
I<vol-name-or-key> is the name or key of the volume to return the path for.

=item B<vol-name> I<vol-key-or-path>

Return the name for a given volume.
I<vol-key-or-path> is the key or path of the volume to return the name for.

=item B<vol-key> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-path>

Return the volume key for a given volume.
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
I<vol-name-or-path> is the name or path of the volume to return the volume key for.

=back

=head1 SECRET COMMMANDS

The following commands manipulate "secrets" (e.g. passwords, passphrases and
encryption keys).  Libvirt can store secrets independently from their use, and
other objects (e.g. volumes or domains) can refer to the secrets for encryption
or possibly other uses.  Secrets are identified using an UUID.  See
L<http://libvirt.org/formatsecret.html> for documentation of the XML format
used to represent properties of secrets.

=over 4

=item B<secret-define> I<file>

Create a secret with the properties specified in I<file>, with no associated
secret value.  If I<file> does not specify a UUID, choose one automatically.
If I<file> specifies an UUID of an existing secret, replace its properties by
properties defined in I<file>, without affecting the secret value.

=item B<secret-dumpxml> I<secret>

Output properties of I<secret> (specified by its UUID) as an XML dump to stdout.

=item B<secret-set-value> I<secret> I<base64>

Set the value associated with I<secret> (specified by its UUID) to the value
Base64-encoded value I<base64>.

=item B<secret-get-value> I<secret>

Output the value associated with I<secret> (specified by its UUID) to stdout,
encoded using Base64.

=item B<secret-undefine> I<secret>

Delete a I<secret> (specified by its UUID), including the associated value, if
any.

=item B<secret-list>

Output a list of UUIDs of known secrets to stdout.

=back

=head1 SNAPSHOT COMMMANDS

The following commands manipulate domain snapshots.  Snapshots take the
disk, memory, and device state of a domain at a point-of-time, and save it
for future use.  They have many uses, from saving a "clean" copy of an OS
image to saving a domain's state before a potentially destructive operation.
Snapshots are identified with a unique name.  See
L<http://libvirt.org/formatsnapshot.html> for documentation of the XML format
used to represent properties of snapshots.

=over 4

=item B<snapshot-create> I<domain> I<xmlfile>

Create a snapshot for domain I<domain> with the properties specified in
I<xmlfile>.  The only properties settable for a domain snapshot are the
<name> and <description>; the rest of the fields are ignored, and
automatically filled in by libvirt.  If I<xmlfile> is completely omitted,
then libvirt will choose a value for all fields.

=item B<snapshot-current> I<domain>

Output the snapshot XML for the domain's current snapshot (if any).

=item B<snapshot-list> I<domain>

List all of the available snapshots for the given domain.

=item B<snapshot-dumpxml> I<domain> I<snapshot>

Output the snapshot XML for the domain's snapshot named I<snapshot>.

=item B<snapshot-revert> I<domain> I<snapshot>

Revert the given domain to the snapshot specified by I<snapshot>.  Be aware
that this is a destructive action; any changes in the domain since the
snapshot was taken will be lost.  Also note that the state of the domain after
snapshot-revert is complete will be the state of the domain at the time
the original snapshot was taken.

=item B<snapshot-delete> I<domain> I<snapshot> I<--children>

Delete the snapshot for the domain named I<snapshot>.  If this snapshot
has child snapshots, changes from this snapshot will be merged into the
children.  If I<--children> is passed, then delete this snapshot and any
children of this snapshot.

=back

=head1 NWFILTER COMMMANDS

The following commands manipulate network filters. Network filters allow
filtering of the network traffic coming from and going to virtual machines.
Individual network traffic filters are written in XML and may contain
references to other network filters, describe traffic filtering rules,
or contain both. Network filters are referenced by virtual machines
from within their interface description. A network filter may be referenced
by multiple virtual machines' interfaces.

=over 4

=item B<nwfilter-define> I<xmlfile>

Make a new network filter known to libvirt. If a network filter with
the same name already exists, it will be replaced with the new XML.
Any running virtual machine referencing this network filter will have
its network traffic rules adapted. If for any reason the network traffic
filtering rules cannot be instantiated by any of the running virtual
machines, then the new XML will be rejected.

=item B<nwfilter-undefine> I<nwfilter-name>

Delete a network filter. The deletion will fail if any running virtual
machine is currently using this network filter.

=item B<nwfilter-list>

List all of the available network filters.

=item B<nwfilter-dumpxml> I<nwfilter-name>

Output the network filter XML.

=item B<nwfilter-edit> I<nwfilter-name>

Edit the XML of a network filter.

This is equivalent to:

 virsh nwfilter-dumpxml myfilter > myfilter.xml
 edit myfilter.xml
 virsh nwfilter-define myfilter.xml

except that it does some error checking.
The new network filter may be rejected due to the same reason as
mentioned in I<nwfilter-define>.

The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
variables, and defaults to C<vi>.

=back

=head1 ENVIRONMENT

The following environment variables can be set to alter the behaviour
of C<virsh>

=over 4

=item VIRSH_DEFAULT_CONNECT_URI

The hypervisor to connect to by default. Set this to a URI, in the same
format as accepted by the B<connect> option.

=item VISUAL

The editor to use by the B<edit> and related options.

=item EDITOR

The editor to use by the B<edit> and related options, if C<VISUAL>
is not set.

=item LIBVIRT_DEBUG=LEVEL

Turn on verbose debugging of all libvirt API calls. Valid levels are

=over 4

=item * LIBVIRT_DEBUG=1

Messages at level DEBUG or above

=item * LIBVIRT_DEBUG=2

Messages at level INFO or above

=item * LIBVIRT_DEBUG=3

Messages at level WARNING or above

=item * LIBVIRT_DEBUG=4

Messages at level ERROR or above

=back

For further information about debugging options consult C<http://libvirt.org/logging.html>

=back

=head1 BUGS

Report any bugs discovered to the libvirt community via the mailing
list C<http://libvirt.org/contact.html> or bug tracker C<http://libvirt.org/bugs.html>.
Alternatively report bugs to your software distributor / vendor.

=head1 AUTHORS

  Please refer to the AUTHORS file distributed with libvirt.

  Based on the xm man page by:
  Sean Dague <sean at dague dot net>
  Daniel Stekloff <dsteklof at us dot ibm dot com>

=head1 COPYRIGHT

Copyright (C) 2005, 2007-2010 Red Hat, Inc., and the authors listed in the
libvirt AUTHORS file.

=head1 LICENSE

virsh is distributed under the terms of the GNU LGPL v2+.
This is free software; see the source for copying conditions. There
is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE

=head1 SEE ALSO

L<virt-install(1)>, L<virt-xml-validate(1)>, L<virt-top(1)>, L<virt-mem(1)>, L<virt-df(1)>, L<http://www.libvirt.org/>

=cut