3 # Copyright (C) 2009 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.
23 use Sys::Guestfs::Lib qw(open_guest);
26 use Locale::TextDomain 'libguestfs';
32 virt-rescue - Run a rescue shell on a virtual machine
36 virt-rescue [--options] domname
38 virt-rescue [--options] disk.img [disk.img ...]
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.
46 However if you use the I<--ro> (read only) option, then you can attach
47 a shell to a live virtual machine. The results might be strange or
48 inconsistent at times but you won't get disk corruption.
52 virt-rescue is like a Rescue CD, but for virtual machines, and without
53 the need for a CD. virt-rescue gives you a rescue shell and some
54 simple recovery tools which you can use to examine or rescue a virtual
55 machine or disk image.
57 You can run virt-rescue on any virtual machine known to libvirt, or
58 directly on disk image(s):
62 virt-rescue --ro /path/to/disk.img
66 For live VMs you I<must> use the --ro option.
68 When you run virt-rescue on a virtual machine or disk image, you are
69 placed in an interactive bash shell where you can use many ordinary
70 Linux commands. What you see in C</> (C</bin>, C</lib> etc) is the
71 rescue appliance. You must mount the virtual machine's filesystems by
72 hand. There is an empty directory called C</sysroot> where you can
75 In the example below, we list logical volumes, then choose one to
76 mount under C</sysroot>:
79 LV VG Attr LSize Origin Snap% Move Log Copy% Convert
80 lv_root vg_f11x64 -wi-a- 8.83G
81 lv_swap vg_f11x64 -wi-a- 992.00M
82 ><rescue> mount /dev/vg_f11x64/lv_root /sysroot
85 If you don't know what filesystems are available on the virtual
86 machine then you can use commands such as L<parted(8)> and L<lvs(8)>
91 Virt-rescue can be used on I<any> disk image file or device, not just
92 a virtual machine. For example you can use it on a blank file if you
93 want to partition that file (although we would recommend using
94 L<guestfish(1)> instead as it is more suitable for this purpose). You
95 can even use virt-rescue on things like SD cards.
97 This tool is just designed for quick interactive hacking on a virtual
98 machine. For more structured access to a virtual machine disk image,
99 you should use L<guestfs(3)>. To get a structured shell that you can
100 use to make scripted changes to guests, use L<guestfish(1)>.
120 Display version number and exit.
126 =item B<--connect URI> | B<-c URI>
128 If using libvirt, connect to the given I<URI>. If omitted, then we
129 connect to the default libvirt hypervisor.
131 If you specify guest block devices directly, then libvirt is not used
138 =item B<--ro> | B<-r>
140 Open the image read-only.
142 The option must always be used if the disk image or virtual machine
143 might be running, and is generally recommended in cases where you
144 don't need write access to the disk.
150 GetOptions ("help|?" => \$help,
151 "version" => \$version,
152 "connect|c=s" => \$uri,
153 "ro|r" => \$readonly,
155 pod2usage (1) if $help;
157 my $g = Sys::Guestfs->new ();
158 my %h = $g->version ();
159 print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
163 pod2usage (__"virt-rescue: no image or VM names rescue given")
167 push @args, address => $uri if $uri;
168 push @args, rw => 1 unless $readonly;
169 my $g = open_guest (@args);
172 $g->set_append ("guestfs_rescue=1");
178 =head1 ENVIRONMENT VARIABLES
180 Several environment variables affect virt-rescue. See
181 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
189 L<Sys::Guestfs::Lib(3)>,
191 L<http://libguestfs.org/>.
195 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
199 Copyright (C) 2009-2010 Red Hat Inc.
201 This program is free software; you can redistribute it and/or modify
202 it under the terms of the GNU General Public License as published by
203 the Free Software Foundation; either version 2 of the License, or
204 (at your option) any later version.
206 This program is distributed in the hope that it will be useful,
207 but WITHOUT ANY WARRANTY; without even the implied warranty of
208 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
209 GNU General Public License for more details.
211 You should have received a copy of the GNU General Public License
212 along with this program; if not, write to the Free Software
213 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.