X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=tools%2Fvirt-rescue;h=7a87fbcffd8930bab5a206c30849eef03798f25b;hp=9ad2fa4fd76151fdc0842bf239173f72a0ac449f;hb=c6c030b64bab98602363485cb62a9e1d847d570e;hpb=945b6e0a085611b45b2ab0752a66e6e60b21666c diff --git a/tools/virt-rescue b/tools/virt-rescue index 9ad2fa4..7a87fbc 100755 --- a/tools/virt-rescue +++ b/tools/virt-rescue @@ -19,6 +19,7 @@ use warnings; use strict; +use Errno; use Sys::Guestfs; use Sys::Guestfs::Lib qw(open_guest); use Pod::Usage; @@ -37,32 +38,67 @@ virt-rescue - Run a rescue shell on a virtual machine virt-rescue [--options] disk.img [disk.img ...] +=head1 WARNING + +You must I use C on live virtual machines. Doing so +will probably result in disk corruption in the VM. C +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 + +For live VMs you I use the --ro option. -After running virt-rescue, what you see under C is the recovery -appliance. You must mount the virtual machine's filesystems by hand, -eg: +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, C etc) is the +rescue appliance. You must mount the virtual machine's filesystems by +hand. There is an empty directory called C where you can +mount filesystems. - # lvs +In the example below, we list logical volumes, then choose one to +mount under C: + + > 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 + > mount /dev/vg_f11x64/lv_root /sysroot + > ls /sysroot + +If you don't know what filesystems are available on the virtual +machine then you can use commands such as L and L +to find out. -B 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. +=head2 NOTES + +Virt-rescue can be used on I 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 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. To get a structured shell, use -L. +you should use L. To get a structured shell that you can +use to make scripted changes to guests, use L. =head1 OPTIONS @@ -86,6 +122,14 @@ Display version number and exit. =cut +my $append; + +=item B<--append kernelopts> + +Pass additional options to the rescue kernel. + +=cut + my $uri; =item B<--connect URI> | B<-c URI> @@ -98,20 +142,47 @@ at all. =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 $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 before using this option. + =back =cut GetOptions ("help|?" => \$help, "version" => \$version, + "append=s" => \$append, "connect|c=s" => \$uri, + "memsize|m=i" => \$memsize, "ro|r" => \$readonly, + "selinux" => \$selinux, ) or pod2usage (2); pod2usage (1) if $help; if ($version) { @@ -129,13 +200,34 @@ push @args, address => $uri if $uri; push @args, rw => 1 unless $readonly; 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; + +# 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 for the complete list. + =head1 SEE ALSO L, @@ -148,11 +240,11 @@ L. =head1 AUTHOR -Richard W.M. Jones L +Richard W.M. Jones L =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