← Back to branch summary

~ubuntu-branches/ubuntu/natty/libvirt/natty-proposed

« back to all changes in this revision

Viewing changes to tools/virsh.pod

  • Committer: Bazaar Package Importer
  • Author(s): Laurent Léonard
  • Date: 2010-07-06 12:14:33 UTC
  • mto: (3.4.17 sid) (1.2.6 upstream) (0.3.1 upstream)
  • mto: This revision was merged to the branch mainline in revision 93.
  • Revision ID: james.westby@ubuntu.com-20100706121433-94utbax9zjvmkcsj
Tags: upstream-0.8.2
Import upstream version 0.8.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/virsh.pod
89
89
 
90
90
=back
91
91
 
92
 
=item B<cd> I<directory> optional
 
92
=item B<cd> optional I<directory>
93
93
 
94
94
Will change current directory to I<directory>.  The default directory
95
95
for the B<cd> command is the home directory or, if there is no I<HOME>
156
156
  L<http://libvirt.org/formatcaps.html>
157
157
The XML also show the NUMA topology information if available.
158
158
 
159
 
=item B<list>
 
159
=item B<list> optional I<--inactive> I<--all>
160
160
 
161
161
Prints information about one or more domains.  If no domains are
162
 
specified it prints out information about all domains.
 
162
specified it prints out information about running domains.
163
163
 
164
164
An example format for the list is as follows:
165
165
 
177
177
 
178
178
B<STATES>
179
179
 
180
 
The State field lists 6 states for a domain, and which ones the
 
180
The State field lists 7 states for a domain, and which ones the
181
181
current domain is in.
182
182
 
183
183
=over 4
205
205
has been notified and should be in the process of stopping its operations
206
206
gracefully.
207
207
 
 
208
=item B<shut off>
 
209
 
 
210
The domain is not running.  Usually this indicates the domain has been
 
211
shut down completely, or has not been started.
 
212
 
208
213
=item B<crashed>
209
214
 
210
215
The domain has crashed, which is always a violent ending.  Usually
260
265
 
261
266
Connect the virtual serial console for the guest.
262
267
 
263
 
=item B<create> I<FILE>
 
268
=item B<create> I<FILE> optional I<--console> I<--paused>
264
269
 
265
270
Create a domain from an XML <file>. An easy way to create the XML
266
271
<file> is to use the B<dumpxml> command to obtain the definition of a
267
 
pre-existing guest.
 
272
pre-existing guest.  The domain will be paused if the I<--paused> option
 
273
is used and supported by the driver; otherwise it will be running.
 
274
If I<--console> is requested, attach to the console after creation.
268
275
 
269
276
B<Example>
270
277
 
271
 
virsh dumpxml <domain-id> > domain.xml
272
 
edit domain.xml
273
 
virsh create < domain.xml
 
278
 virsh dumpxml <domain-id> > domain.xml
 
279
 edit domain.xml
 
280
 virsh create < domain.xml
274
281
 
275
282
=item B<define> I<FILE>
276
283
 
277
 
Define a domain from an XML <file>. The domain definitions is registered
 
284
Define a domain from an XML <file>. The domain definition is registered
278
285
but not started.
279
286
 
280
287
=item B<destroy> I<domain-id>
462
469
The exact behavior of a domain when it shuts down is set by the
463
470
I<on_shutdown> parameter in the domain's XML definition.
464
471
 
465
 
=item B<start> I<domain-name>
 
472
=item B<start> I<domain-name> optional I<--console> I<--paused>
466
473
 
467
 
Start a (previously defined) inactive domain.
 
474
Start a (previously defined) inactive domain.  The domain will be paused
 
475
if the I<--paused> option is used and supported by the driver; otherwise
 
476
it will be running.
 
477
If I<--console> is requested, attach to the console after creation.
468
478
 
469
479
=item B<suspend> I<domain-id>
470
480
 
485
495
=item B<undefine> I<domain-id>
486
496
 
487
497
Undefine the configuration for an inactive domain. Since it's not running
488
 
the domain name or UUId must be used as the I<domain-id>.
 
498
the domain name or UUID must be used as the I<domain-id>.
489
499
 
