tools/virt-rescue

   1 #!/usr/bin/perl -w
   2 # virt-rescue
   3 # Copyright (C) 2009 Red Hat Inc.
   4 #
   5 # This program is free software; you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 2 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program; if not, write to the Free Software
  17 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18
  19 use warnings;
  20 use strict;
  21
  22 use Sys::Guestfs;
  23 use Sys::Guestfs::Lib qw(open_guest);
  24 use Pod::Usage;
  25 use Getopt::Long;
  26 use Locale::TextDomain 'libguestfs';
  27
  28 =encoding utf8
  29
  30 =head1 NAME
  31
  32 virt-rescue - Run a rescue shell on a virtual machine
  33
  34 =head1 SYNOPSIS
  35
  36  virt-rescue [--options] domname
  37
  38  virt-rescue [--options] disk.img [disk.img ...]
  39
  40 =head1 WARNING
  41
  42 You must I<not> use C<virt-rescue> on live virtual machines.  Doing so
  43 will probably result in disk corruption in the VM.  C<virt-rescue>
  44 tries to stop you from doing this, but doesn't catch all cases.
  45
  46 However if you use the I<--ro> (read only) option, then you can attach
  47 a shell to a live virtual machine.  The results might be strange or
  48 inconsistent at times but you won't get disk corruption.
  49
  50 =head1 DESCRIPTION
  51
  52 virt-rescue is like a Rescue CD, but for virtual machines, and without
  53 the need for a CD.  virt-rescue gives you a rescue shell and some
  54 simple recovery tools which you can use to examine or rescue a virtual
  55 machine or disk image.
  56
  57 You can run virt-rescue on any virtual machine known to libvirt, or
  58 directly on disk image(s):
  59
  60  virt-rescue GuestName
  61
  62  virt-rescue --ro /path/to/disk.img
  63
  64  virt-rescue /dev/sdc
  65
  66 For live VMs you I<must> use the --ro option.
  67
  68 When you run virt-rescue on a virtual machine or disk image, you are
  69 placed in an interactive bash shell where you can use many ordinary
  70 Linux commands.  What you see in C</> (C</bin>, C</lib> etc) is the
  71 rescue appliance.  You must mount the virtual machine's filesystems by
  72 hand.  There is an empty directory called C</sysroot> where you can
  73 mount filesystems.
  74
  75 In the example below, we list logical volumes, then choose one to
  76 mount under C</sysroot>:
  77
  78  ><rescue> lvs
  79  LV      VG        Attr   LSize   Origin Snap%  Move Log Copy%  Convert
  80  lv_root vg_f11x64 -wi-a-   8.83G
  81  lv_swap vg_f11x64 -wi-a- 992.00M
  82  ><rescue> mount /dev/vg_f11x64/lv_root /sysroot
  83  ><rescue> ls /sysroot
  84
  85 If you don't know what filesystems are available on the virtual
  86 machine then you can use commands such as L<parted(8)> and L<lvs(8)>
  87 to find out.
  88
  89 =head2 NOTES
  90
  91 Virt-rescue can be used on I<any> disk image file or device, not just
  92 a virtual machine.  For example you can use it on a blank file if you
  93 want to partition that file (although we would recommend using
  94 L<guestfish(1)> instead as it is more suitable for this purpose).  You
  95 can even use virt-rescue on things like SD cards.
  96
  97 This tool is just designed for quick interactive hacking on a virtual
  98 machine.  For more structured access to a virtual machine disk image,
  99 you should use L<guestfs(3)>.  To get a structured shell that you can
 100 use to make scripted changes to guests, use L<guestfish(1)>.
 101
 102 =head1 OPTIONS
 103
 104 =over 4
 105
 106 =cut
 107
 108 my $help;
 109
 110 =item B<--help>
 111
 112 Display brief help.
 113
 114 =cut
 115
 116 my $version;
 117
 118 =item B<--version>
 119
 120 Display version number and exit.
 121
 122 =cut
 123
 124 my $append;
 125
 126 =item B<--append kernelopts>
 127
 128 Pass additional options to the rescue kernel.
 129
 130 =cut
 131
 132 my $uri;
 133
 134 =item B<--connect URI> | B<-c URI>
 135
 136 If using libvirt, connect to the given I<URI>.  If omitted, then we
 137 connect to the default libvirt hypervisor.
 138
 139 If you specify guest block devices directly, then libvirt is not used
 140 at all.
 141
 142 =cut
 143
 144 my $memsize;
 145
 146 =item B<--memsize MB> | B<-m MB>
 147
 148 Change the amount of memory allocated to the rescue system.  The
 149 default is set by libguestfs and is small but adequate for running
 150 system tools.  The occasional program might need more memory.  The
 151 parameter is specified in megabytes.
 152
 153 =cut
 154
 155 my $readonly;
 156
 157 =item B<--ro> | B<-r>
 158
 159 Open the image read-only.
 160
 161 The option must always be used if the disk image or virtual machine
 162 might be running, and is generally recommended in cases where you
 163 don't need write access to the disk.
 164
 165 =cut
 166
 167 my $selinux;
 168
 169 =item B<--selinux>
 170
 171 Enable SELinux in the rescue appliance.  You should read
 172 L<guestfs(3)/SELINUX> before using this option.
 173
 174 =back
 175
 176 =cut
 177
 178 GetOptions ("help|?" => \$help,
 179             "version" => \$version,
 180             "append=s" => \$append,
 181             "connect|c=s" => \$uri,
 182             "memsize|m=i" => \$memsize,
 183             "ro|r" => \$readonly,
 184             "selinux" => \$selinux,
 185     ) or pod2usage (2);
 186 pod2usage (1) if $help;
 187 if ($version) {
 188     my $g = Sys::Guestfs->new ();
 189     my %h = $g->version ();
 190     print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
 191     exit
 192 }
 193
 194 pod2usage (__"virt-rescue: no image or VM names rescue given")
 195     if @ARGV == 0;
 196
 197 my @args = (\@ARGV);
 198 push @args, address => $uri if $uri;
 199 push @args, rw => 1 unless $readonly;
 200 my $g = open_guest (@args);
 201
 202 # Setting "direct mode" is required for the rescue appliance.
 203 $g->set_direct (1);
 204
 205 # Set other features.
 206 $g->set_selinux (1) if $selinux;
 207 $g->set_memsize ($memsize) if defined $memsize;
 208
 209 # Set the kernel command line, which must include guestfs_rescue=1
 210 # (see appliance/init).
 211 my $str = "guestfs_rescue=1";
 212 $str .= " $append" if defined $append;
 213 $g->set_append ($str);
 214
 215 # Run the appliance.  This won't return until the user quite the
 216 # appliance.
 217 $g->launch ();
 218
 219 exit 0;
 220
 221 =head1 ENVIRONMENT VARIABLES
 222
 223 Several environment variables affect virt-rescue.  See
 224 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
 225
 226 =head1 SEE ALSO
 227
 228 L<guestfs(3)>,
 229 L<guestfish(1)>,
 230 L<virt-cat(1)>,
 231 L<Sys::Guestfs(3)>,
 232 L<Sys::Guestfs::Lib(3)>,
 233 L<Sys::Virt(3)>,
 234 L<http://libguestfs.org/>.
 235
 236 =head1 AUTHOR
 237
 238 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 239
 240 =head1 COPYRIGHT
 241
 242 Copyright (C) 2009-2010 Red Hat Inc.
 243
 244 This program is free software; you can redistribute it and/or modify
 245 it under the terms of the GNU General Public License as published by
 246 the Free Software Foundation; either version 2 of the License, or
 247 (at your option) any later version.
 248
 249 This program is distributed in the hope that it will be useful,
 250 but WITHOUT ANY WARRANTY; without even the implied warranty of
 251 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 252 GNU General Public License for more details.
 253
 254 You should have received a copy of the GNU General Public License
 255 along with this program; if not, write to the Free Software
 256 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.