Libguestfs - Dec 2011 - Proposed changes for OpenStack

[These two patches are for discussion only]

Allow FUSE support to be used directly through the API.
This is the second commit.

In order to make this usable from guestfish, we have to
also bind the events API in guestfish.  This is the first
commit.

Rich.

From: "Richard W.M. Jones" <rjones at redhat.com>

Add 'event' and 'delete-event' commands so that event handlers
can be registered and deleted in guestfish.  The event handler
is a shell script snippet or host command.

Cc: P?draig Brady <P at draigBrady.com>
---
 generator/generator_actions.ml |   39 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 39 insertions(+), 0 deletions(-)

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index dae837b..7d7c7af 100644
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -6675,6 +6675,16 @@ them with the help of L</glob> like this:
 
  glob copy-out /home/* .");
 
+  ("delete_event", (RErr,[], []), -1, [], [],
+   "delete a previously registered event handler",
+   " delete-event name
+
+Delete the event handler which was previously registered as C<name>.
+If multiple event handlers were registered with the same name, they
+are all deleted.
+
+See also the guestfish C<event> command.");
+
   ("display", (RErr,[], []), -1, [], [],
    "display an image",
    " display filename
@@ -6706,6 +6716,35 @@ The editor is C<$EDITOR>.  However if you use the
alternate
 commands C<vi> or C<emacs> you will get those corresponding
 editors.");
 
+  ("event", (RErr,[], []), -1, [], [],
+   "register a handler for an event or events",
+   " event name eventset \"shell script ...\"
+
+Register a shell script fragment which is executed when an
+event is raised.  See L<guestfs(3)/guestfs_set_event_callback>
+for a discussion of the event API in libguestfs.
+
+The C<name> parameter is a name that you give to this event
+handler.  It can be any string (even the empty string) and is
+simply there so you can delete the handler using the guestfish
+C<delete-event> command.
+
+The C<eventset> parameter is a comma-separated list of one
+or more events.
+
+The third and final parameter is the shell script fragment
+(or any external command) that is executed when any of the
+events in the eventset occurs.  It is executed using
+C<$SHELL -c>, or if C<$SHELL> is not set then C</bin/sh -c>.
+
+The shell script fragment receives callback parameters as
+arguments C<$1>, C<$2> etc.  The actual event that was
+called is available in the environment variable C<$EVENT>.
+
+ event \"\" close \"echo closed\"
+ event messages appliance,library,trace \"echo $*\"
+ event \"\" progress \"echo progress: $3/$4\"");
+
   ("glob", (RErr,[], []), -1, [], [],
    "expand wildcards in command",
    " glob command args...
-- 
1.7.6

From: "Richard W.M. Jones" <rjones at redhat.com>

Add FUSE support directly to the API.  Instead of needing to
use the external 'guestmount' command, you can mount the
libguestfs filesystem space on a local mountpoint using an
API call from any language.

Cc: P?draig Brady <P at draigBrady.com>
---
 generator/generator_actions.ml |   45 ++++++++++++++++++++++++++++++++++++++++
 generator/generator_events.ml  |    3 ++
 2 files changed, 48 insertions(+), 0 deletions(-)

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index 7d7c7af..3d4e5ec 100644
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -1644,6 +1644,51 @@ This function must be called before
C<guestfs_launch>.");
    "\
 This returns the number of virtual CPUs assigned to the appliance.");
 
+  ("mount_local", (RErr, [String "localmountpoint"],
[String "options"]), -1, [],
+   [], (* tests in fuse subdirectory *)
+   "mount on the local filesystem",
+   "\
+This call exports the libguestfs-accessible filesystem to
+a local mountpoint (directory) called C<localmountpoint>.
+Ordinary reads and writes to files and directories under
+C<localmountpoint> are redirected through libguestfs.
+
+Internally this is currently implemented using FUSE, and
+so this requires that FUSE is available and usable.  This
+may require installing a kernel module and/or adding the
+current user to a special C<fuse> group.  See the documentation
+for your distro and L<http://fuse.sf.net> for further
+information.
+
+The C<guestfs_mount_local> call does not return until the
+filesystem is I<unmounted> by calling C<guestfs_umount_local>.
+The current thread is involved with the processing of
+filesystem requests.  To access the filesystem you need
+to use another thread or process.  B<Note> you must I<not>
+make concurrent libguestfs calls on the same handle from
+another thread, except for C<guestfs_umount_local>.
+
+The mountpoint is not immediately available, since there
+is certain setup required.  When the mountpoint becomes
+ready to use, the C<MOUNTED> callback is called in the
+current thread.  You can register a callback function
+using C<guestfs_set_event_callback>.
+
+To unmount the filesystem, call C<guestfs_umount_local>.
+This may be called from another thread, which is a special
+exception to ordinary libguestfs rules.  Two things happen
+when this is called: firstly the C<UNMOUNTED> callback is
+called, and secondly the current call returns.");
+
+  ("umount_local", (RErr, [], []), -1, [],
+   [], (* tests in fuse subdirectory *)
+   "unmount a locally mounted filesystem",
+   "\
+If libguestfs is exporting the filesystem on a local
+mountpoint, then this unmounts it.
+
+See C<guestfs_mount_local> for full documentation.");
+
 ]
 
 (* daemon_functions are any functions which cause some action
diff --git a/generator/generator_events.ml b/generator/generator_events.ml
index df74af3..ea26cd0 100644
--- a/generator/generator_events.ml
+++ b/generator/generator_events.ml
@@ -37,6 +37,9 @@ let events = [
   "trace";                              (* call trace messages *)
 
   "enter";                              (* enter a function *)
+
+  "mounted";                            (* local filesystem mounted
and ready *)
+  "unmounted";                          (* local filesystem unmounted
*)
 ]
 
 let events = mapi (fun i name -> name, 1 lsl i) events
-- 
1.7.6

On 12/14/2011 08:44 AM, Richard W.M. Jones wrote:
> [These two patches are for discussion only]
>
> Allow FUSE support to be used directly through the API.
> This is the second commit.
>
> In order to make this usable from guestfish, we have to
> also bind the events API in guestfish.  This is the first
> commit.
There's not really enough information here to evaluate the proposed 
changes. Can you give an example of what you're trying to do?

In general, though, this feels wrong for a couple of reasons. Firstly, a 
callback mechanism implemented with shell scripts is simply hideous. 
Imagine trying to use that from another language.

Secondly, mounting filesystems is not the business of the guestfs api, 
it's the business of FUSE. I have't actually checked the libfuse API, 
but this seems like a function which makes much more sense in that context.

Matt
-- 
Matthew Booth, RHCA, RHCSS
Red Hat Engineering, Virtualisation Team

GPG ID:  D33C3490
GPG FPR: 3733 612D 2D05 5458 8A8A 1600 3441 EA19 D33C 3490