checkmk 2: Configuration#

This application is highly-customizable via configuration files and runtime settings.

Configuration files#

On startup it try to load the following files:

• /etc/idoitcmk/config.json (system-wide) and
• ~/.idoitcmk/config.json (user-defined)

Configuration files are formatted as JSON (JavaScript Object Notation), an easily-readable format for both humans and robots.

Create configuration file automatically#

Use command init to create your own configuration file:

1

idoitcmk init

This command will ask you several questions about all settings which are mentioned below. After that a configuration file will be written to ~/.idoitcmk/config.json.

If you run this command with super-user rights (root) a configuration file will be written to /etc/idoitcmk/config.json instead.

With this command you are even able to update your configuration settings. Before that a backup will be created in the background.

Create configuration files manually#

For a good start print the example configuration and edit it locally:

1
2
3

mkdir ~/.idoitcmk
idoitcmk print-example-config > ~/.idoitcmk/config.json
editor ~/.idoitcmk/config.json

Available settings#

The configuration settings are separated by topics:

Required topics are i-doit and check_mk, otherwise sharing information between them won't work. All other topics may be altered optionally.

For almost each setting there is a pre-defined default value. You may remove unchanged settings from your local configuration files.

Access i-doit's JSON-RPC API#

Configure how to access i-doit's JSON-RPC API:

Access checkmk's Web API and Livestatus#

Configure how to access checkmk's Web API:

Livestatus can currently not be connected via TLS.

Configure the used Checkmk Version#

Configure command push#

Configure how to push data from i-doit to checkmk:

Auto tagging#

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
    "push": {
        "autoTagging": {
            "title": {
                "/^00/": {
                    "tag_agent": "cmk-agent",
                    "tag_criticality": "prod"
                },
                "/mail/": {
                    "tag_system": "mail"
                }
            },
            "hostname": {
                "/^vm/": {
                    "tag_networking": "dmz"
                }
            },
            "fqdn": {
                "/test\\.local$/": {
                    "tag_criticality": "test"
                }
            }
        },
        "autoMatching": "all"
    }
}

Try to match all expressions:

• Objects whose titles (title) begin with 00 will be checked by an agent and are tagged as productive.
• Objects whose titles (title) has mail in the middle are tagged as mail hosts.
• Objects whose hostnames ( hostname) begin with vm are assigned to the DMZ.
• Objects whose fully qualified domain names (fqdn) end with test.local are tagged as test

Configure command pull#

Configure how to pull data from checkmk to i-doit:

Identifiers#

In i-doit there are several attributes which are suitable as unique identifiers to match them with hosts in checkmk:

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
    "pull": {
        "identifier": [
            "title",
            "hostname",
            "fqdn",
            "hostaddress",
            "alias",
            "user-defined"
        ],
        "minMatch": 2
    }
}

Attributes#

In i-doit each object attribute is bound to a so-called category. These categories can be altered:

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
    "pull": {
        "attributes": {
            "C__CATG__ACCESS": true,
            "C__CATG__APPLICATION": true,
            "C__CATG__CONTACT": true,
            "C__CATG__CPU": true,
            "C__CATG__DRIVE": true,
            "C__CATG__GRAPHIC": true,
            "C__CATG__IP": true,
            "C__CATG__MEMORY": true,
            "C__CATG__MODEL": true,
            "C__CATG__OPERATING_SYSTEM": true,
            "C__CATG__NETWORK_LOG_PORT": true,
            "C__CATG__NETWORK_PORT": true
        }
    }
}

Object types#

Used object types identified by their constants:

Object titles#

Used objects identified by their titles:

Roles#

This is a list of i-doit roles for contact groups used in contact assignments:

Blocklist object types#

This list of object types will be completely ignored by default:

You are not able to remove object types from this list (please raise an issue if you want to anyway). But you can expand this list by other object types.

In the next example all objects by type Client will be ignored, too. To identify this object type use its constant instead of its (English or German) title:

1
2
3
4
5

{
    "blacklistedObjectTypes": [
        "C__OBJTYPE__CLIENT"
    ]
}

Log levels#

The CLI tool idoitcmk has various log levels:

There is a configuration setting log.verbosity to adjust the default log level. This value will be used when neither runtime option -v|--verbose nor -q|--quiet are used. The current default value is 31. That means all log messages except debug messages are included.

On the one side runtime option -v|--verbose sets this configuration setting temporarily to 63 which includes all log levels. On the other side runtime option -q|--quiet sets it temporarily to 3 (only fatals and errors).

Additional configuration files#

Optionally, you may pass one or more additional JSON-formatted configuration files by using option -c or --config. Repeat option for more then one file. For example:

1

idoitcmk push --config i-doit-testing.json --config check_mk-testing.json

Runtime settings#

You would like to change some settings during runtime? You can do that with options -s and --setting. Separate nested keys with ., for example:

1
2
3

idoitcmk push --setting "push.activateChanges=true"

idoitcmk pull -s ['pull.attributes={"C__CATG__ACCESS": true,"C__CATG__APPLICATION": true,"C__CATG__CONTACT": true,"C__CATG__CPU": true,"C__CATG__DRIVE": true,"C__CATG__GRAPHIC": true,"C__CATG__IP": true,"C__CATG__MEMORY": true,"C__CATG__MODEL": true,"C__CATG__OPERATING_SYSTEM": true,"C__CATG__NETWORK_LOG_PORT": true,"C__CATG__NETWORK_PORT": true}']

Repeat option for more than one setting.

Order of configuration settings matters#

As you already read you have various options to pass your preferred settings to this application. This application follows this order:

1. Default settings will be overwritten by
2. System-wide settings (/etc/idoitcmk/config.json) will be overwritten by
3. User-defined settings (~/.idoitcmk/config.json) will be overwritten by
4. Additional configuration files (options -c FILE or --config FILE) will be overwritten by
5. Runtime settings (options -s KEY=VALUE or --setting KEY=VALUE)

Test your config#

With command configtest you are able to perform a detailed validation of your configuration settings. This is very useful after you create or change your settings:

1

idoitcmk configtest

Print your config#

If you have a bunch of configuration files and runtime settings sometimes it's good to know what are your compiled settings:

1

idoitcmk print-config

This will print your current configuration settings JSON-formatted to STDOUT.