fish: Allow -d UUID (specify libvirt domains by UUID).

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 98286d1..77bf0ca 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.


@@ -402,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>


@@ -466,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.
+By libguestfs 1.12 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.


@@ -793,19 +800,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
+
+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
 
 
 =head1 UPLOADING AND DOWNLOADING FILES
 


@@ -1081,6 +1093,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


@@ -1120,9 +1141,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


@@ -1156,7 +1177,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