fish: Document that remote run in cmd substitution context hangs.

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index a3af17f..5b641ea 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
 
 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>
 
 
 =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.
 
 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.
 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.


@@ -294,9 +296,14 @@ to try to read passphrases from the user by opening C</dev/tty>.
 Fork into the background and listen for remote commands.  See section
 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 
 Fork into the background and listen for remote commands.  See section
 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 

-=item B<-m dev[:mountpoint]>
+=item B<--live>
+
+Connect to a live virtual machine.
+(Experimental, see L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>).
+
+=item B<-m dev[:mountpoint[:options]]>

 
 

-=item B<--mount dev[:mountpoint]>
+=item B<--mount dev[:mountpoint[:options]]>

 
 Mount the named partition or logical volume on the given mountpoint.
 
 
 Mount the named partition or logical volume on the given mountpoint.
 


@@ -313,8 +320,17 @@ filesystems and LVs available (see L</list-partitions>,
 L</list-filesystems> and L</lvs> commands), or you can use the
 L<virt-filesystems(1)> program.
 
 L</list-filesystems> and L</lvs> commands), or you can use the
 L<virt-filesystems(1)> program.
 

-Using this flag is mostly equivalent to using the C<mount-options>
-command or the C<mount-ro> command if the I<--ro> flag was given.
+The third (and rarely used) part of the mount parameter is the list of
+mount options used to mount the underlying filesystem.  If this is not
+given, then the mount options are either the empty string or C<ro>
+(the latter if the I<--ro> flag is used).  By specifying the mount
+options, you override this default choice.  Probably the only time you
+would use this is to enable ACLs and/or extended attributes if the
+filesystem can support them:
+
+ -m /dev/sda1:/:acl,user_xattr
+
+Using this flag is equivalent to using the C<mount-options> command.

 
 =item B<-n>
 
 
 =item B<-n>
 


@@ -388,7 +404,9 @@ Display the guestfish / libguestfs version number and exit.
 
 =item B<--rw>
 
 
 =item B<--rw>
 

-This option does nothing at the moment.
+This changes the I<-a>, I<-d> and I<-m> options so that disks are
+added and mounts are done read-write.
+

 See L</OPENING DISKS FOR READ AND WRITE> below.
 
 =item B<-x>
 See L</OPENING DISKS FOR READ AND WRITE> below.
 
 =item B<-x>


@@ -452,27 +470,30 @@ asked for without doing this.
 
 =head1 OPENING DISKS FOR READ AND WRITE
 
 
 =head1 OPENING DISKS FOR READ AND WRITE
 

-The guestfish (and L<guestmount(1)>) 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.
+The guestfish, L<guestmount(1)> and L<virt-rescue(1)> 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<lt> 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>.
+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.
 
 
 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.  Disk
-images will be opened read-only.  You will have to either specify
-I<guestfish --rw> or change a configuration file in order to get write
-access for disk images specified by those other command line options.
+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
+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.
+This version of guestfish, guestmount and virt-rescue 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 you need
+write access, and prepare your scripts for the day when this option
+will be required for write access.

 
 B<Note:> This does I<not> affect commands like L</add> and L</mount>,
 or any other libguestfs program apart from guestfish and guestmount.
 
 B<Note:> This does I<not> affect commands like L</add> and L</mount>,
 or any other libguestfs program apart from guestfish and guestmount.


@@ -497,6 +518,64 @@ must be escaped with a backslash.
  command "/bin/echo 'foo      bar'"
  command "/bin/echo \'foo\'"
 
  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
 =head1 OPTIONAL ARGUMENTS
 
 Some commands take optional arguments.  These arguments appear in this


@@ -676,6 +755,32 @@ C<local/remote-data.tar.gz>.  (See C<tgz-out>).
 To change the local directory, use the C<lcd> command.  C<!cd> will
 have no effect, due to the way that subprocesses work in Unix.
 
 To change the local directory, use the C<lcd> command.  C<!cd> will
 have no effect, due to the way that subprocesses work in Unix.
 

+=head2 LOCAL COMMANDS WITH INLINE EXECUTION
+
+If a line starts with I<E<lt>!> then the shell command is executed (as
+for I<!>), but subsequently any output (stdout) of the shell command
+is parsed and executed as guestfish commands.
+
+Thus you can use shell script to construct arbitrary guestfish
+commands which are then parsed by guestfish.
+
+For example it is tedious to create a sequence of files
+(eg. C</foo.1> through C</foo.100>) using guestfish commands
+alone.  However this is simple if we use a shell script to
+create the guestfish commands for us:
+
+ <! for n in `seq 1 100`; do echo write /foo.$n $n; done
+
+or with names like C</foo.001>:
+
+ <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
+
+When using guestfish interactively it can be helpful to just run the
+shell script first (ie. remove the initial C<E<lt>> character so it is
+just an ordinary I<!> local command), see what guestfish commands it
+would run, and when you are happy with those prepend the C<E<lt>>
+character to run the guestfish commands for real.
+

 =head1 PIPES
 
 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
 =head1 PIPES
 
 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the


