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

OLD-STYLE COMMAND LINE ARGUMENTS

263       Previous versions of virt-rescue allowed you to write either:
264
265        virt-rescue disk.img [disk.img ...]
266
267       or
268
269        virt-rescue guestname
270
271       whereas in this version you should use -a or -d respectively to avoid
272       the confusing case where a disk image might have the same name as a
273       guest.
274
275       For compatibility the old style is still supported.
276

NETWORK

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

ESCAPE KEY

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

CAPTURING CORE DUMPS

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

ENVIRONMENT VARIABLES

395       Several environment variables affect virt-rescue.  See "ENVIRONMENT
396       VARIABLES" in guestfs(3) for the complete list.
397

FILES

399       $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
400       $HOME/.libguestfs-tools.rc
401       $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
402       /etc/libguestfs-tools.conf
403           This configuration file controls the default read-only or read-
404           write mode (--ro or --rw).
405
406           See libguestfs-tools.conf(5).
407

SEE ALSO

409       guestfs(3), guestfish(1), virt-cat(1), virt-edit(1),
410       virt-filesystems(1), libguestfs-tools.conf(5), http://libguestfs.org/.
411

AUTHOR

413       Richard W.M. Jones http://people.redhat.com/~rjones/
414
416       Copyright (C) 2009-2018 Red Hat Inc.
417

LICENSE

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

BUGS

434       To get a list of bugs against libguestfs, use this link:
435       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
436
437       To report a new bug against libguestfs, use this link:
438       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
439
440       When reporting a bug, please supply:
441
442       ·   The version of libguestfs.
443
444       ·   Where you got libguestfs (eg. which Linux distro, compiled from
445           source, etc)
446
447       ·   Describe the bug accurately and give a way to reproduce it.
448
449       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
450           into the bug report.
451
452
453
454libguestfs-1.38.2                 2018-05-15                    virt-rescue(1)
Impressum