-
Notifications
You must be signed in to change notification settings - Fork 2
/
QUICKSTART.txt
161 lines (109 loc) · 5.25 KB
/
QUICKSTART.txt
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
===========
00. Content
===========
- 01. On the remote host
- 02. On the Nagios host
======================
01. On the remote host
======================
---------------------------
01.01. Create a "conf" file
---------------------------
Disclaimer:
For now, we use a INI-like format. This may change in the future!
You may use "sample-configs/conf/nagixsc_debian.conf" (Debian setup) or
"sample-configs/conf/nagixsc_usrlocal.conf" (installed from source to
/usr/local/nagios/) as templates.
One section for each monitored host is required. The section name (in square
brackets) is the Nagios hostname. The section includes service descriptions
and the commands to be executed.
Option names starting with an underscore are considered Nag(ix)SC-internal
definitions and, thus, are not treated as services. The following internal
options are available:
- "_host_name": Set the hostname to the one specified, overwriting the section
name.
The section named "[nagixsc]" is reserved for future extensions!
----------------------------------------------
01.02. Executing checks, Creating the XML file
----------------------------------------------
For debugging and testing purposes, create the XML file on the command line:
% ./nagixsc_conf2xml.py -e plain -c sample-configs/conf/nagixsc.conf
The switch "-e plain" disables encoding of the data to get human-readable
output. This should not be used in production!
The output will give a good idea about how Nag(ix)SC works internally. Now,
you should go ahead and create a small custom config file ;-)
Then, create an XML file suitable for further processing:
% ./nagixsc_conf2xml.py -c sample-configs/conf/nagixsc.conf -o /tmp/nagixsc.xml
This XML file may be made published by a web-server to be queried from Nagios.
----------------------------
01.03. Checking the XML file
----------------------------
Use "nagixsc_read_xml.py" to dump the content of an Nag(ix)SC XML file:
% ./nagixsc_read_xml.py -f /tmp/nagixsc.xml
The content will be displayed as one block for each check or as formatted
Python dictionary.
======================
02. On the Nagios host
======================
------------------------------------
02.01. Transfer of the check results
------------------------------------
There are two ways to access the check results: either by making them
available in the filesystem ("-f") or by accessing a web-server ("-u"). In the
examples, we'll use the former approach.
The tool "nagixsc_xml2nagios.py" supports five different modes of operation,
specified by the "-O" switch:
- "passive": Submit the results as passive service check to Nagios using the
Nagios command pipe. No output is generated making it suitable
for processing by cron.
- "passive_check": Submit passive service checks using the output format and
return code of Nagios plugins (one line of output and
appropriate exit code).
- "checkresult": Dump the results to the Nagios "checkresults" directory. This
is also suitable for cron.
- "checkresult_check": Same as "checkresult" but behave like a Nagios plugin
(one line of output and appropriate exit code).
- "active": Look for a host/service tuple in the XML file and behave like a
Nagios plugin.
Examples:
% ./nagixsc_xml2nagios.py -O passive -f /tmp/nagixsc.xml
%
% ./nagixsc_xml2nagios.py -O passive_check -f /tmp/nagixsc.xml
Nag(ix)SC OK - Check results are 25077576 seconds old
%
% ./nagixsc_xml2nagios.py -O checkresult -f /tmp/nagixsc.xml
%
% ./nagixsc_xml2nagios.py -O checkresult_check -f /tmp/nagixsc.xml
Nag(ix)SC OK - Wrote checkresult files for 6 services
%
% ./nagixsc_xml2nagios.py -O active -f /tmp/nagixsc.xml -D Disk_Root
DISK OK - free space: / 2167 MB (22% inode=97%);| /=7353MB;8568;9044;0;9520
%
Nag(ix)SC tries to auto-detect the location of "nagios.cmd" and the
"checkresult" directory. If this does not work, you can specify the locations
using the "-p" (pipe) and "-r" (resultdir) options.
For testing and debugging, create temporary files and have a look at the
generated output:
% touch /tmp/nagixsc.cmd # or: mkdir /tmp/nagixsc.result
% nagixsc_xm2nagios.py -p /tmp/nagixsc.cmd [...]
# or: nagixsc_xm2nagios.py -r /tmp/nagixsc.result
--------------------
02.02. Outdated data
--------------------
Data older than four hours (14400 seconds) is considered to be outdated by
"nagixsc_xml2nagios.py" and marked using "Nag(ix)SC: Check result is XX(>1440)
seconds old". This behavior may be customized using the following options:
- "-s SEC": specify the maximum age after which to consider data outdated
- "-m": let the check return the status UNKNOWN when encountering outdated
data
-------------------------
02.03. Further parameters
-------------------------
- "-S": Verify the XML file using the specified DTD file. Nag(ix)SC ships the
file "xml/nagixsc.dtd" for this purpose (no guarantees whatsoever,
though ;-))
- "-H": Filter the XML file for the specified hostname and ignore checks for
different hosts. This may be combined with all variants.
- "-D": Filter the XML file for the specified (service) description. If
combined with "-H", look for the given host/service tuple. Else, use
the first host specified in the XML file.