From 2020eded8a3f381c722abe001be8000723ff2418 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Thu, 27 Jan 2011 22:45:50 +0000
Subject: [PATCH] Add documentation for attach method.

---
 generator/generator_actions.ml |  9 ++++---
 src/guestfs.pod                | 57 ++++++++++++++++++++++++++++++++++++++++++
 src/virt.c                     |  3 ++-
 3 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index 192df77..ca2dfe3 100644
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -1105,7 +1105,8 @@ The optional C<live> flag controls whether this call will try
 to connect to a running virtual machine C<guestfsd> process if
 it sees a suitable E<lt>channelE<gt> element in the libvirt
 XML definition.  The default (if the flag is omitted) is never
-to try.
+to try.  See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
+information.
 
 The other optional parameters are passed directly through to
 C<guestfs_add_drive_opts>.");
@@ -1139,7 +1140,8 @@ The optional C<live> flag controls whether this call will try
 to connect to a running virtual machine C<guestfsd> process if
 it sees a suitable E<lt>channelE<gt> element in the libvirt
 XML definition.  The default (if the flag is omitted) is never
-to try.
+to try.  See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
+information.
 
 The other optional parameters are passed directly through to
 C<guestfs_add_drive_opts>.");
@@ -1399,7 +1401,8 @@ and the default.
 Connect to the Unix domain socket I<path>.
 
 This method lets you connect to an existing daemon or (using
-virtio-serial) to a live guest.
+virtio-serial) to a live guest.  For more information, see
+L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>.
 
 =back");
 
diff --git a/src/guestfs.pod b/src/guestfs.pod
index cfd58c9..0b3b654 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -972,6 +972,63 @@ For example:
 Note that libguestfs also calls qemu with the -help and -version
 options in order to determine features.
 
+=head2 ATTACHING TO RUNNING DAEMONS
+
+I<Note (1):> This is B<highly experimental> and has a tendency to eat
+babies.  Use with caution.
+
+I<Note (2):> This section explains how to attach to a running daemon
+from a low level perspective.  For most users, simply using virt tools
+such as L<guestfish(1)> with the I<--live> option will "just work".
+
+=head3 Using guestfs_set_attach_method
+
+By calling L</guestfs_set_attach_method> you can change how the
+library connects to the C<guestfsd> daemon in L</guestfs_launch>
+(read L</ARCHITECTURE> for some background).
+
+The normal attach method is C<appliance>, where a small appliance is
+created containing the daemon, and then the library connects to this.
+
+Setting attach method to C<unix:I<path>> (where I<path> is the path of
+a Unix domain socket) causes L</guestfs_launch> to connect to an
+existing daemon over the Unix domain socket.
+
+The normal use for this is to connect to a running virtual machine
+that contains a C<guestfsd> daemon, and send commands so you can read
+and write files inside the live virtual machine.
+
+=head3 Using guestfs_add_domain with live flag
+
+L</guestfs_add_domain> provides some help for getting the
+correct attach method.  If you pass the C<live> option to this
+function, then (if the virtual machine is running) it will
+examine the libvirt XML looking for a virtio-serial channel
+to connect to:
+
+ <domain>
+   ...
+   <devices>
+     ...
+     <channel type='unix'>
+       <source mode='bind' path='/path/to/socket'/>
+       <target type='virtio' name='org.libguestfs.channel.0'/>
+     </channel>
+     ...
+   </devices>
+ </domain>
+
+L</guestfs_add_domain> extracts C</path/to/socket> and sets the attach
+method to C<unix:/path/to/socket>.
+
+Some of the libguestfs tools (including guestfish) support a I<--live>
+option which is passed through to L</guestfs_add_domain> thus allowing
+you to attach to and modify live virtual machines.
+
+The virtual machine needs to have been set up beforehand so that it
+has the virtio-serial channel and so that guestfsd is running inside
+it.
+
 =head2 ABI GUARANTEE
 
 We guarantee the libguestfs ABI (binary interface), for public,
diff --git a/src/virt.c b/src/virt.c
index 4b66cc8..a23ac0a 100644
--- a/src/virt.c
+++ b/src/virt.c
@@ -467,7 +467,8 @@ connect_live (guestfs_h *g, virDomainPtr dom)
   }
 
   if (path == NULL) {
-    error (g, _("this guest has no libvirt <channel> definition for guestfsd"));
+    error (g, _("this guest has no libvirt <channel> definition for guestfsd\n"
+                "See ATTACHING TO RUNNING DAEMONS in guestfs(3) for further information."));
     goto cleanup;
   }
 
-- 
1.8.3.1