1virt-rescue(1)              Virtualization Support              virt-rescue(1)
2
3
4

NAME

6       virt-rescue - Run a rescue shell on a virtual machine
7

SYNOPSIS

9        virt-rescue [--options] -d domname
10
11        virt-rescue [--options] -a disk.img [-a disk.img ...] [-i]
12
13       Old style:
14
15        virt-rescue [--options] domname
16
17        virt-rescue [--options] disk.img [disk.img ...]
18

WARNING

20       Using "virt-rescue" in write mode on live virtual machines, or
21       concurrently with other disk editing tools, can be dangerous,
22       potentially causing disk corruption.  The virtual machine must be shut
23       down before you use this command, and disk images must not be edited
24       concurrently.
25
26       Use the --ro (read-only) option to use "virt-rescue" safely if the disk
27       image or virtual machine might be live.  You may see strange or
28       inconsistent results if running concurrently with other changes, but
29       with this option you won't risk disk corruption.
30

DESCRIPTION

32       virt-rescue is like a Rescue CD, but for virtual machines, and without
33       the need for a CD.  virt-rescue gives you a rescue shell and some
34       simple recovery tools which you can use to examine or rescue a virtual
35       machine or disk image.
36
37       You can run virt-rescue on any virtual machine known to libvirt, or
38       directly on disk image(s):
39
40        virt-rescue -d GuestName -i
41
42        virt-rescue --ro -a /path/to/disk.img -i
43
44        virt-rescue -a /dev/sdc
45
46       For live VMs you must use the --ro option.
47
48       When you run virt-rescue on a virtual machine or disk image, you are
49       placed in an interactive bash shell where you can use many ordinary
50       Linux commands.  What you see in / (/bin, /lib etc) is the rescue
51       appliance.  You must mount the virtual machine’s filesystems.  There is
52       an empty directory called /sysroot where you can mount filesystems.
53
54       To automatically mount the virtual machine’s filesystems under /sysroot
55       use the -i option.  This uses libguestfs inspection to find the
56       filesystems and mount them in the right place.  You can also mount
57       filesystems individually using the -m option.
58
59       Another way is to list the logical volumes (with lvs(8)) and partitions
60       (with parted(8)) and mount them by hand:
61
62        ><rescue> lvs
63        LV      VG        Attr   LSize   Origin Snap%  Move Log Copy%  Convert
64        lv_root vg_f15x32 -wi-a-   8.83G
65        lv_swap vg_f15x32 -wi-a- 992.00M
66        ><rescue> mount /dev/vg_f15x32/lv_root /sysroot
67        ><rescue> mount /dev/vda1 /sysroot/boot
68        ><rescue> ls /sysroot
69
70       Another command to list available filesystems is virt-filesystems(1).
71
72       To run commands in a Linux guest (for example, grub), you should chroot
73       into the /sysroot directory first:
74
75        ><rescue> chroot /sysroot
76
77   NOTES
78       Virt-rescue can be used on any disk image file or device, not just a
79       virtual machine.  For example you can use it on a blank file if you
80       want to partition that file (although we would recommend using
81       guestfish(1) instead as it is more suitable for this purpose).  You can
82       even use virt-rescue on things like USB drives, SD cards and hard
83       disks.
84
85       You can get virt-rescue to give you scratch disk(s) to play with.  This
86       is useful for testing out Linux utilities (see --scratch).
87
88       Virt-rescue does not require root.  You only need to run it as root if
89       you need root to open the disk image.
90
91       This tool is just designed for quick interactive hacking on a virtual
92       machine.  For more structured access to a virtual machine disk image,
93       you should use guestfs(3).  To get a structured shell that you can use
94       to make scripted changes to guests, use guestfish(1).
95

OPTIONS

