docs: Document FEBOOTSTRAP_KERNEL, FEBOOTSTRAP_MODULES (RHBZ#671082).

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 58f0bd9..74d222f 100644 (file)
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -176,7 +176,7 @@ force a particular format use the I<--format=..> option.
 
 Using this flag is mostly equivalent to using the C<add> command,
 with C<readonly:true> if the I<--ro> flag was given, and
-with C<format:...> if the I<--format:...> flag was given.
+with C<format:...> if the I<--format=...> flag was given.
 
 =item B<-c URI>
 
@@ -199,6 +199,8 @@ 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.
 
+Domain UUIDs can be used instead of names.
+
 Using this flag is mostly equivalent to using the C<add-domain> command,
 with C<readonly:true> if the I<--ro> flag was given, and
 with C<format:...> if the I<--format:...> flag was given.
@@ -473,14 +475,14 @@ 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<le> 1.8, guestfish, guestmount and virt-rescue
+In libguestfs E<le> 1.10, guestfish, guestmount and virt-rescue
 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.10 we intend to change the default the other way.
+In a future libguestfs we intend to change the default the other way.
 Disk images will be opened read-only.  You will have to either specify
 I<guestfish --rw>, I<guestmount --rw>, I<virt-rescue --rw>, or change
 the configuration file C</etc/libguestfs-tools.conf> in order to get
@@ -516,6 +518,64 @@ must be escaped with a backslash.
  command "/bin/echo 'foo      bar'"
  command "/bin/echo \'foo\'"
 
+=head2 ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
+
+In double-quoted arguments (only) use backslash to insert special
+characters:
+
+=over 4
+
+=item C<\a>
+
+Alert (bell) character.
+
+=item C<\b>
+
+Backspace character.
+
+=item C<\f>
+
+Form feed character.
+
+=item C<\n>
+
+Newline character.
+
+=item C<\r>
+
+Carriage return character.
+
+=item C<\t>
+
+Horizontal tab character.
+
+=item C<\v>
+
+Vertical tab character.
+
+=item C<\">
+
+A literal double quote character.
+
+=item C<\ooo>
+
+A character with octal value I<ooo>.  There must be precisely 3 octal
+digits (unlike C).
+
+=item C<\xhh>
+
+A character with hex value I<hh>.  There must be precisely 2 hex
+digits.
+
+In the current implementation C<\000> and C<\x00> cannot be used
+in strings.
+
+=item C<\\>
+
+A literal backslash character.
+
+=back
+
 =head1 OPTIONAL ARGUMENTS
 
 Some commands take optional arguments.  These arguments appear in this
@@ -798,19 +858,24 @@ on each one.  Then you can close the mapper device:
 =head1 WINDOWS PATHS
 
 If a path is prefixed with C<win:> then you can use Windows-style
-paths (with some limitations).  The following commands are equivalent:
+drive letters and 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
+ file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
+
+The parameter is rewritten "behind the scenes" by looking up the
+position where the drive is mounted, prepending that to the path,
+changing all backslash characters to forward slash, then resolving the
+result using L</case-sensitive-path>.  For example if the E: drive
+was mounted on C</e> then the parameter might be rewritten like this:
 
-This syntax implicitly calls C<case-sensitive-path> (q.v.) so it also
-handles case insensitivity like Windows would.  This only works in
-argument positions that expect a path.
+ win:e:\foo\bar => /e/FOO/bar
+
+This only works in argument positions that expect a path.
 
 =head1 UPLOADING AND DOWNLOADING FILES
 
@@ -1016,6 +1081,21 @@ guestfish returns 0 if the commands completed without error, or
 The C<edit> command uses C<$EDITOR> as the editor.  If not
 set, it uses C<vi>.
 
+=item FEBOOTSTRAP_KERNEL
+
+=item FEBOOTSTRAP_MODULES
+
+These two environment variables allow the kernel that libguestfs uses
+in the appliance to be selected.  If C<$FEBOOTSTRAP_KERNEL> is not
+set, then the most recent host kernel is chosen.  For more information
+about kernel selection, see L<febootstrap-supermin-helper(8)>.  This
+feature is only available in febootstrap E<ge> 3.8.
+
+=item GUESTFISH_DISPLAY_IMAGE
+
+The C<display> command uses C<$GUESTFISH_DISPLAY_IMAGE> to
+display images.  If not set, it uses L<display(1)>.
+
 =item GUESTFISH_PID
 
 Used with the I<--remote> option to specify the remote guestfish
@@ -1134,9 +1214,9 @@ to make guestfish case sensitive.
 
 =item test2.img (etc)
 
-When using the C<-N> or C<--new> option, the prepared disk or
+When using the I<-N> or I<--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.
+directory.  The second use of I<-N> will use C<test2.img> and so on.
 Any existing file with the same name will be overwritten.
 
 =back
@@ -1162,7 +1242,9 @@ L<virt-tar(1)>,
 L<virt-tar-in(1)>,
 L<virt-tar-out(1)>,
 L<virt-win-reg(1)>,
-L<hexedit(1)>.
+L<display(1)>,
+L<hexedit(1)>,
+L<febootstrap-supermin-helper(8)>.
 
 =head1 AUTHORS