[libvirt] Documentation for synchronous hooks

Eric Blake eblake at redhat.com
Mon Apr 12 15:34:59 UTC 2010


On 04/12/2010 09: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

Some nits to fix before pushing, but ACK on getting the documentation
written.

> +    <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
> +       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>

Grammar improvement on the first sentence:

Libvirt includes synchronous hooks, starting from version 0.8.0, as a
way to tie in specific tailored system actions at a specific time.

> +    <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).

s/stops/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>
> +    <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>

hook or hooks?  One of those two <code> is wrong; I'm assuming hooks
based on the rest of the patch (and to prove I'm not too lazy, I also
validated that LIBVIRT_HOOK_DIR is indeed hooks).

> +    <p>The scripts gets arguments as parameter on their command line:</p>

I'd word this:

Each script is given the following command line arguments:

> +       <ul>
> +         <li> the first argument is the name of the object involved in the
> +              operation or '-' if there is none.

s/ or/, or/

> +         <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.

s/like 'start' 'end' or '-'/like 'start' or 'end', or '-'/

> +         <li> the last argument is an extra argument string or '-' if there
> +              is none.

s/ or/, or/

> +       </ul>
> +    <p>There is currently scripts for 3 domains of operation:

s/is/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
> +             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
> +              all the informations from the domain, including UUID or storage

s/informations/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

s/operation/operations/

> +              but at the time of 0.8.0 only those 2 are associated to domains
> +              lifecycle</p>

s/to domains lifesycle/to the domain life cycle/

> +          </li>
> +    </ul>
> +    <p></p>
> +  </body>
> +</html>
> diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in
> index 0c3f0c3..0117c8d 100644
> --- a/docs/sitemap.html.in
> +++ b/docs/sitemap.html.in
> @@ -50,6 +50,10 @@
>                  <a href="logging.html">Logging</a>
>                  <span>The library and the daemon logging support</span>
>                </li>
> +              <li>
> +                <a href="hooks.html">Hooks</a>
> +                <span>Hooks for system specific management</span>
> +              </li>
>              </ul>
>            </li>
>            <li>
> 

-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 323 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20100412/bd30670d/attachment-0001.sig>


More information about the libvir-list mailing list