97       --help
98           Display brief help.
99
100       -a FILE
101       --add FILE
102           Add "FILE" which should be a disk image from a virtual machine.  If
103           the virtual machine has multiple block devices, you must supply all
104           of them with separate -a options.
105
106           The format of the disk image is auto-detected.  To override this
107           and force a particular format use the --format=.. option.
108
109       -a URI
110       --add URI
111           Add a remote disk.  See "ADDING REMOTE STORAGE" in guestfish(1).
112
113       --append KERNELOPTS
114           Pass additional options to the rescue kernel.
115
116       --blocksize=512
117       --blocksize=4096
118       --blocksize
119           This parameter sets the sector size of the disk image.  It affects
120           all explicitly added subsequent disks after this parameter.  Using
121           --blocksize with no argument switches the disk sector size to the
122           default value which is usually 512 bytes.  See also
123           "guestfs_add_drive_opts" in guestfs(3).
124
125       -c URI
126       --connect URI
127           If using libvirt, connect to the given URI.  If omitted, then we
128           connect to the default libvirt hypervisor.
129
130           If you specify guest block devices directly (-a), then libvirt is
131           not used at all.
132
133       -d guest
134       --domain guest
135           Add all the disks from the named libvirt guest.  Domain UUIDs can
136           be used instead of names.
137
138       -e none
139           Disable the escape key.
140
141       -e KEY
142           Set the escape key to the given key sequence.  The default is "^]".
143           To specify the escape key you can use:
144
145           "^x"
146               Control key + "x" key.
147
148           "none"
149               -e none means there is no escape key, escapes are disabled.
150
151           See "ESCAPE KEY" below for further information.
152
153       --format=raw|qcow2|..
154       --format
155           The default for the -a option is to auto-detect the format of the
156           disk image.  Using this forces the disk format for -a options which
157           follow on the command line.  Using --format with no argument
158           switches back to auto-detection for subsequent -a options.
159
160           For example:
161
162            virt-rescue --format=raw -a disk.img
163
164           forces raw format (no auto-detection) for disk.img.
165
166            virt-rescue --format=raw -a disk.img --format -a another.img
167
168           forces raw format (no auto-detection) for disk.img and reverts to
169           auto-detection for another.img.
170
171           If you have untrusted raw-format guest disk images, you should use
172           this option to specify the disk format.  This avoids a possible
173           security problem with malicious guests (CVE-2010-3851).
174
175       -i
176       --inspector
177           Using virt-inspector(1) code, inspect the disks looking for an
178           operating system and mount filesystems as they would be mounted on
179           the real virtual machine.
180
181           The filesystems are mounted on /sysroot in the rescue environment.
182
183       --memsize MB
184           Change the amount of memory allocated to the rescue system.  The
185           default is set by libguestfs and is small but adequate for running
186           system tools.  The occasional program might need more memory.  The
187           parameter is specified in megabytes.
188
189       -m dev[:mountpoint[:options[:fstype]]]
190       --mount dev[:mountpoint[:options[:fstype]]]
191           Mount the named partition or logical volume on the given mountpoint
192           in the guest (this has nothing to do with mountpoints in the host).
193
194           If the mountpoint is omitted, it defaults to /.  You have to mount
195           something on /.
196
197           The filesystems are mounted under /sysroot in the rescue
198           environment.
199
200           The third (and rarely used) part of the mount parameter is the list
201           of mount options used to mount the underlying filesystem.  If this
202           is not given, then the mount options are either the empty string or
203           "ro" (the latter if the --ro flag is used).  By specifying the
204           mount options, you override this default choice.  Probably the only
205           time you would use this is to enable ACLs and/or extended
206           attributes if the filesystem can support them:
207
208            -m /dev/sda1:/:acl,user_xattr
209
210           The fourth part of the parameter is the filesystem driver to use,
211           such as "ext3" or "ntfs". This is rarely needed, but can be useful
212           if multiple drivers are valid for a filesystem (eg: "ext2" and
213           "ext3"), or if libguestfs misidentifies a filesystem.
214
215       --network
216           Enable QEMU user networking in the guest.  See "NETWORK".
217
218       -r
219       --ro
220           Open the image read-only.
221
222           The option must always be used if the disk image or virtual machine
223           might be running, and is generally recommended in cases where you
224           don't need write access to the disk.
225
226           See also "OPENING DISKS FOR READ AND WRITE" in guestfish(1).
227
228       --scratch
229       --scratch=N
230           The --scratch option adds a large scratch disk to the rescue
231           appliance.  --scratch=N adds "N" scratch disks.  The scratch
232           disk(s) are deleted automatically when virt-rescue exits.
233
234           You can also mix -a, -d and --scratch options.  The scratch disk(s)
235           are added to the appliance in the order they appear on the command
236           line.
237
238       --selinux
239           This option is provided for backwards compatibility and does
240           nothing.
241
242       --smp N
243           Enable N ≥ 2 virtual CPUs in the rescue appliance.
244
245       --suggest
246           This option was used in older versions of virt-rescue to suggest
247           what commands you could use to mount filesystems under /sysroot.
248           For the current version of virt-rescue, it is easier to use the -i
249           option instead.
250
251           This option implies --ro and is safe to use even if the guest is up
252           or if another virt-rescue is running.
253
254       -v
255       --verbose
256           Enable verbose messages for debugging.
257
258       -V
259       --version
260           Display version number and exit.
261
262       -w
263       --rw
264           This changes the -a, -d and -m options so that disks are added and
265           mounts are done read-write.
266
267           See "OPENING DISKS FOR READ AND WRITE" in guestfish(1).
268
269       -x  Enable tracing of libguestfs API calls.
270

