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