Table of Contents
Rudder 4.1 introduces the possibility to execute files (hooks), typically scripts, when some predefined event occurs on Rudder.
Hooks are organized in subdirectories. The root of the sub-directories is /opt/rudder/etc/hooks.d/
Each sub-directory has a name related to the event that will trigger the hooks execution. By default, a hook directory contains a template example and a Readme.txt file explaining the generalities about hooks and the specificities of that hook (parameters, etc).
Hooks must be executable. All executable files will be used as hooks EXCEPT if they end with one of the extensions listed in /opt/rudder/etc/rudder-web.properties for property *rudder.hooks.ignore-suffixes. A common convention is to use the .disabled suffixe to do so.
Non executable files will be ignored (which allows to put other files in these directories, like a readme, for example).
Hooks parameter are passed by environment variable. Rudder will fill dedicated environment variable for each hooks.
Hooks are executed sequentially, in lexical order. We encourage you to use the patter "NN-hookname", with NN a number like "05", "20", etc.
Hooks have normalized returned code. Return codes on hooks are interpreted as follow:
- 0 : success, no log (appart if debug one) , continue to next hook
- 1-31 : error , error log in /var/log/rudder/webapp/, stop processing
- 32-63 : warning, warning log in /var/log/rudder/webapp/, continue to next hook
- 64-255 : reserved for future use case. Behavior may change without notice.
Available Hooked events: for now, all hooks are related to different steps of the policy generation process. In the future, more hooks will be supported like node acceptation.
This directory contains hooks executed after a node was successfully accepted.
Typically, these hooks triggers action on other system, like registering the node into a monitoring system or into an external CMDB, or to send notification.
This directory contains hooks executed after a node was successfully deleted.
Typically, these hooks clean resources related to that node and notify external services that the node was deleted from Rudder.
Hooks parameters are passed by environment variable:
- RUDDER_NODE_ID: the nodeId
- RUDDER_NODE_HOSTNAME: the node fully qualified hostname
- RUDDER_NODE_POLICY_SERVER_ID: the node policy server id
- RUDDER_AGENT_TYPE : agent type ("cfengine-nova" or "cfengine-community")
- RUDDER_POLICIES_DIRECTORY_CURRENT: the full path of the base directory containing policies for that node
- RUDDER_POLICIES_DIRECTORY_NEW: the full path of the base directory containing next policies for that node (during a generation)
- RUDDER_POLICIES_DIRECTORY_ARCHIVE: the full path of the base directory containing previous policies for that node
- RUDDER_NODE_ROLES: a comma separated list of node’s server role name
This directory contains hooks executed before a node is deleted.
Typically, these hooks interact with external services using knowledge to validate if the node should actually be deleted.
Hooks parameters are passed by environment variable:
- RUDDER_NODE_ID: the nodeId
- RUDDER_NODE_HOSTNAME: the node fully qualified hostname
- RUDDER_NODE_POLICY_SERVER_ID: the node policy server id
- RUDDER_AGENT_TYPE : agent type ("cfengine-nova" or "cfengine-community")
- RUDDER_POLICIES_DIRECTORY_CURRENT: the full path of the base directory containing policies for that node
- RUDDER_POLICIES_DIRECTORY_NEW: the full path of the base directory containing next policies for that node (during a generation)
- RUDDER_POLICIES_DIRECTORY_ARCHIVE: the full path of the base directory containing previous policies for that node
- RUDDER_NODE_ROLES: a comma separated list of node’s server role name
This directory contains hooks executed after policies are fully generated for all nodes, and these new policies are available for download for the node.
Typically, these hooks are used to log information about the
generation which just happened or notify third parties that
new policies are available (for ex: cf-serverd SIGHUP)
Hooks parameters are passed by environment variable:
- RUDDER_GENERATION_DATETIME : ISO-8601 YYYY-MM-ddTHH:mm:ss.sssZ date/time that identifies that policy generation.
- RUDDER_NODE_IDS : space separated list of node id updated during the process, or the empty string if no nodes were updated.
- RUDDER_END_GENERATION_DATETIME : ISO-8601 YYYY-MM-ddTHH:mm:ss.sssZ date/time when the generation ended (minus these hooks)
- RUDDER_NUMBER_NODES_UPDATED : integer >= 0; number of nodes updated (could be found by counting $RUDDER_NODE_IDS)
- RUDDER_ROOT_POLICY_SERVER_UPDATED: 0 if root was updated, anything else if not
This directory contains hooks executed after policies are fully generated for node and made available for the node to download.
Typically, these hooks interact with external services using knowledge from the generated policies (ex: send node-properties JSON file to a third party service).
Hooks parameters are passed by environment variable:
- RUDDER_GENERATION_DATETIME : generation datetime: ISO-8601 YYYY-MM-ddTHH:mm:ss.sssZ date/time that identify that policy generation start
- RUDDER_NODE_ID : the nodeId
- RUDDER_NODE_HOSTNAME : the node fully qualified hostname
- RUDDER_NODE_POLICY_SERVER_ID : the node policy server id
- RUDDER_AGENT_TYPE : agent type ("cfengine-nova" or "cfengine-community")
- RUDDER_POLICIES_DIRECTORY_CURRENT : new policies directory (for ex for nodes under root: /var/rudder/share/$RUDDER_NODE_ID/rules)
Technically, you could infer RUDDER_POLICIES_DIRECTORY_NEW, from RUDDER_NODE_ID, but it’s tedious for nodes behind a relay, and it is just simpler not to have to track what are the Rudder internal names, which may change without notice.
This directory contains hooks executed after policies are fully generated for node, but before these new policies replace the old ones (technically, before we move /var/rudder/share/$NODEID/rules.new to /var/rudder/share/$NODEID/rules).
Typically, these hooks proceed to sanity checks on the new policies (ex: cf-promises), update permission on files, or interact with external services using information from the generated policies (ex: send node-properties JSON file to a third party service).
Hooks parameters are passed by environment variable:
- RUDDER_GENERATION_DATETIME : generation datetime: ISO-8601 YYYY-MM-ddTHH:mm:ss.sssZ date/time that identify that policy generation start
- RUDDER_NODE_ID : the nodeId
- RUDDER_NODE_HOSTNAME : the node fully qualified hostname
- RUDDER_NODE_POLICY_SERVER_ID : the node policy server id
- RUDDER_AGENT_TYPE : agent type ("cfengine-nova" or "cfengine-community")
- RUDDER_POLICIES_DIRECTORY_NEW: new policies directory (for ex for nodes under root: /var/rudder/share/$RUDDER_NODE_ID/rules.new)
Technically, you could infer RUDDER_POLICIES_DIRECTORY_NEW, from RUDDER_NODE_ID, but it’s tedious for nodes behind a relay, and it is just simpler not to have to track what are the Rudder internal names, which may change without notice.
This directory contains hooks executed when a policy generation starts.
Typically, these hooks are used to log information about the generation which just started or notify third parties that shared information to node should be updated (shared-folder, etc).
