Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

313 lines (277 sloc) 9.886 kb
<html>
<head>
<title>Munin FAQ</title>
</head>
<body bgcolor=white text=black>
<h2>1. Installation</h2>
<h3>Q: What architectures are supported? What operating systems?</h3>
<p>
Munin is programmed in Perl, which can be installed on most operating
systems. In addition, it needs some perl modules, which you can fetch
from <a href="http://www.cpan.org/">CPAN</a>.
</p>
<p>
However, the "plugins" used by the client are often OS or application
spesific. E.g., many of the Linux-plugins use /proc to gather the data.
There are some plugins that should work on most architectures. The
architectures which have their own plugins as well, are
<tt>
<dl>
<dt>Linux<dd>
<dt>FreeBSD<dd>
<dt>SunOS (Solaris)<dd>
<dt>AIX<dd>
</dl>
</tt>
If you port/create/improve plugins, please contribute them to the
project.
</p>
<h2>2. Configuration</h2>
<h3>Q: What should a minimal configuration look like?</h3>
<p>
<pre>
dbdir /var/lib/munin
htmldir /var/www/munin
logdir /var/log/munin
rundir /var/run/munin
[bing.foo.bar]
address 10.232.33.259
</pre>
The server will expand the node to contain all the services it offers.
</p>
<h3>Q: How du I use the "fieldname.cdef"-thingie?</h3>
<p>
The cdef is fed to "rrdtool graph", so the man-page for "rrdgraph" should
give you a bit more info. I'll try to explain it briefly here, though;
</p>
<p>
The cdef is defined using Reverse Polish Notation (RPN), which means that
you would say "4,5,+" instead of "4+5". When you create a cdef-field, be
sure to use the fieldname at least once in the definition, or rrdgraph
will croak with an error.
</p>
<p>
For a more thorough definition of RPN, take a look at the man-page for
"rrdgraph".
</p>
<h3>Q: Can I get a graph to show percentages instead of regular values?</h3>
<p>
You can modify a graph with two data fields to a percentage view with
the following cdef (gotten from Nicolai Langfeldt). It uses two field
names, "hit" and "all", with "hit" being the field you want in
percentages of "all".
</p>
<p>
<code>
hit,all,1,all,0,EQ,IF,/,100,*,UNKN,all,0,EQ,IF,UNKN,all,UNKN,EQ,IF
</code>
</p>
<h3>Q: How do I define aliases with graph_order?</h3>
<p>
Normally, graph_order looks something like this:
<pre>
graph_order apps buffers cache unused swap
</pre>
It can, however, be used to define alises from other graphs. E.g. if you
want to incorporate the number of http-connections in the
"processes"-graph (i.e. together with the number of processes on the
machine), you'd say:
<pre>
graph_order processes connections=port_http.count
</pre>
This would first draw the "proesses" data-source (as normal), then draw
the "count" data-source from the "port_http"-graph. "connections" would
then be a field-name in the same way as "processes", so you could give it
a cdef, draw, negative, etc.
</p>
<p>
Example graph_orders:
<ul>
<li><code>graph_order bing bofh</code>
(will draw two normal values)</li>
<li><code>graph_order bing bang=bing</code>
(will draw two normal values, the second an alias to the first)</li
<li><code>graph_order bing bang=graph.bing</code>
("loan" a data-source from another graph)</li>
<li><code>graph_order bing bang=host:graph.bing</code>
("loan" a data-source from another host's graph)</li>
<li><code>graph_order bing bang=domain;host:graph.bing</code>
("loan" a data-source from another domain's graph)</li>
</ul>
</p>
<h3>Q: How do I use fieldname.stack?</h3>
<p>
The format of "special_stack" is the same as the graph_order-arguments
above. You cannot, however, specify extra arguments for the fields. If you
want to specify a cdef for the 'whole stack', you can use the fieldname
defining the special stack. E.g.
<pre>
[some.machine.boo]
total_mail.graph_order total_received
total_mail.graph_title Mail received by machine1 and machine2
total_mail.graph_vlabel mails/min
total_mail.total_received.label not_used
total_mail.total_received.stack \
machine1=machine1.your.dom:exim_mailstats.received \
machine2=machine2.your.dom:exim_mailstats.received
total_mail.total_received.cdef total_received,60,*
</pre>
</p>
<h3>Q: How do I use fieldname.sum?</h3>
<p>
Same as special_stack, with one exception: drop the "alias"-bit
in the field definition. I.e., the above would become:
<pre>
[some.machine.boo]
total_mail.graph_order total_received
total_mail.graph_title Mail received by machine1 and machine2
total_mail.graph_vlabel mails/min
total_mail.total_received.label mails per minute # Now used
total_mail.total_received.sum \
machine1.your.dom:exim_mailstats:received \
machine2.your.dom:exim_mailstats:received
total_mail.total_received.cdef total_received,60,*
</pre>
</p>
<h3>Q: Can I change the order of the domains?</h3>
<p>
Yes, use the "domain_order" option at the topmost level. To specify
that you want the topmost level, either put the option before any
host/domain definitions, or reset the host/domain definition with
"[]".
<pre>
[]
domain_order foo.bar goo.bar alpha.bar
</pre>
The default domain order is alphabetically.
</p>
<h3>Q: Can I change the order of the nodes under a domain?</h3>
<p>
Yes, use the "node_order" option under a domain. To specify that we
want to modify a variable under the domain, supply an empty host:
<pre>
[bing.foo.bar]
address 10.232.33.259
[fii.foo.bar]
address 10.232.33.259
[goo.foo.bar]
address 10.232.33.259
[foo.bar;]
node_order fii.foo.bar bing.foo.bar goo.foo.bar
</pre>
The default node order is alphabetically.
</p>
<h3>Q: How can I use an SSH tunnel to connect to a node?</h3>
<p>
You have to configure the node thusly:
</p>
<code>
[ssh-node]
address 127.0.0.1
port 5050
</code>
<p>
Then use ssh to establish the tunnel:
</p>
<code>ssh -L 5050:localhost:4949 -f -N -i keyfile user@ssh-node</code>
<p>
This will establish a tunnel between TCP ports 5050 on the calling
machine to 4949 on the called machine. It will also send ssh in the
background after possibly asking for a passphrase, a password or
something like that. Since we are using a key made for this purpose, we
have to specify that file with this key.
</p>
<p>
You should protect against misuse of ssh by creating a special key (and
possibly also a special user). On the node, put something like this in
~user/.ssh/authorized_keys:
</p>
<code>from="192.168.1.35",command="/bin/false",no-pty,no-X11-forwarding,no-agent-forwarding,no-port-forwarding,permitopen="localhost:4949" ssh-dss AAAAB3......</code>
<p>
Thus, we are restricting the key to a forced command "/bin/false" that
is run independent of the request from the calling side. We are also
restricting a few options:
</p>
<dl>
<dt><code>from="192.168.1.35"</code> <dd>accept the key only from this IP address
<dt><code>command="/bin/false"</code> <dd>always run this command
<dt><code>no-pty</code> <dd>never allocate a PTY for interactivity
<dt><code>no-X11-forwarding</code> <dd>do not forward X11 client connections
<dt><code>no-agent-forwarding</code> <dd>prevent ssh-agent usage
<dt><code>no-port-forwarding</code> <dd>prevent ssh -R ...
<dt><code>permitopen="localhost:4949"</code><dd>only allow this for ssh -L ...
</dl>
<p>
This FAQ entry was developed by Lupe Christoph, with the help of Jim Cheetham.
</p>
<h3>Q: I don't like the bandwith usage graph, how to make it look like MRTG or Cricket graphs?</h3>
<p>
For interface eth0 on host foo.bar.example,<pre>
if_eth0.graph no
my_ifeth0.graph_args --base 1000 --lower-limit 0
my_ifeth0.graph_title Traffic on interface eth0
my_ifeth0.graph_order received=foo.bar.example:if_eth0.down sent=foo.bar.example:if_eth0.up
my_ifeth0.graph_vlabel Bits per second
my_ifeth0.received.cdef received,8,*
my_ifeth0.received.draw AREA
my_ifeth0.sent.cdef sent,8,*
my_ifeth0.sent.draw LINE1
</pre>
(Answer supplied by Jacques Caruso.)
</p>
<h3>Q: I added the graph_sums option, bug I only get one new graph (instead of two).</h3>
<p>
The graph_sums option require that rrdtool version 1.0.39 or above is installed.
</p>
<h2>3. Client plugins</h2>
<h3>Q: What is the minimum requirements of a client plugin?</h3>
<p>
<ul>
<li>Without any parameters it should print "&lt;fieldname&gt;.value &lt;value&gt;"</li>
<li>It must support the "config"-parameter</li>
<li>With the config-parameter, it should print at least:
<ul>
<li>&lt;fieldname&gt;.label &lt;label_of_field&gt;</li>
</ul></li>
</ul>
An example plugin (on a linux-system, using /proc/loadavg to graph the load average):
<pre>
#!/bin/sh
if [ "$1" = "config" ]; then
echo "load.label load" # Field label (legend)
# These are not really nedded, but makes the graph prettier.
echo "graph_title Load average" # Set main title
echo 'graph_args -l 0' # Y-axis starts at 0
echo 'graph_scale no' # Say 0.04 load, not 40 milliload
echo 'graph_vlabel load' # Y-axis label
exit 0
fi
# The real data-gathering
printf "load.value "
cut -f1 -d' ' &lt; /proc/loadavg
</pre>
</p>
<h3>Q: Can I make the plugin run as another user/group than nobody/nogroup?</h3>
<p>
Yes, you can create a file in the plugin configuration directory
(client-conf.d). The file should contain the username and group to
run the plugin as. E.g., on linux, the exim_mailqueue-plugin need
access to the exim mail spool (to count the messages in the queue).
It needs "mail" group permissions to do this, so the
"exim_mailqueue.auth" contents look like:
<pre>
[exim_mailqueue]
group mail
</pre>
Similarly, you could use the "user" option to run the plugin as a user.
</p>
<p>
If more than one group is needed, or some of the groups only exist on certain hosts (and
you want a common config file), the syntax supports this:
<pre>
[some_plugin]
group mail,adm,group1,group2,(group3_that_might_not_exist)
</pre>
</p>
</body>
</html>
Jump to Line
Something went wrong with that request. Please try again.