tools: Add section describing quoting libvirt domain names to docs (RHBZ#643624)

[libguestfs.git] / tools / virt-rescue

diff --git a/tools/virt-rescue b/tools/virt-rescue
index dadb2a2..b8902a5 100755 (executable)
--- a/tools/virt-rescue
+++ b/tools/virt-rescue
@@ -19,6 +19,7 @@
 use warnings;
 use strict;
 
+use Errno;
 use Sys::Guestfs;
 use Sys::Guestfs::Lib qw(open_guest);
 use Pod::Usage;
@@ -121,6 +122,14 @@ Display version number and exit.
 
 =cut
 
+my $append;
+
+=item B<--append kernelopts>
+
+Pass additional options to the rescue kernel.
+
+=cut
+
 my $uri;
 
 =item B<--connect URI> | B<-c URI>
@@ -133,6 +142,17 @@ at all.
 
 =cut
 
+my $memsize;
+
+=item B<--memsize MB> | B<-m MB>
+
+Change the amount of memory allocated to the rescue system.  The
+default is set by libguestfs and is small but adequate for running
+system tools.  The occasional program might need more memory.  The
+parameter is specified in megabytes.
+
+=cut
+
 my $readonly;
 
 =item B<--ro> | B<-r>
@@ -143,14 +163,26 @@ The option must always be used if the disk image or virtual machine
 might be running, and is generally recommended in cases where you
 don't need write access to the disk.
 
+=cut
+
+my $selinux;
+
+=item B<--selinux>
+
+Enable SELinux in the rescue appliance.  You should read
+L<guestfs(3)/SELINUX> before using this option.
+
 =back
 
 =cut
 
 GetOptions ("help|?" => \$help,
             "version" => \$version,
+            "append=s" => \$append,
             "connect|c=s" => \$uri,
+            "memsize|m=i" => \$memsize,
             "ro|r" => \$readonly,
+            "selinux" => \$selinux,
     ) or pod2usage (2);
 pod2usage (1) if $help;
 if ($version) {
@@ -168,10 +200,26 @@ push @args, address => $uri if $uri;
 push @args, rw => 1 unless $readonly;
 my $g = open_guest (@args);
 
+# Setting "direct mode" is required for the rescue appliance.
 $g->set_direct (1);
-$g->set_append ("guestfs_rescue=1");
 
-$g->launch ();
+# Set other features.
+$g->set_selinux (1) if $selinux;
+$g->set_memsize ($memsize) if defined $memsize;
+
+# Set the kernel command line, which must include guestfs_rescue=1
+# (see appliance/init).
+my $str = "guestfs_rescue=1";
+$str .= " $append" if defined $append;
+$g->set_append ($str);
+
+# Run the appliance.  This won't return until the user quits the
+# appliance.
+eval { $g->launch (); };
+
+# launch() expects guestfsd to start. However, virt-rescue doesn't run guestfsd,
+# so this will always fail with ECHILD when the appliance exits unexpectedly.
+die $@ unless $!{ECHILD};
 
 exit 0;
 
@@ -180,6 +228,13 @@ exit 0;
 Several environment variables affect virt-rescue.  See
 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
 
+=head1 SHELL QUOTING
+
+Libvirt guest names can contain arbitrary characters, some of which
+have meaning to the shell such as C<#> and space.  You may need to
+quote or escape these characters on the command line.  See the shell
+manual page L<sh(1)> for details.
+
 =head1 SEE ALSO
 
 L<guestfs(3)>,