muninlite/README

README for MuninLite
====================

MuninLite is a single Bourne Shell script that implements the Munin
protocoll as well as some Linux specific plugins. The motivation for
developing MuninLite was to provide a simple Munin Node, using inetd
on systems without a full featured Perl and/or bash or a busybox
system. 

MuninLite is Copyright (C) 2007 Rune Nordb<64>e Skillingstad
<rune@skillingstad.no> and released under GPLv2 (see LICENSE file)

Features
--------
MuninLite implements the following plugins:
* df 
* cpu 
* if_ 
* if_err_ 
* load 
* memory
* processes
* swap
* netstat
* uptime
* interrupts
* irqstats

Included files
--------------
Changelog     			Changelog 
CREDITS	      			Credits to contributors
LICENSE				GPLv2 License
Makefile			Rules to make munin-node
README				This file
TODO				Things to do in future releases
VERSION				Current version
munin-node.in			The MuninLite script skeleton
examples/xinetd.d/munin 	Sample xinetd configuration
examples/inetd.conf		Sample inetd.conf configuration
examples/inetd.busybox		Sample inetd.conf configuration for busybox
examples/hosts.deny		Sample hosts.deny configuration
examples/hosts.allow		Sample hosts.allow configuration
plugins/cpu			CPU usage plugin
plugins/df			Filesystem usage plugin
plugins/if_			Network interface traffic plugin
plugins/if_err_			Network interface errors plugin
plugins/interrupts		Interrupts & context switches plugin
plugins/irqstats		Individual interrupts plugin
plugins/load			Load average plugin
plugins/memory			Memory usage plugin
plugins/netstat			Netstat plugin
plugins/processes		Number of Processes plugin
plugins/swap			Swap in/out plugin
plugins/uptime			Uptime plugin

Build requirements
------------------
Make	     (Not sure what requirements)
Perl         (even very old versions should work)

Requirements
------------
Bourne Shell (ash or dash should be sufficient)
grep   	     (simple grep in busybox is sufficient)
sed	     (simple sed in busybox is sufficient -- but a bit strange...)
cut	     (cut in busybox is sufficient)
wc	     (wc in busybox is sufficient)
xargs	     (xargs in busybox is sufficient)
inetd	     (inetd in busybox is sufficient)

Installation
------------
Download source and unpack it.
Edit Makefile to suit your choice of plugins

Make munin-node by running "make"
  # make
  Making munin-node for muninlite version 0.9.14
  Adding plugin df
  Adding plugin cpu
  Adding plugin if_
  Adding plugin if_err_
  Adding plugin load
  Adding plugin memory
  Adding plugin processes
  Adding plugin swap
  Adding plugin netstat
  Adding plugin uptime
  Adding plugin interrupts
  Adding plugin irqstats

Copy munin-node to a suitable location (/usr/local/bin/) and make it
executable (there will be a "make install" at a later release)

  # cp munin-node /usr/local/bin
  # chmod +x /usr/local/bin/munin-node

Add munin port to /etc/services

  # echo "munin           4949/tcp        lrrd            # Munin" >>/etc/services

Configure inetd or xinetd to fork this script for request on the
munin port (4949). 

Sample configuration for xinetd is located in examples/xinetd.d/munin

  # cp examples/xinetd.d/munin /etc/xinetd.d 
  # killall -HUP xinetd

Sample configuration for inetd is located in examples/inetd.conf

  # cat examples/inetd.conf >> /etc/inetd.conf
  # killall -HUP inetd

Restrict access to munin port using hosts.allow and
hosts.deny or add a rule to your favorite firewall config.
Examples of hosts.allow/deny settings is provided in the examples
directory.

Iptables might be set with something like this:

  # iptables -A INPUT -p tcp --dport munin --source 10.42.42.25 -j ACCEPT 

Test
----
To test script, just run it (/usr/bin/local/munin-node):

  # /usr/local/bin/munin-node
  # munin node at localhost.localdomain
  help
  # Unknown command. Try list, nodes, config, fetch, version or quit
  list
  df cpu if_eth0 if_eth1 if_err_eth0 if_err_eth1 load memory
  version
  munins node on mose.medisin.ntnu.no version: 0.0.5 (munin-lite)
  quit

For inetd-test, try to telnet to munin port from allowed host.

  # telnet localhost 4949
  Trying 127.0.0.1...
  Connected to localhost.
  Escape character is '^]'.
  # munin node at localhost.localdomain
  help
  # Unknown command. Try list, nodes, config, fetch, version or quit
  list
  df cpu if_eth0 if_eth1 if_err_eth0 if_err_eth1 load memory
  version
  munins node on mose.medisin.ntnu.no version: 0.0.5 (munin-lite)
  quit
  Connection closed by foreign host.


Plugin configuration 
------------------------
To configure which plugins should be enabled, locate the PLUGINS
variable in munin-node and remove unwanted plugins.

There is no specific configuration for plugins. 

Munin configuration
-------------------
Configure your /etc/munin/munin.conf as you would for a regular
munin-node.

[some.host.tld]
    address 10.42.42.25
    use_node_name yes