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.
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
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
Guestfish client and server versions must match exactly.
+=head2 USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
+
+From Bash, you can use the following code which creates a guestfish
+instance, correctly quotes the command line, handles failure to start,
+and cleans up guestfish when the script exits:
+
+ #!/bin/bash -
+
+ set -e
+
+ guestfish[0]="guestfish"
+ guestfish[1]="--listen"
+ guestfish[2]="--ro"
+ guestfish[3]="-a"
+ guestfish[4]="disk.img"
+
+ GUESTFISH_PID=
+ eval $("${guestfish[@]}")
+ if [ -z "$GUESTFISH_PID" ]; then
+ echo "error: guestfish didn't start up, see error messages above"
+ exit 1
+ fi
+
+ cleanup_guestfish ()
+ {
+ guestfish --remote -- exit >/dev/null 2>&1 ||:
+ }
+ trap cleanup_guestfish EXIT ERR
+
+ guestfish --remote -- run
+
+ # ...
+
+=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
@ACTIONS@
-=head1 EXIT CODE
+=head1 EXIT STATUS
guestfish returns 0 if the commands completed without error, or
1 if there was an error.
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 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
L<guestfs(3)>,
L<http://libguestfs.org/>,
+L<virt-alignment-scan(1)>,
L<virt-cat(1)>,
L<virt-copy-in(1)>,
L<virt-copy-out(1)>,
L<virt-make-fs(1)>,
L<virt-rescue(1)>,
L<virt-resize(1)>,
+L<virt-sparsify(1)>,
+L<virt-sysprep(1)>,
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