X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=07b9899940b942516f361b7795a388ce61308c23;hp=4e0ff1315af3fa1e380c4911801c855c92a44209;hb=fbc2555903be8c88ad9430d871cf0d27c8fded1e;hpb=ff4ae8633e0ca7c1e679870600830ee4d9f1cd71 diff --git a/fish/guestfish.pod b/fish/guestfish.pod index 4e0ff13..07b9899 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -10,13 +10,13 @@ guestfish - the libguestfs Filesystem Interactive SHell guestfish - guestfish -a disk.img + guestfish [--ro|--rw] -a disk.img - guestfish -a disk.img -m dev[:mountpoint] + guestfish [--ro|--rw] -a disk.img -m dev[:mountpoint] guestfish -d libvirt-domain - guestfish -a disk.img -i + guestfish [--ro|--rw] -a disk.img -i guestfish -d libvirt-domain -i @@ -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: @@ -70,7 +99,7 @@ Update C in a guest: Edit C interactively: - guestfish --add disk.img \ + guestfish --rw --add disk.img \ --mount /dev/vg_guest/lv_root \ --mount /dev/sda1:/boot \ edit /boot/grub/grub.conf @@ -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 --rw -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,12 +165,20 @@ 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 the libvirt URI to use. The default is to use the default libvirt connection. +=item B<--csh> + +If using the I<--listen> option and a csh-like shell, use this option. +See section L below. + =item B<-d libvirt-domain> | B<--domain libvirt-domain> Add disks from the named libvirt domain. If the I<--ro> option is @@ -176,6 +206,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 @@ -192,7 +245,7 @@ Typical usage is either: (for active domains, readonly), or specify the block device directly: - guestfish -a /dev/Guests/MyGuest -i + guestfish --rw -a /dev/Guests/MyGuest -i Note that the command line syntax changed slightly over older versions of guestfish. You can still use the old syntax: @@ -222,10 +275,11 @@ You have to mount something on C before most commands will work. If any I<-m> or I<--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. +If you don't know what filesystems a disk image contains, you can +either run guestfish without this option, then list the partitions, +filesystems and LVs available (see L, +L and L commands), or you can use the +L program. =item B<-n> | B<--no-sync> @@ -267,6 +321,8 @@ don't need write access to the disk. Note that prepared disk images created with I<-N> are not affected by the I<--ro> option. +See also L below. + =item B<--selinux> Enable SELinux support for the guest. See L. @@ -280,6 +336,11 @@ a bug. Display the guestfish / libguestfs version number and exit. +=item B<-w> | B<--rw> + +This option does nothing at the moment. +See L below. + =item B<-x> Echo each command before executing it. @@ -334,9 +395,37 @@ 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 OPENING DISKS FOR READ AND WRITE + +The guestfish (and L) options I<--ro> and I<--rw> +affect whether the other command line options I<-a>, I<-c>, I<-d>, +I<-i> and I<-m> open disk images read-only or for writing. + +In libguestfs E 1.6.2, guestfish and guestmount defaulted to +opening disk images supplied on the command line for write. To open a +disk image read-only you have to do I<-a image --ro>. + +This matters: If you accidentally open a live VM disk image writable +then you will cause irreversible disk corruption. + +By libguestfs 1.8 we intend to change the default the other way. Disk +images will be opened read-only. You will have to either specify +I or change a configuration file in order to get write +access for disk images specified by those other command line options. + +This version of guestfish has a I<--rw> option which does nothing (it +is already the default). However it is highly recommended that you +use this option to indicate that guestfish needs write access, and to +prepare your scripts for the day when this option will be required for +write access. + +B This does I affect commands like L and L, +or any other libguestfs program apart from guestfish and guestmount. =head1 QUOTING @@ -358,6 +447,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 @@ -475,7 +579,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. @@ -492,7 +596,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 @@ -584,8 +688,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. @@ -593,8 +697,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 @@ -666,7 +770,7 @@ up a guestfish process each time. Start a guestfish server process using: - eval `guestfish --listen` + eval "`guestfish --listen`" and then send it commands by doing: @@ -686,14 +790,21 @@ The C statement sets the environment variable C<$GUESTFISH_PID>, which is how the I<--remote> option knows where to send the commands. You can have several guestfish listener processes running using: - eval `guestfish --listen` + eval "`guestfish --listen`" pid1=$GUESTFISH_PID - eval `guestfish --listen` + eval "`guestfish --listen`" pid2=$GUESTFISH_PID ... guestfish --remote=$pid1 cmd guestfish --remote=$pid2 cmd +=head2 REMOTE CONTROL AND CSH + +When using csh-like shells (csh, tcsh etc) you have to add the +I<--csh> option: + + eval "`guestfish --listen --csh`" + =head2 REMOTE CONTROL DETAILS Remote control happens over a Unix domain socket called @@ -782,8 +893,9 @@ other words, they are not part of the L API. help help cmd -Without any parameter, this lists all commands. With a C -parameter, this displays detailed help for a command. +Without any parameter, this provides general help. + +With a C parameter, this displays detailed help for that command. =head2 quit | exit @@ -815,6 +927,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 @@ -860,9 +978,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,6 +1043,7 @@ L, L, L, L, +L, L, L, L, @@ -932,7 +1051,8 @@ L, L, L, L, -L. +L, +L. =head1 AUTHORS