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