rescue/virt-rescue.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 virt-rescue - Run a rescue shell on a virtual machine
   6
   7 =head1 SYNOPSIS
   8
   9  virt-rescue [--options] -d domname
  10
  11  virt-rescue [--options] -a disk.img [-a disk.img ...]
  12
  13  virt-rescue --suggest (-d domname | -a disk.img ...)
  14
  15 Old style:
  16
  17  virt-rescue [--options] domname
  18
  19  virt-rescue [--options] disk.img [disk.img ...]
  20
  21 =head1 WARNING
  22
  23 You must I<not> use C<virt-rescue> on live virtual machines.  Doing so
  24 will probably result in disk corruption in the VM.  C<virt-rescue>
  25 tries to stop you from doing this, but doesn't catch all cases.
  26
  27 However if you use the I<--ro> (read only) option, then you can attach
  28 a shell to a live virtual machine.  The results might be strange or
  29 inconsistent at times but you won't get disk corruption.
  30
  31 =head1 DESCRIPTION
  32
  33 virt-rescue is like a Rescue CD, but for virtual machines, and without
  34 the need for a CD.  virt-rescue gives you a rescue shell and some
  35 simple recovery tools which you can use to examine or rescue a virtual
  36 machine or disk image.
  37
  38 You can run virt-rescue on any virtual machine known to libvirt, or
  39 directly on disk image(s):
  40
  41  virt-rescue -d GuestName
  42
  43  virt-rescue --ro -a /path/to/disk.img
  44
  45  virt-rescue -a /dev/sdc
  46
  47 For live VMs you I<must> use the --ro option.
  48
  49 When you run virt-rescue on a virtual machine or disk image, you are
  50 placed in an interactive bash shell where you can use many ordinary
  51 Linux commands.  What you see in C</> (C</bin>, C</lib> etc) is the
  52 rescue appliance.  You must mount the virtual machine's filesystems by
  53 hand.  There is an empty directory called C</sysroot> where you can
  54 mount filesystems.
  55
  56 You can get virt-rescue to suggest mount commands for you by using the
  57 I<--suggest> option (in another terminal):
  58
  59  $ virt-rescue --suggest -d Fedora15
  60  Inspecting the virtual machine or disk image ...
  61
  62  This disk contains one or more operating systems.  You can use these
  63  mount commands in virt-rescue (at the ><rescue> prompt) to mount the
  64  filesystems.
  65
  66  # /dev/vg_f15x32/lv_root is the root of a linux operating system
  67  # type: linux, distro: fedora, version: 15.0
  68  # Fedora release 15 (Lovelock)
  69
  70  mount /dev/vg_f15x32/lv_root /sysroot/
  71  mount /dev/vda1 /sysroot/boot
  72  mount --bind /dev /sysroot/dev
  73  mount --bind /dev/pts /sysroot/dev/pts
  74  mount --bind /proc /sysroot/proc
  75  mount --bind /sys /sysroot/sys
  76
  77 Another way is to list the logical volumes (with L<lvs(8)>) and
  78 partitions (with L<parted(8)>) and mount them by hand:
  79
  80  ><rescue> lvs
  81  LV      VG        Attr   LSize   Origin Snap%  Move Log Copy%  Convert
  82  lv_root vg_f15x32 -wi-a-   8.83G
  83  lv_swap vg_f15x32 -wi-a- 992.00M
  84  ><rescue> mount /dev/vg_f15x32/lv_root /sysroot
  85  ><rescue> mount /dev/vda1 /sysroot/boot
  86  ><rescue> ls /sysroot
  87
  88 Another command to list available filesystems is
  89 L<virt-filesystems(1)>.
  90
  91 To run commands in a Linux guest (for example, grub), you should
  92 chroot into the /sysroot directory first:
  93
  94  ><rescue> chroot /sysroot
  95
  96 =head2 NOTES
  97
  98 Virt-rescue can be used on I<any> disk image file or device, not just
  99 a virtual machine.  For example you can use it on a blank file if you
 100 want to partition that file (although we would recommend using
 101 L<guestfish(1)> instead as it is more suitable for this purpose).  You
 102 can even use virt-rescue on things like SD cards.
 103
 104 Virt-rescue does not require root.  You only need to run it as root if
 105 you need root to open the disk image.
 106
 107 This tool is just designed for quick interactive hacking on a virtual
 108 machine.  For more structured access to a virtual machine disk image,
 109 you should use L<guestfs(3)>.  To get a structured shell that you can
 110 use to make scripted changes to guests, use L<guestfish(1)>.
 111
 112 =head1 OPTIONS
 113
 114 =over 4
 115
 116 =item B<--help>
 117
 118 Display brief help.
 119
 120 =item B<-a> file
 121
 122 =item B<--add> file
 123
 124 Add I<file> which should be a disk image from a virtual machine.  If
 125 the virtual machine has multiple block devices, you must supply all of
 126 them with separate I<-a> options.
 127
 128 The format of the disk image is auto-detected.  To override this and
 129 force a particular format use the I<--format=..> option.
 130
 131 =item B<--append kernelopts>
 132
 133 Pass additional options to the rescue kernel.
 134
 135 =item B<-c> URI
 136
 137 =item B<--connect> URI
 138
 139 If using libvirt, connect to the given I<URI>.  If omitted, then we
 140 connect to the default libvirt hypervisor.
 141
 142 If you specify guest block devices directly (I<-a>), then libvirt is
 143 not used at all.
 144
 145 =item B<-d> guest
 146
 147 =item B<--domain> guest
 148
 149 Add all the disks from the named libvirt guest.  Domain UUIDs can be
 150 used instead of names.
 151
 152 =item B<--format=raw|qcow2|..>
 153
 154 =item B<--format>
 155
 156 The default for the I<-a> option is to auto-detect the format of the
 157 disk image.  Using this forces the disk format for I<-a> options which
 158 follow on the command line.  Using I<--format> with no argument
 159 switches back to auto-detection for subsequent I<-a> options.
 160
 161 For example:
 162
 163  virt-rescue --format=raw -a disk.img
 164
 165 forces raw format (no auto-detection) for C<disk.img>.
 166
 167  virt-rescue --format=raw -a disk.img --format -a another.img
 168
 169 forces raw format (no auto-detection) for C<disk.img> and reverts to
 170 auto-detection for C<another.img>.
 171
 172 If you have untrusted raw-format guest disk images, you should use
 173 this option to specify the disk format.  This avoids a possible
 174 security problem with malicious guests (CVE-2010-3851).
 175
 176 =item B<-m MB>
 177
 178 =item B<--memsize MB>
 179
 180 Change the amount of memory allocated to the rescue system.  The
 181 default is set by libguestfs and is small but adequate for running
 182 system tools.  The occasional program might need more memory.  The
 183 parameter is specified in megabytes.
 184
 185 =item B<--network>
 186
 187 Enable QEMU user networking in the guest.  See L</NETWORK>.
 188
 189 =item B<-r>
 190
 191 =item B<--ro>
 192
 193 Open the image read-only.
 194
 195 The option must always be used if the disk image or virtual machine
 196 might be running, and is generally recommended in cases where you
 197 don't need write access to the disk.
 198
 199 See also L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
 200
 201 =item B<--selinux>
 202
 203 Enable SELinux in the rescue appliance.  You should read
 204 L<guestfs(3)/SELINUX> before using this option.
 205
 206 =item B<--smp> N
 207
 208 Enable N E<ge> 2 virtual CPUs in the rescue appliance.
 209
 210 =item B<--suggest>
 211
 212 Inspect the disk image and suggest what mount commands should be used
 213 to mount the disks.  You should use the I<--suggest> option in a
 214 second terminal, then paste the commands into another virt-rescue.
 215
 216 This option implies I<--ro> and is safe to use even if the guest is up
 217 or if another virt-rescue is running.
 218
 219 =item B<-v>
 220
 221 =item B<--verbose>
 222
 223 Enable verbose messages for debugging.
 224
 225 =item B<-V>
 226
 227 =item B<--version>
 228
 229 Display version number and exit.
 230
 231 =item B<-w>
 232
 233 =item B<--rw>
 234
 235 This changes the I<-a> and I<-d> options so that disks are
 236 added and mounts are done read-write.
 237
 238 See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
 239
 240 =item B<-x>
 241
 242 Enable tracing of libguestfs API calls.
 243
 244 =back
 245
 246 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
 247
 248 Previous versions of virt-rescue allowed you to write either:
 249
 250  virt-rescue disk.img [disk.img ...]
 251
 252 or
 253
 254  virt-rescue guestname
 255
 256 whereas in this version you should use I<-a> or I<-d> respectively
 257 to avoid the confusing case where a disk image might have the same
 258 name as a guest.
 259
 260 For compatibility the old style is still supported.
 261
 262 =head1 NETWORK
 263
 264 Adding the I<--network> option enables QEMU user networking
 265 in the rescue appliance.  There are some differences between
 266 user networking and ordinary networking:
 267
 268 =over 4
 269
 270 =item ping does not work
 271
 272 Because the ICMP ECHO_REQUEST protocol generally requires root in
 273 order to send the ping packets, and because virt-rescue must be able
 274 to run as non-root, QEMU user networking is not able to emulate the
 275 L<ping(8)> command.  The ping command will appear to resolve addresses
 276 but will not be able to send or receive any packets.  This does not
 277 mean that the network is not working.
 278
 279 =item cannot receive connections
 280
 281 QEMU user networking cannot receive incoming connections.
 282
 283 =item making TCP connections
 284
 285 The virt-rescue appliance needs to be small and so does not include
 286 many network tools.  In particular there is no L<telnet(1)> command.
 287 You can make TCP connections from the shell using the magical
 288 C</dev/tcp/E<lt>hostnameE<gt>/E<lt>portE<gt>> syntax:
 289
 290  exec 3<>/dev/tcp/redhat.com/80
 291  echo "GET /" >&3
 292  cat <&3
 293
 294 See L<bash(1)> for more details.
 295
 296 =back
 297
 298 =head1 ENVIRONMENT VARIABLES
 299
 300 Several environment variables affect virt-rescue.  See
 301 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
 302
 303 =head1 SHELL QUOTING
 304
 305 Libvirt guest names can contain arbitrary characters, some of which
 306 have meaning to the shell such as C<#> and space.  You may need to
 307 quote or escape these characters on the command line.  See the shell
 308 manual page L<sh(1)> for details.
 309
 310 =head1 FILES
 311
 312 =over 4
 313
 314 =item $HOME/.libguestfs-tools.rc
 315
 316 =item /etc/libguestfs-tools.conf
 317
 318 This configuration file controls the default read-only or read-write
 319 mode (I<--ro> or I<--rw>).
 320
 321 See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
 322
 323 =back
 324
 325 =head1 SEE ALSO
 326
 327 L<guestfs(3)>,
 328 L<guestfish(1)>,
 329 L<virt-cat(1)>,
 330 L<virt-edit(1)>,
 331 L<virt-filesystems(1)>,
 332 L<http://libguestfs.org/>.
 333
 334 =head1 AUTHOR
 335
 336 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 337
 338 =head1 COPYRIGHT
 339
 340 Copyright (C) 2009-2011 Red Hat Inc.
 341
 342 This program is free software; you can redistribute it and/or modify
 343 it under the terms of the GNU General Public License as published by
 344 the Free Software Foundation; either version 2 of the License, or
 345 (at your option) any later version.
 346
 347 This program is distributed in the hope that it will be useful,
 348 but WITHOUT ANY WARRANTY; without even the implied warranty of
 349 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 350 GNU General Public License for more details.
 351
 352 You should have received a copy of the GNU General Public License
 353 along with this program; if not, write to the Free Software
 354 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.