X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfish.pod;h=13a9fa7dd2d917233c4a37c0f0612e5e6e39bc7f;hp=5427b23bf42f5447823ff49727975d9a811b0f9f;hb=2e2eb15df010bbcc605c86b0714ad1ca796fc96d;hpb=8249460acfc0ab7298d125b4ea29c72729a4582b diff --git a/guestfish.pod b/guestfish.pod index 5427b23..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 - -=head2 As an interactive shell + edit /boot/grub/grub.conf - $ guestfish +=head2 Using virt-inspector - Welcome to guestfish, the libguestfs filesystem interactive shell for - editing virtual machine filesystems. +Use the I<-i> option to get virt-inspector to mount +the filesystems automatically as they would be mounted +in the virtual machine: - Type: 'help' for help with commands - 'quit' to quit the shell - - > help + 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 - sfdisk /dev/sda 0 0 0 , + 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 @@ -152,6 +181,11 @@ You have to mount something on C before most commands will work. If any C<-m> or C<--mount> options are given, the guest is automatically launched. +If you don't know what filesystems a disk image contains, you +can either run guestfish without this option, then list the partitions +and LVs available (see L and L commands), +or you can use the L program. + =item B<-n> | B<--no-sync> Disable autosync. This is enabled by default. See the discussion @@ -164,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> @@ -250,9 +288,13 @@ quotes. For example: rm '/"' A few commands require a list of strings to be passed. For these, use -a space-separated list, enclosed in quotes. For example: +a whitespace-separated list, enclosed in quotes. Strings containing whitespace +to be passed through must be enclosed in single quotes. A literal single quote +must be escaped with a backslash. vgcreate VG "/dev/sda1 /dev/sdb1" + command "/bin/echo 'foo bar'" + command "/bin/echo \'foo\'" =head1 WILDCARDS AND GLOBBING @@ -346,6 +388,23 @@ it, eg: echo "~" +=head1 WINDOWS PATHS + +If a path is prefixed with C then you can use Windows-style +paths (with some limitations). The following commands are equivalent: + + file /WINDOWS/system32/config/system.LOG + + file win:/windows/system32/config/system.log + + file win:\windows\system32\config\system.log + + file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG + +This syntax implicitly calls C (q.v.) so it also +handles case insensitivity like Windows would. This only works in +argument positions that expect a path. + =head1 EXIT ON ERROR BEHAVIOUR By default, guestfish will ignore any errors when in interactive mode @@ -394,13 +453,6 @@ You can have several guestfish listener processes running using: guestfish --remote=$pid1 cmd guestfish --remote=$pid2 cmd -=head2 STANDARD OUTPUT DURING REMOTE CONTROL - -Because of limitations in the C statement, stdout from the -listener is currently redirected to C. - -Stderr is unchanged. - =head2 REMOTE CONTROL DETAILS Remote control happens over a Unix domain socket called @@ -439,6 +491,18 @@ number of megabytes number of gigabytes +=item CT or CTB + +number of terabytes + +=item CP or CPB + +number of petabytes + +=item CE or CEB + +number of exabytes + =item Csects number of 512 byte sectors @@ -517,6 +581,55 @@ Close and reopen the libguestfs handle. It is not necessary to use this normally, because the handle is closed properly when guestfish exits. However this is occasionally useful for testing. +=head2 sparse + + sparse filename size + +This creates an empty sparse file of the given size, and then adds +so it can be further examined. + +In all respects it works the same as the C command, except that +the image file is allocated sparsely, which means that disk blocks are +not assigned to the file until they are needed. Sparse disk files +only use space when written to, but they are slower and there is a +danger you could run out of real disk space during a write operation. + +For more advanced image creation, see L utility. + +Size can be specified (where C means a number): + +=over 4 + +=item C or CK or CKB + +number of kilobytes, eg: C<1440> = standard 3.5in floppy + +=item CM or CMB + +number of megabytes + +=item CG or CGB + +number of gigabytes + +=item CT or CTB + +number of terabytes + +=item CP or CPB + +number of petabytes + +=item CE or CEB + +number of exabytes + +=item Csects + +number of 512 byte sectors + +=back + =head2 time time command args... @@ -575,6 +688,10 @@ Set the default qemu binary that libguestfs uses. If not set, then the qemu which was found at compile time by the configure script is used. +=item LIBGUESTFS_TRACE + +Set C to enable command traces. + =item PAGER The C command uses C<$PAGER> as the pager. If not @@ -600,7 +717,13 @@ I<1> if there was an error. =head1 SEE ALSO L, -L. +L, +L, +L, +L, +L, +L, +L. =head1 AUTHORS