todo: Add notes on inspecting ISO images.
[libguestfs.git] / rescue / virt-rescue.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 virt-rescue - Run a rescue shell on a virtual machine
6
7 =head1 SYNOPSIS
8
9  virt-rescue [--options] -d domname
10
11  virt-rescue [--options] -a disk.img [-a disk.img ...]
12
13 Old style:
14
15  virt-rescue [--options] domname
16
17  virt-rescue [--options] disk.img [disk.img ...]
18
19 =head1 WARNING
20
21 You must I<not> use C<virt-rescue> on live virtual machines.  Doing so
22 will probably result in disk corruption in the VM.  C<virt-rescue>
23 tries to stop you from doing this, but doesn't catch all cases.
24
25 However if you use the I<--ro> (read only) option, then you can attach
26 a shell to a live virtual machine.  The results might be strange or
27 inconsistent at times but you won't get disk corruption.
28
29 =head1 DESCRIPTION
30
31 virt-rescue is like a Rescue CD, but for virtual machines, and without
32 the need for a CD.  virt-rescue gives you a rescue shell and some
33 simple recovery tools which you can use to examine or rescue a virtual
34 machine or disk image.
35
36 You can run virt-rescue on any virtual machine known to libvirt, or
37 directly on disk image(s):
38
39  virt-rescue -d GuestName
40
41  virt-rescue --ro -a /path/to/disk.img
42
43  virt-rescue -a /dev/sdc
44
45 For live VMs you I<must> use the --ro option.
46
47 When you run virt-rescue on a virtual machine or disk image, you are
48 placed in an interactive bash shell where you can use many ordinary
49 Linux commands.  What you see in C</> (C</bin>, C</lib> etc) is the
50 rescue appliance.  You must mount the virtual machine's filesystems by
51 hand.  There is an empty directory called C</sysroot> where you can
52 mount filesystems.
53
54 In the example below, we list logical volumes, then choose one to
55 mount under C</sysroot>:
56
57  ><rescue> lvs
58  LV      VG        Attr   LSize   Origin Snap%  Move Log Copy%  Convert
59  lv_root vg_f11x64 -wi-a-   8.83G
60  lv_swap vg_f11x64 -wi-a- 992.00M
61  ><rescue> mount /dev/vg_f11x64/lv_root /sysroot
62  ><rescue> ls /sysroot
63
64 If you don't know what filesystems are available on the virtual
65 machine then you can use commands such as L<parted(8)> and L<lvs(8)>
66 to find out.
67
68 =head2 NOTES
69
70 Virt-rescue can be used on I<any> disk image file or device, not just
71 a virtual machine.  For example you can use it on a blank file if you
72 want to partition that file (although we would recommend using
73 L<guestfish(1)> instead as it is more suitable for this purpose).  You
74 can even use virt-rescue on things like SD cards.
75
76 Virt-rescue does not require root.  You only need to run it as root if
77 you need root to open the disk image.
78
79 This tool is just designed for quick interactive hacking on a virtual
80 machine.  For more structured access to a virtual machine disk image,
81 you should use L<guestfs(3)>.  To get a structured shell that you can
82 use to make scripted changes to guests, use L<guestfish(1)>.
83
84 =head1 OPTIONS
85
86 =over 4
87
88 =item B<--help>
89
90 Display brief help.
91
92 =item B<-a> file
93
94 =item B<--add> file
95
96 Add I<file> which should be a disk image from a virtual machine.  If
97 the virtual machine has multiple block devices, you must supply all of
98 them with separate I<-a> options.
99
100 The format of the disk image is auto-detected.  To override this and
101 force a particular format use the I<--format=..> option.
102
103 =item B<--append kernelopts>
104
105 Pass additional options to the rescue kernel.
106
107 =item B<-c> URI
108
109 =item B<--connect> URI
110
111 If using libvirt, connect to the given I<URI>.  If omitted, then we
112 connect to the default libvirt hypervisor.
113
114 If you specify guest block devices directly (I<-a>), then libvirt is
115 not used at all.
116
117 =item B<-d> guest
118
119 =item B<--domain> guest
120
121 Add all the disks from the named libvirt guest.
122
123 =item B<--format=raw|qcow2|..>
124
125 =item B<--format>
126
127 The default for the I<-a> option is to auto-detect the format of the
128 disk image.  Using this forces the disk format for I<-a> options which
129 follow on the command line.  Using I<--format> with no argument
130 switches back to auto-detection for subsequent I<-a> options.
131
132 For example:
133
134  virt-rescue --format=raw -a disk.img
135
136 forces raw format (no auto-detection) for C<disk.img>.
137
138  virt-rescue --format=raw -a disk.img --format -a another.img
139
140 forces raw format (no auto-detection) for C<disk.img> and reverts to
141 auto-detection for C<another.img>.
142
143 If you have untrusted raw-format guest disk images, you should use
144 this option to specify the disk format.  This avoids a possible
145 security problem with malicious guests (CVE-2010-3851).
146
147 =item B<-m MB>
148
149 =item B<--memsize MB>
150
151 Change the amount of memory allocated to the rescue system.  The
152 default is set by libguestfs and is small but adequate for running
153 system tools.  The occasional program might need more memory.  The
154 parameter is specified in megabytes.
155
156 =item B<--network>
157
158 Enable QEMU user networking in the guest.  See L</NETWORK>.
159
160 =item B<-r>
161
162 =item B<--ro>
163
164 Open the image read-only.
165
166 The option must always be used if the disk image or virtual machine
167 might be running, and is generally recommended in cases where you
168 don't need write access to the disk.
169
170 =item B<--selinux>
171
172 Enable SELinux in the rescue appliance.  You should read
173 L<guestfs(3)/SELINUX> before using this option.
174
175 =item B<-v>
176
177 =item B<--verbose>
178
179 Enable verbose messages for debugging.
180
181 =item B<-V>
182
183 =item B<--version>
184
185 Display version number and exit.
186
187 =item B<-x>
188
189 Enable tracing of libguestfs API calls.
190
191 =back
192
193 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
194
195 Previous versions of virt-rescue allowed you to write either:
196
197  virt-rescue disk.img [disk.img ...]
198
199 or
200
201  virt-rescue guestname
202
203 whereas in this version you should use I<-a> or I<-d> respectively
204 to avoid the confusing case where a disk image might have the same
205 name as a guest.
206
207 For compatibility the old style is still supported.
208
209 =head1 NETWORK
210
211 Adding the I<--network> option enables QEMU user networking
212 in the rescue appliance.  There are some differences between
213 user networking and ordinary networking:
214
215 =over 4
216
217 =item ping does not work
218
219 Because the ICMP ECHO_REQUEST protocol generally requires root in
220 order to send the ping packets, and because virt-rescue must be able
221 to run as non-root, QEMU user networking is not able to emulate the
222 L<ping(8)> command.  The ping command will appear to resolve addresses
223 but will not be able to send or receive any packets.  This does not
224 mean that the network is not working.
225
226 =item cannot receive connections
227
228 QEMU user networking cannot receive incoming connections.
229
230 =item making TCP connections
231
232 The virt-rescue appliance needs to be small and so does not include
233 many network tools.  In particular there is no L<telnet(1)> command.
234 You can make TCP connections from the shell using the magical
235 C</dev/tcp/E<lt>hostnameE<gt>/E<lt>portE<gt>> syntax:
236
237  exec 3<>/dev/tcp/redhat.com/80
238  echo "GET /" >&3
239  cat <&3
240
241 See L<bash(1)> for more details.
242
243 =back
244
245 =head1 ENVIRONMENT VARIABLES
246
247 Several environment variables affect virt-rescue.  See
248 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
249
250 =head1 SHELL QUOTING
251
252 Libvirt guest names can contain arbitrary characters, some of which
253 have meaning to the shell such as C<#> and space.  You may need to
254 quote or escape these characters on the command line.  See the shell
255 manual page L<sh(1)> for details.
256
257 =head1 SEE ALSO
258
259 L<guestfs(3)>,
260 L<guestfish(1)>,
261 L<virt-cat(1)>,
262 L<virt-edit(1)>,
263 L<http://libguestfs.org/>.
264
265 =head1 AUTHOR
266
267 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
268
269 =head1 COPYRIGHT
270
271 Copyright (C) 2009-2010 Red Hat Inc.
272
273 This program is free software; you can redistribute it and/or modify
274 it under the terms of the GNU General Public License as published by
275 the Free Software Foundation; either version 2 of the License, or
276 (at your option) any later version.
277
278 This program is distributed in the hope that it will be useful,
279 but WITHOUT ANY WARRANTY; without even the implied warranty of
280 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
281 GNU General Public License for more details.
282
283 You should have received a copy of the GNU General Public License
284 along with this program; if not, write to the Free Software
285 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.