forked from zorkian/nagios-api
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
409 lines (296 loc) · 12.7 KB
/
README
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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
nagios-api
==========
NAME
----
nagios-api - presents a REST-like JSON interface to Nagios
SYNOPSIS
--------
nagios-api [OPTIONS]
DEPENDENCIES
------------
Dependencies include: diesel, greenlet and python-openssl bindings. These
should be available via pip/easy_install.
DESCRIPTION
-----------
This program provides a simple REST-like interface to Nagios. Run this
on your Nagios host and then sit back and enjoy a much easier, more
straightforward way to accomplish things with Nagios. You can use the
bundled nagios-cli, but you may find it easier to write your own system
for interfacing with the API.
USAGE
-----
Usage is pretty easy:
nagios-api -p 8080 -c /var/lib/nagios3/rw/nagios.cmd \
-s /var/cache/nagios3/status.dat -l /var/log/nagios3/nagios.log
You must at least provide the status file options. If you don't provide
the other options, then we will disable that functionality and error to
clients who request it.
HTTP USAGE
----------
The server speaks JSON. You can either GET data from it or POST data to
it and take an action. It's pretty straightforward, here's an idea of
what you can do from the command line:
curl http://localhost:8080/state
That calls the `state` method and returns the JSON result.
curl -d '{"host": "web01", "duration": 600}' \
http://localhost:8080/schedule_downtime
This POSTs the given JSON object to the `schedule_downtime` method. You
will note that all objects returned follow a predictable format:
{"content": <object>, "result": <bool>}
The `result` field is always `true` or `false`, allowing you to
determine at a glance if the command succeeded. The `content` field may
be any valid JavaScript object: an int, string, null, bool, hash, list,
etc etc. What is returned depends on the method being called.
NAGIOS-CLI USAGE
----------------
Once your API server is up and running you can access it through the
included nagios-cli script. The script now has some decent built-in help
so you should be able to get all you need:
nagios-cli -h
The original raw JSON mode is still supported by passing the --raw
option.
OPTIONS
-------
-p, --port=PORT
Listen on port 'PORT' for HTTP requests.
-b, --bind=ADDR
Bind to ADDR for HTTP requests (defaults to all interfaces).
-c, --command-file=FILE
Use 'FILE' to write commands to Nagios. This is where external
commands are sent. If your Nagios installation does not allow
external commands, do not set this option.
-s, --status-file=FILE
Set 'FILE' to the status file where Nagios stores its status
information. This is where we learn about the state of the world and
is the only required parameter.
-l, --log-file=FILE
Point 'FILE' to the location of Nagios's log file if you want to
allow people to subscribe to it.
-o, --allow-origin=ORIGIN
Modern web browsers implement the Cross-Origin Resource Sharing
specification from W3C. This spec allows you to host your
JavaScript/HTML on one host and have it access an endpoint on a
different service. This requires setting a header on the endpoint,
which this option allows you to do.
You can simply set this header to `*` and not worry about it
if you want to allow all access. For more information see the
[CORS specification](http://www.w3.org/TR/cors/).
-q, --quiet
If present, we will only print warning/critical messages. Useful if
you are running this in the background.
API
---
This program currently supports only a subset of the Nagios API. More
is being added as it is needed. If you need something that isn't here,
please consider submitting a patch!
This section is organized into methods and sorted alphabetically. Each
method is specified as a URL and may include an integer component on the
path. Most data is passed as JSON objects in the body of a POST.
acknowledge_problem
~~~~~~~~~~~~~~~~~~~
This method allows you to acknowledge a given problem on a host or service.
*host*='STRING' [required]::
Which host to act on.
*service*='STRING'::
Optional. If specified, act on this service.
*comment*='STRING' [required]::
This is required and should contain some sort of message that explains why
this alert is being acknowledged.
*sticky*='BOOL'::
Optional, default TRUE. When true, this acknowledgement stays until the
host enters an OK state. If false, the acknowledgement clears on ANY state
change.
*notify*='BOOL'::
Optional, default TRUE. Whether or not to send a notification that this
problem has been acknowledged.
*persistent*='BOOL'::
Optional, default FALSE. If this is enabled, the comment given will stay
on the host or service. By default, when an acknowledgement expires, the
comment associated with it is deleted.
*author*='STRING'::
Optional. The name of the author. This is useful in UIs if you want
to disambiguate who is doing what.
add_comment
~~~~~~~~~~~
For a given host and/or service, add a comment. This is free-form text that can
include whatever you want and is visible in the Nagios UI and API output.
*host*='STRING' [required]::
Which host to act on.
*service*='STRING'::
Optional. If specified, act on this service.
*comment*='STRING' [required]::
This is required and should contain the text of the comment you want to
add to this host or service.
*persistent*='BOOL'::
Optional, default FALSE. If this is enabled, the comment given will stay
on the host or service until deleted manually. By default, they only stay
until Nagios is restarted.
*author*='STRING'::
Optional. The name of the author. This is useful in UIs if you want
to disambiguate who is doing what.
cancel_downtime
~~~~~~~~~~~~~~~
Very simply, this immediately lifts a downtime that is currently in
effect on a host or service. If you know the `downtime_id`, you can
specify that as a URL argument like this:
curl -d "{}" http://localhost:8080/cancel_downtime/15
That would cancel the downtime with `downtime_id` of 15. Most of the
time you will probably not have this information and so we allow you to
cancel by host/service as well.
*host*='STRING' [required]::
Which host to cancel downtime from. This must be specified if you
are not using the `downtime_id` directly.
*service*='STRING'::
Optional. If specified, cancel any downtimes on this service.
*services_too*='BOOL'::
Optional. If true and you have not specified a `service` in
specific, then we will cancel all downtimes on this host and all of
the services it has.
disable_notifications
~~~~~~~~~~~~~~~~~~~~~
This disables alert notifications on a host or service. (As an operational
note, you might want to schedule downtime instead. Disabling notifications
has a habit of leaving things off and people forgetting about it.)
*host*='STRING' [required]::
Which host to act on.
*service*='STRING'::
Optional. If specified, act on this service.
delete_comment
~~~~~~~~~~~~~~
Deletes comments from a host or service. Can be used to delete all comments or
just a particular comment.
*host*='STRING' [required]::
Which host to act on.
*service*='STRING'::
Optional. If specified, act on this service.
*comment_id*='INTEGER' [required]::
The ID of the comment you wish to delete. You may set this to -1 to delete
all comments on the given host or service.
enable_notifications
~~~~~~~~~~~~~~~~~~~~
This enables alert notifications on a host or service.
*host*='STRING' [required]::
Which host to act on.
*service*='STRING'::
Optional. If specified, act on this service.
log
~~~
Simply returns the most recent 1000 items in the Nagios event log. These
are currently unparsed. There is a plan to parse this in the future and
return event objects.
objects
~~~~~~~
Returns a dict with the key being hostnames and the values being a list
of services defined for that host. Use this method to get the contents
of the world -- i.e., all hosts and services.
remove_acknowledgement
~~~~~~~~~~~~~~~~~~~~~~
This method cancels an acknowledgement on a host or service.
*host*='STRING' [required]::
Which host to act on.
*service*='STRING'::
Optional. If specified, act on this service.
schedule_check
~~~~~~~~~~~~~~
This API lets you schedule a check for a host or service. This also allows
you to force a check.
*host*='STRING' [required]::
The host to schedule a check for. Required.
*service*='STRING'::
Optional. If present, we'll schedule a check on this service at the given
time.
*check_time*='INTEGER'::
Optional, defaults to now. You can specify what time you want the check
to be run at.
*forced*='BOOL'::
Optional, defaults to FALSE. When true, then you force Nagios to run the
check at the given time. By default, Nagios will only run the check if it
meets the standard eligibility criteria.
*output*='STRING' [required]::
The plugin output to be displayed in the UI and stored. This is a
single line of text, normally returned by checkers.
schedule_downtime
~~~~~~~~~~~~~~~~~
This general purpose method is used for creating fixed length downtimes.
This method can be used on hosts and services. You are allowed to
specify the author and comment to go with the downtime, too. The JSON
parameters are:
*host*='STRING' [required]::
Which host to schedule a downtime for. This must be specified.
*duration*='INTEGER' [required]::
How many seconds this downtime will last for. They begin immediately
and continue for `duration` seconds before ending.
*service*='STRING'::
Optional. If specified, we will schedule a downtime for this service
on the above host. If not specified, then the downtime will be
scheduled for the host itself.
*services_too*='BOOL'::
Optional. If true and you have not specified a `service` in
specific, then we will schedule a downtime for the host and all of
the services on that host. Potentially many downtimes are scheduled.
*author*='STRING'::
Optional. The name of the author. This is useful in UIs if you want
to disambiguate who is doing what.
*comment*='STRING'::
Optional. As above, useful in the UI.
The result of this method is a text string that indicates whether or
not the downtimes have been scheduled or if a different error occurred.
We do not have the ability to get the `downtime_id` that is generated,
unfortunately, as that would require waiting for Nagios to regenerate
the status file.
schedule_hostgroup_downtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This method is used for creating fixed length downtimes on all the hosts
belonging to a hostgroup. You are allowed to specify the author and comment
to go with the downtime, too. The JSON parameters are:
*hostgroup*='STRING' [required]::
Which hostgroup to schedule a downtime for. This must be specified.
*duration*='INTEGER' [required]::
How many seconds this downtime will last for. They begin immediately
and continue for `duration` seconds before ending.
*services_too*='BOOL'::
Optional. If true, then we will schedule a downtime for all the hosts in
the hostgroup and all of the services on those hosts.
Potentially many downtimes are scheduled.
*author*='STRING'::
Optional. The name of the author. This is useful in UIs if you want
to disambiguate who is doing what.
*comment*='STRING'::
Optional. As above, useful in the UI.
The result of this method is a text string that indicates whether or
not the downtimes have been scheduled or if a different error occurred.
We do not have the ability to get the `downtime_id` that is generated,
unfortunately, as that would require waiting for Nagios to regenerate
the status file.
state
~~~~~
This method takes no parameters. It returns a large JSON object
containing all of the active state from Nagios. Included are all hosts,
services, downtimes, comments, and other things that may be in the
global state object.
submit_result
~~~~~~~~~~~~~
If you are using passive service checks or you just want to submit a
result for a check, you can use this method to submit your result to
Nagios.
*host*='STRING' [required]::
The host to submit a result for. This is required.
*service*='STRING'::
Optional. If specified, we will submit a result for this service on
the above host. If not specified, then the result will be submitted
for the host itself.
*status*='INTEGER' [required]::
The status code to set this host/service check to. If you are
updating a host's status: 0 = OK, 1 = DOWN, 2 = UNREACHABLE. For
service checks, 0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN.
*output*='STRING' [required]::
The plugin output to be displayed in the UI and stored. This is a
single line of text, normally returned by checkers.
The response indicates if we successfully wrote the command to the log.
AUTHOR
------
Written by Mark Smith <[email protected]> while under the employ of Bump
Technologies, Inc.
COPYING
-------
See the LICENSE file for licensing information.