X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=4f4e1f0b4f243dd27b0f5b51493e4f0cb1653f1c;hp=285d901b18f24bba8c7dd9c0bf7ec94d9304e6eb;hb=61da709722ec244da1c3c7d4f1a8706f76687cb3;hpb=d72a617a262e000ce7bc97838ad1f0d640dc66ec;ds=sidebyside

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 285d901..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<guestfs(3)>.
+
+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<virt-rescue(1)> 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
  
- ><fs> man
+ ><fs> add-ro disk.img
+ ><fs> run
+ ><fs> list-filesystems
+ /dev/sda1: ext4
+ /dev/vg_guest/lv_root: ext4
+ /dev/vg_guest/lv_swap: swap
+ ><fs> mount /dev/vg_guest/lv_root /
+ ><fs> cat /etc/fstab
+ # /etc/fstab
+ # Created by anaconda
+ [...]
+ ><fs> exit
 
 =head2 From shell scripts
 
-Create a new C</etc/motd> file in a guest:
+Create a new C</etc/motd> file in a guest or disk image:
 
  guestfish <<_EOF_
  add disk.img
@@ -53,13 +75,20 @@ Create a new C</etc/motd> 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</etc/resolv.conf> 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</boot/grub/grub.conf> 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<guestfs(3)>.
-
-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<virt-rescue(1)> command.
-
 =head1 OPTIONS
 
 =over 4
@@ -143,6 +165,9 @@ Displays detailed help on a single command C<cmd>.
 
 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
@@ -176,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<disk.img>.
+
+ guestfish --format=raw -a disk.img --format -a another.img
+
+forces raw format (no auto-detection) for C<disk.img> and reverts to
+auto-detection for C<another.img>.
+
+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</add-drive-opts>.
+
 =item B<-i> | B<--inspector>
 
 Using L<virt-inspector(1)> code, inspect the disks looking for
@@ -334,9 +382,10 @@ any other commands
 C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
 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<run> is done
+automatically, simply because guestfish can't perform the action you
+asked for without doing this.
 
 =head1 QUOTING
 
@@ -358,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
@@ -475,7 +539,7 @@ following will not do what you expect:
 
  rm-rf /home/*
 
-Assuming you don't have a directory literally called C</home/*>
+Assuming you don't have a directory called literally C</home/*>
 then the above command will return an error.
 
 To perform wildcard expansion, use the C<glob> command.
@@ -492,7 +556,7 @@ the command many times), equivalent to:
 C<glob> 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 +648,8 @@ device-mapper device called C</dev/mapper/luksdev>.
 Finally you have to tell LVM to scan for volume groups on
 the newly created mapper device:
 
- ><fs> vgscan
- ><fs> vg-activate-all true
+ vgscan
+ vg-activate-all true
 
 The logical volume(s) can now be mounted in the usual way.
 
@@ -593,8 +657,8 @@ Before closing a LUKS device you must unmount any logical volumes on
 it and deactivate the volume groups by calling C<vg-activate false VG>
 on each one.  Then you can close the mapper device:
 
- ><fs> vg-activate false /dev/VG
- ><fs> luks-close /dev/mapper/luksdev
+ vg-activate false /dev/VG
+ luks-close /dev/mapper/luksdev
 
 =head1 WINDOWS PATHS