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 $memsize;
 146
 147 =item B<--memsize MB> | B<-m MB>
 148
 149 Change the amount of memory allocated to the rescue system.  The
 150 default is set by libguestfs and is small but adequate for running
 151 system tools.  The occasional program might need more memory.  The
 152 parameter is specified in megabytes.
 153
 154 =cut
 155
 156 my $readonly;
 157
 158 =item B<--ro> | B<-r>
 159
 160 Open the image read-only.
 161
 162 The option must always be used if the disk image or virtual machine
 163 might be running, and is generally recommended in cases where you
 164 don't need write access to the disk.
 165
 166 =cut
 167
 168 my $selinux;
 169
 170 =item B<--selinux>
 171
 172 Enable SELinux in the rescue appliance.  You should read
 173 L<guestfs(3)/SELINUX> before using this option.
 174
 175 =back
 176
 177 =cut
 178
 179 GetOptions ("help|?" => \$help,
 180             "version" => \$version,
 181             "append=s" => \$append,
 182             "connect|c=s" => \$uri,
 183             "memsize|m=i" => \$memsize,
 184             "ro|r" => \$readonly,
 185             "selinux" => \$selinux,
 186     ) or pod2usage (2);
 187 pod2usage (1) if $help;
 188 if ($version) {
 189     my $g = Sys::Guestfs->new ();
 190     my %h = $g->version ();
 191     print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
 192     exit
 193 }
 194
 195 pod2usage (__"virt-rescue: no image or VM names rescue given")
 196     if @ARGV == 0;
 197
 198 my @args = (\@ARGV);
 199 push @args, address => $uri if $uri;
 200 push @args, rw => 1 unless $readonly;
 201 my $g = open_guest (@args);
 202
 203 # Setting "direct mode" is required for the rescue appliance.
 204 $g->set_direct (1);
 205
 206 # Set other features.
 207 $g->set_selinux (1) if $selinux;
 208 $g->set_memsize ($memsize) if defined $memsize;
 209
 210 # Set the kernel command line, which must include guestfs_rescue=1
 211 # (see appliance/init).
 212 my $str = "guestfs_rescue=1";
 213 $str .= " $append" if defined $append;
 214 $g->set_append ($str);
 215
 216 # Run the appliance.  This won't return until the user quits the
 217 # appliance.
 218 eval { $g->launch (); };
 219
 220 # launch() expects guestfsd to start. However, virt-rescue doesn't run guestfsd,
 221 # so this will always fail with ECHILD when the appliance exits unexpectedly.
 222 die $@ unless $!{ECHILD};
 223
 224 exit 0;
 225
 226 =head1 ENVIRONMENT VARIABLES
 227
 228 Several environment variables affect virt-rescue.  See
 229 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
 230
 231 =head1 SHELL QUOTING
 232
 233 Libvirt guest names can contain arbitrary characters, some of which
 234 have meaning to the shell such as C<#> and space.  You may need to
 235 quote or escape these characters on the command line.  See the shell
 236 manual page L<sh(1)> for details.
 237
 238 =head1 SEE ALSO
 239
 240 L<guestfs(3)>,
 241 L<guestfish(1)>,
 242 L<virt-cat(1)>,
 243 L<Sys::Guestfs(3)>,
 244 L<Sys::Guestfs::Lib(3)>,
 245 L<Sys::Virt(3)>,
 246 L<http://libguestfs.org/>.
 247
 248 =head1 AUTHOR
 249
 250 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 251
 252 =head1 COPYRIGHT
 253
 254 Copyright (C) 2009-2010 Red Hat Inc.
 255
 256 This program is free software; you can redistribute it and/or modify
 257 it under the terms of the GNU General Public License as published by
 258 the Free Software Foundation; either version 2 of the License, or
 259 (at your option) any later version.
 260
 261 This program is distributed in the hope that it will be useful,
 262 but WITHOUT ANY WARRANTY; without even the implied warranty of
 263 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 264 GNU General Public License for more details.
 265
 266 You should have received a copy of the GNU General Public License
 267 along with this program; if not, write to the Free Software
 268 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.