Web www.freebsdmadeeasy.com
Main Menu

Monitoring FreeBSD with Munin

Munin is a monitoring tool available in the FreeBSD ports. It tracks the vital signs of your servers and charts everything on graphs by day, week, month and year. It makes it easy to see when your server gets spikes of traffic and how well it handles them. It can also show you how your traffic is increasing over the month or year so that you can plan out when you will need to upgrade or add more servers.

Munin-Node

Munin is split between two ports. One port is for the clients and one is for the server that tracks and charts the data. On all machines that you plan to monitor, including the machine that will act as the munin server if you wish, install munin-node from the ports.

# cd /usr/ports/sysutils/munin-node
# make install distclean

It will prompt you to add the group. Press y for both these as they come up.

You need a group "munin".
Would you like me to create it [y]? y
Would you like me to set up log rotation [y]?

Now that munin-node has been installed you need to enable it in the rc.conf file before you can run it.

# ee /etc/rc.conf

Open the file and add the following line

munin_node_enable="YES"

Munin-Node Config File

The munin node config file contains the settings as well as the ips that can access the data from the node. Open this file:

# ee /usr/local/etc/munin/munin-node.conf

The only critical setting in this file that you will need to change at first is the list of allowed addresses. It defaults to only allow the localhost to access the node data. If you are running the munin-main server on the same machine then this is all you will want, but if you have it on a seperate machine you will need to add the ip. If your server running munin-main was on 192.168.0.50 you would add the following:

allow ^192\.168\.0\.50$

If munin node is already running restart it to put these changes into effect with:

# sh /usr/local/etc/rc.d/munin-node.sh restart

Starting up Munin-Node

Now that your node is configurated start it up from the rc.d folder.

# sh /usr/local/etc/rc.d/munin-node.sh start
Starting munin_node.

You can test that everything is working correctly by telneting into munin from the local machine. Type version to check the munin version and fetch cpu to see the current cpu stats.

# telnet localhost 4949
Trying 127.0.0.1...
Connected to localhost.freebsdmadeeasy.com.
Escape character is '^]'.
# munin node at www.freebsdmadeeay.com
version
munins node on www.freebsdmadeeasy.com version: 1.2.5
fetch cpu
user.value 11975593
nice.value 14303
system.value 5550264
interrupt.value 3717056
idle.value 948846761
.
quit
Connection closed by foreign host.

Munin-Main

Munin-Main is the server which goes out to all of the nodes, fetches the data, and then graphs it. It is installed only on the one central machine that will be monitoring the nodes. It can be installed from the ports with the following commands.

# cd /usr/ports/www/munin-main
make install distclean

You will be prompted to create the munin group and user if it does not already exist. Press y for these questions.

You need a group "munin".
Would you like me to create it [y]? y
Done.
You need a user "munin".
Would you like me to create it [y]? y

Munin-Main has a config file that stores the node IPs and some of its graphing options. To add nodes besides the localhost you will need to edit this file.

# ee /usr/local/etc/munin/munin.conf

The default directory to ouput the html to is /usr/local/www/munin, you will need to either set up a vhost for this to access it or change the htmldir to /usr/local/www/data/munin so that you can get to it from the default directory. You will need to create this directory and set the permissions or the update will fail.

# chown -R munin:munin /usr/local/www/data/munin/

Adding Nodes to the Munin Tree

In the munin.conf file you will have a tree containing the local machine as set up by the ports.

# a simple host tree
[master.freebsdmadeeasy.com]
    address 127.0.0.1
    use_node_name yes

To add the other nodes copy this format and change the hostname and ip for each machine. For example if we wanted to add 2 more machines:

# a simple host tree
[master.freebsdmadeeasy.com]
    address 127.0.0.1
    use_node_name yes

[april.freebsdmadeeasy.com]
    address 192.168.0.15
    use_node_name yes

[may.freebsdmadeeasy.com]
    address 192.168.0.27
    use_node_name yes

Munin-Main will now contact these machines and pull in their data which is given by munin-node running on each of these machines.

The Munin user

Unlike munin-node which starts with a script in rc.d, munin-main runs under the munin user from a cron job. To see this job you can su to munin under the root account.

# su munin
$ crontab -e

The crontab -e command will show you the scheduled jobs which will look like this:

#BEGIN_MUNIN_MAIN
MAILTO=root

*/5 * * * *     /usr/local/bin/munin-cron
#END_MUNIN_MAIN

If you wish to change who gets the emails about munin change root to that username.

If you are stuck in vi press escape ZZ to get out.

Munin-main will start running as soon as the port installs, but will not do more then access itself until you make the changes above to the config file.

Viewing the Graphs

Once five minutes have gone by and munin has run with the new config file you can check that it outputted them to the htmldir.

If the html is there open it up in your web browser on the server and you will be able to see the munin graphs.

Changing the Templates

Templates are found under the following directory

# cd /usr/local/etc/munin/templates/

If you are processing .html files as PHP you will need to remove the XML line from the top of every .tmpl page or your pages will not show up. After changing the templates the changes will not show up under after an update has run using the new templates.

Changing the Port

If you wish to change the port from something besides 4949 change it first in your munin-node.conf files on the nodes, and then add the port line to each node in your tree with the port you set.

# ee /usr/local/etc/munin/munin.conf
[april.freebsdmadeeasy.com]
        address 192.168.0.15
        port 7000
        use_node_name yes

Troubleshooting

If you are having problems check the logs.

# cd /var/log/munin-main

There are many log files that will tell you everything that munin is currently doing.

You can also run munin-cron manually by doing an su to munin and then running the cron with

$ munin-cron

This will show you some error messages if they are there.

Another trick to try is to telnet from the server into the munin-nodes to make sure that munin-main is able to access them and that you do not have a problem with your ip access in the munin-node.conf files.