@@ -753,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
 =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 /WINDOWS/system32/config/system.LOG
 

- file win:/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

 
 

-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.
+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:
+
+ win:e:\foo\bar => /e/FOO/bar
+
+This only works in argument positions that expect a path.

 
 =head1 UPLOADING AND DOWNLOADING FILES
 
 
 =head1 UPLOADING AND DOWNLOADING FILES
 


@@ -863,6 +973,17 @@ user ID of the process, and C<$PID> is the process ID of the server.
 
 Guestfish client and server versions must match exactly.
 
 
 Guestfish client and server versions must match exactly.
 

+=head2 REMOTE CONTROL RUN COMMAND HANGING
+
+Using the C<run> (or C<launch>) command remotely in a command
+substitution context hangs, ie. don't do (note the backquotes):
+
+ a=`guestfish --remote run`
+
+Since the C<run> command produces no output on stdout, this is not
+useful anyway.  For further information see
+L<https://bugzilla.redhat.com/show_bug.cgi?id=592910>.
+

 =head1 PREPARED DISK IMAGES
 
 Use the I<-N type> or I<--new type> parameter to select one of a set
 =head1 PREPARED DISK IMAGES
 
 Use the I<-N type> or I<--new type> parameter to select one of a set


@@ -971,6 +1092,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>.
 
 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
 =item GUESTFISH_PID
 
 Used with the I<--remote> option to specify the remote guestfish


@@ -1026,12 +1162,13 @@ set, it uses C<more>.
 
 =item TMPDIR
 
 
 =item TMPDIR
 

-Location of temporary directory, defaults to C</tmp>.
+Location of temporary directory, defaults to C</tmp> except for the
+cached supermin appliance which defaults to C</var/tmp>.

 
 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
 
 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</tmp> is not large
+configure another directory to use in case C</var/tmp> is not large

 enough.
 
 =back
 enough.
 
 =back


@@ -1040,6 +1177,15 @@ enough.
 
 =over 4
 
 
 =over 4
 

+=item $HOME/.libguestfs-tools.rc
+
+=item /etc/libguestfs-tools.conf
+
+This configuration file controls the default read-only or read-write
+mode (I<--ro> or I<--rw>).
+
+See L</OPENING DISKS FOR READ AND WRITE>.
+

 =item $HOME/.guestfish
 
 If compiled with GNU readline support, then the command history
 =item $HOME/.guestfish
 
 If compiled with GNU readline support, then the command history


@@ -1079,9 +1225,9 @@ to make guestfish case sensitive.
 
 =item test2.img (etc)
 
 
 =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
 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
 Any existing file with the same name will be overwritten.
 
 =back


@@ -1091,6 +1237,8 @@ Any existing file with the same name will be overwritten.
 L<guestfs(3)>,
 L<http://libguestfs.org/>,
 L<virt-cat(1)>,
 L<guestfs(3)>,
 L<http://libguestfs.org/>,
 L<virt-cat(1)>,

+L<virt-copy-in(1)>,
+L<virt-copy-out(1)>,

 L<virt-df(1)>,
 L<virt-edit(1)>,
 L<virt-filesystems(1)>,
 L<virt-df(1)>,
 L<virt-edit(1)>,
 L<virt-filesystems(1)>,


@@ -1102,8 +1250,12 @@ L<virt-make-fs(1)>,
 L<virt-rescue(1)>,
 L<virt-resize(1)>,
 L<virt-tar(1)>,
 L<virt-rescue(1)>,
 L<virt-resize(1)>,
 L<virt-tar(1)>,

+L<virt-tar-in(1)>,
+L<virt-tar-out(1)>,

 L<virt-win-reg(1)>,
 L<virt-win-reg(1)>,

-L<hexedit(1)>.
+L<display(1)>,
+L<hexedit(1)>,
+L<febootstrap-supermin-helper(8)>.

 
 =head1 AUTHORS
 
 
 =head1 AUTHORS
 


@@ -1111,7 +1263,7 @@ Richard W.M. Jones (C<rjones at redhat dot com>)
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright (C) 2009-2010 Red Hat Inc.
+Copyright (C) 2009-2011 Red Hat Inc.

 L<http://libguestfs.org/>
 
 This program is free software; you can redistribute it and/or modify
 L<http://libguestfs.org/>
 
 This program is free software; you can redistribute it and/or modify