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 This tool is just designed for quick interactive hacking on a virtual
  77 machine.  For more structured access to a virtual machine disk image,
  78 you should use L<guestfs(3)>.  To get a structured shell that you can
  79 use to make scripted changes to guests, use L<guestfish(1)>.
  80
  81 =head1 OPTIONS
  82
  83 =over 4
  84
  85 =item B<--help>
  86
  87 Display brief help.
  88
  89 =item B<-a> file
  90
  91 =item B<--add> file
  92
  93 Add I<file> which should be a disk image from a virtual machine.  If
  94 the virtual machine has multiple block devices, you must supply all of
  95 them with separate I<-a> options.
  96
  97 The format of the disk image is auto-detected.  To override this and
  98 force a particular format use the I<--format=..> option.
  99
 100 =item B<--append kernelopts>
 101
 102 Pass additional options to the rescue kernel.
 103
 104 =item B<-c> URI
 105
 106 =item B<--connect> URI
 107
 108 If using libvirt, connect to the given I<URI>.  If omitted, then we
 109 connect to the default libvirt hypervisor.
 110
 111 If you specify guest block devices directly (I<-a>), then libvirt is
 112 not used at all.
 113
 114 =item B<-d> guest
 115
 116 =item B<--domain> guest
 117
 118 Add all the disks from the named libvirt guest.
 119
 120 =item B<--format=raw|qcow2|..>
 121
 122 =item B<--format>
 123
 124 The default for the I<-a> option is to auto-detect the format of the
 125 disk image.  Using this forces the disk format for I<-a> options which
 126 follow on the command line.  Using I<--format> with no argument
 127 switches back to auto-detection for subsequent I<-a> options.
 128
 129 For example:
 130
 131  virt-rescue --format=raw -a disk.img
 132
 133 forces raw format (no auto-detection) for C<disk.img>.
 134
 135  virt-rescue --format=raw -a disk.img --format -a another.img
 136
 137 forces raw format (no auto-detection) for C<disk.img> and reverts to
 138 auto-detection for C<another.img>.
 139
 140 If you have untrusted raw-format guest disk images, you should use
 141 this option to specify the disk format.  This avoids a possible
 142 security problem with malicious guests (CVE-2010-3851).  See also
 143 L</add-drive-opts>.
 144
 145 =item B<-m MB>
 146
 147 =item B<--memsize MB>
 148
 149 Change the amount of memory allocated to the rescue system.  The
 150 default is set by libguestfs and is small but adequate for running
 151 system tools.  The occasional program might need more memory.  The
 152 parameter is specified in megabytes.
 153
 154 =item B<--network>
 155
 156 Enable QEMU user networking in the guest.
 157
 158 =item B<-r>
 159
 160 =item B<--ro>
 161
 162 Open the image read-only.
 163
 164 The option must always be used if the disk image or virtual machine
 165 might be running, and is generally recommended in cases where you
 166 don't need write access to the disk.
 167
 168 =item B<--selinux>
 169
 170 Enable SELinux in the rescue appliance.  You should read
 171 L<guestfs(3)/SELINUX> before using this option.
 172
 173 =item B<-v>
 174
 175 =item B<--verbose>
 176
 177 Enable verbose messages for debugging.
 178
 179 =item B<-V>
 180
 181 =item B<--version>
 182
 183 Display version number and exit.
 184
 185 =item B<-x>
 186
 187 Enable tracing of libguestfs API calls.
 188
 189 =back
 190
 191 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
 192
 193 Previous versions of virt-rescue allowed you to write either:
 194
 195  virt-rescue disk.img [disk.img ...]
 196
 197 or
 198
 199  virt-rescue guestname
 200
 201 whereas in this version you should use I<-a> or I<-d> respectively
 202 to avoid the confusing case where a disk image might have the same
 203 name as a guest.
 204
 205 For compatibility the old style is still supported.
 206
 207 =head1 ENVIRONMENT VARIABLES
 208
 209 Several environment variables affect virt-rescue.  See
 210 L<guestfs(3)/ENVIRONMENT VARIABLES> for the complete list.
 211
 212 =head1 SHELL QUOTING
 213
 214 Libvirt guest names can contain arbitrary characters, some of which
 215 have meaning to the shell such as C<#> and space.  You may need to
 216 quote or escape these characters on the command line.  See the shell
 217 manual page L<sh(1)> for details.
 218
 219 =head1 SEE ALSO
 220
 221 L<guestfs(3)>,
 222 L<guestfish(1)>,
 223 L<virt-cat(1)>,
 224 L<virt-edit(1)>,
 225 L<http://libguestfs.org/>.
 226
 227 =head1 AUTHOR
 228
 229 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 230
 231 =head1 COPYRIGHT
 232
 233 Copyright (C) 2009-2010 Red Hat Inc.
 234
 235 This program is free software; you can redistribute it and/or modify
 236 it under the terms of the GNU General Public License as published by
 237 the Free Software Foundation; either version 2 of the License, or
 238 (at your option) any later version.
 239
 240 This program is distributed in the hope that it will be useful,
 241 but WITHOUT ANY WARRANTY; without even the implied warranty of
 242 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 243 GNU General Public License for more details.
 244
 245 You should have received a copy of the GNU General Public License
 246 along with this program; if not, write to the Free Software
 247 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.