-
Notifications
You must be signed in to change notification settings - Fork 471
/
munin-doc-base.html
325 lines (299 loc) · 12.1 KB
/
munin-doc-base.html
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
<html>
<head>
<title>Munin
</title>
</head>
<body bgcolor=white text=black>
<h2>Background</h2>
Munin is a server/node pair that graph, htmlifies and optionaly
warns nagios about data it gathers. It's designed to let it be very easy to
graph new datasources.
<h2>The Node</h2>
<h3>munin-node</h3>
Munin-node is a small perlscript listening to port 4949 using
Net::Server. It reads all the scripts in /etc/munin/plugins on
startup. The node accepts these commands:
<tt>
<dl>
<dt>list [node]<dd>list available scripts for this node
<dt>nodes<dd>List availbale nodes
<dt>config [script]<dd>output configuration for [script]
<dt>fetch [script]<dd>output script values
<dt>version<dd>Output version string
<dt>quit<dd>disconnect
</dl>
</tt>
<h3>Scripts</h3>
These scripts can be in your language of choice: bash, perl, python, C,
or anything else that your system can execute. The scripts can be run in
several modes, the important ones being without parameters, and with the
"config"-parameter. When run with "config" as parameter, the script
should output the configuration of the graph.
<pre>
jo@yes:~$ munin-run load config
graph_title Load average
graph_args --base 1000 -l 0
graph_vlabel load
graph_scale no
load.label load
load.warning 10
load.critical 120
</pre>
The node supports quite a few options.
<dl>
<dt><code>graph_title</code><dd>The title of the graph, defaults to the servicename.</dd>
<dt><code>create_args</code><dd>If set, the arguments will be passed on to rrdcreate.</dd>
<dt><code>graph_args</code><dd>If set, the arguments will be passed on to rrdgraph.</dd>
<dt><code>graph_order</code><dd>In witch order to draw the datasources. Can also include path aliases on the form alias=domain;host:graph.datasource. See further down for details.</dd>
<dt><code>graph_vlabel</code><dd>Y-axis label of the graph. </dd>
<dt><code>graph_vtitle</code><dd>Y-axis label of the graph. NOTE: Deprecated, use graph_vlabel.</dd>
<dt><code>graph_info</code><dd>A description of the graph contents.</dd>
<dt><code>graph_total</code><dd>If set, summarise all the datasources' values and use the value of graph_total as a label.</dd>
<dt><code>graph_scale</code><dd>Default on. If set, disables scaling of min/max/cur values.</dd>
<dt><code>graph</code><dd>Set to "yes" or "no". Decides wether to draw the graph. Defaults to "yes".</dd>
<dt><code>update</code><dd>Set to "yes" or "no". Decides wether munin-update should fetch data for the graph. Defaults to "yes".</dd>
<dt><code>host_name</code><dd>Override which host name this plugin is run for. Ugly -
see further down on how to do this in the node configuration files
instead, which is more elegant.</dd>
<dt><code>{name}.label</code><dd>REQUIRED. Name of the datasource. You can have many
datasouces in one graph.</dd>
<dt><code>{name}.cdef</code><dd>RPN-expression. Modify the values before graphing. See the FAQ for examples.</dd>
<dt><code>{name}.draw</code><dd>What to draw from the data source: AREA, LINE1-3. Defaults to LINE2.</dd>
<dt><code>{name}.graph</code><dd>Set to "no" or "yes. Decides wether to graph the data source. Defaults to yes.</dd>
<dt><code>{name}.max</code><dd>Maximum value. If the fetched value is above "max", it will be discarded.</dd>
<dt><code>{name}.min</code><dd>Minimum value. If the fetched value is below "min", it will be discarded.</dd>
<dt><code>{name}.negative</code><dd>Name of field to 'mirror' on the opposite side of zero. See the FAQ for examples.</dd>
<dt><code>{name}.skipdraw</code><dd>Disables drawing of datasource. NOTE: Deprecated - use {name}.graph instead.</dd>
<dt><code>{name}.info</code><dd>A description of the field.</dd>
<dt><code>{name}.type</code><dd>Type of datasource, COUNTER, ABSOLUTE, DERIVE and
GAUGE, defaults to GAUGE. Read "man rrdcreate" for more info. </dd>
<dt><code>{name}.warning</code><dd>Used by munin-nagios. Can be a max value or a range
sepereated by colon. E.g. "min:", ":max", "min:max", "max".</dd>
<dt><code>{name}.critical</code><dd>Same as above.</dd>
</dl>
{name} is limited to 19 characters, and the characters [a-zA-Z0-9_].<br>
<p>
Without options the script should only give out {name}.value
(value):
<pre>
jo@yes:~$ munin-run load
load.value 0.41
</pre>
<p>
All scriptnames containing other characters than alphanumerics, "-",
"_", and ".", or starting with "." will be skipped.
</p>
<p>
To run a plugin as a specific user and/or group, create a file in the
plugin configuration. This file is parsed as munin-node starts up. It
can contain the following options:
<dl>
<dt>[<plugin-name>]<dd>The following lines are for
<code>plugin-name</code>.
<dt><code>user <username|userid></code><dd>Run plugin as this user
<dt><code>group <groupname|groupid>[, <groupname|groupid>] [...]</code><dd>Run plugin as this group. If group is inside paranthesis, don't croak if it's nonexistant.
<dt><code>command <command></code><dd>Run command instad of plugin. "%c" will
be expanded to what would otherwise have been run. E.g. "<code>command sudo
-u root %c</code>".
<dt><code>allow <regex></code><dd>Allow hosts matching regex to run this plugin.
<dt><code>deny <regex></code><dd>Deny hosts matching regex from running this plugin.
<dt><code>env.<var> <contents></code><dd>Will cause the environment
variable <code>var</code> to be set to <code>contents</code> when
running the plugin.
</dl>
Example:
<pre>
[exim_mailstats]
group mail
[cps_*]
user root
# Will cause the variable "mysqlopts" to be set...
[mysql_*]
env.mysqlopts --user foo --password fii
</pre>
</p>
<h3>File locations</h3>
According to <a href="http://www.pathname.com/fhs/">FHS</a>, this is
where you should place the files.
<h4>System package (Debian, RedHat, maybe others)</h4>
<dl>
<dt>CONFDIR<dd>/etc/munin/
<dt>SBINDIR<dd>/usr/sbin/
<dt>LIBDIR<dd>/usr/share/munin/
<dt>STATEDIR<dd>/var/run/munin/
<dt>LOGDIR<dd>/var/log/munin/
</dl>
<h4>Independent install (tarball)</h4>
<dl>
<dt>CONFDIR<dd>/etc/opt/munin/
<dt>SBINDIR<dd>/opt/munin/sbin/
<dt>LIBDIR<dd>/opt/munin/lib/
<dt>STATEDIR<dd>/var/run/munin/
<dt>LOGDIR<dd>/var/log/munin/
</dl>
<h2>The Server</h2>
The server runs a cronjob as the user munin every 5 minutes. The cronjob
runs munin-update,munin-nagios,munin-graph and munin-html one by one. All
scripts creates a lockfile in @@STATEDIR@@.
Everytime a script starts, it checks if the pid in the lockfile is alive
before starting.
<h3>/etc/munin/munin.conf</h3>
This is the configuration-file for all serverscripts.
<pre>
#Configfile for munin-server
dbdir /var/lib/munin/
htmldir /var/www/munin/
logdir /var/log/munin
rundir /var/run/munin/
#To warn Nagios
#nsca /usr/bin/send_nsca
#nsca_config /etc/nagios/send_nsca.cfg
#nsca_server nagios.server.org
#
# Edit and uncomment the following to start surveilance
#
#[machine.testdomain.org]
# address localhost
</pre>
Explaination:
<tt>
<dl>
<dt>dbdir<dd>Rootdir for alle rrd-files (files go into $dbdir/$domain/)
<dt>htmldir<dd>Where to png's and htmlfiles end up
<dt>logdir<dd>Where to send logs
<dt>rundir<dd>Where to put state files
<dt>htaccess<dd>The default htaccessfile
<dt>tmpldir<dd>Where the templates reside
<dt>graph_strategy<dd>Set to "cron" to draw the graphs periodically via cron every 5 minutes. Set to "cgi" to draw on-demand. (default cron)
<dt>fork<dd>If set, run updates of several hosts simultaneously. (default yes)
<dt>max_processes<dd>Set max number of simultaneous Munin processes.
<dt>nsca*<dd>Nagios options. See seperate section
<dt>domain_order<dd>Change the order of domains. (Default is alphabetically sorted.)
<dt>[foo.com;machine.dom.ain]<dd>Add machine.dom.ain to domain foo.com.
<dt>[machine.dom.ain]<dd>Add machine.dom.ain to domain dom.ain. (A short form of [dom.ain;machine.dom.ain].)
</dl>
</tt>
To add a new node, just put in a new section and add the
<tt>address</tt> option.
Domain-level options
<tt>
<dl>
<dt>node_order<dd>Changes order of nodes in a domain. (Default is alphabetically sorted.)
</dl>
</tt>
Node-level options
<tt>
<dl>
<dt>address<dd>Set the node address
<dt>port<dd>Set node port number (default 4949)
<dt>use_node_name<dd>Set to "yes" or "y" to force getting all the
default plugins from a node. Good for hosts which changes hostname
(e.g. laptops).
<dt>use_default_name<dd>Set to "yes" or "y" to force getting all the
default plugins from a node. Good for hosts which changes hostname
(e.g. laptops). NOTE: Deprecated. Use use_node_name instaed.
</dl>
</tt>
Field-level options
<tt>
<dl>
<dt>sum<dd>Summarise other fields. See the FAQ for how to use this.
<dt>stack<dd>Stack other fields. See the FAQ for how to use this.
<dt>+++<dd>Check the node configuration (further up) for everything else.
</dl>
</tt>
<h3>munin-update</h3>
Munin-update reads /etc/munin/munin.conf, searches for nodes,
and connect to the munin-nodes using the address-field. When connected
it will run the list-command to fetch available scripts, then it will
run config for each script. This configuration will expand in the
/etc/munin/munin.conf-file and rdd-databases will be created.
Already expanded configuration will be skipped. Then munin-update runs
through it's newly modified configuration file and runs <tt>fetch</tt> on all
scripts.
<h3>munin-graph</h3>
Munin-graph reads /etc/munin/munin.conf and graphs all services
unless <tt>[service].graph no</tt>. The following options are available
in the configuration
<dl>
limited to 19 characters
<dt>[service].graph_title<dd>The title of the graph
<dt>[service].graph_order<dd>Which order to graph the lines.
<dt>[service].graph_args<dd>Extra arguments to the graph
<dt>[field].label<dd>REQUIRED, the name of the value to be graphed,
<dt>[field].type<dd>Type of value. COUNTER, GAUGE, defaults to GAUGE.
NOTE: When GAUGE is used, only "snapshots" of every 5 minutes are
recorded. Peaks in-between updates will not be graphed. When you use
COUNTER, the numbers are averaged out over the past 5 minutes, so short
peaks will show up as substancially lower than they were.
</dl>
<h3>munin-html</h3>
Munin-html creates the html-pages for the graphs.<br>
Usefull configuration in the server.conf file is:
<dt>node_order [node1] [node2] .... <dd>In which order the nodes
should be listed, defaults to sorted. This is a domain-level
option.</dd>
<dt>domain_order [domain1] [domain2] .... <dd>In which order the domains
should be listed, defaults to sorted. This is a top-level option.</dd>
<h3>munin-nagios</h3>
Munin-nagios is a optional script to send a passive alert to a
nagios-server. For this to work, you need a nagios-nsca server,
a working send_nsca configuration and the following configuration in
/etc/munin/munin.conf:
<pre>
nsca /usr/bin/send_nsca
nsca_config /etc/nagios/send_nsca.cfg
nsca_server [nsca-server]
</pre>
Then add .warning and .critical fields in your configuration or
directly into you plugin scripts.
The value for these field can be a single maxvalue or a colonseperated
range
<pre>
processes.warning 10:300
processes.critical 5:500
</pre>
A value lower than 10 or higher then 300 will result in a warning to
nagios, a value lower than 5 or higher than 500 will result in a
critical to nagios
<p>
Other usefull ranges:
<pre>
[service].warning :400
</pre>
is equal to:
<pre>
[service].warning 400
</pre>
Only warn if lower than 300:
<pre>
[service].warning 300:
</pre>
When a service contains .critical or .warning it will chech it's status
agains the last fetched value. If it's ok, a "{service}.ok" file will be created
in the $dbdir/$domain directory. If the value is not ok. This file will
be removed and munin-nagios will update nagios every 5 minutes untill the
value is ok and a new ".ok" file will be created.
<h3>File locations</h3>
According to <a href="http://www.pathname.com/fhs/">FHS</a>, this is
where you should place the files.
<h4>System package (Debian, RedHat, maybe others)</h4>
<dl>
<dt>CONFDIR<dd>/etc/munin/
<dt>SBINDIR<dd>/usr/sbin/
<dt>LIBDIR<dd>/usr/share/munin/
<dt>STATEDIR<dd>/var/run/munin/
<dt>LOGDIR<dd>/var/log/munin/
<dt>DBDIR<dd>/var/lib/munin/
</dl>
<h4>Independent install (tarball)</h4>
<dl>
<dt>CONFDIR<dd>/etc/opt/munin/
<dt>SBINDIR<dd>/opt/munin/sbin/
<dt>LIBDIR<dd>/opt/munin/lib/
<dt>STATEDIR<dd>/var/run/munin/
<dt>LOGDIR<dd>/var/log/munin/
<dt>DBDIR<dd>/var/opt/munin/
</dl>
</body>
</html>