diff options
| -rw-r--r-- | generator/generator_actions.ml | 9 | ||||
| -rw-r--r-- | src/guestfs.pod | 57 | ||||
| -rw-r--r-- | src/virt.c | 3 |
3 files changed, 65 insertions, 4 deletions
diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml index 192df77f..ca2dfe30 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 cfd58c97..0b3b6544 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, @@ -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; } |