490
500
=item B<vcpuinfo> I<domain-id>
491
501
 
518
528
 
519
529
Attach a device to the domain, using a device definition in an XML file.
520
530
See the documentation to learn about libvirt XML format for a device.
 
531
For cdrom and floppy devices, this command only replaces the media within
 
532
the single existing device; consider using B<update-device> for this usage.
521
533
 
522
534
=item B<attach-disk> I<domain-id> I<source> I<target> optional I<--driver driver> I<--subdriver subdriver> I<--type type> I<--mode mode>
523
535
 
524
536
Attach a new disk device to the domain.
525
537
I<source> and I<target> are paths for the files and devices.
526
538
I<driver> can be I<file>, I<tap> or I<phy> depending on the kind of access.
527
 
I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default.
 
539
I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default,
 
540
although this use only replaces the media within the existing virtual cdrom or
 
541
floppy device; consider using B<update-device> for this usage instead.
528
542
I<mode> can specify the two specific mode I<readonly> or I<shareable>.
529
543
 
530
544
=item B<attach-interface> I<domain-id> I<type> I<source> optional I<--target target> I<--mac mac> I<--script script>
554
568
It is recommended to use the I<mac> option to distinguish between the interfaces
555
569
if more than one are present on the domain.
556
570
 
 
571
=item B<update-device> I<domain-id> I<file> optional I<--persistent>
 
572
 
 
573
Update the characteristics of a device associated with I<domain-id>,
 
574
based on the device definition in an XML I<file>.  If the I<--persistent>
 
575
option is used, the changes will affect the next boot of the domain.
 
576
See the documentation to learn about libvirt XML format for a device.
 
577
 
557
578
=back
558
579
 
559
580
=head1 VIRTUAL NETWORK COMMANDS
667
688
Create and start a pool object from the XML I<file>.
668
689
 
669
690
=item B<pool-create-as> I<name> I<--print-xml> I<type> optional I<source-host>
670
 
I<source-path> I<source-dev> I<source-name> <target>
 
691
I<source-path> I<source-dev> I<source-name> <target> I<--source-format format>
671
692
 
672
693
Create and start a pool object I<name> from the raw parameters.  If
673
694
I<--print-xml> is specified, then print the XML of the pool object
679
700
Create, but do not start, a pool object from the XML I<file>.
680
701
 
681
702
=item B<pool-define-as> I<name> I<--print-xml> I<type> optional I<source-host>
682
 
I<source-path> I<source-dev> I<source-name> <target>
 
703
I<source-path> I<source-dev> I<source-name> <target> I<--source-format format>
683
704
 
684
705
Create, but do not start, a pool object I<name> from the raw parameters.  If
685
706
I<--print-xml> is specified, then print the XML of the pool object
722
743
 
723
744
Returns basic information about the I<pool> object.
724
745
 
725
 
=item B<pool-list> optional I<--inactive> I<--all>
 
746
=item B<pool-list> optional I<--inactive> I<--all> I<--details>
726
747
 
727
748
List pool objects known to libvirt.  By default, only pools in use by
728
749
active domains are listed; I<--inactive> lists just the inactive
729
 
pools, and I<--all> lists all pools.
 
750
pools, and I<--all> lists all pools. The I<--details> option instructs
 
751
virsh to additionally display pool persistence and capacity related
 
752
information where available.
730
753
 
731
754
=item B<pool-name> I<uuid>
732
755
 
748
771
 
749
772
Returns the UUID of the named I<pool>.
750
773
 
 
774
=back
 
775
 
 
776
=head1 VOLUME COMMANDS
 
777
 
 
778
=item B<vol-create> I<pool-or-uuid> I<FILE>
 
779
 
 
780
Create a volume from an XML <file>.
 
781
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
 
782
I<FILE> is the XML <file> with the volume definition. An easy way to create the
 
783
XML <file> is to use the B<vol-dumpxml> command to obtain the definition of a
 
784
pre-existing volume.
 
785
 
 
786
B<Example>
 
787
 
 
788
 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
 
789
 edit newvolume.xml
 
790
 virsh vol-create differentstoragepool newvolume.xml
 
