Highlight that the tool is not a general purpose snapshotting tool. Add some examples. --- snapshot/v2v-snapshot.pl | 79 +++++++++++++++++++++++++++++++++++++++++++--- 1 files changed, 74 insertions(+), 5 deletions(-) diff --git a/snapshot/v2v-snapshot.pl b/snapshot/v2v-snapshot.pl index ce66bca..8408d13 100755 --- a/snapshot/v2v-snapshot.pl +++ b/snapshot/v2v-snapshot.pl @@ -48,11 +48,13 @@ v2v-snapshot - Convert a guest to use a qcow2 snapshot for storage =head1 DESCRIPTION -v2v-snapshot is a tool for creating a local snapshot of a guest's storage. It -is suitable for use when making a change to a guest which might have to be -rolled back. It is not intended as a long-term storage option. v2v-snapshot -creates a qcow2 snapshot for all a guest's block devices and updates the guest's -libvirt domain to use them. +v2v-snapshot is a tool for creating a local snapshot of a guest's storage. It is +suitable for use when making a change to a guest which might have to be rolled +back. v2v-snapshot creates a qcow2 snapshot for all a guest's block devices and +updates the guest's libvirt domain to use them. + +B<v2v-snapshot can only snapshot a guest which is shutdown. It is not intended +as a long-term storage option.> When a change has been tested, v2v-snapshot can either commit the change, which will update the original storage with the changes made to the snapshot, or @@ -757,6 +759,73 @@ sub _get_xml_path return $xmldir.'/'._get_guest_name($dom).'.xml'; } +=head1 EXAMPLES + +=head2 Snapshot a local guest + +=over + +This example covers snapshotting a guest which is available through libvirt on +the local machine. The guest domain's name is I<E<lt>guestE<gt>>. + +First ensure the guest is shutdown: + + # virsh destroy <guest> + +Snapshot the guest: + + # v2v-snapshot <guest> + +Start the guest, make some changes, modify hardware, test changes. To commit +the changes: + + # v2v-snapshot --commit <guest> + +Alternatively, to rollback the changes: + + # v2v-snapshot --rollback <guest> + +=back + +=head2 Snapshot an imported guest + +=over + +This example covers snapshotting a guest which has been copied from another +machine. For this to work you must have the domain XML exported from the origin +machine: + + (Origin) # virsh dumpxml <guest> > guest.xml + +You must also present all of the guest's disk images to the local machine in the +locations specified in guest.xml. If copying the images, the easiest +way to achieve this is to copy it to the same path on the local machine as it +had on the origin machine. If the storage can be remotely mounted, it should be +presented to the local machine with the same paths as on the origin machine. If +the location of the storage must change, you must manually edit guest.xml to +reflect the new paths. + +If it is possible to create the domain on the local machine: + + # v2v-snapshot -i libvirtxml guest.xml + +This command will create the imported domain locally with snapshot storage. + +If it is not possible to create the domain locally, for example because it is a +Xen domain and the local libvirt cannot manage Xen domains: + + # v2v-snapshot -o snapshot-guest.xml -i libvirtxml guest.xml + +This command does not attempt the create the domain locally, which would fail. +Instead it writes updated domain XML to I<snapshot-guest.xml>. The disks in +snapshot-guest.xml point to the newly created snapshot volumes. + +The latter method of import is intended for use when importing a Xen domain from +a origin machine for conversion with L<virt-v2v(1)>. virt-v2v should be given +I<snapshot-guest.xml> as the domain XML. + +=back + =head1 SEE ALSO L<virt-v2v(1)>, -- 1.6.2.5