Add 'virt-rescue' command.

This command runs a "rescue appliance" against a virtual machine
or disk image.  This is useful for making ad-hoc interactive
changes to virtual machines.

  $ virt-rescue --ro /dev/vg_trick/F11x64

  Welcome to virt-rescue, the libguestfs rescue shell.

  Note: The contents of / are the rescue appliance.
  You have to mount the guest's partitions under /sysroot
  before you will be able to examine them.

  bash: cannot set terminal process group (-1): Inappropriate ioctl for device
  bash: no job control in this shell
  ><rescue> mount /dev/vg_f11x64/lv_root /sysroot
  EXT4-fs (dm-0): barriers enabled
  kjournald2 starting: pid 269, dev dm-0:8, commit interval 5 seconds
  EXT4-fs (dm-0): internal journal on dm-0:8
  EXT4-fs (dm-0): delayed allocation enabled
  EXT4-fs: file extents enabled
  EXT4-fs: mballoc enabled
  EXT4-fs (dm-0): mounted filesystem with ordered data mode
  ><rescue> ls /sysroot/
  bin   dev  home  lib64       media  opt   root  selinux  sys  usr
  boot  etc  lib   lost+found  mnt    proc  sbin  srv      tmp  var
  ><rescue> exit

10 files changed, 309 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
index beca7410..37580925 100644
--- a/.gitignore
+++ b/.gitignore
@@ -74,6 +74,7 @@ html/recipes.html
 html/virt-cat.1.html
 html/virt-df.1.html
 html/virt-inspector.1.html
+html/virt-rescue.1.html
 images/100kallnewlines
 images/100kallspaces
 images/100kallzeroes
@@ -170,6 +171,7 @@ python/guestfs.py
 python/guestfs-py.c
 python/guestfs.pyc
 regressions/test1.img
+rescue/virt-rescue.1
 ruby/bindtests.rb
 ruby/ext/guestfs/extconf.h
 ruby/ext/guestfs/_guestfs.c
diff --git a/HACKING b/HACKING
index 7156bf70..a051d8a9 100644
--- a/HACKING
+++ b/HACKING
@@ -122,6 +122,9 @@ python/
 regressions/
         Regression tests.
 
+rescue/
+	The virt-rescue tool.
+
 ruby/
         Ruby bindings.
 
diff --git a/Makefile.am b/Makefile.am
index 32853fc7..043e84a3 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -47,6 +47,9 @@ endif
 if HAVE_CAT
 SUBDIRS += cat
 endif
+if HAVE_RESCUE
+SUBDIRS += rescue
+endif
 
 EXTRA_DIST = \
 	guestfs.pod guestfs-actions.pod guestfs-structs.pod \
diff --git a/TODO b/TODO
index 12b1ce68..2833d461 100644
--- a/TODO
+++ b/TODO
@@ -264,3 +264,19 @@ quickly, eg:
   load ext2
 
 Maybe it's better to create these on the fly?
+
+virt-rescue pty
+---------------
+
+See:
+http://search.cpan.org/~rgiersig/IO-Tty-1.08/Pty.pm
+http://www.perlmonks.org/index.pl?node_id=582185
+
+Note that pty requires cooperation inside the C code too (there are
+two sides to a pty, and one has to be handled after the fork).
+
+virt-rescue TERM
+----------------
+
+Pass TERM from the library, through the kernel command line, to the
+init script.
diff --git a/appliance/init b/appliance/init
index 8b97590a..545232ce 100755
--- a/appliance/init
+++ b/appliance/init
@@ -65,7 +65,15 @@ if ! grep -sq guestfs_rescue=1 /proc/cmdline; then
   exec guestfsd -f
 fi
 
+# Use appliance in rescue mode, also used by the virt-rescue command.
 TERM=linux ;# XXX library should pass this from library's environment
 PS1='><rescue> '
 export TERM PS1
+echo
+echo "Welcome to virt-rescue, the libguestfs rescue shell."
+echo
+echo "Note: The contents of / are the rescue appliance."
+echo "You have to mount the guest's partitions under /sysroot"
+echo "before you can examine them."
+echo
 exec bash -i
