From: Richard Jones Date: Thu, 26 Nov 2009 22:32:15 +0000 (+0000) Subject: guestfish: Freshen documentation. X-Git-Tag: 1.0.80~16 X-Git-Url: http://git.annexia.org/?a=commitdiff_plain;h=47ecaa9ad4224803313ecc1d5b96def8eed3dac8;p=libguestfs.git guestfish: Freshen documentation. --- diff --git a/guestfish.pod b/guestfish.pod index 876b988..13a9fa7 100644 --- a/guestfish.pod +++ b/guestfish.pod @@ -2,18 +2,36 @@ =head1 NAME -guestfish - the libguestfs filesystem interactive shell +guestfish - the libguestfs Filesystem Interactive SHell =head1 SYNOPSIS guestfish [--options] [commands] + guestfish + + guestfish -a disk.img + + guestfish -a disk.img -m dev[:mountpoint] + guestfish -i libvirt-domain - guestfish -i disk-image(s) + guestfish -i disk.img [disk.img ...] =head1 EXAMPLES +=head2 As an interactive shell + + $ guestfish + + Welcome to guestfish, the libguestfs filesystem interactive shell for + editing virtual machine filesystems. + + Type: 'help' for help with commands + 'quit' to quit the shell + + > help + =head2 From shell scripts Create a new C file in a guest: @@ -21,55 +39,56 @@ Create a new C file in a guest: guestfish <<_EOF_ add disk.img run - mount /dev/VolGroup00/LogVol00 / - write_file /etc/motd "Hello users" 0 + mount /dev/vg_guest/lv_root / + write_file /etc/motd "Welcome, new users" 0 _EOF_ -List the LVs in a guest: +List the LVM logical volumes in a guest: - guestfish <<_EOF_ - add disk.img + guestfish -a disk.img --ro <<_EOF_ run lvs _EOF_ -=head2 On the command line +=head2 On one command line -List the LVM PVs in a guest image: +Update C in a guest: - guestfish add disk.img : run : pvs + guestfish \ + add disk.img : run : mount /dev/vg_guest/lv_root / : \ + write-file /etc/resolv.conf "nameserver 1.2.3.4" 0 -Remove C (in reality not such a great idea): +Edit C interactively: guestfish --add disk.img \ - --mount /dev/VolGroup00/LogVol00 \ + --mount /dev/vg_guest/lv_root \ --mount /dev/sda1:/boot \ - rm /boot/grub/menu.lst + edit /boot/grub/grub.conf -=head2 As an interactive shell +=head2 Using virt-inspector - $ guestfish - - Welcome to guestfish, the libguestfs filesystem interactive shell for - editing virtual machine filesystems. - - Type: 'help' for help with commands - 'quit' to quit the shell - - > help +Use the I<-i> option to get virt-inspector to mount +the filesystems automatically as they would be mounted +in the virtual machine: + + guestfish --ro -i disk.img cat /etc/group =head2 As a script interpreter +Create a 50MB disk containing an ext2-formatted partition: + #!/usr/bin/guestfish -f - alloc /tmp/output.img 10M + alloc /tmp/output.img 50M run part-disk /dev/sda mbr mkfs ext2 /dev/sda1 =head2 Remote control - eval `guestfish --listen` - guestfish --remote cmd + eval `guestfish --listen --ro` + guestfish --remote add disk.img + guestfish --remote run + guestfish --remote lvs =head1 DESCRIPTION @@ -77,6 +96,16 @@ Guestfish is a shell and command-line tool for examining and modifying virtual machine filesystems. It uses libguestfs and exposes all of the functionality of the guestfs API, see L. +Guestfish gives you structured access to the libguestfs API, from +shell scripts or the command line or interactively. If you want to +rescue a broken virtual machine image, you might want to look at the +L command. + +Using guestfish in read/write mode on live virtual machines can be +dangerous, potentially causing disk corruption. Use the I<--ro> +(read-only) option to use guestfish safely if the disk image or +virtual machine might be live. + =head1 OPTIONS =over 4 @@ -169,8 +198,12 @@ I below. =item B<-r> | B<--ro> -This changes the C<-m> option so that mounts are done read-only -(see C in the L manpage). +This changes the C<-a> and C<-m> options so that disks are added and +mounts are done read-only (see L). + +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>