From: Eric Blake <eblake@redhat.com>
Date: Wed, 23 Mar 2011 20:50:29 +0000 (-0600)
Subject: docs: document recent hook additions
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=ef701fd8cb12d7db69271bf852b54f2d4c7a1055;p=libvirt.git

docs: document recent hook additions

* src/qemu/qemu_process.c (qemuProcessStart, qemuProcessStop): Fix
typos.
* docs/hooks.html.in: Document 'prepare' and 'release' hooks.
---

diff --git a/docs/hooks.html.in b/docs/hooks.html.in
index 3503f8c2ad..eec7a6aaa0 100644
--- a/docs/hooks.html.in
+++ b/docs/hooks.html.in
@@ -100,11 +100,26 @@
 
     <h5><a name="qemu">/etc/libvirt/hooks/qemu</a></h5>
     <ul>
-      <li>When a QEMU guest is started, the qemu hook script is called as:<br/>
-          <pre>/etc/libvirt/hooks/qemu guest_name start begin -</pre></li>
+      <li>Before a QEMU guest is started, the qemu hook script is
+        called in two locations; if either location fails, the guest
+        is not started.  The first location, <span class="since">since
+        0.9.0</span>, is before libvirt performs any resource
+        labeling, and the hook can allocate resources not managed by
+        libvirt such as DRBD or missing bridges.  This is called as:</br>
+        <pre>/etc/libvirt/hooks/qemu guest_name prepare begin -</pre>
+        The second location, available <span class="since">Since
+        0.8.0</span>, occurs after libvirt has finished labeling
+        all resources, but has not yet started the guest, called as:</br>
+        <pre>/etc/libvirt/hooks/qemu guest_name start begin -</pre></li>
       <li>When a QEMU guest is stopped, the qemu hook script is called
-          as:<br/>
-          <pre>/etc/libvirt/hooks/qemu guest_name stopped end -</pre></li>
+        in two locations, to match the startup.
+        First, <span class="since">since 0.8.0</span>, the hook is
+        called before libvirt restores any labels:</br>
+        <pre>/etc/libvirt/hooks/qemu guest_name stopped end -</pre>
+        Then, after libvirt has released all resources, the hook is
+        called again, <span class="since">since 0.9.0</span>, to allow
+        any additional resource cleanup:<br/>
+        <pre>/etc/libvirt/hooks/qemu guest_name release end -</pre></li>
     </ul>
 
     <h5><a name="lxc">/etc/libvirt/hooks/lxc</a></h5>
diff --git a/src/qemu/qemu_process.c b/src/qemu/qemu_process.c
index 76cceadc01..209c8cfb4d 100644
--- a/src/qemu/qemu_process.c
+++ b/src/qemu/qemu_process.c
@@ -1928,7 +1928,7 @@ int qemuProcessStart(virConnectPtr conn,
 
     vm->def->id = driver->nextvmid++;
 
-    /* Run a early hook to set-up missing devices */
+    /* Run an early hook to set-up missing devices */
     if (virHookPresent(VIR_HOOK_DRIVER_QEMU)) {
         char *xml = virDomainDefFormat(vm->def, 0);
         int hookret;
@@ -2436,7 +2436,7 @@ retry:
     VIR_FREE(priv->vcpupids);
     priv->nvcpupids = 0;
 
-    /* The "release" hook cleans up additional ressources */
+    /* The "release" hook cleans up additional resources */
     if (virHookPresent(VIR_HOOK_DRIVER_QEMU)) {
         char *xml = virDomainDefFormat(vm->def, 0);