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, but 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 gives you a rescue shell and some simple recovery tools
  53 which you can use on a virtual machine disk image.
  54
  55 After running virt-rescue, what you see under C</> is the recovery
  56 appliance.
  57
  58 You must mount the virtual machine's filesystems by hand.  There
  59 is a directory C</sysroot> where you can mount filesystems.  For
  60 example:
  61
  62  ><rescue> lvs
  63  LV      VG        Attr   LSize   Origin Snap%  Move Log Copy%  Convert
  64  lv_root vg_f11x64 -wi-a-   8.83G
  65  lv_swap vg_f11x64 -wi-a- 992.00M
  66  ><rescue> mount /dev/vg_f11x64/lv_root /sysroot
  67  ><rescue> ls /sysroot
  68
  69 This tool is just designed for quick interactive hacking on a virtual
  70 machine.  For more structured access to a virtual machine disk image,
  71 you should use L<guestfs(3)>.  To get a structured shell, use
  72 L<guestfish(1)>.
  73
  74 =head1 OPTIONS
  75
  76 =over 4
  77
  78 =cut
  79
  80 my $help;
  81
  82 =item B<--help>
  83
  84 Display brief help.
  85
  86 =cut
  87
  88 my $version;
  89
  90 =item B<--version>
  91
  92 Display version number and exit.
  93
  94 =cut
  95
  96 my $uri;
  97
  98 =item B<--connect URI> | B<-c URI>
  99
 100 If using libvirt, connect to the given I<URI>.  If omitted, then we
 101 connect to the default libvirt hypervisor.
 102
 103 If you specify guest block devices directly, then libvirt is not used
 104 at all.
 105
 106 =cut
 107
 108 my $readonly;
 109
 110 =item B<--ro> | B<-r>
 111
 112 Open the image read-only.
 113
 114 The option must always be used if the disk image or virtual machine
 115 might be running, and is generally recommended in cases where you
 116 don't need write access to the disk.
 117
 118 =back
 119
 120 =cut
 121
 122 GetOptions ("help|?" => \$help,
 123             "version" => \$version,
 124             "connect|c=s" => \$uri,
 125             "ro|r" => \$readonly,
 126     ) or pod2usage (2);
 127 pod2usage (1) if $help;
 128 if ($version) {
 129     my $g = Sys::Guestfs->new ();
 130     my %h = $g->version ();
 131     print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
 132     exit
 133 }
 134
 135 pod2usage (__"virt-rescue: no image or VM names rescue given")
 136     if @ARGV == 0;
 137
 138 my @args = (\@ARGV);
 139 push @args, address => $uri if $uri;
 140 push @args, rw => 1 unless $readonly;
 141 my $g = open_guest (@args);
 142
 143 $g->set_direct (1);
 144 $g->set_append ("guestfs_rescue=1");
 145
 146 $g->launch ();
 147
 148 exit 0;
 149
 150 =head1 SEE ALSO
 151
 152 L<guestfs(3)>,
 153 L<guestfish(1)>,
 154 L<virt-cat(1)>,
 155 L<Sys::Guestfs(3)>,
 156 L<Sys::Guestfs::Lib(3)>,
 157 L<Sys::Virt(3)>,
 158 L<http://libguestfs.org/>.
 159
 160 =head1 AUTHOR
 161
 162 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 163
 164 =head1 COPYRIGHT
 165
 166 Copyright (C) 2009 Red Hat Inc.
 167
 168 This program is free software; you can redistribute it and/or modify
 169 it under the terms of the GNU General Public License as published by
 170 the Free Software Foundation; either version 2 of the License, or
 171 (at your option) any later version.
 172
 173 This program is distributed in the hope that it will be useful,
 174 but WITHOUT ANY WARRANTY; without even the implied warranty of
 175 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 176 GNU General Public License for more details.
 177
 178 You should have received a copy of the GNU General Public License
 179 along with this program; if not, write to the Free Software
 180 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.