=encoding utf8

=head1 NAME

munin.conf - Munin configuration file

=head1 DESCRIPTION

Munin is a group of programs to gather data from hosts, graph them,
create html-pages, and optionally warn contacts about any off-limit
values.

The hosts are divided into three groups: One master (could be more,
but Munin is not cluster aware so they'll likely be independent).  The
master contacts a number of machines running munin-node, these are
called nodes.  Each node has data from one or more hosts that is
monitored by Munin.

F<munin.conf> is the configuration file for the Munin master server.
The programs using it are munin-update, munin-graph, munin-limits and
munin-html.  There is also quite extensive documentation of this file
at L<http://munin-monitoring.org/wiki/munin.conf>

The format of the file is simple. A minimal configuration looks
something like:

	[machine1.your.dom]
		address localhost

The default location of F<munin.conf> is F<@@CONFDIR@@/munin.conf>.
If your placement deviates from this norm, use the "--config
E<lt>fileE<gt>"-option when running the munin-* programs.

Munin-update will expand all node-entries in this file, and save them
to F<@@DBDIR@@/datafile>, which is used by all programs in the package
together with this file.

Any directives in this file will override directives of the same name
in F<datafile>.  E.g., if you want to change the title of the
"load"-graph in the above minimum configuration, you would modify the
two bottom lines to:

	[machine1.your.dom]
		address localhost
		load.graph_title Edited title of the load-graph

This will override the C<graph_title> attribute of the C<load>
field/data series while keeping all the others at their default.

=head1 GLOBAL DIRECTIVES

These directives should appear in F<munin.conf> before any host or
group definitions.

=over

=item B<dbdir> I<path>   (Default: F<@@DBDIR@@>)

Directory for generated database files.  Required.

=item B<logdir> I<path>  (Default: F<@@LOGDIR@@>)

Directory for log files.  Required.

=item B<htmldir> I<path> (Default: F<@@HTMLDIR@@>)

Directory for HTML pages and graphs.  Required.

=item B<rundir> I<path>  (Default: F<@@STATEDIR@@>)

Directory for files tracking munin's current running state.  Required.

=item B<tmpldir> I<path> (Default: F<@@CONFDIR@@/templates>)

Directory for templates used to generate HTML pages.  Required.

=item B<fork> I<value>

This directive determines whether munin-update fork when gathering
information from nodes.  Possible values are C<yes> and C<no>.
Default is C<yes>.  If you set it to C<no> munin-update will collect
data from the nodes in sequence rather than in parallel and this will
take considerably more time.  Affects: munin-update.

=item B<palette> I<default|old>

Choose palette between the very nice "C<default>", and the good old
"C<old>".

=item B<graph_data_size> I<value>

This directive sets the resolution of the RRD files that are created.
Possible values are C<normal> and C<huge>.  Default is C<normal>.
C<Huge> is really huge, it saves the complete data with 5 minute
resolution for 400 days.  This will probably increase the I/O load on
your Munin master, and currently has very little benefit.  Affects:
munin-update.

=item B<graph_strategy> I<value>

Deprecated. (Graphs are now always drawn via CGI.)

=item B<local_address> I<value>

The local address to connect any node from in case the master has
several IP interfaces.  This can be overridden by a group or global
directive.  Without this directive Munins traffic will originate from
the master server according to the IP routing table.

=item B<max_processes> <value>

This directive specifies the maximum number of processes to be used
for gathering information from nodes.  If left blank, munin will use
as many processes as necessary.  Affects: munin-update.

=item B<max_graph_jobs> <value>

This directive specifies the maximum number of concurrent rrdgraph
proesses started by munin-graph.  The default is 6.  A setting of 0
disables concurrent processing.  Affects: munin-graph

=item B<max_cgi_graph_jobs> <value>

This directive specifies the maximum number of concurrent
munin-cgi-graph jobs.  The web server can start a high number of
munin-cgi-graph jobs which we can't stop, but munin-cgi-graph will
throttle down how many rrdgraph calls will be running at the same time
to this number.  Affects: munin-cgi-graph and munin-fastcgi-graph.

=item B<timeout_fetch_all_nodes> I<seconds>

This directive will set the maximum amount of time in seconds the munin-update
task may run. So we'll make sure the update ended within the 5 minutes
timespan needed to have complete graphs without gaps.

You should probably not increase this value, unless all nodes are using ssh
with munin-async.  Otherwise you may expecience gaps in graphs, if
C<munin-update> takes longer, than the default period (5 minutes).

Munin-async can retrieve historical data, and if there is a big backlog,
we could need more time depending on the size of the data generated by the plugin
and the size of the backlog. This would also mean that we wouldn't care to skip
an update. So munin-async will get more time to retrieve the backlog data.
Afterwards new data will incrementally be fetched.
Default is 240.
Affects: munin-update

=item B<timeout_fetch_one_node> I<seconds>

This directive will set the maximum amount of time in seconds the munin-update
task may run for a single node. This value can't be bigger than
C<timeout_fetch_all_nodes>.
Default is 180.
Affects: munin-update

=item B<ssh_command> I<value>

The name of the secure shell command to use.  Can be fully qualified,
or looked up in $PATH.  Default: C<ssh>

=item B<ssh_options> I<value>

The C<ssh> command line options.  Defaults: C<-o
ChallengeResponseAuthentication=no -o StrictHostKeyChecking=no>.

If you need per-host ssh configuration, add these to
F<~/munin/.ssh/config>

=item B<tls> <value>

Can have four values. C<paranoid>, C<enabled>, C<auto>, and
C<disabled>.  C<Paranoid> and C<enabled> require a TLS connection,
while C<disabled> will not attempt one at all.

The current default is C<disabled> because C<auto> is broken.  C<Auto>
causes bad interaction between munin-update and munin-node if the node
is unprepared to go to TLS.

If you see data dropouts (gaps in graphs) please try to disable TLS.
Affects: munin-update.

=item B<tls_verify_certificate> <value>

This directive can be C<yes> or C<no>.  It determines if the remote
certificate needs to be signed by a CA that is known locally.  Default
is C<no>.  Affects: munin-update.

=item B<tls_private_key> <value>

This directive sets the location of the private key to be used for
TLS.  Default is @@CONFDIR@@/munin.pem.  The private key and
certificate can be stored in the same file.  Affects: munin-update.

=item B<tls_certificate> <value>

This directive sets the location of the TLS certificate to be used for
TLS.  Default is @@CONFDIR@@/munin.pem.  The private key and
certificate can be stored in the same file.  Affects: munin-update.

=item B<tls_ca_certificate> <value>

This directive sets the CA certificate to be used to verify the node's
certificate, if tls_verify_certificate is set to C<yes>.  Default is
@@CONFDIR@@/cacert.pem.  Affects: munin-update.

=item B<tls_verify_depth> <value>

This directive sets how many signings up a chain of signatures TLS is
willing to go to reach a known, trusted CA when verifying a
certificate.  Default is C<5>.  Affects: munin-update.

=item B<tls_match> <value>

This directive, if defined, searches a dump of the certificate provided by the
remote host for the given regex.  The dump of the certificate is two lines of
the form:

	Subject Name: /C=c/ST=st/L=l/O=o/OU=ou/CN=cn/emailAddress=email
	Issuer  Name: /C=c/ST=st/O=o/OU=ou/CN=cn/emailAddress=email

So, for example, one could match the subject distinguished name by the directive:

	tls_match Subject Name: /C=c/ST=st/L=l/O=o/OU=ou/CN=cn/emailAddress=email

Note that the fields are dumped in the order they appear in the certificate.
It's best to view the dump of the certificate by running munin-update in debug
mode and reviewing the logs.

Unfortunately, due to the limited functionality of the SSL module in use, it is
not possible to provide finer-grained filtering.  By default this value is not
defined.  Affects: munin-update.

=item FIXME: This section MAY be complete, it may be missing a directive or two.

=back

=head1 HOST DEFINITIONS

Host definitions can have several types.  In all forms, the definition
is used to generate the host name and group for the host, and the
following lines define its directives.  All following directives apply
to that node until another node definition or EOF.  Note that when
defining a nodename it is vital that you use a standard DNS name, as
in, one that uses only a-z, '-', and '.'.  While other characters can
be used in a DNS name, it is against the RFC, and Munin uses the other
characters as delimiters.  If they appear in nodenames, unexpected
behavior may occur.

The simplest node definition defines the section for a new node by
simply wrapping the DNS name of the node in brackets, e.g.
C<[machine1.your.dom]>.  This will add the node C<machine1.your.dom>
to the group C<your.dom>.

The next form of definition is used to define the node and group
independently.  It follows the form
C<[your.dom;machine1.sub.your.dom]>.  This adds the node
C<machine1.sub.your.dom> to the group C<your.dom>.  This can be useful
if you have machines you want to put together as a group that are
under different domains (as in the given example).  This can also
solve a problem if your machine is C<machine1.com>, where having a
group of C<com> makes little sense.

Multiple groups can be specified by adding more C<groupname;>s, e.g.
C<[servers;local;mail;mail.foo.net]>, if you need a more hierarchical
structure.

=head1 NODE DIRECTIVES

These are directives that can follow a node definition and will apply
only to that node.

=over

=item B<address> <value>

The IP address of the node.  Required.

=item B<local_address> <value>

The local address to connect to the node from.  This overrides a group or
global directive.

=item FIXME: This section is incomplete.

=back

=head1 PLUGIN DIRECTIVES

These directives should appear after a node definition and are of the
form C<plugin.directive E<lt>valueE<gt>>.  Using these directives you
can override various directives for a plugin, such as its contacts,
and can also be used to create graphs containing data from other
plugins.

=over

=item FIXME: This section is (obviously) incomplete.

=back

=head1 FIELD DIRECTIVES

These directives should appear after a node definition and are of the
form C<plugin.field E<lt>valueE<gt>>.  Using these directives you can
override values originally set by plugins on the nodes, such as
warning and critical levels or graph names.

=over

=item B<graph_height> <value>

The graph height for a specific service.  Default is C<175>.  Affects:
munin-graph.

=item B<graph_width> <value>

The graph width for a specific service.  Default is C<400>.  Affects:
munin-graph.

=item B<warning> <value>

The value at which munin-limits will mark the service as being in a
warning state.  Value can be a single number to specify a limit that
must be passed or they can be a comma separated pair of numbers
defining a valid range of values.  Affects: munin-limits.

=item B<critical> <value>

The value at which munin-limits will mark the service as being in a
critical state.  Value can be a single number to specify a limit that
must be passed or they can be a comma separated pair of numbers
defining a valid range of values Affects: munin-limits.

=item FIXME: This section is incomplete.

=back

=head1 EXAMPLES

On all the examples below, all the 'top-level' parameters (dbdir,
logdir, htmldir, tmpldir) are not present. They are only skipped for
brevity - they are needed.

=head1 EXAMPLE 1

An example with three servers on two domains:

	[machine1.one.dom]
		address machine1.one.dom

	[machine2.one.dom]
		address 10.33.32.123

	[machine3.two.dom]
		address localhost

This will appear as two groups (one.dom and two.dom), having
respectively two and one node.

=head1 EXAMPLE 2

Summarize the 'load'-graphs of the two servers in one.dom, in a 'total
load'-graph.

	[one.dom;Totals]
		update no
		load.graph_title Total load
		load.sum_load.label load
		load.sum_load.special_stack machine1=machine1.one.dom:load.load machine2=machine2.one.dom:load.load


=head1 AUTHORS

Jimmy Olsen, Audun Ytterdal, Brian de Wolf, Nicolai Langfeldt

=head1 COPYRIGHT

Copyright (C) 2002-2008 Audun Ytterdal, Jimmy Olsen, Nicolai
Langfeldt, Linpro AS and others.

This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.

This program is released under the GNU General Public License

=head1 SEE ALSO

For more information, see the man pages of the individual munin-*
programs or the Munin homepage L<http://munin-monitoring.org/>.

=cut
