X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=4f4e1f0b4f243dd27b0f5b51493e4f0cb1653f1c;hp=ed2e7980ce8858c2c48530b369c367ca556a1dad;hb=1d5ec10659d67020c5b709e4df4c49bc0d59d58c;hpb=0003ea2c3dbaa7e22f4f616539136821d80694b8 diff --git a/fish/guestfish.pod b/fish/guestfish.pod index ed2e798..4f4e1f0 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -27,6 +27,17 @@ 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 DESCRIPTION + +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 should look at the +L command. + =head1 EXAMPLES =head2 As an interactive shell @@ -40,11 +51,22 @@ virtual machine might be live. 'man' to read the manual 'quit' to quit the shell - > man + > add-ro disk.img + > run + > list-filesystems + /dev/sda1: ext4 + /dev/vg_guest/lv_root: ext4 + /dev/vg_guest/lv_swap: swap + > mount /dev/vg_guest/lv_root / + > cat /etc/fstab + # /etc/fstab + # Created by anaconda + [...] + > exit =head2 From shell scripts -Create a new C file in a guest: +Create a new C file in a guest or disk image: guestfish <<_EOF_ add disk.img @@ -53,13 +75,20 @@ Create a new C file in a guest: write /etc/motd "Welcome, new users" _EOF_ -List the LVM logical volumes in a guest: +List the LVM logical volumes in a disk image: guestfish -a disk.img --ro <<_EOF_ run lvs _EOF_ +List all the filesystems in a disk image: + + guestfish -a disk.img --ro <<_EOF_ + run + list-filesystems + _EOF_ + =head2 On one command line Update C in a guest: @@ -84,6 +113,10 @@ disks from a virtual machine: guestfish --ro -d libvirt-domain -i cat /etc/group +Another way to edit C interactively is: + + guestfish -a disk.img -i edit /boot/grub/grub.conf + =head2 As a script interpreter Create a 100MB disk containing an ext2-formatted partition: @@ -107,22 +140,11 @@ To list what is available do: =head2 Remote control - eval `guestfish --listen --ro` - guestfish --remote add disk.img + eval `guestfish --listen` + guestfish --remote add-ro disk.img guestfish --remote run guestfish --remote lvs -=head1 DESCRIPTION - -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 should look at the -L command. - =head1 OPTIONS =over 4 @@ -143,6 +165,9 @@ Displays detailed help on a single command C. Add a block device or virtual machine image to the shell. +The format of the disk image is auto-detected. To override this and +force a particular format use the I<--format=..> option. + =item B<-c URI> | B<--connect URI> When used in conjunction with the I<-d> option, this specifies @@ -162,6 +187,13 @@ able to hit the tab key to complete paths on the guest filesystem, but this causes extra "hidden" guestfs calls to be made, so this option is here to allow this feature to be disabled. +=item B<--echo-keys> + +When prompting for keys and passphrases, guestfish normally turns +echoing off so you cannot see what you are typing. If you are not +worried about Tempest attacks and there is no one else in the room +you can specify this flag to see what you are typing. + =item B<-f file> | B<--file file> Read commands from C. To write pure guestfish @@ -169,6 +201,29 @@ scripts, use: #!/usr/bin/guestfish -f +=item B<--format=raw|qcow2|..> | 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: + + guestfish --format=raw -a disk.img + +forces raw format (no auto-detection) for C. + + guestfish --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<-i> | B<--inspector> Using L code, inspect the disks looking for @@ -327,9 +382,10 @@ any other commands C is a synonym for C. You must C (or C) your guest before mounting or performing any other commands. -The only exception is that if the I<-m> or I<--mount> option was -given, the guest is automatically run for you (simply because -guestfish can't mount the disks you asked for without doing this). +The only exception is that if any of the I<-i>, I<-m>, I<--mount>, +I<-N> or I<--new> options were given then C is done +automatically, simply because guestfish can't perform the action you +asked for without doing this. =head1 QUOTING @@ -351,6 +407,21 @@ must be escaped with a backslash. command "/bin/echo 'foo bar'" command "/bin/echo \'foo\'" +=head1 OPTIONAL ARGUMENTS + +Some commands take optional arguments. These arguments appear in this +documentation as C<[argname:..]>. You can use them as in these +examples: + + add-drive-opts filename + + add-drive-opts filename readonly:true + + add-drive-opts filename format:qcow2 readonly:false + +Each optional argument can appear at most once. All optional +arguments must appear after the required ones. + =head1 NUMBERS This section applies to all commands which can take integers @@ -468,7 +539,7 @@ following will not do what you expect: rm-rf /home/* -Assuming you don't have a directory literally called C +Assuming you don't have a directory called literally C then the above command will return an error. To perform wildcard expansion, use the C command. @@ -485,7 +556,7 @@ the command many times), equivalent to: C only works on simple guest paths and not on device names. If you have several parameters, each containing a wildcard, then glob -will perform a cartesian product. +will perform a Cartesian product. =head1 COMMENTS @@ -577,8 +648,8 @@ device-mapper device called C. Finally you have to tell LVM to scan for volume groups on the newly created mapper device: - > vgscan - > vg-activate-all true + vgscan + vg-activate-all true The logical volume(s) can now be mounted in the usual way. @@ -586,8 +657,8 @@ Before closing a LUKS device you must unmount any logical volumes on it and deactivate the volume groups by calling C on each one. Then you can close the mapper device: - > vg-activate false /dev/VG - > luks-close /dev/mapper/luksdev + vg-activate false /dev/VG + luks-close /dev/mapper/luksdev =head1 WINDOWS PATHS @@ -808,6 +879,12 @@ Used with the I<--remote> option to specify the remote guestfish process to control. See section L. +=item HEXEDITOR + +The L command uses C<$HEXEDITOR> as the external hex +editor. If not specified, the external L program +is used. + =item HOME If compiled with GNU readline support, various files in the @@ -853,9 +930,9 @@ set, it uses C. Location of temporary directory, defaults to C. -If libguestfs was compiled to use the supermin appliance then each -handle will require rather a large amount of space in this directory -for short periods of time (~ 80 MB). You can use C<$TMPDIR> to +If libguestfs was compiled to use the supermin appliance then the +real appliance is cached in this directory, shared between all +handles belonging to the same EUID. You can use C<$TMPDIR> to configure another directory to use in case C is not large enough. @@ -925,7 +1002,8 @@ L, L, L, L, -L. +L, +L. =head1 AUTHORS