X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=tools%2Fvirt-rescue;h=dadb2a2fece57a4f4b957cfe0bcf97ba6c0c1df7;hp=9ad2fa4fd76151fdc0842bf239173f72a0ac449f;hb=d0afef23e54f75a521eed8c7261a533776242cfc;hpb=945b6e0a085611b45b2ab0752a66e6e60b21666c;ds=sidebyside

diff --git a/tools/virt-rescue b/tools/virt-rescue
index 9ad2fa4..dadb2a2 100755
--- a/tools/virt-rescue
+++ b/tools/virt-rescue
@@ -37,32 +37,67 @@ virt-rescue - Run a rescue shell on a virtual machine
 
  virt-rescue [--options] disk.img [disk.img ...]
 
+=head1 WARNING
+
+You must I<not> use C<virt-rescue> on live virtual machines.  Doing so
+will probably result in disk corruption in the VM.  C<virt-rescue>
+tries to stop you from doing this, but doesn't catch all cases.
+
+However if you use the I<--ro> (read only) option, then you can attach
+a shell to a live virtual machine.  The results might be strange or
+inconsistent at times but you won't get disk corruption.
+
 =head1 DESCRIPTION
 
-virt-rescue gives you a rescue shell and some simple recovery tools
-which you can use on a virtual machine disk image.
+virt-rescue is like a Rescue CD, but for virtual machines, and without
+the need for a CD.  virt-rescue gives you a rescue shell and some
+simple recovery tools which you can use to examine or rescue a virtual
+machine or disk image.
+
+You can run virt-rescue on any virtual machine known to libvirt, or
+directly on disk image(s):
+
+ virt-rescue GuestName
+
+ virt-rescue --ro /path/to/disk.img
+
+ virt-rescue /dev/sdc
 
-After running virt-rescue, what you see under C</> is the recovery
-appliance.  You must mount the virtual machine's filesystems by hand,
-eg:
+For live VMs you I<must> use the --ro option.
 
- # lvs
+When you run virt-rescue on a virtual machine or disk image, you are
+placed in an interactive bash shell where you can use many ordinary
+Linux commands.  What you see in C</> (C</bin>, C</lib> etc) is the
+rescue appliance.  You must mount the virtual machine's filesystems by
+hand.  There is an empty directory called C</sysroot> where you can
+mount filesystems.
+
+In the example below, we list logical volumes, then choose one to
+mount under C</sysroot>:
+
+ ><rescue> lvs
  LV      VG        Attr   LSize   Origin Snap%  Move Log Copy%  Convert
  lv_root vg_f11x64 -wi-a-   8.83G
  lv_swap vg_f11x64 -wi-a- 992.00M
- # mount /dev/vg_f11x64/lv_root /sysroot
- # ls /sysroot
+ ><rescue> mount /dev/vg_f11x64/lv_root /sysroot
+ ><rescue> ls /sysroot
+
+If you don't know what filesystems are available on the virtual
+machine then you can use commands such as L<parted(8)> and L<lvs(8)>
+to find out.
+
+=head2 NOTES
 
-B<Note> that the virtual machine must not be powered on when you use
-this tool.  Doing so will probably result in disk corruption in the
-VM.  However if you use the I<--ro> (read only) option, then you can
-attach a shell to a running machine, but the results might be strange
-or inconsistent.
+Virt-rescue can be used on I<any> disk image file or device, not just
+a virtual machine.  For example you can use it on a blank file if you
+want to partition that file (although we would recommend using
+L<guestfish(1)> instead as it is more suitable for this purpose).  You
+can even use virt-rescue on things like SD cards.
 
 This tool is just designed for quick interactive hacking on a virtual
 machine.  For more structured access to a virtual machine disk image,
-you should use L<guestfs(3)>.  To get a structured shell, use
-L<guestfish(1)>.
+you should use L<guestfs(3)>.  To get a structured shell that you can
+use to make scripted changes to guests, use L<guestfish(1)>.
 
 =head1 OPTIONS
 
@@ -104,6 +139,10 @@ my $readonly;
 
 Open the image read-only.
 
+The option must always be used if the disk image or virtual machine
+might be running, and is generally recommended in cases where you
+don't need write access to the disk.
+
 =back
 
 =cut
@@ -136,6 +175,11 @@ $g->launch ();
 
 exit 0;
 
+=head1 ENVIRONMENT VARIABLES
+
+Several environment variables affect virt-rescue.  See
+L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
+
 =head1 SEE ALSO
 
 L<guestfs(3)>,
@@ -148,11 +192,11 @@ L<http://libguestfs.org/>.
 
 =head1 AUTHOR
 
-Richard W.M. Jones L<http://et.redhat.com/~rjones/>
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 
 =head1 COPYRIGHT
 
-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009-2010 Red Hat Inc.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by