muninlite/README.md

218 lines
6.0 KiB
Markdown
Raw Normal View History

2019-07-19 06:19:13 +02:00
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
2019-07-23 04:52:37 +02:00
system.
2019-07-19 06:19:13 +02:00
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"
```shell
$ 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)
```shell
cp munin-node /usr/local/bin
chmod +x /usr/local/bin/munin-node
```
Two typical ways of using MuninLite as a `munin-node` replacement are:
* direct execution: suitable for remote hosts lacking root access (e.g. shared host)
* TCP service via inetd/xinetd: providing a service that is accessible via TCP (like `munin-node`)
Both approaches are detailed below.
Installation for direct execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Configure the `address` setting of the node in the master's configuration with
a suitable transport, e.g.:
```
[some.host.tld]
address ssh://node-a.example.org/usr/local/bin/munin-node
```
The above example causes the master to connect to the node via ssh and to
execute the MuninLite script directly. The running script responds to request
from standard input just like it would do as a TCP service via inetd/xinetd.
Installation as a TCP service (inetd/xinetd)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Add munin port to `/etc/services` (in case it is missing):
2019-07-19 06:19:13 +02:00
```shell
echo "munin 4949/tcp lrrd # Munin" >>/etc/services
```
Configure inetd or xinetd to fork this script for request on the
2019-07-23 04:52:37 +02:00
munin port (4949).
2019-07-19 06:19:13 +02:00
Sample configuration for xinetd is located in `examples/xinetd.d/munin`:
```shell
cp examples/xinetd.d/munin /etc/xinetd.d
killall -HUP xinetd
```
Sample configuration for inetd is located in `examples/inetd.conf`:
```shell
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:
```shell
iptables -A INPUT -p tcp --dport munin --source 10.42.42.25 -j ACCEPT
```
Test
----
To test the script, just run it (`/usr/bin/local/munin-node`):
2019-07-19 06:19:13 +02:00
```shell
$ /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.
```shell
# 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.
2019-07-23 04:52:37 +02:00
There is no specific configuration for plugins.
2019-07-19 06:19:13 +02:00
Munin configuration
-------------------
Configure your /etc/munin/munin.conf as you would for a regular
`munin-node`, if you configured MuninLite as a TCP service (e.g. via
inetd/xinetd):
2019-07-19 06:19:13 +02:00
```
[some.host.tld]
address 10.42.42.25
use_node_name yes
```
In case of direct execution of MuninLite on the remote host (without a TCP
service), you need to configure a transport and execute the script directly:
```
[some.host.tld]
address ssh://10.42.42.25/usr/local/bin/munin-node
use_node_name yes
```