1virt-rescue(1) Virtualization Support virt-rescue(1)
2
6 virt-rescue - Run a rescue shell on a virtual machine
7
9 virt-rescue [--options] -d domname
10 virt-rescue [--options] -a disk.img [-a disk.img ...]
12 virt-rescue --suggest (-d domname | -a disk.img ...)
14 Old style:
16 virt-rescue [--options] domname
18 virt-rescue [--options] disk.img [disk.img ...]
20
22 You must not use "virt-rescue" on live virtual machines. Doing so will
23 probably result in disk corruption in the VM. "virt-rescue" tries to
24 stop you from doing this, but doesn't catch all cases.
25 However if you use the --ro (read only) option, then you can attach a
27 shell to a live virtual machine. The results might be strange or
28 inconsistent at times but you won't get disk corruption.
29
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 You can run virt-rescue on any virtual machine known to libvirt, or
37 directly on disk image(s):
38 virt-rescue -d GuestName
40 virt-rescue --ro -a /path/to/disk.img
42 virt-rescue -a /dev/sdc
44 For live VMs you must use the --ro option.
46 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 "/" ("/bin", "/lib" etc) is the rescue
50 appliance. You must mount the virtual machine's filesystems by hand.
51 There is an empty directory called "/sysroot" where you can mount
52 filesystems.
53 You can get virt-rescue to suggest mount commands for you by using the
55 --suggest option (in another terminal):
56 $ virt-rescue --suggest -d Fedora15
58 Inspecting the virtual machine or disk image ...
59 This disk contains one or more operating systems. You can use these
61 mount commands in virt-rescue (at the ><rescue> prompt) to mount the
62 filesystems.
63 # /dev/vg_f15x32/lv_root is the root of a linux operating system
65 # type: linux, distro: fedora, version: 15.0
66 # Fedora release 15 (Lovelock)
67 mount /dev/vg_f15x32/lv_root /sysroot/
69 mount /dev/vda1 /sysroot/boot
70 mount --bind /dev /sysroot/dev
71 mount --bind /dev/pts /sysroot/dev/pts
72 mount --bind /proc /sysroot/proc
73 mount --bind /sys /sysroot/sys
74 Another way is to list the logical volumes (with lvs(8)) and partitions
76 (with parted(8)) and mount them by hand:
77 ><rescue> lvs
79 LV VG Attr LSize Origin Snap% Move Log Copy% Convert
80 lv_root vg_f15x32 -wi-a- 8.83G
81 lv_swap vg_f15x32 -wi-a- 992.00M
82 ><rescue> mount /dev/vg_f15x32/lv_root /sysroot
83 ><rescue> mount /dev/vda1 /sysroot/boot
84 ><rescue> ls /sysroot
85 Another command to list available filesystems is virt-filesystems(1).
87 To run commands in a Linux guest (for example, grub), you should chroot
89 into the /sysroot directory first:
90 ><rescue> chroot /sysroot
92 NOTES
94 Virt-rescue can be used on any disk image file or device, not just a
95 virtual machine. For example you can use it on a blank file if you
96 want to partition that file (although we would recommend using
97 guestfish(1) instead as it is more suitable for this purpose). You can
98 even use virt-rescue on things like SD cards.
99 You can get virt-rescue to give you scratch disk(s) to play with. This
101 is useful for testing out Linux utilities (see --scratch).
102 Virt-rescue does not require root. You only need to run it as root if
104 you need root to open the disk image.
105 This tool is just designed for quick interactive hacking on a virtual
107 machine. For more structured access to a virtual machine disk image,
108 you should use guestfs(3). To get a structured shell that you can use
109 to make scripted changes to guests, use guestfish(1).
110
112 --help
113 Display brief help.
114 -a file
116 --add file
117 Add file which should be a disk image from a virtual machine. If
118 the virtual machine has multiple block devices, you must supply all
119 of them with separate -a options.
120 The format of the disk image is auto-detected. To override this
122 and force a particular format use the --format=.. option.
123 --append kernelopts
125 Pass additional options to the rescue kernel.
126 -c URI
128 --connect URI
129 If using libvirt, connect to the given URI. If omitted, then we
130 connect to the default libvirt hypervisor.
131 If you specify guest block devices directly (-a), then libvirt is
133 not used at all.
134 -d guest
136 --domain guest
137 Add all the disks from the named libvirt guest. Domain UUIDs can
138 be used instead of names.
139 --format=raw|qcow2|..
141 --format
142 The default for the -a option is to auto-detect the format of the
143 disk image. Using this forces the disk format for -a options which
144 follow on the command line. Using --format with no argument
145 switches back to auto-detection for subsequent -a options.
146 For example:
148 virt-rescue --format=raw -a disk.img
150 forces raw format (no auto-detection) for "disk.img".
152 virt-rescue --format=raw -a disk.img --format -a another.img
154 forces raw format (no auto-detection) for "disk.img" and reverts to
156 auto-detection for "another.img".
157 If you have untrusted raw-format guest disk images, you should use
159 this option to specify the disk format. This avoids a possible
160 security problem with malicious guests (CVE-2010-3851).
161 -m MB
163 --memsize MB
164 Change the amount of memory allocated to the rescue system. The
165 default is set by libguestfs and is small but adequate for running
166 system tools. The occasional program might need more memory. The
167 parameter is specified in megabytes.
168 --network
170 Enable QEMU user networking in the guest. See "NETWORK".
171 -r
173 --ro
174 Open the image read-only.
175 The option must always be used if the disk image or virtual machine
177 might be running, and is generally recommended in cases where you
178 don't need write access to the disk.
179 See also "OPENING DISKS FOR READ AND WRITE" in guestfish(1).
181 --scratch
183 --scratch=N
184 The --scratch option adds a large scratch disk to the rescue
185 appliance. --scratch=N adds "N" scratch disks. The scratch
186 disk(s) are deleted automatically when virt-rescue exits.
187 You can also mix -a, -d and --scratch options. The scratch disk(s)
189 are added to the appliance in the order they appear on the command
190 line.
191 --selinux
193 Enable SELinux in the rescue appliance. You should read "SELINUX"
194 in guestfs(3) before using this option.
195 --smp N
197 Enable N ≥ 2 virtual CPUs in the rescue appliance.
198 --suggest
200 Inspect the disk image and suggest what mount commands should be
201 used to mount the disks. You should use the --suggest option in a
202 second terminal, then paste the commands into another virt-rescue.
203 This option implies --ro and is safe to use even if the guest is up
205 or if another virt-rescue is running.
206 -v
208 --verbose
209 Enable verbose messages for debugging.
210 -V
212 --version
213 Display version number and exit.
214 -w
216 --rw
217 This changes the -a and -d options so that disks are added and
218 mounts are done read-write.
219 See "OPENING DISKS FOR READ AND WRITE" in guestfish(1).
221 -x Enable tracing of libguestfs API calls.
223
225 Previous versions of virt-rescue allowed you to write either:
226 virt-rescue disk.img [disk.img ...]
228 or
230 virt-rescue guestname
232 whereas in this version you should use -a or -d respectively to avoid
234 the confusing case where a disk image might have the same name as a
235 guest.
236 For compatibility the old style is still supported.
238
240 Adding the --network option enables QEMU user networking in the rescue
241 appliance. There are some differences between user networking and
242 ordinary networking:
243 ping does not work
245 Because the ICMP ECHO_REQUEST protocol generally requires root in
246 order to send the ping packets, and because virt-rescue must be
247 able to run as non-root, QEMU user networking is not able to
248 emulate the ping(8) command. The ping command will appear to
249 resolve addresses but will not be able to send or receive any
250 packets. This does not mean that the network is not working.
251 cannot receive connections
253 QEMU user networking cannot receive incoming connections.
254 making TCP connections
256 The virt-rescue appliance needs to be small and so does not include
257 many network tools. In particular there is no telnet(1) command.
258 You can make TCP connections from the shell using the magical
259 "/dev/tcp/<hostname>/<port>" syntax:
260 exec 3<>/dev/tcp/redhat.com/80
262 echo "GET /" >&3
263 cat <&3
264 See bash(1) for more details.
266
268 If you are testing a tool inside virt-rescue and the tool (not virt-
269 rescue) segfaults, it can be tricky to capture the core dump outside
270 virt-rescue for later analysis. This section describes one way to do
271 this.
272 1. Create a scratch disk for core dumps:
274 truncate -s 4G /tmp/corefiles
276 virt-format --partition=mbr --filesystem=ext2 -a /tmp/corefiles
277 virt-filesystems -a /tmp/corefiles --all --long -h
278 2. When starting virt-rescue, attach the core files disk last:
280 virt-rescue --rw [-a ...] -a /tmp/corefiles
282 NB. If you use the --ro option, then virt-rescue will silently not
284 write any core files to "/tmp/corefiles".
285 3. Inside virt-rescue, mount the core files disk. Note replace
287 "/dev/sdb1" with the last disk index. For example if the core
288 files disk is the last of four disks, you would use "/dev/sdd1".
289 ><rescue> mkdir /tmp/mnt
291 ><rescue> mount /dev/sdb1 /tmp/mnt
292 4. Enable core dumps in the rescue kernel:
294 ><rescue> echo '/tmp/mnt/core.%p' > /proc/sys/kernel/core_pattern
296 ><rescue> ulimit -Hc unlimited
297 ><rescue> ulimit -Sc unlimited
298 5. Run the tool that caused the core dump. The core dump will be
300 written to "/tmp/mnt/core.PID".
301 ><rescue> ls -l /tmp/mnt
303 total 1628
304 -rw------- 1 root root 1941504 Dec 7 13:13 core.130
305 drwx------ 2 root root 16384 Dec 7 13:00 lost+found
306 6. Before exiting virt-rescue, unmount (or at least sync) the disks:
308 ><rescue> umount /tmp/mnt
310 ><rescue> exit
311 7. Outside virt-rescue, the core dump(s) can be removed from the disk
313 using guestfish(1). For example:
314 guestfish --ro -a /tmp/corefiles -m /dev/sda1
316 ><fs> ll /
317 ><fs> download /core.NNN /tmp/core.NNN
318
320 Several environment variables affect virt-rescue. See "ENVIRONMENT
321 VARIABLES" in guestfs(3) for the complete list.
322
324 Libvirt guest names can contain arbitrary characters, some of which
325 have meaning to the shell such as "#" and space. You may need to quote
326 or escape these characters on the command line. See the shell manual
327 page sh(1) for details.
328
330 $HOME/.libguestfs-tools.rc
331 /etc/libguestfs-tools.conf
332 This configuration file controls the default read-only or read-
333 write mode (--ro or --rw).
334 See "OPENING DISKS FOR READ AND WRITE" in guestfish(1).
336
338 guestfs(3), guestfish(1), virt-cat(1), virt-edit(1),
339 virt-filesystems(1), http://libguestfs.org/.
340
342 Richard W.M. Jones http://people.redhat.com/~rjones/
343
345 Copyright (C) 2009-2013 Red Hat Inc.
346
348 This program is free software; you can redistribute it and/or modify it
349 under the terms of the GNU General Public License as published by the
350 Free Software Foundation; either version 2 of the License, or (at your
351 option) any later version.
352 This program is distributed in the hope that it will be useful, but
354 WITHOUT ANY WARRANTY; without even the implied warranty of
355 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
356 General Public License for more details.
357 You should have received a copy of the GNU General Public License along
359 with this program; if not, write to the Free Software Foundation, Inc.,
360 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
361
363 To get a list of bugs against libguestfs, use this link:
364 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
365 To report a new bug against libguestfs, use this link:
367 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
368 When reporting a bug, please supply:
370 · The version of libguestfs.
372 · Where you got libguestfs (eg. which Linux distro, compiled from
374 source, etc)
375 · Describe the bug accurately and give a way to reproduce it.
377 · Run libguestfs-test-tool(1) and paste the complete, unedited output
379 into the bug report.
380libguestfs-1.20.11 2013-08-27 virt-rescue(1)