diff --git a/docs/hooks.html.in b/docs/hooks.html.in index 2afdecfe14..411f2ec9bf 100644 --- a/docs/hooks.html.in +++ b/docs/hooks.html.in @@ -2,69 +2,184 @@

Hooks for specific system management

-

Libvirt includes synchronous hooks, starting from version 0.8.0, as a - way to tie in specific tailored system actions at a specific time. - If these scripts are present on the host where the hypervisor - is running, then they are called when the libvirt daemon is doingi - some significant action.

-

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

-

The scripts are stored in the directory /etc/libvirt/hooks/ - when using a standard installation path - ($SYSCONF_DIR/libvirt/hooks/ in general).

-

Each script is given the following command line arguments:

- -

There are currently scripts for 3 domains of operation: + +

+ +

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:

-

+ +

Script location

+

The libvirt hook scripts are located in the directory + $SYSCONF_DIR/libvirt/hooks/.

+ +

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 three hook scripts that can be called:

+ +
+ +

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.

+ +

The command line arguments take this approach:

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

    2. +
  2. The second argument is the name of the operation being + performed.

    + For example, "start" if a guest is being started.

    3. +
  3. The third argument is a sub-operation indication, or '-' if there + is none.

    4. +
  4. The last argument is an extra argument string, or '-' if there is + none.
    5. +
+ +

Specifics

+

This translates to the following specifics for each hook script:

+ +
/etc/libvirt/hooks/daemon
+ +

Please note that when the libvirt daemon is restarted, the qemu + 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
+ + +
/etc/libvirt/hooks/lxc
+ +
+ +

Script execution

+ +
+ +

QEMU guest migration

+

Migration of a QEMU guest involves running hook scripts on both the + source and destination hosts:

+
    +
  1. At the beginning of the migration, the qemu hook script on + the destination host is executed with the "start" + operation.

    2. +
  2. If this hook script returns indicating success (error code 0), the + migration continues. Any other return code indicates failure, and + the migration is aborted.

    3. +
  3. The QEMU guest is then migrated to the destination host.
    +
    4. +
  4. Unless an error occurs during the migration process, the qemu + hook script on the source host is then executed with the "stopped" + operation, to indicate it is no longer running on this + host.

    + Regardless of the return code from this hook script, the migration + is not aborted as it has already been performed.
    5. +
+
+ +

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 it with return code 256, 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:416 : Hook script execution failed: Hook script /etc/libvirt/hooks/qemu qemu failed with error code 256:Could not find required XYZZY