10:16 a.m.
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
+ 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>
+ <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).
+ 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>
+ <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:
+ <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
+ 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
+ but at the time of 0.8.0 only those 2 are associated to domains
+ lifecycle</p>
+ </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>
--
Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
daniel(a)veillard.com | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library http://libvirt.org/
10:26 a.m.
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
10:34 a.m.
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(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
11:04 a.m.
On Mon, Apr 12, 2010 at 09:34:59AM -0600, Eric Blake wrote:
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.
Whoops thanks for both of you, I merged the improvements, fixes and
pushed !
Daniel
--
Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
daniel(a)veillard.com | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library http://libvirt.org/
5337
days inactive
5337
days old
3 comments
3 participants
participants (3)
-
Chris Lalancette -
Daniel Veillard -
Eric Blake