generator: Move src/guestfs-bindtests.c next to other src/ files.
[libguestfs.git] / 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://et.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.