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