diff --git a/configure.ac b/configure.ac
index beef03f4..7554a59b 100644
--- a/configure.ac
+++ b/configure.ac
@@ -653,7 +653,7 @@ for pm in Pod::Usage Getopt::Long Sys::Virt Data::Dumper XML::Writer Locale::Tex
     fi
 done
 if test "x$missing_perl_modules" = "xyes"; then
-    AC_MSG_WARN([some Perl modules required to compile virt-cat, virt-df and virt-inspector are missing])
+    AC_MSG_WARN([some Perl modules required to compile virt-cat, virt-df, virt-inspector and virt-rescue are missing])
 fi
 
 AM_CONDITIONAL([HAVE_CAT],
@@ -662,6 +662,8 @@ AM_CONDITIONAL([HAVE_DF],
     [test "x$PERL" != "xno" -a "x$missing_perl_modules" != "xyes"])
 AM_CONDITIONAL([HAVE_INSPECTOR],
     [test "x$PERL" != "xno" -a "x$missing_perl_modules" != "xyes"])
+AM_CONDITIONAL([HAVE_RESCUE],
+    [test "x$PERL" != "xno" -a "x$missing_perl_modules" != "xyes"])
 
 dnl Library versioning.
 MAX_PROC_NR=`cat $srcdir/src/MAX_PROC_NR`
@@ -700,6 +702,7 @@ AC_CONFIG_FILES([Makefile
                  cat/Makefile
                  df/Makefile
                  inspector/Makefile
+                 rescue/Makefile
                  libguestfs.pc
                  gnulib/lib/Makefile
                  gnulib/tests/Makefile
@@ -733,6 +736,8 @@ echo -n "virt-df ............................. "
 if test "x$HAVE_DF" = "x"; then echo "yes"; else echo "no"; fi
 echo -n "virt-inspector ...................... "
 if test "x$HAVE_INSPECTOR" = "x"; then echo "yes"; else echo "no"; fi
+echo -n "virt-rescue ......................... "
+if test "x$HAVE_RESCUE" = "x"; then echo "yes"; else echo "no"; fi
 echo "supermin appliance .................. $enable_supermin"
 echo
 echo "If any optional component is configured 'no' when you expected 'yes'"
diff --git a/po/POTFILES.in b/po/POTFILES.in
index 44e472b9..5c703412 100644
--- a/po/POTFILES.in
+++ b/po/POTFILES.in
@@ -80,6 +80,7 @@ perl/lib/Sys/Guestfs.pm
 perl/lib/Sys/Guestfs/Lib.pm
 python/guestfs-py.c
 regressions/test-noexec-stack.pl
+rescue/virt-rescue.pl
 ruby/ext/guestfs/_guestfs.c
 src/guestfs-actions.c
 src/guestfs-bindtests.c
diff --git a/rescue/Makefile.am b/rescue/Makefile.am
new file mode 100644
index 00000000..a9a533c9
--- /dev/null
+++ b/rescue/Makefile.am
@@ -0,0 +1,48 @@
+# libguestfs virt-rescue
+# Copyright (C) 2009 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
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+EXTRA_DIST = \
+	run-rescue-locally \
+	virt-rescue.pl
+
+if HAVE_RESCUE
+
+man_MANS = virt-rescue.1
+
+noinst_DATA = @top_builddir@/html/virt-rescue.1.html
+
+virt-rescue.1: virt-rescue.pl
+	$(POD2MAN) \
+	  --section 1 \
+	  -c "Virtualization Support" \
+	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
+	  $< > $@
+
+@top_builddir@/html/virt-rescue.1.html: virt-rescue.pl
+	mkdir -p @top_builddir@/html
+	cd @top_builddir@ && pod2html \
+	  --css 'pod.css' \
+	  --title 'virt-rescue, run a rescue shell on a virtual machine' \
+	  --htmldir html \
+	  --outfile html/virt-rescue.1.html \
+	  rescue/$<
+
+install-data-hook:
+	mkdir -p $(DESTDIR)$(bindir)
+	install -m 0755 virt-rescue.pl $(DESTDIR)$(bindir)/virt-rescue
+
+endif
diff --git a/rescue/run-rescue-locally b/rescue/run-rescue-locally
new file mode 100755
index 00000000..d814ed5f
--- /dev/null
+++ b/rescue/run-rescue-locally
@@ -0,0 +1,53 @@
+#!/usr/bin/perl
+# virt-rescue
+# Copyright (C) 2009 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
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+# This script sets up the environment so you can run virt-rescue in
+# place without needing to do 'make install' first. You can also run
+# virt-rescue by creating a symlink to this script and putting it in
+# your path.
+#
+# Use it like this:
+#   ./run-rescue-locally [usual virt-rescue args ...]
+
+use strict;
+use warnings;
+
+use File::Basename qw(dirname);
+use File::Spec;
+use Cwd qw(abs_path);
+
+my $path = $0;
+
+# Follow symlinks until we get to the real file
+while(-l $path) {
+    my $link = readlink($path);
+    if(File::Spec->file_name_is_absolute($link)) {
+        $path = $link;
+    } else {
+        $path = File::Spec->catfile(dirname($path), $link);
+    }
+}
+
+# Get the absolute path of the parent directory
+$path = abs_path(dirname($path).'/..');
+
+$ENV{LD_LIBRARY_PATH} = $path.'/src/.libs';
+$ENV{LIBGUESTFS_PATH} = $path.'/appliance';
+$ENV{PERL5LIB}        = $path.'/perl/blib/lib:'.$path.'/perl/blib/arch';
+
+exec('perl', $path.'/rescue/virt-rescue.pl', @ARGV);
diff --git a/rescue/virt-rescue.pl b/rescue/virt-rescue.pl
new file mode 100755
index 00000000..a44940d5
--- /dev/null
+++ b/rescue/virt-rescue.pl
@@ -0,0 +1,169 @@
+#!/usr/bin/perl -w
+# virt-rescue
+# Copyright (C) 2009 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
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+use warnings;
+use strict;
+
+use Sys::Guestfs;
+use Sys::Guestfs::Lib qw(open_guest);
+use Pod::Usage;
+use Getopt::Long;
+use Locale::TextDomain 'libguestfs';
+
+=encoding utf8
+
+=head1 NAME
+
+virt-rescue - Run a rescue shell on a virtual machine
+
+=head1 SYNOPSIS
+
+ virt-rescue [--options] domname
+
+ virt-rescue [--options] disk.img [disk.img ...]
+
+=head1 DESCRIPTION
+
+virt-rescue gives you a rescue shell and some simple recovery tools
+which you can use on a virtual machine disk image.
+
+After running virt-rescue, what you see under C</> is the recovery
+appliance.  You must mount the virtual machine's filesystems by hand,
+eg:
+
+ # 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
+
+B<Note> 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.
+
+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<guestfs(3)>.  To get a structured shell, use
+L<guestfish(1)>.
+
+=head1 OPTIONS
+
+=over 4
+
+=cut
+
+my $help;
+
+=item B<--help>
+
+Display brief help.
+
+=cut
+
+my $version;
+
+=item B<--version>
+
+Display version number and exit.
+
+=cut
+
+my $uri;
+
+=item B<--connect URI> | B<-c URI>
+
+If using libvirt, connect to the given I<URI>.  If omitted, then we
+connect to the default libvirt hypervisor.
+
+If you specify guest block devices directly, then libvirt is not used
+at all.
+
+=cut
+
+my $readonly;
+
+=item B<--ro> | B<-r>
+
+Open the image read-only.
+
+=back
+
+=cut
+
+GetOptions ("help|?" => \$help,
+            "version" => \$version,
+            "connect|c=s" => \$uri,
+	    "ro|r" => \$readonly,
+    ) or pod2usage (2);
+pod2usage (1) if $help;
+if ($version) {
+    my $g = Sys::Guestfs->new ();
+    my %h = $g->version ();
+    print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
+    exit
+}
+
+pod2usage (__"virt-rescue: no image or VM names rescue given")
+    if @ARGV == 0;
+
+my @args = (\@ARGV);
+push @args, address => $uri if $uri;
+push @args, rw => 1 unless $readonly;
+my $g = open_guest (@args);
+
+$g->set_direct (1);
+$g->set_append ("guestfs_rescue=1");
+
+$g->launch ();
+
+exit 0;
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<guestfish(1)>,
+L<virt-cat(1)>,
+L<Sys::Guestfs(3)>,
+L<Sys::Guestfs::Lib(3)>,
+L<Sys::Virt(3)>,
+L<http://libguestfs.org/>.
+
+=head1 AUTHOR
+
+Richard W.M. Jones L<http://et.redhat.com/~rjones/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009 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
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.