summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorSaku Ytti <saku@ytti.fi>2015-09-05 12:32:37 +0300
committerSaku Ytti <saku@ytti.fi>2015-09-05 12:32:37 +0300
commitbaf19a281121cf065685f34c20978f0f2ef610af (patch)
tree959b3b4e55cbe319cc4a7bce7882fed837966ff8 /README.md
parentba79dea58b459eff8e2dadcffdf5a97e020c8783 (diff)
parent323f5968e3593539eca0477779114caddbfc751d (diff)
Merge branch 'feature-hook'
Diffstat (limited to 'README.md')
-rw-r--r--README.md51
1 files changed, 51 insertions, 0 deletions
diff --git a/README.md b/README.md
index 92f2b62..f6ce764 100644
--- a/README.md
+++ b/README.md
@@ -401,6 +401,57 @@ model_map:
juniper: junos
```
+# Hooks
+You can define arbitrary number of hooks that subscribe different events. The hook system is modular and different kind of hook types can be enabled.
+
+## Configuration
+Following configuration keys need to be defined for all hooks:
+
+ * `events`: which events to subscribe. Needs to be an array. See below for the list of available events.
+ * `type`: what hook class to use. See below for the list of available hook types.
+
+### Events
+ * `node_success`: triggered when configuration is succesfully pulled from a node and right before storing the configuration.
+ * `node_fail`: triggered after `retries` amount of failed node pulls.
+ * `post_store`: triggered after node configuration is stored.
+
+## Hook type: exec
+The `exec` hook type allows users to run an arbitrary shell command or a binary when triggered.
+
+The command is executed on a separate child process either in synchronous or asynchronous fashion. Non-zero exit values cause errors to be logged. STDOUT and STDERR are currently not collected.
+
+Command is executed with the following environment:
+```
+OX_EVENT
+OX_NODE_NAME
+OX_NODE_FROM
+OX_NODE_MSG
+OX_NODE_GROUP
+OX_JOB_STATUS
+OX_JOB_TIME
+```
+
+Exec hook recognizes following configuration keys:
+
+ * `timeout`: hard timeout for the command execution. SIGTERM will be sent to the child process after the timeout has elapsed. Default: 60
+ * `async`: influences whether main thread will wait for the command execution. Set this true for long running commands so node pull is not blocked. Default: false
+ * `cmd`: command to run.
+
+
+## Hook configuration example
+```
+hooks:
+ name_for_example_hook1:
+ type: exec
+ events: [node_success]
+ cmd: 'echo "Node success $OX_NODE_NAME" >> /tmp/ox_node_success.log'
+ name_for_example_hook2:
+ type: exec
+ events: [post_store, node_fail]
+ cmd: 'echo "Doing long running stuff for $OX_NODE_NAME" >> /tmp/ox_node_stuff.log; sleep 60'
+ async: true
+ timeout: 120
+```
# Ruby API