.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MUNIN.CONF 5" .TH MUNIN.CONF 5 "2023-04-11" "2.0.73" "Munin Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" munin.conf \- Munin configuration file .SH "DESCRIPTION" .IX Header "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. .PP 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. .PP \&\fImunin.conf\fR 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 .PP The format of the file is simple. A minimal configuration looks something like: .PP .Vb 2 \& [machine1.your.dom] \& address localhost .Ve .PP The default location of \fImunin.conf\fR is \fI/etc/munin/munin.conf\fR. If your placement deviates from this norm, use the \*(L"\-\-config \*(R"\-option when running the munin\-* programs. .PP Munin-update will expand all node-entries in this file, and save them to \fI/var/lib/munin/datafile\fR, which is used by all programs in the package together with this file. .PP Any directives in this file will override directives of the same name in \fIdatafile\fR. E.g., if you want to change the title of the \&\*(L"load\*(R"\-graph in the above minimum configuration, you would modify the two bottom lines to: .PP .Vb 3 \& [machine1.your.dom] \& address localhost \& load.graph_title Edited title of the load\-graph .Ve .PP This will override the \f(CW\*(C`graph_title\*(C'\fR attribute of the \f(CW\*(C`load\*(C'\fR field/data series while keeping all the others at their default. .SH "GLOBAL DIRECTIVES" .IX Header "GLOBAL DIRECTIVES" These directives should appear in \fImunin.conf\fR before any host or group definitions. .IP "\fBdbdir\fR \fIpath\fR (Default: \fI/var/lib/munin\fR)" 4 .IX Item "dbdir path (Default: /var/lib/munin)" Directory for generated database files. Required. .IP "\fBlogdir\fR \fIpath\fR (Default: \fI/var/log/munin\fR)" 4 .IX Item "logdir path (Default: /var/log/munin)" Directory for log files. Required. .IP "\fBhtmldir\fR \fIpath\fR (Default: \fI/var/cache/munin/www\fR)" 4 .IX Item "htmldir path (Default: /var/cache/munin/www)" Directory for \s-1HTML\s0 pages and graphs. Required. .IP "\fBrundir\fR \fIpath\fR (Default: \fI/var/run/munin\fR)" 4 .IX Item "rundir path (Default: /var/run/munin)" Directory for files tracking munin's current running state. Required. .IP "\fBtmpldir\fR \fIpath\fR (Default: \fI/etc/munin/templates\fR)" 4 .IX Item "tmpldir path (Default: /etc/munin/templates)" Directory for templates used to generate \s-1HTML\s0 pages. Required. .IP "\fBfork\fR \fIvalue\fR" 4 .IX Item "fork value" This directive determines whether munin-update fork when gathering information from nodes. Possible values are \f(CW\*(C`yes\*(C'\fR and \f(CW\*(C`no\*(C'\fR. Default is \f(CW\*(C`yes\*(C'\fR. If you set it to \f(CW\*(C`no\*(C'\fR munin-update will collect data from the nodes in sequence rather than in parallel and this will take considerably more time. Affects: munin-update. .IP "\fBpalette\fR \fIdefault|old\fR" 4 .IX Item "palette default|old" Choose palette between the very nice "\f(CW\*(C`default\*(C'\fR\*(L", and the good old \&\*(R"\f(CW\*(C`old\*(C'\fR". .IP "\fBgraph_data_size\fR \fIvalue\fR" 4 .IX Item "graph_data_size value" This directive sets the resolution of the \s-1RRD\s0 files that are created. Possible values are \f(CW\*(C`normal\*(C'\fR and \f(CW\*(C`huge\*(C'\fR. Default is \f(CW\*(C`normal\*(C'\fR. \&\f(CW\*(C`Huge\*(C'\fR 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. .IP "\fBgraph_strategy\fR \fIvalue\fR" 4 .IX Item "graph_strategy value" Deprecated. (Graphs are now always drawn via \s-1CGI.\s0) .IP "\fBlocal_address\fR \fIvalue\fR" 4 .IX Item "local_address value" The local address to connect any node from in case the master has several \s-1IP\s0 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 \s-1IP\s0 routing table. .IP "\fBmax_processes\fR " 4 .IX Item "max_processes " 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. .IP "\fBmax_graph_jobs\fR " 4 .IX Item "max_graph_jobs " 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 .IP "\fBmax_cgi_graph_jobs\fR " 4 .IX Item "max_cgi_graph_jobs " 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. .IP "\fBtimeout_fetch_all_nodes\fR \fIseconds\fR" 4 .IX Item "timeout_fetch_all_nodes 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. .Sp You should probably not increase this value, unless all nodes are using ssh with munin-async. Otherwise you may expecience gaps in graphs, if \&\f(CW\*(C`munin\-update\*(C'\fR takes longer, than the default period (5 minutes). .Sp 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 .IP "\fBtimeout_fetch_one_node\fR \fIseconds\fR" 4 .IX Item "timeout_fetch_one_node 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 \&\f(CW\*(C`timeout_fetch_all_nodes\*(C'\fR. Default is 180. Affects: munin-update .IP "\fBssh_command\fR \fIvalue\fR" 4 .IX Item "ssh_command value" The name of the secure shell command to use. Can be fully qualified, or looked up in \f(CW$PATH\fR. Default: \f(CW\*(C`ssh\*(C'\fR .IP "\fBssh_options\fR \fIvalue\fR" 4 .IX Item "ssh_options value" The \f(CW\*(C`ssh\*(C'\fR command line options. Defaults: \f(CW\*(C`\-o ChallengeResponseAuthentication=no \-o StrictHostKeyChecking=no\*(C'\fR. .Sp If you need per-host ssh configuration, add these to \&\fI~/munin/.ssh/config\fR .IP "\fBtls\fR " 4 .IX Item "tls " Can have four values. \f(CW\*(C`paranoid\*(C'\fR, \f(CW\*(C`enabled\*(C'\fR, \f(CW\*(C`auto\*(C'\fR, and \&\f(CW\*(C`disabled\*(C'\fR. \f(CW\*(C`Paranoid\*(C'\fR and \f(CW\*(C`enabled\*(C'\fR require a \s-1TLS\s0 connection, while \f(CW\*(C`disabled\*(C'\fR will not attempt one at all. .Sp The current default is \f(CW\*(C`disabled\*(C'\fR because \f(CW\*(C`auto\*(C'\fR is broken. \f(CW\*(C`Auto\*(C'\fR causes bad interaction between munin-update and munin-node if the node is unprepared to go to \s-1TLS.\s0 .Sp If you see data dropouts (gaps in graphs) please try to disable \s-1TLS.\s0 Affects: munin-update. .IP "\fBtls_verify_certificate\fR " 4 .IX Item "tls_verify_certificate " This directive can be \f(CW\*(C`yes\*(C'\fR or \f(CW\*(C`no\*(C'\fR. It determines if the remote certificate needs to be signed by a \s-1CA\s0 that is known locally. Default is \f(CW\*(C`no\*(C'\fR. Affects: munin-update. .IP "\fBtls_private_key\fR " 4 .IX Item "tls_private_key " This directive sets the location of the private key to be used for \&\s-1TLS.\s0 Default is /etc/munin/munin.pem. The private key and certificate can be stored in the same file. Affects: munin-update. .IP "\fBtls_certificate\fR " 4 .IX Item "tls_certificate " This directive sets the location of the \s-1TLS\s0 certificate to be used for \&\s-1TLS.\s0 Default is /etc/munin/munin.pem. The private key and certificate can be stored in the same file. Affects: munin-update. .IP "\fBtls_ca_certificate\fR " 4 .IX Item "tls_ca_certificate " This directive sets the \s-1CA\s0 certificate to be used to verify the node's certificate, if tls_verify_certificate is set to \f(CW\*(C`yes\*(C'\fR. Default is /etc/munin/cacert.pem. Affects: munin-update. .IP "\fBtls_verify_depth\fR " 4 .IX Item "tls_verify_depth " This directive sets how many signings up a chain of signatures \s-1TLS\s0 is willing to go to reach a known, trusted \s-1CA\s0 when verifying a certificate. Default is \f(CW5\fR. Affects: munin-update. .IP "\fBtls_match\fR " 4 .IX Item "tls_match " 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: .Sp .Vb 2 \& 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 .Ve .Sp So, for example, one could match the subject distinguished name by the directive: .Sp .Vb 1 \& tls_match Subject Name: /C=c/ST=st/L=l/O=o/OU=ou/CN=cn/emailAddress=email .Ve .Sp 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. .Sp Unfortunately, due to the limited functionality of the \s-1SSL\s0 module in use, it is not possible to provide finer-grained filtering. By default this value is not defined. Affects: munin-update. .IP "\s-1FIXME:\s0 This section \s-1MAY\s0 be complete, it may be missing a directive or two." 4 .IX Item "FIXME: This section MAY be complete, it may be missing a directive or two." .SH "HOST DEFINITIONS" .IX Header "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 \s-1EOF.\s0 Note that when defining a nodename it is vital that you use a standard \s-1DNS\s0 name, as in, one that uses only a\-z, '\-', and '.'. While other characters can be used in a \s-1DNS\s0 name, it is against the \s-1RFC,\s0 and Munin uses the other characters as delimiters. If they appear in nodenames, unexpected behavior may occur. .PP The simplest node definition defines the section for a new node by simply wrapping the \s-1DNS\s0 name of the node in brackets, e.g. \&\f(CW\*(C`[machine1.your.dom]\*(C'\fR. This will add the node \f(CW\*(C`machine1.your.dom\*(C'\fR to the group \f(CW\*(C`your.dom\*(C'\fR. .PP The next form of definition is used to define the node and group independently. It follows the form \&\f(CW\*(C`[your.dom;machine1.sub.your.dom]\*(C'\fR. This adds the node \&\f(CW\*(C`machine1.sub.your.dom\*(C'\fR to the group \f(CW\*(C`your.dom\*(C'\fR. 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 \f(CW\*(C`machine1.com\*(C'\fR, where having a group of \f(CW\*(C`com\*(C'\fR makes little sense. .PP Multiple groups can be specified by adding more \f(CW\*(C`groupname;\*(C'\fRs, e.g. \&\f(CW\*(C`[servers;local;mail;mail.foo.net]\*(C'\fR, if you need a more hierarchical structure. .SH "NODE DIRECTIVES" .IX Header "NODE DIRECTIVES" These are directives that can follow a node definition and will apply only to that node. .IP "\fBaddress\fR " 4 .IX Item "address " The \s-1IP\s0 address of the node. Required. .IP "\fBlocal_address\fR " 4 .IX Item "local_address " The local address to connect to the node from. This overrides a group or global directive. .IP "\s-1FIXME:\s0 This section is incomplete." 4 .IX Item "FIXME: This section is incomplete." .SH "PLUGIN DIRECTIVES" .IX Header "PLUGIN DIRECTIVES" These directives should appear after a node definition and are of the form \f(CW\*(C`plugin.directive \*(C'\fR. 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. .IP "\s-1FIXME:\s0 This section is (obviously) incomplete." 4 .IX Item "FIXME: This section is (obviously) incomplete." .SH "FIELD DIRECTIVES" .IX Header "FIELD DIRECTIVES" These directives should appear after a node definition and are of the form \f(CW\*(C`plugin.field \*(C'\fR. Using these directives you can override values originally set by plugins on the nodes, such as warning and critical levels or graph names. .IP "\fBgraph_height\fR " 4 .IX Item "graph_height " The graph height for a specific service. Default is \f(CW175\fR. Affects: munin-graph. .IP "\fBgraph_width\fR " 4 .IX Item "graph_width " The graph width for a specific service. Default is \f(CW400\fR. Affects: munin-graph. .IP "\fBwarning\fR " 4 .IX Item "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 comma separated pair of numbers defining a valid range of values. Affects: munin-limits. .IP "\fBcritical\fR " 4 .IX Item "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 comma separated pair of numbers defining a valid range of values Affects: munin-limits. .IP "\s-1FIXME:\s0 This section is incomplete." 4 .IX Item "FIXME: This section is incomplete." .SH "EXAMPLES" .IX Header "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. .SH "EXAMPLE 1" .IX Header "EXAMPLE 1" An example with three servers on two domains: .PP .Vb 2 \& [machine1.one.dom] \& address machine1.one.dom \& \& [machine2.one.dom] \& address 10.33.32.123 \& \& [machine3.two.dom] \& address localhost .Ve .PP This will appear as two groups (one.dom and two.dom), having respectively two and one node. .SH "EXAMPLE 2" .IX Header "EXAMPLE 2" Summarize the 'load'\-graphs of the two servers in one.dom, in a 'total load'-graph. .PP .Vb 5 \& [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 .Ve .SH "AUTHORS" .IX Header "AUTHORS" Jimmy Olsen, Audun Ytterdal, Brian de Wolf, Nicolai Langfeldt .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2002\-2008 Audun Ytterdal, Jimmy Olsen, Nicolai Langfeldt, Linpro \s-1AS\s0 and others. .PP This is free software; see the source for copying conditions. There is \&\s-1NO\s0 warranty; not even for \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 .PP This program is released under the \s-1GNU\s0 General Public License .SH "SEE ALSO" .IX Header "SEE ALSO" For more information, see the man pages of the individual munin\-* programs or the Munin homepage .