5 virt-rescue - Run a rescue shell on a virtual machine
9 virt-rescue [--options] -d domname
11 virt-rescue [--options] -a disk.img [-a disk.img ...]
15 virt-rescue [--options] domname
17 virt-rescue [--options] disk.img [disk.img ...]
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.
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.
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.
36 You can run virt-rescue on any virtual machine known to libvirt, or
37 directly on disk image(s):
39 virt-rescue -d GuestName
41 virt-rescue --ro -a /path/to/disk.img
43 virt-rescue -a /dev/sdc
45 For live VMs you I<must> use the --ro option.
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
54 In the example below, we list logical volumes, then choose one to
55 mount under C</sysroot>:
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
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)>
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.
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.
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)>.
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.
100 The format of the disk image is auto-detected. To override this and
101 force a particular format use the I<--format=..> option.
103 =item B<--append kernelopts>
105 Pass additional options to the rescue kernel.
109 =item B<--connect> URI
111 If using libvirt, connect to the given I<URI>. If omitted, then we
112 connect to the default libvirt hypervisor.
114 If you specify guest block devices directly (I<-a>), then libvirt is
119 =item B<--domain> guest
121 Add all the disks from the named libvirt guest. Domain UUIDs can be
122 used instead of names.
124 =item B<--format=raw|qcow2|..>
128 The default for the I<-a> option is to auto-detect the format of the
129 disk image. Using this forces the disk format for I<-a> options which
130 follow on the command line. Using I<--format> with no argument
131 switches back to auto-detection for subsequent I<-a> options.
135 virt-rescue --format=raw -a disk.img
137 forces raw format (no auto-detection) for C<disk.img>.
139 virt-rescue --format=raw -a disk.img --format -a another.img
141 forces raw format (no auto-detection) for C<disk.img> and reverts to
142 auto-detection for C<another.img>.
144 If you have untrusted raw-format guest disk images, you should use
145 this option to specify the disk format. This avoids a possible
146 security problem with malicious guests (CVE-2010-3851).
150 =item B<--memsize MB>
152 Change the amount of memory allocated to the rescue system. The
153 default is set by libguestfs and is small but adequate for running
154 system tools. The occasional program might need more memory. The
155 parameter is specified in megabytes.
159 Enable QEMU user networking in the guest. See L</NETWORK>.
165 Open the image read-only.
167 The option must always be used if the disk image or virtual machine
168 might be running, and is generally recommended in cases where you
169 don't need write access to the disk.
171 See also L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
175 Enable SELinux in the rescue appliance. You should read
176 L<guestfs(3)/SELINUX> before using this option.
182 Enable verbose messages for debugging.
188 Display version number and exit.
194 This changes the I<-a> and I<-d> options so that disks are
195 added and mounts are done read-write.
197 See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
201 Enable tracing of libguestfs API calls.
205 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
207 Previous versions of virt-rescue allowed you to write either:
209 virt-rescue disk.img [disk.img ...]
213 virt-rescue guestname
215 whereas in this version you should use I<-a> or I<-d> respectively
216 to avoid the confusing case where a disk image might have the same
219 For compatibility the old style is still supported.
223 Adding the I<--network> option enables QEMU user networking
224 in the rescue appliance. There are some differences between
225 user networking and ordinary networking:
229 =item ping does not work
231 Because the ICMP ECHO_REQUEST protocol generally requires root in
232 order to send the ping packets, and because virt-rescue must be able
233 to run as non-root, QEMU user networking is not able to emulate the
234 L<ping(8)> command. The ping command will appear to resolve addresses
235 but will not be able to send or receive any packets. This does not
236 mean that the network is not working.
238 =item cannot receive connections
240 QEMU user networking cannot receive incoming connections.
242 =item making TCP connections
244 The virt-rescue appliance needs to be small and so does not include
245 many network tools. In particular there is no L<telnet(1)> command.
246 You can make TCP connections from the shell using the magical
247 C</dev/tcp/E<lt>hostnameE<gt>/E<lt>portE<gt>> syntax:
249 exec 3<>/dev/tcp/redhat.com/80
253 See L<bash(1)> for more details.
257 =head1 ENVIRONMENT VARIABLES
259 Several environment variables affect virt-rescue. See
260 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
264 Libvirt guest names can contain arbitrary characters, some of which
265 have meaning to the shell such as C<#> and space. You may need to
266 quote or escape these characters on the command line. See the shell
267 manual page L<sh(1)> for details.
273 =item $HOME/.libguestfs-tools.rc
275 =item /etc/libguestfs-tools.conf
277 This configuration file controls the default read-only or read-write
278 mode (I<--ro> or I<--rw>).
280 See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
290 L<http://libguestfs.org/>.
294 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
298 Copyright (C) 2009-2011 Red Hat Inc.
300 This program is free software; you can redistribute it and/or modify
301 it under the terms of the GNU General Public License as published by
302 the Free Software Foundation; either version 2 of the License, or
303 (at your option) any later version.
305 This program is distributed in the hope that it will be useful,
306 but WITHOUT ANY WARRANTY; without even the implied warranty of
307 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
308 GNU General Public License for more details.
310 You should have received a copy of the GNU General Public License
311 along with this program; if not, write to the Free Software
312 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.