OLD-STYLE COMMAND LINE ARGUMENTS

272       Previous versions of virt-rescue allowed you to write either:
273
274        virt-rescue disk.img [disk.img ...]
275
276       or
277
278        virt-rescue guestname
279
280       whereas in this version you should use -a or -d respectively to avoid
281       the confusing case where a disk image might have the same name as a
282       guest.
283
284       For compatibility the old style is still supported.
285

NETWORK

287       Adding the --network option enables QEMU user networking in the rescue
288       appliance.  There are some differences between user networking and
289       ordinary networking:
290
291       ping does not work
292           Because the ICMP ECHO_REQUEST protocol generally requires root in
293           order to send the ping packets, and because virt-rescue must be
294           able to run as non-root, QEMU user networking is not able to
295           emulate the ping(8) command.  The ping command will appear to
296           resolve addresses but will not be able to send or receive any
297           packets.  This does not mean that the network is not working.
298
299       cannot receive connections
300           QEMU user networking cannot receive incoming connections.
301
302       making TCP connections
303           The virt-rescue appliance needs to be small and so does not include
304           many network tools.  In particular there is no telnet(1) command.
305           You can make TCP connections from the shell using the magical
306           /dev/tcp/<hostname>/<port> syntax:
307
308            exec 3<>/dev/tcp/redhat.com/80
309            echo "GET /" >&3
310            cat <&3
311
312           See bash(1) for more details.
313

ESCAPE KEY

315       Virt-rescue supports various keyboard escape sequences which are
316       entered by pressing "^]" (Control key + "]" key).
317
318       You can change the escape key using the -e option on the command line
319       (see above), and you can disable escapes completely using -e none.  The
320       rest of this section assumes the default escape key.
321
322       The following escapes can be used:
323
324       "^] ?"
325       "^] h"
326           Prints a brief help text about escape sequences.
327
328       "^] i"
329           Prints brief libguestfs inspection information for the guest.  This
330           only works if you used -i on the virt-rescue command line.
331
332       "^] q"
333       "^] x"
334           Quits virt-rescue immediately.
335
336       "^] s"
337           Synchronize the filesystems (sync).
338
339       "^] u"
340           Unmounts all the filesystems, except for the root (appliance)
341           filesystems.
342
343       "^] z"
344           Suspend virt-rescue (like pressing "^Z" except that it affects
345           virt-rescue rather than the program inside the rescue shell).
346
347       "^] ^]"
348           Sends the literal character "^]" (ASCII 0x1d) through to the rescue
349           shell.
350

CAPTURING CORE DUMPS

