6
<body bgcolor=white text=black>
8
Munin is a server/node pair that graph, htmlifies and optionaly
9
warns nagios about data it gathers. It's designed to let it be very easy to
10
graph new datasources.
15
Munin-node is a small perlscript listening to port 4949 using
16
Net::Server. It reads all the scripts in /etc/munin/plugins on
17
startup. The node accepts these commands:
20
<dt>list [node]<dd>list available scripts for this node
21
<dt>nodes<dd>List availbale nodes
22
<dt>config [script]<dd>output configuration for [script]
23
<dt>fetch [script]<dd>output script values
24
<dt>version<dd>Output version string
25
<dt>quit<dd>disconnect
30
These scripts can be in your language of choice: bash, perl, python, C,
31
or anything else that your system can execute. The scripts can be run in
32
several modes, the important ones being without parameters, and with the
33
"config"-parameter. When run with "config" as parameter, the script
34
should output the configuration of the graph.
36
jo@yes:~$ munin-run load config
37
graph_title Load average
38
graph_args --base 1000 -l 0
45
The node supports quite a few options.
47
<dt><code>graph_title</code><dd>The title of the graph, defaults to the servicename.</dd>
48
<dt><code>create_args</code><dd>If set, the arguments will be passed on to rrdcreate.</dd>
49
<dt><code>graph_args</code><dd>If set, the arguments will be passed on to rrdgraph.</dd>
50
<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>
51
<dt><code>graph_vlabel</code><dd>Y-axis label of the graph. </dd>
52
<dt><code>graph_vtitle</code><dd>Y-axis label of the graph. NOTE: Deprecated, use graph_vlabel.</dd>
53
<dt><code>graph_total</code><dd>If set, summarise all the datasources' values and use the value of graph_total as a label.</dd>
54
<dt><code>graph_scale</code><dd>Default on. If set, disables scaling of min/max/cur values.</dd>
55
<dt><code>graph</code><dd>Set to "yes" or "no". Decides wether to draw the graph. Defaults to "yes".</dd>
56
<dt><code>update</code><dd>Set to "yes" or "no". Decides wether munin-update should fetch data for the graph. Defaults to "yes".</dd>
57
<dt><code>host_name</code><dd>Override which host name this plugin is run for. Ugly -
58
see further down on how to do this in the node configuration files
59
instead, which is more elegant.</dd>
60
<dt><code>{name}.label</code><dd>REQUIRED. Name of the datasource. You can have many
61
datasouces in one graph.</dd>
62
<dt><code>{name}.cdef</code><dd>RPN-expression. Modify the values before graphing. See the FAQ for examples.</dd>
63
<dt><code>{name}.draw</code><dd>What to draw from the data source: AREA, LINE1-3. Defaults to LINE2.</dd>
64
<dt><code>{name}.graph</code><dd>Set to "no" or "yes. Decides wether to graph the data source. Defaults to yes.</dd>
65
<dt><code>{name}.max</code><dd>Maximum value. If the fetched value is below "max", it will be discarded.</dd>
66
<dt><code>{name}.min</code><dd>Minimum value. If the fetched value is below "min", it will be discarded.</dd>
67
<dt><code>{name}.negative</code><dd>Name of field to 'mirror' on the opposite side of zero. See the FAQ for examples.</dd>
68
<dt><code>{name}.skipdraw</code><dd>Disables drawing of datasource. NOTE: Deprecated - use {name}.graph instead.</dd>
69
<dt><code>{name}.type</code><dd>Type of datasource, COUNTER, ABSOLUTE, DERIVE and
70
GAUGE, defaults to GAUGE. Read "man rrdcreate" for more info. </dd>
71
<dt><code>{name}.warning</code><dd>Used by munin-nagios. Can be a max value or a range
72
sepereated by colon. E.g. "min:", ":max", "min:max", "max".</dd>
73
<dt><code>{name}.critical</code><dd>Same as above.</dd>
75
{name} is limited to 19 characters, and the characters [a-zA-Z0-9_].<br>
77
Without options the script should only give out {name}.value
80
jo@yes:~$ munin-run load
84
All scriptnames containing other characters than alphanumerics, "-",
85
"_", and ".", or starting with "." will be skipped.
88
To run a plugin as a specific user and/or group, create a file in the
89
plugin configuration. This file is parsed as munin-node starts up. It
90
can contain the following options:
92
<dt>[<plugin-name>]<dd>The following lines are for
93
<code>plugin-name</code>.
94
<dt><code>user <username|userid></code><dd>Run plugin as this user
95
<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.
96
<dt><code>command <command></code><dd>Run command instad of plugin. "%c" will
97
be expanded to what would otherwise have been run. E.g. "<code>command sudo
99
<dt><code>env.<var> <contents></code><dd>Will cause the environment
100
variable <code>var</code> to be set to <code>contents</code> when
111
# Will cause the variable "mysqlopts" to be set...
113
env.mysqlopts --user foo --password fii
117
<h3>File locations</h3>
118
According to <a href="http://www.pathname.com/fhs/">FHS</a>, this is
119
where you should place the files.
120
<h4>System package (Debian, RedHat, maybe others)</h4>
122
<dt>CONFDIR<dd>/etc/munin/
123
<dt>SBINDIR<dd>/usr/sbin/
124
<dt>LIBDIR<dd>/usr/share/munin/
125
<dt>STATEDIR<dd>/var/run/munin/
126
<dt>LOGDIR<dd>/var/log/munin/
129
<h4>Independent install (tarball)</h4>
131
<dt>CONFDIR<dd>/etc/opt/munin/
132
<dt>SBINDIR<dd>/opt/munin/sbin/
133
<dt>LIBDIR<dd>/opt/munin/lib/
134
<dt>STATEDIR<dd>/var/run/munin/
135
<dt>LOGDIR<dd>/var/log/munin/
140
The server runs a cronjob as the user munin every 5 minutes. The cronjob
141
runs munin-update,munin-nagios,munin-graph and munin-html one by one. All
142
scripts creates a lockfile in @@STATEDIR@@.
144
Everytime a script starts, it checks if the pid in the lockfile is alive
147
<h3>/etc/munin/munin.conf</h3>
148
This is the configuration-file for all serverscripts.
151
#Configfile for munin-server
152
dbdir /var/lib/munin/
153
htmldir /var/www/munin/
154
logdir /var/log/munin
155
rundir /var/run/munin/
158
#nsca /usr/bin/send_nsca
159
#nsca_config /etc/nagios/send_nsca.cfg
160
#nsca_server nagios.server.org
163
# Edit and uncomment the following to start surveilance
165
#[machine.testdomain.org]
174
<dt>dbdir<dd>Rootdir for alle rrd-files (files go into $dbdir/$domain/)
175
<dt>htmldir<dd>Where to png's and htmlfiles end up
176
<dt>logdir<dd>Where to send logs
177
<dt>rundir<dd>Where to put state files
178
<dt>htaccess<dd>The default htaccessfile
179
<dt>tmpldir<dd>Where the templates reside
180
<dt>fork<dd>If set, run updates of several hosts simultaneously. (default yes)
181
<dt>max_processes<dd>Set max number of simultaneous Munin processes.
182
<dt>nsca*<dd>Nagios options. See seperate section
183
<dt>domain_order<dd>Change the order of domains. (Default is alphabetically sorted.)
184
<dt>[foo.com;machine.dom.ain]<dd>Add machine.dom.ain to domain foo.com.
185
<dt>[machine.dom.ain]<dd>Add machine.dom.ain to domain dom.ain. (A short form of [dom.ain;machine.dom.ain].)
189
To add a new node, just put in a new section and add the
190
<tt>address</tt> option.
195
<dt>node_order<dd>Changes order of nodes in a domain. (Default is alphabetically sorted.)
202
<dt>address<dd>Set the node address
203
<dt>port<dd>Set node port number (default 4949)
204
<dt>use_node_name<dd>Set to "yes" or "y" to force getting all the
205
default plugins from a node. Good for hosts which changes hostname
207
<dt>use_default_name<dd>Set to "yes" or "y" to force getting all the
208
default plugins from a node. Good for hosts which changes hostname
209
(e.g. laptops). NOTE: Deprecated. Use use_node_name instaed.
216
<dt>sum<dd>Summarise other fields. See the FAQ for how to use this.
217
<dt>stack<dd>Stack other fields. See the FAQ for how to use this.
218
<dt>+++<dd>Check the node configuration (further up) for everything else.
222
<h3>munin-update</h3>
223
Munin-update reads /etc/munin/munin.conf, searches for nodes,
224
and connect to the munin-nodes using the address-field. When connected
225
it will run the list-command to fetch available scripts, then it will
226
run config for each script. This configuration will expand in the
227
/etc/munin/munin.conf-file and rdd-databases will be created.
228
Already expanded configuration will be skipped. Then munin-update runs
229
through it's newly modified configuration file and runs <tt>fetch</tt> on all
232
Munin-graph reads /etc/munin/munin.conf and graphs all services
233
unless <tt>[service].graph no</tt>. The following options are available
236
limited to 19 characters
237
<dt>[service].graph_title<dd>The title of the graph
238
<dt>[service].graph_order<dd>Which order to graph the lines.
239
<dt>[service].graph_args<dd>Extra arguments to the graph
240
<dt>[field].label<dd>REQUIRED, the name of the value to be graphed,
241
<dt>[field].type<dd>Type of value. COUNTER, GAUGE, defaults to GAUGE.
242
NOTE: When GAUGE is used, only "snapshots" of every 5 minutes are
243
recorded. Peaks in-between updates will not be graphed. When you use
244
COUNTER, the numbers are averaged out over the past 5 minutes, so short
245
peaks will show up as substancially lower than they were.
248
Munin-html creates the html-pages for the graphs.<br>
249
Usefull configuration in the server.conf file is:
250
<dt>node_order [node1] [node2] .... <dd>In which order the nodes
251
should be listed, defaults to sorted. This is a domain-level
253
<dt>domain_order [domain1] [domain2] .... <dd>In which order the domains
254
should be listed, defaults to sorted. This is a top-level option.</dd>
255
<h3>munin-nagios</h3>
256
Munin-nagios is a optional script to send a passive alert to a
257
nagios-server. For this to work, you need a nagios-nsca server,
258
a working send_nsca configuration and the following configuration in
259
/etc/munin/munin.conf:
261
nsca /usr/bin/send_nsca
262
nsca_config /etc/nagios/send_nsca.cfg
263
nsca_server [nsca-server]
265
Then add .warning and .critical fields in your configuration or
266
directly into you plugin scripts.
267
The value for these field can be a single maxvalue or a colonseperated
270
processes.warning 10:300
271
processes.critical 5:500
273
A value lower than 10 or higher then 300 will result in a warning to
274
nagios, a value lower than 5 or higher than 500 will result in a
277
Other usefull ranges:
279
[service].warning :400
283
[service].warning 400
285
Only warn if lower than 300:
287
[service].warning 300:
290
When a service contains .critical or .warning it will chech it's status
291
agains the last fetched value. If it's ok, a "{service}.ok" file will be created
292
in the $dbdir/$domain directory. If the value is not ok. This file will
293
be removed and munin-nagios will update nagios every 5 minutes untill the
294
value is ok and a new ".ok" file will be created.
296
<h3>File locations</h3>
297
According to <a href="http://www.pathname.com/fhs/">FHS</a>, this is
298
where you should place the files.
299
<h4>System package (Debian, RedHat, maybe others)</h4>
301
<dt>CONFDIR<dd>/etc/munin/
302
<dt>SBINDIR<dd>/usr/sbin/
303
<dt>LIBDIR<dd>/usr/share/munin/
304
<dt>STATEDIR<dd>/var/run/munin/
305
<dt>LOGDIR<dd>/var/log/munin/
306
<dt>DBDIR<dd>/var/lib/munin/
309
<h4>Independent install (tarball)</h4>
311
<dt>CONFDIR<dd>/etc/opt/munin/
312
<dt>SBINDIR<dd>/opt/munin/sbin/
313
<dt>LIBDIR<dd>/opt/munin/lib/
314
<dt>STATEDIR<dd>/var/run/munin/
315
<dt>LOGDIR<dd>/var/log/munin/
316
<dt>DBDIR<dd>/var/opt/munin/
added
removed
munin-doc-base.html
