3 # Copyright (C) 2009-2010 Red Hat Inc.
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.
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.
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.
24 use Sys::Guestfs::Lib qw(open_guest);
27 use Locale::TextDomain 'libguestfs';
33 virt-rescue - Run a rescue shell on a virtual machine
37 virt-rescue [--options] domname
39 virt-rescue [--options] disk.img [disk.img ...]
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.
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.
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.
58 You can run virt-rescue on any virtual machine known to libvirt, or
59 directly on disk image(s):
63 virt-rescue --ro /path/to/disk.img
67 For live VMs you I<must> use the --ro option.
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
76 In the example below, we list logical volumes, then choose one to
77 mount under C</sysroot>:
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
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)>
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.
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)>.
121 Display version number and exit.
127 =item B<--append kernelopts>
129 Pass additional options to the rescue kernel.
135 =item B<--connect URI> | B<-c URI>
137 If using libvirt, connect to the given I<URI>. If omitted, then we
138 connect to the default libvirt hypervisor.
140 If you specify guest block devices directly, then libvirt is not used
147 =item B<--format> raw
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
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.
157 If working with untrusted raw-format guest disk images, you should
158 ensure the format is always specified.
164 =item B<--memsize MB> | B<-m MB>
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.
175 =item B<--network MB>
177 Enable QEMU user networking in the guest.
183 =item B<--ro> | B<-r>
185 Open the image read-only.
187 The option must always be used if the disk image or virtual machine
188 might be running, and is generally recommended in cases where you
189 don't need write access to the disk.
197 Enable SELinux in the rescue appliance. You should read
198 L<guestfs(3)/SELINUX> before using this option.
204 GetOptions ("help|?" => \$help,
205 "version" => \$version,
206 "append=s" => \$append,
207 "connect|c=s" => \$uri,
208 "format=s" => \$format,
209 "memsize|m=i" => \$memsize,
210 "network" => \$network,
211 "ro|r" => \$readonly,
212 "selinux" => \$selinux,
214 pod2usage (1) if $help;
216 my $g = Sys::Guestfs->new ();
217 my %h = $g->version ();
218 print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
222 pod2usage (__"virt-rescue: no image or VM names rescue given")
226 push @args, address => $uri if $uri;
227 push @args, rw => 1 unless $readonly;
228 push @args, format => $format if defined $format;
229 my $g = open_guest (@args);
231 # Setting "direct mode" is required for the rescue appliance.
234 # Set other features.
235 $g->set_selinux (1) if $selinux;
236 $g->set_memsize ($memsize) if defined $memsize;
237 $g->set_network (1) if $network;
239 # Set the kernel command line, which must include guestfs_rescue=1
240 # (see appliance/init).
241 my $str = "guestfs_rescue=1";
242 $str .= " $append" if defined $append;
243 $g->set_append ($str);
245 # Run the appliance. This won't return until the user quits the
247 eval { $g->launch (); };
249 # launch() expects guestfsd to start. However, virt-rescue doesn't run guestfsd,
250 # so this will always fail with ECHILD when the appliance exits unexpectedly.
251 die $@ unless $!{ECHILD};
255 =head1 ENVIRONMENT VARIABLES
257 Several environment variables affect virt-rescue. See
258 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
262 Libvirt guest names can contain arbitrary characters, some of which
263 have meaning to the shell such as C<#> and space. You may need to
264 quote or escape these characters on the command line. See the shell
265 manual page L<sh(1)> for details.
273 L<Sys::Guestfs::Lib(3)>,
275 L<http://libguestfs.org/>.
279 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
283 Copyright (C) 2009-2010 Red Hat Inc.
285 This program is free software; you can redistribute it and/or modify
286 it under the terms of the GNU General Public License as published by
287 the Free Software Foundation; either version 2 of the License, or
288 (at your option) any later version.
290 This program is distributed in the hope that it will be useful,
291 but WITHOUT ANY WARRANTY; without even the implied warranty of
292 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
293 GNU General Public License for more details.
295 You should have received a copy of the GNU General Public License
296 along with this program; if not, write to the Free Software
297 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.