X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=rescue%2Fvirt-rescue.pod;fp=rescue%2Fvirt-rescue.pod;h=c24d9ec9df3cecf856e9e7efee752215d78d2269;hp=0000000000000000000000000000000000000000;hb=a6054bf90f39a84c1a8f8f7d3b9e81e84cb13696;hpb=076a9726e608c914cd4785e9a14e9a903a61ca34 diff --git a/rescue/virt-rescue.pod b/rescue/virt-rescue.pod new file mode 100755 index 0000000..c24d9ec --- /dev/null +++ b/rescue/virt-rescue.pod @@ -0,0 +1,247 @@ +=encoding utf8 + +=head1 NAME + +virt-rescue - Run a rescue shell on a virtual machine + +=head1 SYNOPSIS + + virt-rescue [--options] -d domname + + virt-rescue [--options] -a disk.img [-a disk.img ...] + +Old style: + + virt-rescue [--options] domname + + virt-rescue [--options] disk.img [disk.img ...] + +=head1 WARNING + +You must I use C on live virtual machines. Doing so +will probably result in disk corruption in the VM. C +tries to stop you from doing this, but doesn't catch all cases. + +However if you use the I<--ro> (read only) option, then you can attach +a shell to a live virtual machine. The results might be strange or +inconsistent at times but you won't get disk corruption. + +=head1 DESCRIPTION + +virt-rescue is like a Rescue CD, but for virtual machines, and without +the need for a CD. virt-rescue gives you a rescue shell and some +simple recovery tools which you can use to examine or rescue a virtual +machine or disk image. + +You can run virt-rescue on any virtual machine known to libvirt, or +directly on disk image(s): + + virt-rescue -d GuestName + + virt-rescue --ro -a /path/to/disk.img + + virt-rescue -a /dev/sdc + +For live VMs you I use the --ro option. + +When you run virt-rescue on a virtual machine or disk image, you are +placed in an interactive bash shell where you can use many ordinary +Linux commands. What you see in C (C, C etc) is the +rescue appliance. You must mount the virtual machine's filesystems by +hand. There is an empty directory called C where you can +mount filesystems. + +In the example below, we list logical volumes, then choose one to +mount under C: + + > lvs + LV VG Attr LSize Origin Snap% Move Log Copy% Convert + lv_root vg_f11x64 -wi-a- 8.83G + lv_swap vg_f11x64 -wi-a- 992.00M + > mount /dev/vg_f11x64/lv_root /sysroot + > ls /sysroot + +If you don't know what filesystems are available on the virtual +machine then you can use commands such as L and L +to find out. + +=head2 NOTES + +Virt-rescue can be used on I disk image file or device, not just +a virtual machine. For example you can use it on a blank file if you +want to partition that file (although we would recommend using +L instead as it is more suitable for this purpose). You +can even use virt-rescue on things like SD cards. + +This tool is just designed for quick interactive hacking on a virtual +machine. For more structured access to a virtual machine disk image, +you should use L. To get a structured shell that you can +use to make scripted changes to guests, use L. + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +Display brief help. + +=item B<-a> file + +=item B<--add> file + +Add I which should be a disk image from a virtual machine. If +the virtual machine has multiple block devices, you must supply all of +them with separate I<-a> options. + +The format of the disk image is auto-detected. To override this and +force a particular format use the I<--format=..> option. + +=item B<--append kernelopts> + +Pass additional options to the rescue kernel. + +=item B<-c> URI + +=item B<--connect> URI + +If using libvirt, connect to the given I. If omitted, then we +connect to the default libvirt hypervisor. + +If you specify guest block devices directly (I<-a>), then libvirt is +not used at all. + +=item B<-d> guest + +=item B<--domain> guest + +Add all the disks from the named libvirt guest. + +=item B<--format=raw|qcow2|..> + +=item B<--format> + +The default for the I<-a> option is to auto-detect the format of the +disk image. Using this forces the disk format for I<-a> options which +follow on the command line. Using I<--format> with no argument +switches back to auto-detection for subsequent I<-a> options. + +For example: + + virt-rescue --format=raw -a disk.img + +forces raw format (no auto-detection) for C. + + virt-rescue --format=raw -a disk.img --format -a another.img + +forces raw format (no auto-detection) for C and reverts to +auto-detection for C. + +If you have untrusted raw-format guest disk images, you should use +this option to specify the disk format. This avoids a possible +security problem with malicious guests (CVE-2010-3851). See also +L. + +=item B<-m MB> + +=item B<--memsize MB> + +Change the amount of memory allocated to the rescue system. The +default is set by libguestfs and is small but adequate for running +system tools. The occasional program might need more memory. The +parameter is specified in megabytes. + +=item B<--network> + +Enable QEMU user networking in the guest. + +=item B<-r> + +=item B<--ro> + +Open the image read-only. + +The option must always be used if the disk image or virtual machine +might be running, and is generally recommended in cases where you +don't need write access to the disk. + +=item B<--selinux> + +Enable SELinux in the rescue appliance. You should read +L before using this option. + +=item B<-v> + +=item B<--verbose> + +Enable verbose messages for debugging. + +=item B<-V> + +=item B<--version> + +Display version number and exit. + +=item B<-x> + +Enable tracing of libguestfs API calls. + +=back + +=head1 OLD-STYLE COMMAND LINE ARGUMENTS + +Previous versions of virt-rescue allowed you to write either: + + virt-rescue disk.img [disk.img ...] + +or + + virt-rescue guestname + +whereas in this version you should use I<-a> or I<-d> respectively +to avoid the confusing case where a disk image might have the same +name as a guest. + +For compatibility the old style is still supported. + +=head1 ENVIRONMENT VARIABLES + +Several environment variables affect virt-rescue. See +L for the complete list. + +=head1 SHELL QUOTING + +Libvirt guest names can contain arbitrary characters, some of which +have meaning to the shell such as C<#> and space. You may need to +quote or escape these characters on the command line. See the shell +manual page L for details. + +=head1 SEE ALSO + +L, +L, +L, +L, +L. + +=head1 AUTHOR + +Richard W.M. Jones L + +=head1 COPYRIGHT + +Copyright (C) 2009-2010 Red Hat Inc. + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.