7:10 a.m.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/hooks.html.in | 406 -----------------------------------
docs/hooks.rst | 518 +++++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 519 insertions(+), 407 deletions(-)
delete mode 100644 docs/hooks.html.in
create mode 100644 docs/hooks.rst
diff --git a/docs/hooks.html.in b/docs/hooks.html.in
deleted file mode 100644
index bbbc414dc4..0000000000
--- a/docs/hooks.html.in
+++ /dev/null
@@ -1,406 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Hooks for specific system management</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="intro">Custom event scripts</a></h2>
- <p>Beginning with libvirt 0.8.0, specific events on a host system will
- trigger custom scripts.</p>
- <p>These custom <b>hook</b> scripts are executed when any of the
following
- actions occur:</p>
- <ul>
- <li>The libvirt daemon starts, stops, or reloads its
- configuration
- (<span class="since">since
0.8.0</span>)<br/><br/></li>
- <li>A QEMU guest is started or stopped
- (<span class="since">since
0.8.0</span>)<br/><br/></li>
- <li>An LXC guest is started or stopped
- (<span class="since">since
0.8.0</span>)<br/><br/></li>
- <li>A libxl-handled Xen guest is started or stopped
- (<span class="since">since
2.1.0</span>)<br/><br/></li>
- <li>A network is started or stopped or an interface is
- plugged/unplugged to/from the network
- (<span class="since">since
1.2.2</span>)<br/><br/></li>
- </ul>
-
- <h2><a id="location">Script location</a></h2>
- <p>The libvirt hook scripts are located in the directory
- <code>$SYSCONFDIR/libvirt/hooks/</code>.</p>
- <ul>
- <li>In Linux distributions such as Fedora and RHEL, this is
- <code>/etc/libvirt/hooks/</code>. Other Linux distributions may
do
- this differently.</li>
- <li>If your installation of libvirt has instead been compiled from
- source, it is likely to be
- <code>/usr/local/etc/libvirt/hooks/</code>.</li>
- <li><span class="since">Since 6.5.0</span>, you can
also place several
- hook scripts in the directories
-
<code>/etc/libvirt/hooks/<driver>.d/</code>.</li>
- </ul>
- <p>To use hook scripts, you will need to create this
<code>hooks</code>
- directory manually, place the desired hook scripts inside, then make
- them executable.</p>
- <br/>
-
- <h2><a id="names">Script names</a></h2>
- <p>At present, there are five hook scripts that can be called:</p>
- <ul>
- <li><code>/etc/libvirt/hooks/daemon</code><br/><br/>
- Executed when the libvirt daemon is started, stopped, or reloads
- its configuration<br/><br/></li>
- <li><code>/etc/libvirt/hooks/qemu</code><br/><br/>
- Executed when a QEMU guest is started, stopped, or
migrated<br/><br/></li>
- <li><code>/etc/libvirt/hooks/lxc</code><br /><br/>
- Executed when an LXC guest is started or stopped</li>
- <li><code>/etc/libvirt/hooks/libxl</code><br/><br/>
- Executed when a libxl-handled Xen guest is started, stopped, or
- migrated<br/><br/></li>
-
<li><code>/etc/libvirt/hooks/network</code><br/><br/>
- Executed when a network is started or stopped or an
- interface is plugged/unplugged to/from the network</li>
- </ul>
- <p><span class="since">Since 6.5.0</span>, you can also
have
- several scripts with any name in the directories
- <code>/etc/libvirt/hooks/<driver>.d/</code>. They are
- executed in alphabetical order after main script.</p>
- <br/>
-
- <h2><a id="structure">Script structure</a></h2>
- <p>The hook scripts are executed using standard Linux process creation
- functions. Therefore, they must begin with the declaration of the
- command interpreter to use.</p>
- <p>For example:</p>
- <pre>#!/bin/bash</pre>
- <p>or:</p>
- <pre>#!/usr/bin/python</pre>
- <p>Other command interpreters are equally valid, as is any executable
- binary, so you are welcome to use your favourite languages.</p>
- <br/>
-
- <h2><a id="arguments">Script arguments</a></h2>
- <p>The hook scripts are called with specific command line arguments,
- depending upon the script, and the operation being performed.</p>
- <p>The guest hook scripts, qemu and lxc, are also given the
<b>full</b>
- XML description for the domain on their stdin. This includes items
- such the UUID of the domain and its storage information, and is
- intended to provide all the libvirt information the script needs.</p>
- <p>For all cases, stdin of the network hook script is provided with the
- full XML description of the network status in the following form:</p>
-
-<pre><hookData>
- <network>
- <name>$network_name</name>
- <uuid>afca425a-2c3a-420c-b2fb-dd7b4950d722</uuid>
- ...
- </network>
-</hookData></pre>
-
- <p>In the case of an network port being created / deleted, the network
- XML will be followed with the full XML description of the port:</p>
-
-<pre><hookData>
- <network>
- <name>$network_name</name>
- <uuid>afca425a-2c3a-420c-b2fb-dd7b4950d722</uuid>
- ...
- </network>
- <networkport>
- <uuid>5d744f21-ba4a-4d6e-bdb2-30a35ff3207d</uuid>
- ...
- <plug type='direct' dev='ens3' mode='vepa'/>
- </networkport>
-</hookData></pre>
-
- <p>Please note that this approach is different from other cases such as
- <code>daemon</code>, <code>qemu</code> or
<code>lxc</code> hook scripts,
- because two XMLs may be passed here, while in the other cases only a single
- XML is passed.</p>
-
- <p>The command line arguments take this approach:</p>
- <ol>
- <li>The first argument is the name of the <b>object</b> involved
in the
- operation, or '-' if there is none.<br/><br/>
- For example, the name of a guest being
started.<br/><br/></li>
- <li>The second argument is the name of the <b>operation</b>
being
- performed.<br/><br/>
- For example, "start" if a guest is being
started.<br/><br/></li>
- <li>The third argument is a <b>sub-operation</b> indication, or
'-' if there
- is none.<br/><br/></li>
- <li>The last argument is an <b>extra argument</b> string, or
'-' if there is
- none.</li>
- </ol>
-
- <h4><a id="arguments_specifics">Specifics</a></h4>
- <p>This translates to the following specifics for each hook script:</p>
-
- <h5><a
id="daemon">/etc/libvirt/hooks/daemon</a></h5>
- <ul>
- <li>When the libvirt daemon is started, this script is called as:<br/>
- <pre>/etc/libvirt/hooks/daemon - start - start</pre></li>
- <li>When the libvirt daemon is shut down, this script is called
as:<br/>
- <pre>/etc/libvirt/hooks/daemon - shutdown -
shutdown</pre></li>
- <li>When the libvirt daemon receives the SIGHUP signal, it reloads its
- configuration and triggers the hook script as:<br/>
- <pre>/etc/libvirt/hooks/daemon - reload begin
SIGHUP</pre></li>
- </ul>
- <p>Please note that when the libvirt daemon is restarted, the
<i>daemon</i>
- hook script is called once with the "shutdown" operation, and then once
- with the "start" operation. There is no specific operation to indicate
- a "restart" is occurring.</p>
-
- <h5><a id="qemu">/etc/libvirt/hooks/qemu</a></h5>
- <ul>
- <li>Before a QEMU guest is started, the qemu hook script is
- called in three locations; if any 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>
- The third location, <span class="since">0.9.13</span>,
- occurs after the QEMU process has successfully started up:<br/>
- <pre>/etc/libvirt/hooks/qemu guest_name started begin -</pre>
- </li>
- <li>When a QEMU guest is stopped, the qemu hook script is called
- 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>
- <li><span class="since">Since 0.9.11</span>, the qemu
hook script
- is also called at the beginning of incoming migration. It is called
- as: <pre>/etc/libvirt/hooks/qemu guest_name migrate begin -</pre>
- with domain XML sent to standard input of the script. In this case,
- the script acts as a filter and is supposed to modify the domain
- XML and print it out on its standard output. Empty output is
- identical to copying the input XML without changing it. In case the
- script returns failure or the output XML is not valid, incoming
- migration will be canceled. This hook may be used, e.g., to change
- location of disk images for incoming domains.</li>
- <li><span class="since">Since 1.2.9</span>, the qemu
hook script is
- also called when restoring a saved image either via the API or
- automatically when restoring a managed save machine. It is called
- as: <pre>/etc/libvirt/hooks/qemu guest_name restore begin -</pre>
- with domain XML sent to standard input of the script. In this case,
- the script acts as a filter and is supposed to modify the domain
- XML and print it out on its standard output. Empty output is
- identical to copying the input XML without changing it. In case the
- script returns failure or the output XML is not valid, restore of the
- image will be aborted. This hook may be used, e.g., to change
- location of disk images for restored domains.</li>
- <li><span class="since">Since 6.5.0</span>, you can
also place several
- hook scripts in the directory
- <code>/etc/libvirt/hooks/qemu.d/</code>. They are executed in
- alphabetical order after main script. In this case each script also
- acts as filter and can modify the domain XML and print it out on
- its standard output. This script output is passed to standard input
- next script in order. Empty output from any script is also identical
- to copying the input XML without changing it.
- In case any script returns failure common process will be aborted,
- but all scripts from the directory will are executed.</li>
- <li><span class="since">Since 0.9.13</span>, the qemu
hook script
- is also called when the libvirtd daemon restarts and reconnects
- to previously running QEMU processes. If the script fails, the
- existing QEMU process will be killed off. It is called as:
- <pre>/etc/libvirt/hooks/qemu guest_name reconnect begin -</pre>
- </li>
- <li><span class="since">Since 0.9.13</span>, the qemu
hook script
- is also called when the QEMU driver is told to attach to an
- externally launched QEMU process. It is called as:
- <pre>/etc/libvirt/hooks/qemu guest_name attach begin -</pre>
- </li>
- </ul>
-
- <h5><a id="lxc">/etc/libvirt/hooks/lxc</a></h5>
- <ul>
- <li>Before a LXC guest is started, the lxc hook script is
- called in three locations; if any location fails, the guest
- is not started. The first location, <span class="since">since
- 0.9.13</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/lxc 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/lxc guest_name start begin -</pre>
- The third location, <span class="since">0.9.13</span>,
- occurs after the LXC process has successfully started up:<br/>
- <pre>/etc/libvirt/hooks/lxc guest_name started begin -</pre>
- </li>
- <li>When a LXC guest is stopped, the lxc hook script is called
- 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/lxc 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/lxc guest_name release end
-</pre></li>
- <li><span class="since">Since 0.9.13</span>, the lxc
hook script
- is also called when the libvirtd daemon restarts and reconnects
- to previously running LXC processes. If the script fails, the
- existing LXC process will be killed off. It is called as:
- <pre>/etc/libvirt/hooks/lxc guest_name reconnect begin -</pre>
- </li>
- </ul>
-
- <h5><a
id="libxl">/etc/libvirt/hooks/libxl</a></h5>
- <ul>
- <li>Before a Xen guest is started using libxl driver, the libxl hook
- script is called in three locations; if any location fails, the guest
- is not started. The first location, <span class="since">since
- 2.1.0</span>, is before libvirt performs any resource
- labeling, and the hook can allocate resources not managed by
- libvirt. This is called as:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name prepare begin -</pre>
- The second location, available <span class="since">Since
- 2.1.0</span>, occurs after libvirt has finished labeling
- all resources, but has not yet started the guest, called as:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name start begin -</pre>
- The third location, <span class="since">2.1.0</span>,
- occurs after the domain has successfully started up:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name started begin -</pre>
- </li>
- <li>When a libxl-handled Xen guest is stopped, the libxl hook script
- is called in two locations, to match the startup.
- First, <span class="since">since 2.1.0</span>, the hook is
- called before libvirt restores any labels:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name stopped end -</pre>
- Then, after libvirt has released all resources, the hook is
- called again, <span class="since">since 2.1.0</span>, to
allow
- any additional resource cleanup:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name release end
-</pre></li>
- <li><span class="since">Since 2.1.0</span>, the libxl
hook script
- is also called at the beginning of incoming migration. It is called
- as: <pre>/etc/libvirt/hooks/libxl guest_name migrate begin -</pre>
- with domain XML sent to standard input of the script. In this case,
- the script acts as a filter and is supposed to modify the domain
- XML and print it out on its standard output. Empty output is
- identical to copying the input XML without changing it. In case the
- script returns failure or the output XML is not valid, incoming
- migration will be canceled. This hook may be used, e.g., to change
- location of disk images for incoming domains.</li>
- <li><span class="since">Since 6.5.0</span>, you can
also place several
- hook scripts in the directory
- <code>/etc/libvirt/hooks/libxl.d/</code>. They are executed in
- alphabetical order after main script. In this case each script also
- acts as filter and can modify the domain XML and print it out on
- its standard output. This script output is passed to standard input
- next script in order. Empty output from any script is also identical
- to copying the input XML without changing it.
- In case any script returns failure common process will be aborted,
- but all scripts from the directory will are executed.</li>
- <li><span class="since">Since 2.1.0</span>, the libxl
hook script
- is also called when the libvirtd daemon restarts and reconnects
- to previously running Xen domains. If the script fails, the
- existing Xen domains will be killed off. It is called as:
- <pre>/etc/libvirt/hooks/libxl guest_name reconnect begin -</pre>
- </li>
- </ul>
-
- <h5><a
id="network">/etc/libvirt/hooks/network</a></h5>
- <ul>
- <li><span class="since">Since 1.2.2</span>, before a
network is started,
- this script is called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name start begin
-</pre></li>
- <li>After the network is started, up & running, the script is
- called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name started begin
-</pre></li>
- <li>When a network is shut down, this script is called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name stopped end
-</pre></li>
- <li>Later, when network is started and there's an interface from a
- domain to be plugged into the network, the hook script is called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name port-created begin
-</pre>
- Please note, that in this case, the script is passed both network and
- port XMLs on its stdin.</li>
- <li>When network is updated, the hook script is called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name updated begin
-</pre></li>
- <li>When the domain from previous case is shutting down, the interface
- is unplugged. This leads to another script invocation:<br/>
- <pre>/etc/libvirt/hooks/network network_name port-deleted begin
-</pre>
- And again, as in previous case, both network and port XMLs are passed
- onto script's stdin.</li>
- </ul>
-
- <br/>
-
- <h2><a id="execution">Script execution</a></h2>
- <ul>
- <li>The "start" operation for the guest and network hook scripts,
- executes <b>prior</b> to the object (guest or network) being
created.
- This allows the object start operation to be aborted if the script
- returns indicating failure.<br/><br/></li>
- <li>The "stopped" operation for the guest and network hook
scripts,
- executes <b>after</b> the object (guest or network) has stopped.
If
- the hook script indicates failure in its return, the shut down of the
- object cannot be aborted because it has already been performed.
- <br/><br/></li>
- <li>Hook scripts execute in a synchronous fashion. Libvirt waits
- for them to return before continuing the given
operation.<br/><br/>
- This is most noticeable with the guest or network start operation,
- as a lengthy operation in the hook script can mean an extended wait
- for the guest or network to be available to end
users.<br/><br/></li>
- <li>For a hook script to be utilised, it must have its execute bit set
- (e.g. chmod o+rx <i>qemu</i>), and must be present when the
libvirt
- daemon is started.<br/><br/></li>
- <li>If a hook script is added to a host after the libvirt daemon is
- already running, it won't be used until the libvirt daemon
- next starts.</li>
- </ul>
- <br/>
-
- <h2><a id="qemu_migration">QEMU guest
migration</a></h2>
- <p>Migration of a QEMU guest involves running hook scripts on both the
- source and destination hosts:</p>
- <ol>
- <li>At the beginning of the migration, the <i>qemu</i> hook
script on
- the <b>destination</b> host is executed with the
"migrate"
- operation.</li>
- <li>Before QEMU process is spawned, the two operations ("prepare"
and
- "start") called for domain start are executed on
- <b>destination</b> host.</li>
- <li>If both of these hook script executions exit successfully (exit
- status 0), the migration continues. Any other exit code indicates
- failure, and the migration is aborted.</li>
- <li>The QEMU guest is then migrated to the destination host.</li>
- <li>Unless an error occurs during the migration process, the
<i>qemu</i>
- hook script on the <b>source</b> host is then executed with the
- "stopped" and "release" operations to indicate it is no
longer
- running on this host. Regardless of the return codes, the
- migration is not aborted as it has already been performed.</li>
- </ol>
- <br/>
-
- <h2><a id="recursive">Calling libvirt functions from within a
hook script</a></h2>
- <p><b>DO NOT DO THIS!</b></p>
- <p>A hook script must not call back into libvirt, as the libvirt daemon
- is already waiting for the script to exit.</p>
- <p>A deadlock is likely to occur.</p>
- <br/>
-
- <h2><a id="return_codes">Return codes and
logging</a></h2>
- <p>If a hook script returns with an exit code of 0, the libvirt daemon
- regards this as successful and performs no logging of it.</p>
- <p>However, if a hook script returns with a non zero exit code, the libvirt
- daemon regards this as a failure, logs its return code, and
- additionally logs anything on stderr the hook script returns.</p>
- <p>For example, a hook script might use this code to indicate failure,
- and send a text string to stderr:</p>
- <pre>echo "Could not find required XYZZY" >&2
-exit 1</pre>
- <p>The resulting entry in the libvirt log will appear as:</p>
- <pre>20:02:40.297: error : virHookCall:285 : Hook script execution failed:
internal error Child process (LC_ALL=C
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
- HOME=/root USER=root LOGNAME=root /etc/libvirt/hooks/qemu qemu
prepare begin -) unexpected exit status 1: Could not find required XYZZY</pre>
- </body>
-</html>
diff --git a/docs/hooks.rst b/docs/hooks.rst
new file mode 100644
index 0000000000..9c5f3ff456
--- /dev/null
+++ b/docs/hooks.rst
@@ -0,0 +1,518 @@
+.. role:: since
+
+====================================
+Hooks for specific system management
+====================================
+
+.. contents::
+
+Custom event scripts
+--------------------
+
+Beginning with libvirt 0.8.0, specific events on a host system will trigger
+custom scripts.
+
+These custom **hook** scripts are executed when any of the following actions
+occur:
+
+- The libvirt daemon starts, stops, or reloads its configuration (
+ :since:`since 0.8.0` )
+- A QEMU guest is started or stopped ( :since:`since 0.8.0` )
+- An LXC guest is started or stopped ( :since:`since 0.8.0` )
+- A libxl-handled Xen guest is started or stopped ( :since:`since 2.1.0` )
+- A network is started or stopped or an interface is plugged/unplugged to/from
+ the network ( :since:`since 1.2.2` )
+
+Script location
+---------------
+
+The libvirt hook scripts are located in the directory
+``$SYSCONFDIR/libvirt/hooks/``.
+
+- In Linux distributions such as Fedora and RHEL, this is
+ ``/etc/libvirt/hooks/``. Other Linux distributions may do this differently.
+- If your installation of libvirt has instead been compiled from source, it is
+ likely to be ``/usr/local/etc/libvirt/hooks/``.
+- :since:`Since 6.5.0` , you can also place several hook scripts in the
+ directories ``/etc/libvirt/hooks/<driver>.d/``.
+
+To use hook scripts, you will need to create this ``hooks`` directory manually,
+place the desired hook scripts inside, then make them executable.
+
+Script names
+------------
+
+At present, there are five hook scripts that can be called:
+
+- ``/etc/libvirt/hooks/daemon``
+ Executed when the libvirt daemon is started, stopped, or reloads its
+ configuration
+- ``/etc/libvirt/hooks/qemu``
+ Executed when a QEMU guest is started, stopped, or migrated
+- ``/etc/libvirt/hooks/lxc``
+ Executed when an LXC guest is started or stopped
+- ``/etc/libvirt/hooks/libxl``
+ Executed when a libxl-handled Xen guest is started, stopped, or migrated
+- ``/etc/libvirt/hooks/network``
+ Executed when a network is started or stopped or an interface is
+ plugged/unplugged to/from the network
+
+:since:`Since 6.5.0` , you can also have several scripts with any name in the
+directories ``/etc/libvirt/hooks/<driver>.d/``. They are executed in
+alphabetical order after main script.
+
+Script structure
+----------------
+
+The hook scripts are executed using standard Linux process creation functions.
+Therefore, they must begin with the declaration of the command interpreter to
+use.
+
+For example:
+
+::
+
+ #!/bin/bash
+
+or:
+
+::
+
+ #!/usr/bin/python
+
+Other command interpreters are equally valid, as is any executable binary, so
+you are welcome to use your favourite languages.
+
+Script arguments
+----------------
+
+The hook scripts are called with specific command line arguments, depending upon
+the script, and the operation being performed.
+
+The guest hook scripts, qemu and lxc, are also given the **full** XML
+description for the domain on their stdin. This includes items such the UUID of
+the domain and its storage information, and is intended to provide all the
+libvirt information the script needs.
+
+For all cases, stdin of the network hook script is provided with the full XML
+description of the network status in the following form:
+
+::
+
+ <hookData>
+ <network>
+ <name>$network_name</name>
+ <uuid>afca425a-2c3a-420c-b2fb-dd7b4950d722</uuid>
+ ...
+ </network>
+ </hookData>
+
+In the case of an network port being created / deleted, the network XML will be
+followed with the full XML description of the port:
+
+::
+
+ <hookData>
+ <network>
+ <name>$network_name</name>
+ <uuid>afca425a-2c3a-420c-b2fb-dd7b4950d722</uuid>
+ ...
+ </network>
+ <networkport>
+ <uuid>5d744f21-ba4a-4d6e-bdb2-30a35ff3207d</uuid>
+ ...
+ <plug type='direct' dev='ens3' mode='vepa'/>
+ </networkport>
+ </hookData>
+
+Please note that this approach is different from other cases such as ``daemon``,
+``qemu`` or ``lxc`` hook scripts, because two XMLs may be passed here, while in
+the other cases only a single XML is passed.
+
+The command line arguments take this approach:
+
+#. The first argument is the name of the **object** involved in the operation,
+ or '-' if there is none.
+ For example, the name of a guest being started.
+#. The second argument is the name of the **operation** being performed.
+ For example, "start" if a guest is being started.
+#. The third argument is a **sub-operation** indication, or '-' if there is
+ none.
+#. The last argument is an **extra argument** string, or '-' if there is none.
+
+Specifics
+~~~~~~~~~
+
+This translates to the following specifics for each hook script:
+
+/etc/libvirt/hooks/daemon
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- | When the libvirt daemon is started, this script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/daemon - start - start
+
+- | When the libvirt daemon is shut down, this script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/daemon - shutdown - shutdown
+
+- | When the libvirt daemon receives the SIGHUP signal, it reloads its
+ configuration and triggers the hook script as:
+
+ ::
+
+ /etc/libvirt/hooks/daemon - reload begin SIGHUP
+
+Please note that when the libvirt daemon is restarted, the *daemon* hook script
+is called once with the "shutdown" operation, and then once with the
"start"
+operation. There is no specific operation to indicate a "restart" is
occurring.
+
+/etc/libvirt/hooks/qemu
+^^^^^^^^^^^^^^^^^^^^^^^
+
+- | Before a QEMU guest is started, the qemu hook script is called in three
+ locations; if any location fails, the guest is not started. The first
+ location, :since:`since 0.9.0` , 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:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name prepare begin -
+
+ | The second location, available :since:`Since 0.8.0` , occurs after libvirt
+ has finished labeling all resources, but has not yet started the guest,
+ called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name start begin -
+
+ | The third location, :since:`0.9.13` , occurs after the QEMU process has
+ successfully started up:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name started begin -
+
+- | When a QEMU guest is stopped, the qemu hook script is called in two
+ locations, to match the startup. First, :since:`since 0.8.0` , the hook is
+ called before libvirt restores any labels:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name stopped end -
+
+ | Then, after libvirt has released all resources, the hook is called again,
+ :since:`since 0.9.0` , to allow any additional resource cleanup:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name release end -
+
+- :since:`Since 0.9.11` , the qemu hook script is also called at the beginning
+ of incoming migration. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name migrate begin -
+
+ with domain XML sent to standard input of the script. In this case, the
+ script acts as a filter and is supposed to modify the domain XML and print it
+ out on its standard output. Empty output is identical to copying the input
+ XML without changing it. In case the script returns failure or the output XML
+ is not valid, incoming migration will be canceled. This hook may be used,
+ e.g., to change location of disk images for incoming domains.
+
+- :since:`Since 1.2.9` , the qemu hook script is also called when restoring a
+ saved image either via the API or automatically when restoring a managed save
+ machine. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name restore begin -
+
+ with domain XML sent to standard input of the script. In this case, the
+ script acts as a filter and is supposed to modify the domain XML and print it
+ out on its standard output. Empty output is identical to copying the input
+ XML without changing it. In case the script returns failure or the output XML
+ is not valid, restore of the image will be aborted. This hook may be used,
+ e.g., to change location of disk images for restored domains.
+
+- :since:`Since 6.5.0` , you can also place several hook scripts in the
+ directory ``/etc/libvirt/hooks/qemu.d/``. They are executed in alphabetical
+ order after main script. In this case each script also acts as filter and can
+ modify the domain XML and print it out on its standard output. This script
+ output is passed to standard input next script in order. Empty output from
+ any script is also identical to copying the input XML without changing it. In
+ case any script returns failure common process will be aborted, but all
+ scripts from the directory will are executed.
+
+- :since:`Since 0.9.13` , the qemu hook script is also called when the libvirtd
+ daemon restarts and reconnects to previously running QEMU processes. If the
+ script fails, the existing QEMU process will be killed off. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name reconnect begin -
+
+- :since:`Since 0.9.13` , the qemu hook script is also called when the QEMU
+ driver is told to attach to an externally launched QEMU process. It is called
+ as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name attach begin -
+
+/etc/libvirt/hooks/lxc
+^^^^^^^^^^^^^^^^^^^^^^
+
+- | Before a LXC guest is started, the lxc hook script is called in three
+ locations; if any location fails, the guest is not started. The first
+ location, :since:`since 0.9.13` , 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:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name prepare begin -
+
+ | The second location, available :since:`Since 0.8.0` , occurs after libvirt
+ has finished labeling all resources, but has not yet started the guest,
+ called as:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name start begin -
+
+ | The third location, :since:`0.9.13` , occurs after the LXC process has
+ successfully started up:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name started begin -
+
+- | When a LXC guest is stopped, the lxc hook script is called in two
+ locations, to match the startup. First, :since:`since 0.8.0` , the hook is
+ called before libvirt restores any labels:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name stopped end -
+
+ | Then, after libvirt has released all resources, the hook is called again,
+ :since:`since 0.9.0` , to allow any additional resource cleanup:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name release end -
+
+- :since:`Since 0.9.13` , the lxc hook script is also called when the libvirtd
+ daemon restarts and reconnects to previously running LXC processes. If the
+ script fails, the existing LXC process will be killed off. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name reconnect begin -
+
+/etc/libvirt/hooks/libxl
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- | Before a Xen guest is started using libxl driver, the libxl hook script is
+ called in three locations; if any location fails, the guest is not started.
+ The first location, :since:`since 2.1.0` , is before libvirt performs any
+ resource labeling, and the hook can allocate resources not managed by
+ libvirt. This is called as:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name prepare begin -
+
+ | The second location, available :since:`Since 2.1.0` , occurs after libvirt
+ has finished labeling all resources, but has not yet started the guest,
+ called as:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name start begin -
+
+ | The third location, :since:`2.1.0` , occurs after the domain has
+ successfully started up:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name started begin -
+
+- | When a libxl-handled Xen guest is stopped, the libxl hook script is called
+ in two locations, to match the startup. First, :since:`since 2.1.0` , the
+ hook is called before libvirt restores any labels:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name stopped end -
+
+ | Then, after libvirt has released all resources, the hook is called again,
+ :since:`since 2.1.0` , to allow any additional resource cleanup:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name release end -
+
+- :since:`Since 2.1.0` , the libxl hook script is also called at the beginning
+ of incoming migration. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name migrate begin -
+
+ with domain XML sent to standard input of the script. In this case, the
+ script acts as a filter and is supposed to modify the domain XML and print it
+ out on its standard output. Empty output is identical to copying the input
+ XML without changing it. In case the script returns failure or the output XML
+ is not valid, incoming migration will be canceled. This hook may be used,
+ e.g., to change location of disk images for incoming domains.
+
+- :since:`Since 6.5.0` , you can also place several hook scripts in the
+ directory ``/etc/libvirt/hooks/libxl.d/``. They are executed in alphabetical
+ order after main script. In this case each script also acts as filter and can
+ modify the domain XML and print it out on its standard output. This script
+ output is passed to standard input next script in order. Empty output from
+ any script is also identical to copying the input XML without changing it. In
+ case any script returns failure common process will be aborted, but all
+ scripts from the directory will are executed.
+
+- :since:`Since 2.1.0` , the libxl hook script is also called when the libvirtd
+ daemon restarts and reconnects to previously running Xen domains. If the
+ script fails, the existing Xen domains will be killed off. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name reconnect begin -
+
+/etc/libvirt/hooks/network
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- | :since:`Since 1.2.2` , before a network is started, this script is called
+ as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name start begin -
+
+- | After the network is started, up & running, the script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name started begin -
+
+- | When a network is shut down, this script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name stopped end -
+
+- | Later, when network is started and there's an interface from a domain to be
+ plugged into the network, the hook script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name port-created begin -
+
+ Please note, that in this case, the script is passed both network and port
+ XMLs on its stdin.
+
+- | When network is updated, the hook script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name updated begin -
+
+- | When the domain from previous case is shutting down, the interface is
+ unplugged. This leads to another script invocation:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name port-deleted begin -
+
+ And again, as in previous case, both network and port XMLs are passed onto
+ script's stdin.
+
+Script execution
+----------------
+
+- The "start" operation for the guest and network hook scripts, executes
+ **prior** to the object (guest or network) being created. This allows the
+ object start operation to be aborted if the script returns indicating
+ failure.
+- The "stopped" operation for the guest and network hook scripts, executes
+ **after** the object (guest or network) has stopped. If the hook script
+ indicates failure in its return, the shut down of the object cannot be
+ aborted because it has already been performed.
+- Hook scripts execute in a synchronous fashion. Libvirt waits for them to
+ return before continuing the given operation.
+ This is most noticeable with the guest or network start operation, as a
+ lengthy operation in the hook script can mean an extended wait for the guest
+ or network to be available to end users.
+- For a hook script to be utilised, it must have its execute bit set (e.g.
+ chmod o+rx *qemu*), and must be present when the libvirt daemon is started.
+- If a hook script is added to a host after the libvirt daemon is already
+ running, it won't be used until the libvirt daemon next starts.
+
+QEMU guest migration
+--------------------
+
+Migration of a QEMU guest involves running hook scripts on both the source and
+destination hosts:
+
+#. At the beginning of the migration, the *qemu* hook script on the
+ **destination** host is executed with the "migrate" operation.
+#. Before QEMU process is spawned, the two operations ("prepare" and
"start")
+ called for domain start are executed on **destination** host.
+#. If both of these hook script executions exit successfully (exit status 0),
+ the migration continues. Any other exit code indicates failure, and the
+ migration is aborted.
+#. The QEMU guest is then migrated to the destination host.
+#. Unless an error occurs during the migration process, the *qemu* hook script
+ on the **source** host is then executed with the "stopped" and
"release"
+ operations to indicate it is no longer running on this host. Regardless of
+ the return codes, the migration is not aborted as it has already been
+ performed.
+
+Calling libvirt functions from within a hook script
+---------------------------------------------------
+
+**DO NOT DO THIS!**
+
+A hook script must not call back into libvirt, as the libvirt daemon is already
+waiting for the script to exit.
+
+A deadlock is likely to occur.
+
+Return codes and logging
+------------------------
+
+If a hook script returns with an exit code of 0, the libvirt daemon regards this
+as successful and performs no logging of it.
+
+However, if a hook script returns with a non zero exit code, the libvirt daemon
+regards this as a failure, logs its return code, and additionally logs anything
+on stderr the hook script returns.
+
+For example, a hook script might use this code to indicate failure, and send a
+text string to stderr:
+
+::
+
+ echo "Could not find required XYZZY" >&2
+ exit 1
+
+The resulting entry in the libvirt log will appear as:
+
+::
+
+ 20:02:40.297: error : virHookCall:285 : Hook script execution failed: internal error
Child process (LC_ALL=C PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+ HOME=/root USER=root LOGNAME=root /etc/libvirt/hooks/qemu qemu
prepare begin -) unexpected exit status 1: Could not find required XYZZY
diff --git a/docs/meson.build b/docs/meson.build
index 22eca7d8bd..a0e96e2453 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -25,7 +25,6 @@ docs_html_in_files = [
'formatnetwork',
'formatnode',
'formatnwfilter',
- 'hooks',
'index',
'internals',
'java',
@@ -92,6 +91,7 @@ docs_rst_files = [
'goals',
'governance',
'hacking',
+ 'hooks',
'libvirt-go',
'libvirt-go-xml',
'macos',
--
2.35.1