You can find the shiny new documentation here, which is replacing over time this one.
Thus, this article is obsolete and may be not valid anymore - however, the new one is not finished yet!
1. The main configuration file main.mk
Checkmk needs at least one configuration file: main.mk. You have to define at least one variable: all_hosts. It lists all hosts you want to monitor with Checkmk:
all_hosts = [ "localhost", "srvlnx01", "srvlnx02" ]
Checkmk looks for main.mk in the directory you configured at setup (the default is /etc/check_mk/main.mk). You can override the location of the configuration file with the option -c (useful for tests). In OMD the path to main.mk is in ~/etc/check_mk/main.mk, where ~ is the home directory of your site.
2. Further configuration files in conf.d
After reading main.mk Checkmk is looking for a subdirectory conf.d of the configuration directory. That defaults to /etc/check_mk/conf.d. Note that if you use the option -c /tmp/test/main.mk then that directory will be /tmp/test/conf.d.
Checkmk will read in all files ending with .mk in that directory just as main.mk. That will be done in no particular order. Please do not rely on the order - it might change in future.
Starting from version 1.1.9i9 the files in conf.d are read in in alphabetical order. That way you can enforce a certain order, e.g. by prefixing the files with 01-, 02- and so on.
Starting from version 1.1.11i1 also subdirectories below conf.d will be honored (recursively). Checkmk will read in all files it finds anywhere below conf.d as long as the end with .mk.
Start from version 1.2.0p2 the order the files are read in is even more precise. The following rules hold:
- When Checkmk reads in all the entries of a directory it:
- first reads the configuration files (*.mk)
- then reads the subdirectories
- Files / directories on the same level are read in alphabetical order (as introduced in version 1.1.9i9).
After having read everything in conf.d finally the file final.mk is being read if present. It's looked for in the same directory as main.mk. You can put things there that you need to be sure are read last.
If you are working with Backup & Restore, then you might also want to make use of the file local.mk, which is read yet after all other files. This file is ignored by backup and restore and allows to put settings outside the scope of the backup there. This is a feature of version 1.1.9i9 and later.
3. The syntax of main.mk is Python
Checkmk's config files are all in Python syntax. Since Checkmk itself is written in Python that makes life easier for Checkmk. But that makes life easier for you since it allows you to make use of Python's flexibility.
3.1. Comments, empty lines
Empty lines, comments and spaces are allowed everywhere:
# comments begin with hash marks. Empty lines are allowed nagios_command_pipe_path = "/var/log/nagios/rw/nagios.cmd"
But: all variable definitions must begin at the first column:
variable1 = 17 # this makes Python unhappy: variable2 = 18
3.2. Quotes, strings, comments
Other then in the Shell all strings and texts have to be written in Quotes. You are free to use either single quotes or double quotes:
nagios_command_pipe_path = '/var/log/nagios/rw/nagios.cmd'
... is just as valid as:
nagios_command_pipe_path = "/var/log/nagios/rw/nagios.cmd"
Where we deal with numbers quotes are disallowed. Python makes a distinction between numbers and strings:
tcp_connect_timeout = 5.0
3.3. Brackets and lines breaks
Line breaks are special for Python. They denote the end of a command. There is one exception to that rule: While waiting for a closing bracket line breaks are ignored. So this is valid:
all_hosts = [ "localhost", "lnxsrv01", "lnxsrv02" ]
... while this is not:
all_hosts = [ "localhost", "lnxsrv01", "lnxsrv02" ]
3.4. Trailing commas
If you deal with lists of hosts you might get annoyed about the missing comma after the last entry. You needn't: Python allows a comma even here:
all_hosts = [ "localhost", "lnxsrv01", "lnxsrv02", ]
This comes in handy if you want to comment out the last entry. You can do this without worring about commas:
all_hosts = [ "localhost", "lnxsrv01", # "lnxsrv02", ]
4. Appending to lists and other entries
The directory conf.d allows you to modularize your configuration. You could create one file for Windows hosts, one for Linux hosts and so on. You do not put all hosts into all_hosts directly in main.mk but add them later in separate configuration files. This is simply done by adding lists with a plus sign.
Let's make an example: This is the main file, only defining localhost:
all_hosts = [ 'localhost' ]
In conf.d/windows.mk you add some Windows hosts:
all_hosts = all_hosts + [ 'winserv01', 'winserv02', ]
Even if you want to add just a single entry, do not forget to put it into a list:
all_hosts = all_hosts + [ 'lnxsrv01' ]
The same mechanism is useful in many other places, for example when you define checks:
checks += [ ( ['linux'], ALL_HOSTS, 'cpu.loads', None, ( 20.0, 40.0 ) ), ]
Some configuration variables are organized as dictionaries. In those cases it is most convenient to add values with Python's bracket operator:
clusters['oracluster1'] = ( 'zsrvora01', 'zsrvora02' )