352       If you are testing a tool inside virt-rescue and the tool (not virt-
353       rescue) segfaults, it can be tricky to capture the core dump outside
354       virt-rescue for later analysis.  This section describes one way to do
355       this.
356
357       1.  Create a scratch disk for core dumps:
358
359            truncate -s 4G /tmp/corefiles
360            virt-format --partition=mbr --filesystem=ext2 -a /tmp/corefiles
361            virt-filesystems -a /tmp/corefiles --all --long -h
362
363       2.  When starting virt-rescue, attach the core files disk last:
364
365            virt-rescue --rw [-a ...] -a /tmp/corefiles
366
367           NB. If you use the --ro option, then virt-rescue will silently not
368           write any core files to /tmp/corefiles.
369
370       3.  Inside virt-rescue, mount the core files disk.  Note replace
371           /dev/sdb1 with the last disk index.  For example if the core files
372           disk is the last of four disks, you would use /dev/sdd1.
373
374            ><rescue> mkdir /tmp/mnt
375            ><rescue> mount /dev/sdb1 /tmp/mnt
376
377       4.  Enable core dumps in the rescue kernel:
378
379            ><rescue> echo '/tmp/mnt/core.%p' > /proc/sys/kernel/core_pattern
380            ><rescue> ulimit -Hc unlimited
381            ><rescue> ulimit -Sc unlimited
382
383       5.  Run the tool that caused the core dump.  The core dump will be
384           written to /tmp/mnt/core.PID.
385
386            ><rescue> ls -l /tmp/mnt
387            total 1628
388            -rw------- 1 root root 1941504 Dec  7 13:13 core.130
389            drwx------ 2 root root   16384 Dec  7 13:00 lost+found
390
391       6.  Before exiting virt-rescue, unmount (or at least sync) the disks:
392
393            ><rescue> umount /tmp/mnt
394            ><rescue> exit
395
396       7.  Outside virt-rescue, the core dump(s) can be removed from the disk
397           using guestfish(1).  For example:
398
399            guestfish --ro -a /tmp/corefiles -m /dev/sda1
400            ><fs> ll /
401            ><fs> download /core.NNN /tmp/core.NNN
402

ENVIRONMENT VARIABLES

404       Several environment variables affect virt-rescue.  See "ENVIRONMENT
405       VARIABLES" in guestfs(3) for the complete list.
406

FILES

408       $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
409       $HOME/.libguestfs-tools.rc
410       $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
411       /etc/libguestfs-tools.conf
412           This configuration file controls the default read-only or read-
413           write mode (--ro or --rw).
414
415           See libguestfs-tools.conf(5).
416

SEE ALSO

418       guestfs(3), guestfish(1), virt-cat(1), virt-edit(1),
419       virt-filesystems(1), libguestfs-tools.conf(5), http://libguestfs.org/.
420

AUTHOR

422       Richard W.M. Jones http://people.redhat.com/~rjones/
423
425       Copyright (C) 2009-2023 Red Hat Inc.
426

LICENSE

428       This program is free software; you can redistribute it and/or modify it
429       under the terms of the GNU General Public License as published by the
430       Free Software Foundation; either version 2 of the License, or (at your
431       option) any later version.
432
433       This program is distributed in the hope that it will be useful, but
434       WITHOUT ANY WARRANTY; without even the implied warranty of
435       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
436       General Public License for more details.
437
438       You should have received a copy of the GNU General Public License along
439       with this program; if not, write to the Free Software Foundation, Inc.,
440       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
441

BUGS

443       To get a list of bugs against libguestfs, use this link:
444       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
445
446       To report a new bug against libguestfs, use this link:
447       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
448
449       When reporting a bug, please supply:
450
451       •   The version of libguestfs.
452
453       •   Where you got libguestfs (eg. which Linux distro, compiled from
454           source, etc)
455
456       •   Describe the bug accurately and give a way to reproduce it.
457
458       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
459           into the bug report.
460
461
462
463libguestfs-1.51.9                 2023-12-09                    virt-rescue(1)
Impressum