[Libguestfs] [PATCH v4 5/5] v2v: better explain --in-place

[Roman Kagan]

It seems that the documentation for --in-place mode of v2v wasn't clear
enough, so try to explain it better.

Signed-off-by: Roman Kagan <rkagan at virtuozzo.com>
---
 v2v/virt-v2v.pod | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/v2v/virt-v2v.pod b/v2v/virt-v2v.pod
index 14da764..c4b49e9 100644
--- a/v2v/virt-v2v.pod
+++ b/v2v/virt-v2v.pod
@@ -348,11 +348,13 @@ format in the metadata.
 
 Do not create an output virtual machine in the target hypervisor.
 Instead, adjust the guest OS in the source VM to run in the input
-hypervisor.
+hypervisor (which is also the target one in this case) on the virtual
+hardware defined in the VM configuration.
 
 This mode is meant for integration with other toolsets, which take the
 responsibility of converting the VM configuration, providing for
-rollback in case of errors, transforming the storage, etc.
+rollback in case of errors, transforming the storage, etc.  See
+L</IN PLACE CONVERSION> below.
 
 Conflicts with all I<-o *> options.
 
@@ -1730,6 +1732,31 @@ that instead.
    </devices>
  </domain>
 
+=head1 IN PLACE CONVERSION
+
+It is also possible to use virt-v2v in scenarios where a foreign VM has already
+been imported into a KVM-based hypervisor, but still needs ajustments in the
+guest to make it run in the new virtual hardware.
+
+In that case it is assumed that a third-party tool has created the target VM in
+the supported KVM-based hypervisor (libvirt/qemu) based on the source VM
+configuration and contents, but using virtual devices more appropriate for KVM
+(e.g. virtio storage and network, etc.).
+
+Then, to make the guest OS boot and run in the changed environment, one can
+use:
+
+ virt-v2v -ic qemu:///system converted_vm --in-place
+
+virt-v2v will analyze the configuration of I<converted_vm> in I<qemu:///system>
+libvirt instance, and apply various fixups to the guest OS configuration to
+make it match the VM configuration.  In particular, it may include installing
+virtio drivers, configuring the bootloader, the mountpoints, the network
+interfaces, and so on.
+
+Should an error occur during the operation, virt-v2v exits with an error code
+leaving the VM in an undefined state.
+
 =head1 MACHINE READABLE OUTPUT
 
 The I<--machine-readable> option can be used to make the output more
-- 
2.5.0