On 04/12/2010 11:16 AM, Daniel Veillard wrote:
Was still missing from main commits and would be needed for 0.8.0
Add documentation for synchronous hooks
* docs/sitemap.html.in: add in navigation under Documentation/Deployment/Hooks * docs/hooks.html.in: new doc describing current support for 0.8.0
diff --git a/docs/hooks.html.in b/docs/hooks.html.in new file mode 100644 index 0000000..4ebeec3 --- /dev/null +++ b/docs/hooks.html.in @@ -0,0 +1,71 @@ +<?xml version="1.0"?> +<html> + <body> + <h1>Hooks for specific system management</h1> + <p>Libvirt includes synchronous hooks starting from version 0.8.0, + this is a way to tie specific tailored system actions at specific ^^^^ which
+ time. This is based on scripts being called on the Host where the + hypervisor is running, if the script is present when the libvirtd + daemon is doing some significant actions.</p>
This last sentence is probably better worded as something like: "If these scripts are present on the host where the hypervisor is running, then they are called when the libvirt daemon is doing some significant action."
+ <p>The scripts are expected to execute quickly, return a zero exit + status if all conditions are set for the daemon to continue the + action (non zero will be considered a failure which may + be ignored but in general will stops the ongoing operation). ^^^^^ stop
+ The script also should not call back into libvirt as the daemon + is waiting for the script exit and deadlock is likely to occur + otherwise.</p> ^^^^^^^^^ s/otherwise//
+ <p>The scripts are stored in the directory <code>/etc/libvirt/hooks/</code> + when using a standard installation path + (<code>$SYSCONF_DIR/libvirt/hook/</code> in general).</p> + <p>The scripts gets arguments as parameter on their command line:</p> + <ul> + <li> the first argument is the name of the object involved in the + operation or '-' if there is none. + <li> the second argument is the name of the operation. + <li> the third argument is a suboperation indication like 'start' + 'end' or '-' if there is none. + <li> the last argument is an extra argument string or '-' if there + is none. + </ul> + <p>There is currently scripts for 3 domains of operation: ^^ are
+ <ul> + <li><p><code>/etc/libvirt/hooks/daemon</code> script if + present is called at 3 points in time:</p> + <p>at daemon startup, typically started with the following + arguments:</p> + <pre>/etc/libvirt/hooks/daemon - start - start</pre> + <p>at daemon shutdown when it is about to exit, with the following + arguments:</p> + <pre>/etc/libvirt/hooks/daemon - shutdown - shutdown</pre> + <p>When the daemon is asked to reload its driver state when + receiving the SIGHUP signal, arguments are:</p> + <pre>/etc/libvirt/hooks/daemon - reload begin SIGHUP</pre> + </li> + <li><p><code>/etc/libvirt/hooks/qemu</code> script and <br/> + <code>/etc/libvirt/hooks/lxc</code> to associate hooks for domain ^^ s/to//
+ operation on the respective QEmu/KVM and LXC drivers.</p> + <p> The domain related hooks also receive the full XML description + for the concerned domain on their stdin, which allows to get ^ them
+ all the informations from the domain, including UUID or storage ^^^^^^^^^^^^ information
+ if that is needed for the script operation.</p> + <p> Currently only domain startup and domain end operations + involve the hook, the first one just before the domain gets + created. + For example if starting a QEmu domain named <code>test</code> + the following script will get called:</p> + <pre>/etc/libvirt/hooks/qemu test start begin -</pre> + <p> note that a non-zero return value from the script will abort the + domain startup operation, and if an error string is passed on + stderr by the hook script, it will be provided back to the user + at the libvirt API level.</p> + <p> For domain shutdown, the script will be called just after the + domain has finished execution, and the script will get:</p> + <pre>/etc/libvirt/hooks/qemu test stopped end -</pre> + <p> It is expected that other operation will be associated to hooks ^^^^^^^^^ operations
-- Chris Lalancette