list-applications: If software hive is missing, this is an error.

[libguestfs.git] / cat / virt-cat.pod

diff --git a/cat/virt-cat.pod b/cat/virt-cat.pod
index b203bbf..4ec9a0b 100755 (executable)
--- a/cat/virt-cat.pod
+++ b/cat/virt-cat.pod
@@ -27,7 +27,7 @@ directory (starting with '/').
 
 C<virt-cat> can be used to quickly view a file.  To edit a file, use
 C<virt-edit>.  For more complex cases you should look at the
-L<guestfish(1)> tool.
+L<guestfish(1)> tool (see L</USING GUESTFISH> below).
 
 =head1 EXAMPLES
 
@@ -101,7 +101,9 @@ echoing off so you cannot see what you are typing.  If you are not
 worried about Tempest attacks and there is no one else in the room you
 can specify this flag to see what you are typing.
 
-=item B<--format=raw|qcow2|..> | B<--format>
+=item B<--format=raw|qcow2|..>
+
+=item B<--format>
 
 The default for the I<-a> option is to auto-detect the format of the
 disk image.  Using this forces the disk format for I<-a> options which
@@ -110,19 +112,18 @@ switches back to auto-detection for subsequent I<-a> options.
 
 For example:
 
- virt-cat --format=raw -a disk.img
+ virt-cat --format=raw -a disk.img file
 
 forces raw format (no auto-detection) for C<disk.img>.
 
- virt-cat --format=raw -a disk.img --format -a another.img
+ virt-cat --format=raw -a disk.img --format -a another.img file
 
 forces raw format (no auto-detection) for C<disk.img> and reverts to
 auto-detection for C<another.img>.
 
 If you have untrusted raw-format guest disk images, you should use
 this option to specify the disk format.  This avoids a possible
-security problem with malicious guests (CVE-2010-3851).  See also
-L</add-drive-opts>.
+security problem with malicious guests (CVE-2010-3851).
 
 =item B<--keys-from-stdin>
 
@@ -163,6 +164,30 @@ name as a guest.
 
 For compatibility the old style is still supported.
 
+=head1 USING GUESTFISH
+
+L<guestfish(1)> is a more powerful, lower level tool which you can use
+when C<virt-cat> doesn't work.
+
+Using C<virt-cat> is approximately equivalent to doing:
+
+ guestfish --ro -i -d domname download file -
+
+where C<domname> is the name of the libvirt guest, and C<file> is the
+full path to the file.  Note the final C<-> (meaning "output to
+stdout").
+
+The command above uses libguestfs's guest inspection feature and so
+does not work on guests that libguestfs cannot inspect, or on things
+like arbitrary disk images that don't contain guests.  To display a
+file from a disk image directly, use:
+
+ guestfish --ro -a disk.img -m /dev/sda1 download file -
+
+where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
+within the disk image to edit, and C<file> is the full path to the
+file.
+
 =head1 SHELL QUOTING
 
 Libvirt guest names can contain arbitrary characters, some of which
@@ -174,7 +199,9 @@ manual page L<sh(1)> for details.
 
 L<guestfs(3)>,
 L<guestfish(1)>,
+L<virt-copy-out(1)>,
 L<virt-edit(1)>,
+L<virt-tar-out(1)>,
 L<http://libguestfs.org/>.
 
 =head1 AUTHOR
@@ -183,7 +210,7 @@ Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 
 =head1 COPYRIGHT
 
-Copyright (C) 2010 Red Hat Inc.
+Copyright (C) 2010-2011 Red Hat Inc.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by