blob: fb80a19f1145fd03c08805ee50153ae4d05395d9 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
# 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 successfully 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 (this is executed only when the configuration has changed).
* `nodes_done`: triggered after finished fetching all nodes.
## 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:
```text
OX_EVENT
OX_NODE_NAME
OX_NODE_IP
OX_NODE_FROM
OX_NODE_MSG
OX_NODE_GROUP
OX_NODE_MODEL
OX_JOB_STATUS
OX_JOB_TIME
OX_REPO_COMMITREF
OX_REPO_NAME
```
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.
### exec hook configuration example
```yaml
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
```
## Hook type: githubrepo
The `githubrepo` hook executes a `git push` to a configured `remote_repo` when the specified event is triggered.
Several authentication methods are supported:
* Provide a `password` for username + password authentication
* Provide both a `publickey` and a `privatekey` for ssh key-based authentication
* Don't provide any credentials for ssh-agent authentication
The username will be set to the relevant part of the `remote_repo` URI, with a fallback to `git`. It is also possible to provide one by setting the `username` configuration key.
For ssh key-based authentication, it is possible to set the environment variable `OXIDIZED_SSH_PASSPHRASE` to a passphrase if the private key requires it.
`githubrepo` hook recognizes the following configuration keys:
* `remote_repo`: the remote repository to be pushed to.
* `username`: username for repository auth.
* `password`: password for repository auth.
* `publickey`: public key for repository auth.
* `privatekey`: private key for repository auth.
When using groups, each group must have a unique entry in the `remote_repo` config.
```yaml
hooks:
push_to_remote:
remote_repo:
routers: git@git.intranet:oxidized/routers.git
switches: git@git.intranet:oxidized/switches.git
firewalls: git@git.intranet:oxidized/firewalls.git
```
### githubrepo hook configuration example
Authenticate with a username and a password:
```yaml
hooks:
push_to_remote:
type: githubrepo
events: [post_store]
remote_repo: git@git.intranet:oxidized/test.git
username: user
password: pass
```
Authenticate with the username `git` and an ssh key:
```yaml
hooks:
push_to_remote:
type: githubrepo
events: [post_store]
remote_repo: git@git.intranet:oxidized/test.git
publickey: /root/.ssh/id_rsa.pub
privatekey: /root/.ssh/id_rsa
```
## Hook type: awssns
The `awssns` hook publishes messages to AWS SNS topics. This allows you to notify other systems of device configuration changes, for example a config orchestration pipeline. Multiple services can subscribe to the same AWS topic.
Fields sent in the message:
* `event`: Event type (e.g. `node_success`)
* `group`: Group name
* `model`: Model name (e.g. `eos`)
* `node`: Device hostname
### awssns hook configuration example
```yaml
hooks:
hook_script:
type: awssns
events: [node_fail,node_success,post_store]
region: us-east-1
topic_arn: arn:aws:sns:us-east-1:1234567:oxidized-test-backup_events
```
AWS SNS hook requires the following configuration keys:
* `region`: AWS Region name
* `topic_arn`: ASN Topic reference
Your AWS credentials should be stored in `~/.aws/credentials`.
## Hook type: slackdiff
The `slackdiff` hook posts colorized config diffs to a [Slack](http://www.slack.com) channel of your choice. It only triggers for `post_store` events.
You will need to manually install the `slack-api` gem on your system:
```shell
gem install slack-api
```
### slackdiff hook configuration example
```yaml
hooks:
slack:
type: slackdiff
events: [post_store]
token: SLACK_BOT_TOKEN
channel: "#network-changes"
```
Optionally you can disable snippets and post a formatted message, for instance linking to a commit in a git repo. Named parameters `%{node}`, `%{group}`, `%{model}` and `%{commitref}` are available.
```yaml
hooks:
slack:
type: slackdiff
events: [post_store]
token: SLACK_BOT_TOKEN
channel: "#network-changes"
diff: false
message: "%{node} %{group} %{model} updated https://git.intranet/network-changes/commit/%{commitref}"
```
Note the channel name must be in quotes.
## Hook type: xmppdiff
The `xmppdiff` hook posts config diffs to a [XMPP](https://en.wikipedia.org/wiki/XMPP) chatroom of your choice. It only triggers for `post_store` events.
You will need to manually install the `xmpp4r` gem on your system:
```shell
gem install xmpp4r
```
### xmppdiff hook configuration example
```yaml
hooks:
xmpp:
type: xmppdiff
events: [post_store]
jid: "user@server.tld/resource"
password: "password"
channel: "room@server.tld"
nick: "nickname"
```
Note the channel name must be in quotes.
|
