Configuration#

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

Configuration Files#

On startup, the application attempts to load the following files:

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

The configuration files are formatted as JSON (JavaScript Object Notation), a format that is easily readable by both humans and machines.

Create Configuration File Automatically#

Use the init command to create your own configuration file:

1

idoitcmk init

This command asks you several questions about all settings listed below. Afterward, a configuration file is written to ~/.idoitcmk/config.json.

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

With this command you can even update your configuration settings. A backup is created in the background beforehand.

Create Configuration Files Manually#

For a good start, output 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 topic:

Required topics are i-doit and check_mk, otherwise the information exchange between them will not work. All other topics can be optionally changed.

There is a predefined default value for almost every setting. You can remove unchanged settings from your local configuration files.

Access to the JSON-RPC API of i-doit#

Configure access to the JSON-RPC API of i-doit:

Access to the Checkmk Web API and Livestatus#

Configure access to the Checkmk Web API:

Livestatus currently cannot be connected via TLS.

Configuration of the Used Checkmk Version#

Configuration of the push Command#

Configure how data is transferred 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"
    }
}

Tries to find all expressions:

• Objects whose title starts with 00 are checked by an agent and classified as productive.
• Objects whose title contains mail are tagged as mail hosts.
• Objects whose hostname starts with vm are assigned to the DMZ.
• Objects whose fully qualified domain name (fqdn) ends with test.local are tagged as test.

Configuration of the pull Command#

Configure how data is pulled from Checkmk to i-doit:

Identifiers#

In i-doit, there are several attributes that can serve 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, every object attribute is bound to a so-called category. The following categories can be modified:

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 title:

Roles#

List of i-doit roles for contact groups used in contact assignments:

Blacklisted Object Types#

The following list of object types is completely ignored by default:

It is not possible to remove object types from this list (please create a ticket if you still want to do so). However, you can extend this list with other object types.

In the following example, all objects of type Client are also ignored. 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 Level#

The CLI tool idoitcmk has various log levels:

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

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

Additional configuration files#

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

1

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

Runtime Settings#

Do you want to change some settings at runtime? You can do so with the -s and --setting options. Separate nested keys with ., for example:

1
2

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 the option for more than one setting.

Order of Configuration Settings Matters#

As you have already read, you have various options for passing your preferred settings to this application. The application follows this order:

1. The default settings are overridden by
2. System-wide settings (/etc/idoitcmk/config.json), which are overridden by
3. User-defined settings (~/.idoitcmk/config.json), which are overridden by
4. Additional configuration files (options -c FILE or --config FILE), which are overridden by
5. Runtime settings (options -s KEY=VALUE or --setting KEY=VALUE)

Test Your Configuration#

With the configtest command, you can perform a detailed check of your configuration settings. This is very useful after you have created or changed your settings:

1

idoitcmk configtest

Print Your Configuration#

If you have a number of configuration files and runtime settings, it is sometimes useful to know what your compiled settings are:

1

idoitcmk print-config

This outputs your current configuration settings in JSON format to STDOUT.