Add useful hints to hooks documentation
authorHelga Velroyen <helgav@google.com>
Tue, 12 Jan 2016 10:39:17 +0000 (11:39 +0100)
committerHelga Velroyen <helgav@google.com>
Tue, 12 Jan 2016 15:52:58 +0000 (16:52 +0100)
Our documentation about hooks is lacking some useful
hints for people setting up hooks for the first time.
This patch adds the information that was otherwise
only available from reading the code or the mailinglist's
archive.

Signed-off-by: Helga Velroyen <helgav@google.com>
Reviewed-by: Klaus Aehlig <aehlig@google.com>

doc/hooks.rst

index e0d127f..667906b 100644 (file)
@@ -9,7 +9,8 @@ Introduction
 ------------
 
 In order to allow customisation of operations, Ganeti runs scripts in
-sub-directories of ``@SYSCONFDIR@/ganeti/hooks``. These sub-directories
+sub-directories of ``@SYSCONFDIR@/ganeti/hooks`` (that is usually
+``/etc/ganeti/hooks``). These sub-directories
 are named ``$hook-$phase.d``, where ``$phase`` is either ``pre`` or
 ``post`` and ``$hook`` matches the directory name given for a hook (e.g.
 ``cluster-verify-post.d`` or ``node-add-pre.d``).
@@ -17,6 +18,10 @@ are named ``$hook-$phase.d``, where ``$phase`` is either ``pre`` or
 This is similar to the ``/etc/network/`` structure present in Debian
 for network interface handling.
 
+Note that Ganeti does not create its ``hooks`` directory by default.
+If you want to use hooks scripts, create it on all nodes. This applies
+also to all sub directories such as ``node-add-pre.d``.
+
 Organisation
 ------------
 
@@ -31,6 +36,11 @@ depending on the operation type.
 Note that, even though we call them scripts, we are actually talking
 about any executable.
 
+The filenames of the scripts need to match the regular expression
+``^[a-zA-Z0-9_-]+$``. This means in particular, that scripts having
+a filename extension (such as ``myhook.sh``) are silently ignored
+by Ganeti.
+
 *pre* scripts
 ~~~~~~~~~~~~~