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

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

diff --git a/rescue/virt-rescue.pod b/rescue/virt-rescue.pod
index df4fb30..81a24cf 100755 (executable)
--- a/rescue/virt-rescue.pod
+++ b/rescue/virt-rescue.pod
@@ -73,6 +73,9 @@ want to partition that file (although we would recommend using
 L<guestfish(1)> instead as it is more suitable for this purpose).  You
 can even use virt-rescue on things like SD cards.
 
+Virt-rescue does not require root.  You only need to run it as root if
+you need root to open the disk image.
+
 This tool is just designed for quick interactive hacking on a virtual
 machine.  For more structured access to a virtual machine disk image,
 you should use L<guestfs(3)>.  To get a structured shell that you can
@@ -115,7 +118,8 @@ not used at all.
 
 =item B<--domain> guest
 
-Add all the disks from the named libvirt guest.
+Add all the disks from the named libvirt guest.  Domain UUIDs can be
+used instead of names.
 
 =item B<--format=raw|qcow2|..>
 
@@ -152,7 +156,7 @@ parameter is specified in megabytes.
 
 =item B<--network>
 
-Enable QEMU user networking in the guest.
+Enable QEMU user networking in the guest.  See L</NETWORK>.
 
 =item B<-r>
 
@@ -164,6 +168,8 @@ The option must always be used if the disk image or virtual machine
 might be running, and is generally recommended in cases where you
 don't need write access to the disk.
 
+See also L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
+
 =item B<--selinux>
 
 Enable SELinux in the rescue appliance.  You should read
@@ -181,6 +187,15 @@ Enable verbose messages for debugging.
 
 Display version number and exit.
 
+=item B<-w>
+
+=item B<--rw>
+
+This changes the I<-a> and I<-d> options so that disks are
+added and mounts are done read-write.
+
+See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
+
 =item B<-x>
 
 Enable tracing of libguestfs API calls.
@@ -203,6 +218,42 @@ name as a guest.
 
 For compatibility the old style is still supported.
 
+=head1 NETWORK
+
+Adding the I<--network> option enables QEMU user networking
+in the rescue appliance.  There are some differences between
+user networking and ordinary networking:
+
+=over 4
+
+=item ping does not work
+
+Because the ICMP ECHO_REQUEST protocol generally requires root in
+order to send the ping packets, and because virt-rescue must be able
+to run as non-root, QEMU user networking is not able to emulate the
+L<ping(8)> command.  The ping command will appear to resolve addresses
+but will not be able to send or receive any packets.  This does not
+mean that the network is not working.
+
+=item cannot receive connections
+
+QEMU user networking cannot receive incoming connections.
+
+=item making TCP connections
+
+The virt-rescue appliance needs to be small and so does not include
+many network tools.  In particular there is no L<telnet(1)> command.
+You can make TCP connections from the shell using the magical
+C</dev/tcp/E<lt>hostnameE<gt>/E<lt>portE<gt>> syntax:
+
+ exec 3<>/dev/tcp/redhat.com/80
+ echo "GET /" >&3
+ cat <&3
+
+See L<bash(1)> for more details.
+
+=back
+
 =head1 ENVIRONMENT VARIABLES
 
 Several environment variables affect virt-rescue.  See
@@ -215,6 +266,21 @@ have meaning to the shell such as C<#> and space.  You may need to
 quote or escape these characters on the command line.  See the shell
 manual page L<sh(1)> for details.
 
+=head1 FILES
+
+=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<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
+
+=back
+
 =head1 SEE ALSO
 
 L<guestfs(3)>,
@@ -229,7 +295,7 @@ Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 
 =head1 COPYRIGHT
 
-Copyright (C) 2009-2010 Red Hat Inc.
+Copyright (C) 2009-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