LRRD FAQ


Table of Contents

1. Installation

Q: Why only Debian packages? Why not Redhat?

We're using Debian on our machines and servers. We're working on RPM-packages for RedHat 9, though.

Q: What architectures are supported? What operating systems?

LRRD is programmed in Perl, which can be installed on most operating systems. In addition, it needs some perl modules, which you can fetch from CPAN.

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

Linux
FreeBSD
SunOS (Solaris)
AIX
If you port/create/improve plugins, please contribute them to the project.

2. Configuration

Q: What should a minimal configuration look like? 

	dbdir     /var/lib/lrrd
	htmldir   /var/www/lrrd
	logdir    /var/log/lrrd
	rundir    /var/run/lrrd

	[bing.foo.bar]
		address 10.232.33.259
The server will expand the node to contain all the services it offers.

Q: How du I use the "fieldname.cdef"-thingie?

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;

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.

An example can be found in the plugin "exim_mailstats" - the plugin graphs the number of mails that have been received and delivered locally by the system. The values are gathered and stored in a "mails per second"-format. On most systems, this is a bit odd, since you'll get numbers like "300 ultramail per second". :-) A cdef is therefore defined to adjust the values into "mails per minute" instead - a much more sensible and readable number. To do this, the value is just multiplied by 60. The configuration line looks like this: received.cdef received,60,* . In "normal" math, you'd just say "received=received*60".

For a more thorough definition of RPN, take a look at the man-page for "rrdgraph".

Q: How do I define aliases with graph_order?

Normally, graph_order looks something like this:

graph_order apps buffers cache unused swap
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: 
    graph_order processes connections=port_http.count
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.

Example graph_orders:

Q: How do I use fieldname.stack?

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.

[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,*

Q: How do I use fieldname.sum?

Same as special_stack, with one exception: drop the "alias"-bit in the field definition. I.e., the above would become:

[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,*

Q: Can I change the order of the nodes under a domain?

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:

	[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
The default node order is alphabetically.

3. Client plugins

Q: What is the minimum requirements of a client plugin?

An example plugin (on a linux-system, using /proc/loadavg to graph the load average): 
#!/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
echo -n "load.value "
cut -f1 -d' ' < /proc/loadavg

Q: Can I make the plugin run as another user/group than nobody/nogroup?

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:

[exim_mailqueue]
	group mail
Similarly, you could use the "user" option to run the plugin as a user.