.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "MUNIN.CONF" "5" "February 10, 2022" "2.1" "Munin" .SH NAME munin.conf \- Configuration file for the munin master .SH DESCRIPTION .sp This is the configuration file for the munin master. It is used by munin\-update, munin\-limits and munin\-httpd\&. .sp Location in packages is usually \fB/etc/munin/\fP while if compiled from source it is often found in \fB/etc/opt/munin/\fP\&. .sp The structure is: .INDENT 0.0 .IP 1. 3 One general/global section .IP 2. 3 Zero or more group section(s) .IP 3. 3 One or more host section(s) .UNINDENT .sp Group and host sections are defined by declaring the group or host name in brackets. Everything under a section definition belongs to that section, until a new group or host section is defined. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As \fBthe global section\fP is not defined through brackets, it \fBmust be found prior to any group or host sections\fP\&. It will not work if you place them in later sections of the config file. We recommend to use the delivered munin.conf file and adapt it to your needs. .UNINDENT .UNINDENT .sp Comments can be included by prefacing them with \fB#\fP\&. A literal \fB#\fP in a configuration value can be escaped with a backslash: \fB\e#\fP\&. Long lines can be wrapped by ending them with \fB\e\fP\&. Note that \fB\e\fP has no special meaning otherwise, nor do any other characters; in particular, quotes have no special meaning, so a line like \fBcontact.irc.command irc\-notify "#munin\-alerts"\fP will be parsed as \fBcontact.irc.command irc\-notify "\fP unless the \fB#\fP is escaped. .SH GLOBAL DIRECTIVES .sp Global directives affect all munin master components unless specified otherwise. .INDENT 0.0 .TP .B dbdir The directory where munin stores its database files (Default: \fB/var/lib/munin\fP). It must be writable for the user running munin\-cron\&. RRD files are placed in subdirectories \fI$dbdir/$domain/\fP .UNINDENT .INDENT 0.0 .TP .B htmldir The directory shown by munin\-httpd\&. It must be writable for the user running munin\-httpd\&. For munin 2.0: The directory where munin\-html stores generated HTML pages, and where munin\-graph stores graphs. .UNINDENT .INDENT 0.0 .TP .B logdir The directory where munin stores its logfiles (Default: \fB/var/log/munin\fP). It must be writable by the user running munin\-cron. .UNINDENT .INDENT 0.0 .TP .B rundir Directory for files tracking munin’s current running state. Default: \fB/var/run/munin\fP .UNINDENT .INDENT 0.0 .TP .B tmpldir Directories for templates used by munin\-httpd (munin 2.0: munin\-html) to generate HTML pages. Default \fB/etc/munin/templates\fP .UNINDENT .INDENT 0.0 .TP .B staticdir Where to look for the static www files. .UNINDENT .INDENT 0.0 .TP .B cgitmpdir Temporary cgi files are here. It has to be writable by the cgi user (For Munin stable 2.0 usually \fBnobody\fP or \fBhttpd\fP). .UNINDENT .INDENT 0.0 .TP .B includedir (Exactly one) directory to include all files from. Default \fB/etc/munin/plugin\-conf.d/\fP .UNINDENT .INDENT 0.0 .TP .B local_address
Sets the local IP address that \fImunin\-update\fP should bind to when contacting the nodes. May be used several times (one line each) on a multi\-homed host. Should default to the most appropriate interface, based on routing decision. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This directive can be overwritten via settings on lower hierarchy levels (group, node). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B fork This directive determines whether munin\-update fork when gathering information from nodes. Default is “yes”. .sp If you set it to “no” munin\-update will collect data from the nodes in sequence. This will take more time, but use less resources. Not recommended unless you have only a handful of nodes. .sp Affects: munin\-update .UNINDENT .INDENT 0.0 .TP .B timeout This directive will set how long to wait in seconds before giving up on establishing a connection to a munin node when using the munin protocol. Default is “180”. .sp Affects: munin\-update .UNINDENT .INDENT 0.0 .TP .B timeout_fetch_all_nodes 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. .sp Do not set this value higher, unless all nodes are using ssh with munin\-async. 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. .sp Affects: munin\-update .UNINDENT .INDENT 0.0 .TP .B timeout_fetch_one_node This directive will set the maximum amount of time in seconds the munin\-update task may run 1 single node. This value can’t be bigger than timeout_fetch_all_nodes. Default is 180. .sp Affects: munin\-update .UNINDENT .INDENT 0.0 .TP .B palette The palette used by munin\-httpd to color the graphs. The “default” palette has more colors and better contrast than the “old” palette. .UNINDENT .INDENT 0.0 .TP .B custom_palette rrggbb rrggbb ... The user defined custom palette used by munin\-httpd to color the graphs. This option overrides the existing palette. The palette must be space\-separated 24\-bit hex color code. .UNINDENT .INDENT 0.0 .TP .B graph_period You can choose the time reference for “DERIVE” like graphs, and show “per minute” => \fBminute\fP, “per hour” => \fBhour\fP values instead of the default “per second”. .UNINDENT .INDENT 0.0 .TP .B html_dynamic_images 1 Munin HTML templates use this variable to decide whether to use dynamic (“lazy”) loading of images with javascript so that images are loaded as they are scrolled in view. This prevents excessive load on the web server. Default is 0 (off). .UNINDENT .INDENT 0.0 .TP .B max_graph_jobs 6 Available since Munin 1.4.0. Maximum number of parallel processes used by \fI\%munin\-graph\fP when calling \fI\%rrdgraph\fP\&. The optimal number is very hard to guess and depends on the number of cores of CPU, the I/O bandwidth available, if you have SCSI or (S)ATA disks and so on. You will need to experiment. Set on the command line with the \fB\-n n\fP option. Set to 0 for no forking. .UNINDENT .INDENT 0.0 .TP .B munin_cgi_graph_jobs 6 munin\-cgi\-graph is invoked by the web server up to very many times at the same time. This is not optimal since it results in high CPU and memory consumption to the degree that the system can thrash. Again the default is 6. Most likely the optimal number for \fBmax_cgi_graph_jobs\fP is the same as \fBmax_graph_jobs\fP\&. .UNINDENT .INDENT 0.0 .TP .B cgiurl_graph /munin\-cgi/munin\-cgi\-graph If the automatic CGI url is wrong for your system override it here. .UNINDENT .INDENT 0.0 .TP .B max_size_x 4000 The max width of images in pixel. Default is 4000. Do not make it too large otherwise RRD might use all RAM to generate the images. .UNINDENT .INDENT 0.0 .TP .B max_size_y 4000 The max height of images in pixel. Default is 4000. Do not make it too large otherwise RRD might use all RAM to generate the images. .UNINDENT .INDENT 0.0 .TP .B graph_strategy This option is available only in munin 2.0. In munin 2.0 graphics files are generated either via cron or by a CGI process. .sp If set to “cron”, munin\-graph will graph all services on all nodes every run interval. .sp If set to “cgi”, munin\-graph will do nothing. Instead graphs are generated by the webserver on demand. .UNINDENT .INDENT 0.0 .TP .B html_strategy This option is available only in munin 2.0. In munin 2.0 HTML files are generated either via cron (default) or by a CGI process. .sp If set to “cron”, munin\-html will recreate all html pages every run interval. .sp If set to “cgi”, munin\-html will do nothing. Instead HTML files are generated by the webserver on demand. This setting implies \fBgraph_strategy cgi\fP .UNINDENT .INDENT 0.0 .TP .B max_processes 16 \fImunin\-update\fP runs in parallel. .sp The default max number of processes is 16, and is probably ok for you. Should be not higher than 4 x CPU cores. .sp If set too high, it might hit some process/ram/filedesc limits. If set too low, munin\-update might take more than 5 min. If you want munin\-update to not be parallel set it to 1. .UNINDENT .INDENT 0.0 .TP .B rrdcached_socket /var/run/rrdcached.sock RRD updates are per default, performed directly on the rrd files. To reduce IO and enable the use of the rrdcached, uncomment it and set it to the location of the socket that rrdcached uses. .UNINDENT .INDENT 0.0 .TP .B graph_data_size This directive sets the resolution of the RRD files that are created by munin\-update\&. .sp Default is “normal”. .sp “huge” saves the complete data with 5 minute resolution for 400 days. .sp With “custom” you can define your own resolution. See the instruction on custom RRD sizing for the details. .sp Changing this directive has no effect on existing graphs .UNINDENT .INDENT 0.0 .TP .B contact.your_contact_name.command Define which contact command to run. See the tutorial Let Munin croak alarm for detailed instruction about the configuration. .UNINDENT .INDENT 0.0 .TP .B contact.your_contact_name.text Text to pipe into the command. .UNINDENT .INDENT 0.0 .TP .B contact.your_contact_name.max_messages Close (and reopen) command after given number of messages. E.g. if set to 1 for an email target, Munin sends 1 email for each warning/critical. Useful when relaying messages to external processes that may handle a limited number of simultaneous warnings. .UNINDENT .INDENT 0.0 .TP .B contact.your_contact_name.always_send If there are alerts of the given severities, send them to this contact every time munin\-limits runs, even if they haven’t changed since last time. .UNINDENT .INDENT 0.0 .TP .B ssh_command The name of the secure shell command to use. Can be fully qualified or looked up in $PATH. .sp Defaults to “ssh”. .UNINDENT .INDENT 0.0 .TP .B ssh_options The options for the secure shell command. .sp Defaults are “\-o ChallengeResponseAuthentication=no \-o StrictHostKeyChecking=no”. Please adjust this according to your desired security level. .sp With the defaults, the master will accept and store the node ssh host keys with the first connection. If a host ever changes its ssh host keys, you will need to manually remove the old host key from the ssh known hosts file. (with: ssh\-keygen \-R , as well as ssh\-keygen \-R ) .sp You can remove “StrictHostKeyChecking=no” to increase security, but you will have to manually manage the known hosts file. Do so by running “ssh ” manually as the munin user, for each node, and accept the ssh host keys. .sp If you would like the master to accept all node host keys, even when they change, use the options “\-o UserKnownHostsFile=/dev/null \-o StrictHostKeyChecking=no \-o PreferredAuthentications=publickey”. .UNINDENT .INDENT 0.0 .TP .B domain_order .. Change the order of domains/groups. Default: Alphabetically sorted .UNINDENT .SH GROUP DIRECTIVES .sp If you want to set directives on the group level you have to start the group section with the groups name in square brackets. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [mygroup.mydomain] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B node_order .. Changes the order of nodes in a domain. Default: Alphabetically sorted. .UNINDENT .INDENT 0.0 .TP .B contacts A list of contacts used by munin\-limits to report values passing the warning and critical thresholds. .sp If set to something else than “no”, names a list of contacts which should be notified for this node. Default is “no” and then \fBall\fP defined contacts will get informed when values go over or below thresholds. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This directive can be overwritten via settings on lower levels of the hierarchy (node, plugin). .UNINDENT .UNINDENT .SH NODE DEFINITIONS .sp Node definitions can have several types. In all forms, the definition is used to generate the node name and group for the node, and the following lines define its directives. All following directives apply to that node until another node definition or EOF. .sp 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. .sp The simplest node definition defines the section for a new node by simply wrapping the DNS name of the node in brackets, e.g. \fB[machine1.example.com]\fP\&. This will add the node \fImachine1.example.com\fP to the group \fIexample.com\fP\&. .sp The next form of definition is used to define the node and group explicitly. It follows the form \fB[example.com;machine1.sub.example.com]\fP\&. This adds the node \fImachine1.sub.example.com\fP to the group \fIexample.com\fP\&. 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 \fIexample.com\fP, where having a group of \fIcom\fP makes little sense. .sp A deeper hierarchy can be specified by using a list of groups, separated with “;”. For example: \fB[site1;customer2;production;mail.customer2.example.org]\fP\&. .SS NODE DIRECTIVES .sp These are directives that can follow a node definition and will apply only to that node. .INDENT 0.0 .TP .B address Specifies the host name or IP address, with an optional scheme. .sp Permitted schemes are “munin://”, “ssh://” or “cmd://”. If no scheme is specified, the default is “munin://” .sp The “\fI\%ssh://\fP” and “cmd://” schemes take arguments after the URL. See \fI\%Address schemes\fP for examples. .UNINDENT .INDENT 0.0 .TP .B port The port number of the node. Ignored if using alternate transport. Default is “4949”. .UNINDENT .INDENT 0.0 .TP .B use_node_name If “yes”, when querying the node, the master will trust the name the node reports for itself, and ask for plugins associated with that name. This means that it will fetch metrics from plugins running on the node itself, which is usually what you want. .sp If “no”, the master will ignore the name reported by the node when it connects, and ask for plugins associated with the name configured in munin.conf. This is generally what you want when the node is collecting metrics on behalf of other systems, e.g. via SNMP plugins. .sp When you have one node that collects metrics from several systems (e.g. querying multiple routers via SNMP), it’s common to have multiple entries for it in munin.conf with the same \fBaddress\fP, different node names, and \fBuse_node_name no\fP\&. .sp See also Using SNMP Plugins\&. .UNINDENT .INDENT 0.0 .TP .B notify_alias Used by munin\-limits\&. .sp If set, changes the name by which the node presents itself when warning through munin\-limits\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This directive can also be used on hierarchy level plugin to change the name by which the plugin presents itself when warning through \fBmunin\-limits\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B ignore_unknown Available since Munin 3.0. .sp If set, ignore any unknown values reported by the node. Allowed values are “yes” and “no”. Defaults to “no”. .sp Useful when a node is expected to be off\-line frequently. .UNINDENT .INDENT 0.0 .TP .B update Fetch data from this node with munin\-update? Allowed values are “yes” and “no”. Defaults to “yes”. .sp If you make a virtual node which borrow data from real nodes for aggregate graphs, set this to “no” for that node. .UNINDENT .SS PLUGIN DIRECTIVES .sp These directives follow a node definition and are of the form “plugin.directive ”. .sp 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. .INDENT 0.0 .TP .B graph_title Override the title of a specific graph. .UNINDENT .INDENT 0.0 .TP .B graph_category Override the category of a specific service. .UNINDENT .INDENT 0.0 .TP .B graph_height The graph height for a specific service. Default is 200. .sp Affects: munin\-httpd\&. .UNINDENT .INDENT 0.0 .TP .B graph_width The graph width for a specific service. Default is 400. .sp Affects: munin\-httpd\&. .UNINDENT .sp For a complete list see the reference of global plugin attributes\&. .SS FIELD DIRECTIVES .sp These directives follow a node definition and are of the form “plugin.field ”. .sp Using these directives you can override values originally set by plugins on the nodes, such as warning and critical levels or graph names. .INDENT 0.0 .TP .B warning 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 colon separated pair of numbers defining a valid range of values. .sp Affects: munin\-limits\&. .UNINDENT .INDENT 0.0 .TP .B critical 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 colon separated pair of numbers defining a valid range of values. .sp Affects: munin\-limits\&. .UNINDENT .sp For a complete list see the reference of plugin data source attributes\&. .SH EXAMPLES .SS Three nodes .sp A minimal configuration file, using default settings for everything, and specifying three nodes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [mail.example.com] address mail.example.com [web.example.com] address web.example.com [munin.example.com] address localhost .ft P .fi .UNINDENT .UNINDENT .SS Virtual node .sp A virtual node definition. Disable update, and make a graph consisting of data from other graphs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [example.com;Totals] update no load.graph_title Total load load.sum_load.label load load.sum_load.stack mail=mail.example.com web=web.example.com munin=munin.example.com .ft P .fi .UNINDENT .UNINDENT .SS Address schemes .sp The scheme tells munin how to connect to munin nodes. .sp The munin:// scheme is default, if no scheme is specified. By default, Munin will connect to the munin node with TCP on port 4949. .sp The following examples are equivalent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # master: /etc/munin/munin.conf.d/node.example.conf [mail.site2.example.org] address munin://mail.site2.example.org [mail.site2.example.org] address munin://mail.site2.example.org:4949 [mail.site2.example.org] address mail.site2.example.org [mail.site2.example.org] address mail.site2.example.org port 4949 .ft P .fi .UNINDENT .UNINDENT .sp To connect to a munin node through a shell command, use the “cmd://” prefix. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # master: /etc/munin/munin.conf.d/node.example.conf [mail.site2.example.org] address cmd:///usr/bin/munin\-async [...] .ft P .fi .UNINDENT .UNINDENT .sp To connect through ssh, use the “\fI\%ssh://\fP” prefix. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # master: /etc/munin/munin.conf.d/node.example.conf [mail.site2.example.org] address ssh://bastion.site2.example.org/bin/nc mail.site2.example.org 4949 [www.site2.example.org] address ssh://bastion.site2.example.org/bin/nc www.site2.example.org 4949 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using the ssh:// transport, you can configure how ssh behaves by editing \fI~munin/.ssh/config\fP\&. See the ssh transport configuration examples\&. .UNINDENT .UNINDENT .SH SEE ALSO .sp See munin for an overview over munin. .sp example\-transport\-ssh .SH AUTHOR The Munin project and its contributors, Stig Sandbeck Mathisen .SH COPYRIGHT 2012-2022, The Munin project and its contributors .\" Generated by docutils manpage writer. .