1----------
2NDO README
3----------
4
5
6****************
7ABOUT THIS ADDON
8****************
9
10The NDOUTILS (Nagios Data Output Utils) addon allows you to move status and event
11information from Nagios to a database for later retrieval and processing.
12
13This addon consists of several parts. Here are the most interesting ones...
14
151. The NDOMOD event broker module. This module is intended to be loaded
16 by the Nagios process at runtime. Its only role is to dump all events and
17 data from Nagios to a TCP socket or a regular file or Unix domain socket on
18 the local filesystem somewhere. If you want realtime transfer of data to MySQL,
19 dump the data to a TCP or Unix domain socket. If you want delayed transfer of
20 data into MySQL (i.e. you need to transfer the data to another host first),
21 dump the data to a regular file.
22
232. The NDO2DB daemon. This standalone daemon reads input (that was produced
24 by the NDOMOD broker module) from a TCP or Unix domain socket, parses that
25 data, and then dumps it into one or more MySQL databases. The daemon is
26 capable of handling multiple client connections simultaneously, so you can
27 have multiple instances of the NDOMOD module writing to the same TCP or Unix
28 domain socket at the same time.
29
303. The FILE2SOCK utility. This simple utility reads data from a standard file
31 and dumps it to either a TCP or a Unix domain socket. This is useful if you
32 are having the NDOMOD module write to a standard file that you later want to
33 send to the NDO2DB daemon. If the module and the daemon are running on
34 different machines, you can periodically use SSH to transfer the file from the
35 monitoring machine to the machine running the NDO2DB daemon, and then use the
36 FILE2SOCK utility to send the contents of that file to the TCP socket or Unix
37 domain socket that the NDO2DB daemon is reading.
38
394. The LOG2NDO utility. This utility is used for importing historical log
40 archives from NetSaint and Nagios and sending them to the NDO2DB daemon.
41 It takes a single log file as its input and can output data to either a
42 TCP socket, a Unix domain socket or standard output.
43
44
45
46
47**********************
48COMPILING INSTRUCTIONS
49**********************
50
51Use the following commands to compile the NDO broker module, NDO2DB daemon, and
52additional utilities:
53
54 ./configure
55 make
56
57If the configure script is unable to locate your MySQL development libraries,
58you may need to help it out by using the --with-mysql-lib or option. Here's an
59example:
60
61 ./configure --with-mysql-lib=/usr/lib/mysql
62
63
64
65*****************************
66INITIALIZING THE SQL DATABASE
67*****************************
68
69Before you start using the NDO utilities, you should create the database where
70you will be storing all Nagios-related information.
71
72NOTE: As of 02/12/2006, only MySQL databases are supported.
73
74
751. Create a database for storing the data (e.g. 'nagios')
76
772. Create a username/password that has at least the following privileges for
78 the database:
79
80 SELECT, INSERT, UPDATE, DELETE
81
823. Run the DB installation script in the db/ subdirectory of the NDO distribution
83 to create the necessary tables in the database.
84
85 cd db
86 ./installdb
87
884. Make sure the database name, prefix, and username/password you just created
89 and setup match the variable specified in the NDO2DB config file (see below).
90
91
92
93***********************************
94INSTALLING THE NDOMOD BROKER MODULE
95***********************************
96
97NOTE:
98There are two different versions of the NDOMOD module that
99get compiled, so make sure you use the module that matches the
100version of Nagios you are running, and adjust the directions given
101below to fit the name of the module version you're using.
102
103 ndomod-2x.o = NDOMOD module for Nagios 2.x
104 ndomod-3x.o = NDOMOD module for Nagios 3.x
105 ndomod-4x.o = NDOMOD module for Nagios 4.x
106
107
1081. Copy the compiled NDOMOD module to your Nagios installation:
109
110 cp src/ndomod-2x.o /usr/local/nagios/bin/ndomod.o
111
112 The command above assumes that you are using Nagios 2.x, and thus
113 are installing the 2.x version of the NDOMOD module.
114
1152. Copy the sample NDOMOD config file to your Nagios installation
116 after modifying it to suit your needs:
117
118 cp config/ndomod.cfg /usr/local/nagios/etc
119
120
1213. Add a line similar to the following to the *main* Nagios config
122 file (usually /usr/local/nagios/etc/nagios.cfg):
123
124 broker_module=/usr/local/nagios/bin/ndomod.o config_file=/usr/local/nagios/etc/ndomod.cfg
125
126 The config directive above will cause Nagios to load the NDOMOD
127 event broker the next time it starts. Of course, this requires that
128 you compiled Nagios with support for the event broker in the first
129 place. :-)
130
131
1324. Make sure you have a line similar to the following in the *main* Nagios
133 config file (usually /usr/local/nagios/etc/nagios.cfg):
134
135 event_broker_options=-1
136
137 That directive will cause the Nagios daemon to send data to the NDOMOD
138 module. Without that option, NDOMOD won't get any information.
139
1405. ndomod processing options. As of ndoutils2.x, users can define which
141 types of data are processed and stored by ndoutils. Each of these options
142 can be defined in the ndomod.cfg file, and are considered a replacement for
143 previous ndomod_processing_options config option, which used a bitmask. The
144 following processing options are available.
145
146 acknowledgement_data=1
147 adaptive_contact_data=1
148 adaptive_host_data=1
149 adaptive_program_data=1
150 adaptive_service_data=1
151 aggregated_status_data=1
152 comment_data=1
153 contact_status_data=1
154 downtime_data=1
155 event_handler_data=1
156 external_command_data=1
157 flapping_data=1
158 host_check_data=1
159 host_status_data=1
160 log_data=1
161 main_config_data=1
162 notification_data=1
163 object_config_data=1
164 process_data=1
165 program_status_data=1
166 retention_data=1
167 service_check_data=1
168 service_status_data=1
169 statechange_data=1
170 system_command_data=1
171 timed_event_data=1
172
173
174****************************
175INSTALLING THE NDO2DB DAEMON
176****************************
177
178NOTE:
179There are two different versions of the NDO2DB daemon that
180get compiled, so make sure you use the daemon that matches the
181version of Nagios you are running, and adjust the directions given
182below to fit the name of the daemon you're using.
183
184 ndo2db-2x.o = NDO2DB daemon for Nagios 2.x
185 ndo2db-3x.o = NDO2DB daemon for Nagios 3.x
186 ndo2db-4x.o = NDO2DB daemon for Nagios 4.x
187
188
1891. Copy the compiled NDO2DB daemon to your Nagios installation:
190
191 cp src/ndo2db-2x /usr/local/nagios/bin/ndo2db
192
193 The command above assumes that you are using Nagios 2.x, and thus
194 are installing the 2.x version of the NDO2DB daemon.
195
1962. Copy the sample NDO2DB config file to your Nagios installation
197 after modifying it to suit your needs (pay attention to the DB
198 config settings).
199
200 cp config/ndo2db.cfg /usr/local/nagios/etc
201
2023. Start the daemon running! An init script will be developed soon...
203
204 /usr/local/nagios/bin/ndo2db -c /usr/local/nagios/etc/ndo2db.cfg
205
206
207
208
209************************
210TUNING KERNEL PARAMETERS
211************************
212
213NDOUTILS uses a single message queue to communicate between the broker
214module and the NDO2DB daemon. Depending on the operating system, there
215may be parameters that need to be tuned in order for this communication
216to work correctly. The discussion below applies specifically to Linux,
217but may apply generally to other Unices as well.
218
219There are three Linux kernel parameters that determine the resources
220provided to the messaging subsystem:
221 * kernel.msgmax is the maximum size of a single message in a
222 message queue
223 * kernel.msgmni is the maximum number of messages allowed in any
224 one message queue
225 * kernel.msgmnb is the total number of bytes allow in all messages
226 in any one message queue
227
228To see the current values for any of these parameters, cat
229/proc/sys/kernel/msg{max|mni|mnb}.
230
231In order for NDOUTILS to work at all, kernel.msgmax must be greater than
232the size of the queue_msg struct (currently 1026 bytes). Most Linux
233distributions set kernel.msgmax to a default of 65536.
234
235If there are insufficient resources for sending messages between the
236broker and the daemon, you will see an entry similar to the following
237in your logs. (This is logged via the syslog facility, using the level
238LOG_ERR and the default facility.)
239
240 ndo2db: Warning: Retrying message send. This can occur because
241 you have too few messages allowed or too few total bytes
242 allowed in message queues. You are currently using 16 of 16
243 mesages and 65536 of 65536 bytes in the queue. See README for
244 kernel tuning options.
245
246If you see this entry, the message will likely eventually be sent,
247but retrying uses system resources, and there is the possibility that
248more messages will queued than can be handled, causing the broker
249module to stall.
250
251If you are close to or have exceeded the number of messages, you may
252need to increase kernel.msgmni. If you are close to or have exceeded
253the number of bytes in the queue, you may need to increase
254kernel.msgmnb. In some cases you may need to increase both.
255
256A conservative approach would be to double the necessary value, stop
257and restart both the NDO2DB daemon and Nagios Core, and watch for any
258further messages. Note that if NDO2DB is started after Nagios Core,
259you may see the warning above as the broker module first attempts to
260flush its backlog of messages.
261
262To increase a value, echo the value to /proc/sys/kernel/msgmni or
263/proc/sys/kernel/msgmnb as appropriate.
264
265For example, to increase the number of messages allowed in the queue
266to 32, use the command 'echo 32 > /proc/sys/kernel/msgmni' (without
267the quotes).
268
269Once you have determine the correct parameters, you can make them
270permanent by editing /etc/sysctl.conf. Add or update the line of
271the form 'kernel.msg{mni|mnb} = <value>' with the value(s) determined
272above. The next time the system is booted, the values of the
273parameters in /etc/sysctl.conf will be loaded.
274