#!/usr/bin/perl -w
# virt-rescue
-# 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
use warnings;
use strict;
+use Errno;
use Sys::Guestfs;
use Sys::Guestfs::Lib qw(open_guest);
use Pod::Usage;
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
-After running virt-rescue, what you see under C</> is the recovery
-appliance. You must mount the virtual machine's filesystems by hand,
-eg:
+ virt-rescue /dev/sdc
- # lvs
+For live VMs you I<must> use the --ro option.
+
+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
-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.
+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
+
+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
=cut
+my $append;
+
+=item B<--append kernelopts>
+
+Pass additional options to the rescue kernel.
+
+=cut
+
my $uri;
=item B<--connect URI> | B<-c URI>
=cut
+my $format;
+
+=item B<--format> raw
+
+Specify the format of disk images given on the command line. If this
+is omitted then the format is autodetected from the content of the
+disk image.
+
+If disk images are requested from libvirt, then this program asks
+libvirt for this information. In this case, the value of the format
+parameter is ignored.
+
+If working with untrusted raw-format guest disk images, you should
+ensure the format is always specified.
+
+=cut
+
+my $memsize;
+
+=item B<--memsize MB> | B<-m MB>
+
+Change the amount of memory allocated to the rescue system. The
+default is set by libguestfs and is small but adequate for running
+system tools. The occasional program might need more memory. The
+parameter is specified in megabytes.
+
+=cut
+
+my $network;
+
+=item B<--network MB>
+
+Enable QEMU user networking in the guest.
+
+=cut
+
my $readonly;
=item B<--ro> | B<-r>
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.
+
+=cut
+
+my $selinux;
+
+=item B<--selinux>
+
+Enable SELinux in the rescue appliance. You should read
+L<guestfs(3)/SELINUX> before using this option.
+
=back
=cut
GetOptions ("help|?" => \$help,
"version" => \$version,
+ "append=s" => \$append,
"connect|c=s" => \$uri,
+ "format=s" => \$format,
+ "memsize|m=i" => \$memsize,
+ "network" => \$network,
"ro|r" => \$readonly,
+ "selinux" => \$selinux,
) or pod2usage (2);
pod2usage (1) if $help;
if ($version) {
my @args = (\@ARGV);
push @args, address => $uri if $uri;
push @args, rw => 1 unless $readonly;
+push @args, format => $format if defined $format;
my $g = open_guest (@args);
+# Setting "direct mode" is required for the rescue appliance.
$g->set_direct (1);
-$g->set_append ("guestfs_rescue=1");
-$g->launch ();
+# Set other features.
+$g->set_selinux (1) if $selinux;
+$g->set_memsize ($memsize) if defined $memsize;
+$g->set_network (1) if $network;
+
+# Set the kernel command line, which must include guestfs_rescue=1
+# (see appliance/init).
+my $str = "guestfs_rescue=1";
+$str .= " $append" if defined $append;
+$g->set_append ($str);
+
+# Run the appliance. This won't return until the user quits the
+# appliance.
+eval { $g->launch (); };
+
+# launch() expects guestfsd to start. However, virt-rescue doesn't run guestfsd,
+# so this will always fail with ECHILD when the appliance exits unexpectedly.
+die $@ unless $!{ECHILD};
exit 0;
+=head1 ENVIRONMENT VARIABLES
+
+Several environment variables affect virt-rescue. See
+L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
+
+=head1 SHELL QUOTING
+
+Libvirt guest names can contain arbitrary characters, some of which
+have meaning to the shell such as C<#> and space. You may need to
+quote or escape these characters on the command line. See the shell
+manual page L<sh(1)> for details.
+
=head1 SEE ALSO
L<guestfs(3)>,
=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
git.annexia.org / libguestfs.git / blobdiff