X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=cf1140a59597c96ab1e860fb82e5f520d382fd69;hp=a6d341e4b465b4e85e969dd011784f87c79c8d21;hb=4932fdca3ca1e9002164a1c0b73876f32739d34d;hpb=5e1aff7856f721bf5737815a5b65c0de23ab0b0c

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index a6d341e..cf1140a 100644
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -14,9 +14,18 @@ guestfish - the libguestfs Filesystem Interactive SHell
 
  guestfish -a disk.img -m dev[:mountpoint]
 
- guestfish -i libvirt-domain
+ guestfish -d libvirt-domain
 
- guestfish -i disk.img [disk.img ...]
+ guestfish -a disk.img -i
+
+ guestfish -d libvirt-domain -i
+
+=head1 WARNING
+
+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 EXAMPLES
 
@@ -66,13 +75,14 @@ Edit C</boot/grub/grub.conf> interactively:
    --mount /dev/sda1:/boot \
    edit /boot/grub/grub.conf
 
-=head2 Using virt-inspector
+=head2 Mount disks automatically
 
-Use the I<-i> option to get virt-inspector to mount
-the filesystems automatically as they would be mounted
-in the virtual machine:
+Use the I<-i> option to automatically mount the
+disks from a virtual machine:
 
- guestfish --ro -i disk.img cat /etc/group
+ guestfish --ro -a disk.img -i cat /etc/group
+
+ guestfish --ro -d libvirt-domain -i cat /etc/group
 
 =head2 As a script interpreter
 
@@ -113,11 +123,6 @@ 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.
 
-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
@@ -138,6 +143,18 @@ Displays detailed help on a single command C<cmd>.
 
 Add a block device or virtual machine image to the shell.
 
+=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<-d libvirt-domain> | B<--domain libvirt-domain>
+
+Add disks from the named libvirt domain.  If the I<--ro> option is
+also used, then any libvirt domain can be used.  However in write
+mode, only libvirt domains which are shut down can be named here.
+
 =item B<-D> | B<--no-dest-paths>
 
 Don't tab-complete paths on the guest filesystem.  It is useful to be
@@ -154,28 +171,33 @@ scripts, use:
 
 =item B<-i> | B<--inspector>
 
-Run virt-inspector on the named libvirt domain or list of disk
-images.  If virt-inspector is available and if it can identify
-the domain or disk images, then partitions will be mounted
-correctly at start-up.
+Using L<virt-inspector(1)> code, inspect the disks looking for
+an operating system and mount filesystems as they would be
+mounted on the real virtual machine.
 
 Typical usage is either:
 
- guestfish -i myguest
+ guestfish -d myguest -i
 
 (for an inactive libvirt domain called I<myguest>), or:
 
- guestfish --ro -i myguest
+ guestfish --ro -d myguest -i
 
 (for active domains, readonly), or specify the block device directly:
 
- guestfish -i /dev/Guests/MyGuest
+ guestfish -a /dev/Guests/MyGuest -i
 
-You cannot use I<-a>, I<-m>, I<-N>, I<--listen>, I<--remote> or
-I<--selinux> in conjunction with this option, and options other than
-I<--ro> might not behave correctly.
+Note that the command line syntax changed slightly over older
+versions of guestfish.  You can still use the old syntax:
 
-See also: L<virt-inspector(1)>.
+ guestfish [--ro] -i disk.img
+
+ guestfish [--ro] -i libvirt-domain
+
+=item B<--keys-from-stdin>
+
+Read key or passphrase parameters from stdin.  The default is
+to try to read passphrases from the user by opening C</dev/tty>.
 
 =item B<--listen>
 
@@ -523,6 +545,39 @@ it, eg:
 
  echo "~"
 
+=head1 ENCRYPTED DISKS
+
+Libguestfs has some support for Linux guests encrypted according to
+the Linux Unified Key Setup (LUKS) standard, which includes nearly all
+whole disk encryption systems used by modern Linux guests.  Currently
+only LVM-on-LUKS is supported.
+
+Identify encrypted block devices and partitions using L</vfs-type>:
+
+ ><fs> vfs-type /dev/sda2
+ crypto_LUKS
+
+Then open those devices using L</luks-open>.  This creates a
+device-mapper device called C</dev/mapper/luksdev>.
+
+ ><fs> luks-open /dev/sda2 luksdev
+ Enter key or passphrase ("key"): <enter the passphrase>
+
+Finally you have to tell LVM to scan for volume groups on
+the newly created mapper device:
+
+ ><fs> vgscan
+ ><fs> vg-activate-all true
+
+The logical volume(s) can now be mounted in the usual way.
+
+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
+
 =head1 WINDOWS PATHS
 
 If a path is prefixed with C<win:> then you can use Windows-style
@@ -785,6 +840,16 @@ For more advanced image creation, see L<qemu-img(1)> utility.
 
 Size can be specified using standard suffixes, eg. C<1M>.
 
+=head2 supported
+
+ supported
+
+This command returns a list of the optional groups
+known to the daemon, and indicates which ones are
+supported by this build of the libguestfs appliance.
+
+See also L<guestfs(3)/AVAILABILITY>.
+
 =head2 time
 
  time command args...
@@ -796,6 +861,11 @@ can be useful for benchmarking operations.
 
 @ACTIONS@
 
+=head1 EXIT CODE
+
+guestfish returns 0 if the commands completed without error, or
+1 if there was an error.
+
 =head1 ENVIRONMENT VARIABLES
 
 =over 4
@@ -813,8 +883,8 @@ L</REMOTE CONTROL GUESTFISH OVER A SOCKET>.
 
 =item HOME
 
-If compiled with GNU readline support, then the command history
-is saved in C<$HOME/.guestfish>
+If compiled with GNU readline support, various files in the
+home directory can be used.  See L</FILES>.
 
 =item LIBGUESTFS_APPEND
 
@@ -864,10 +934,55 @@ enough.
 
 =back
 
-=head1 EXIT CODE
+=head1 FILES
 
-guestfish returns 0 if the commands completed without error, or
-1 if there was an error.
+=over 4
+
+=item $HOME/.guestfish
+
+If compiled with GNU readline support, then the command history
+is saved in this file.
+
+=item $HOME/.inputrc
+
+=item /etc/inputrc
+
+If compiled with GNU readline support, then these files can be used to
+configure readline.  For further information, please see
+L<readline(3)/INITIALIZATION FILE>.
+
+To write rules which only apply to guestfish, use:
+
+ $if guestfish
+ ...
+ $endif
+
+Variables that you can set in inputrc that change the behaviour
+of guestfish in useful ways include:
+
+=over 4
+
+=item completion-ignore-case (default: on)
+
+By default, guestfish will ignore case when tab-completing
+paths on the disk.  Use:
+
+ set completion-ignore-case off
+
+to make guestfish case sensitive.
+
+=back
+
+=item test1.img
+
+=item test2.img (etc)
+
+When using the C<-N> or C<--new> option, the prepared disk or
+filesystem will be created in the file C<test1.img> in the current
+directory.  The second use of C<-N> will use C<test2.img> and so on.
+Any existing file with the same name will be overwritten.
+
+=back
 
 =head1 SEE ALSO