791
 
 
792
=item B<vol-create-from> I<pool-or-uuid> I<FILE> [optional I<--inputpool>
 
793
I<pool-or-uuid>] I<vol-name-or-key-or-path>
 
794
 
 
795
Create a volume, using another volume as input.
 
796
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
 
797
I<FILE> is the XML <file> with the volume definition.
 
798
I<--inputpool> I<pool-or-uuid> is the name or uuid of the storage pool the
 
799
source volume is in.
 
800
I<vol-name-or-key-or-path> is the name or key or path of the source volume.
 
801
 
 
802
=item B<vol-create-as> I<pool-or-uuid> I<name> I<capacity> optional
 
803
I<--allocation> I<size> I<--format> I<string> I<--backing-vol>
 
804
I<vol-name-or-key-or-path> I<--backing-vol-format> I<string>
 
805
 
 
806
Create a volume from a set of arguments.
 
807
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume
 
808
in.
 
809
I<name> is the name of the new volume.
 
810
I<capacity> is the size of the volume to be created, with optional k, M, G, or
 
811
T suffix.
 
812
I<--allocation> I<size> is the initial size to be allocated in the volume, with
 
813
optional k, M, G, or T suffix.
 
814
I<--format> I<string> is used in file based storage pools to specify the volume
 
815
file format to use; raw, bochs, qcow, qcow2, vmdk.
 
816
I<--backing-vol> I<vol-name-or-key-or-path> is the source backing
 
817
volume to be used if taking a snapshot of an existing volume.
 
818
I<--backing-vol-format> I<string> is the format of the snapshot backing volume;
 
819
raw, bochs, qcow, qcow2, vmdk, host_device.
 
820
 
 
821
=item B<vol-clone> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path> I<name>
 
822
 
 
823
Clone an existing volume.  Less powerful, but easier to type, version of
 
824
B<vol-create-from>.
 
825
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
 
826
I<vol-name-or-key-or-path> is the name or key or path of the source volume.
 
827
I<name> is the name of the new volume.
 
828
 
 
829
=item B<vol-delete> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
 
830
 
 
831
Delete a given volume.
 
832
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
 
833
I<vol-name-or-key-or-path> is the name or key or path of the volume to delete.
 
834
 
 
835
=item B<vol-wipe> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
 
836
 
 
837
Wipe a volume, ensure data previously on the volume is not accessible to future reads.
 
838
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
 
839
I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.
 
840
 
 
841
=item B<vol-dumpxml> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
 
842
 
 
843
Output the volume information as an XML dump to stdout.
 
844
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
 
845
I<vol-name-or-key-or-path> is the name or key or path of the volume to output the XML of.
 
846
 
 
847
=item B<vol-info> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
 
848
 
 
849
Returns basic information about the given storage volume.
 
850
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
 
851
I<vol-name-or-key-or-path> is the name or key or path of the volume to return information for.
 
852
 
 
853
=item B<vol-list> I<--pool> I<pool-or-uuid>
 
854
 
 
855
Return the list of volumes in the given storage pool.
 
856
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool.
 
857
 
 
858
=item B<vol-pool> [optional I<--uuid>] I<vol-key-or-path>
 
859
 
 
860
Return the pool name or UUID for a given volume. By default, the pool name is
 
861
returned. If the I<--uuid> option is given, the pool UUID is returned instead.
 
862
I<vol-key-or-path> is the key or path of the volume to return the pool
 
863
information for.
 
864
 
 
865
=item B<vol-path> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key>
 
866
 
 
867
Return the path for a given volume.
 
868
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
 
869
I<vol-name-or-key> is the name or key of the volume to return the path for.
 
870
 
 
871
=item B<vol-name> I<vol-key-or-path>
 
872
 
 
873
Return the name for a given volume.
 
874
I<vol-key-or-path> is the key or path of the volume to return the name for.
 
875
 
 
876
=item B<vol-key> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-path>
 
877
 
 
878
Return the volume key for a given volume.
 
879
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
 
880
I<vol-name-or-path> is the name or path of the volume to return the volume key for.
 
881
 
 
882
=back
 
883
 
751
884
=head1 SECRET COMMMANDS
752
885
 
753
886
The following commands manipulate "secrets" (e.g. passwords, passphrases and