Migrating to the new HTTP active check

As a site user, run the command

cmk-migrate-http --help

to get an overview of the available subcommands. These are:

• migrate: Migrate the v1 rules to v2 rules. This either performs a dry run or creates (for now inactive) rules to use side-by-side. Which mode is performed is determined by additional parameters: --dry-run or --write.
• activate: Activate the previously created, inactive v2 rules.
• deactivate: Deactivate active, but not finalized v2 rules.
• delete: Delete all v2 rules that have not been finalized yet.
• finalize: Delete migrated v1 rules and remove the references from the v2 counterparts. This step is irreversible!

Each subcommand has its own help option. Here those of migrate are the most important ones since this prepares the migration. All actions can be limited to folders (optionally recursively) and hosts. The latter option does not work on host names but on host conditions.

Also note that the folder option does not work on folder names as shown in the GUI, but on the mangled folder names (changed to lower case, special characters and spaces replaced) used internally: Try with the known folder name first, if this does not exist, you will be presented with a list of the available internal folder names:

cmk-migrate-http migrate --dry-run --folder 'a nested folder with spaces'
Starting dry run.
Importing...
Loading plugins...
Loading rule sets...
No folder found for the given argument. Use the 'script_folder_key' for the desired folder. Available folders:
Main > ''
badssl > 'badssl'
somefolder > 'somefolder'
somefolder/a nested folder with spaces > 'somefolder/a_nested_folder_with_spaces'

As mentioned above, the migration script allows dry-running, testing the effect of both v1 and v2 rules on the monitoring in parallel and later finalizing the configuration as well as rollbacks at any point. Additionally, you can edit any new rule before finalizing. If you mess something up, just roll it back and start over again. In this chapter we show you how to run a migration.

Do the dry run first:

cmk-migrate-http migrate --dry-run

The check will then show how many rules are present, how many of those could be automatically converted and how many need interaction. In case of incompatible rules, we suggest skipping the migration. You can migrate only compatible rules by adding the appropriate flags, for example

cmk-migrate-http migrate --dry-run --ssl-incompatible skip

for rules found that try to force an outdated TLS version. These will be ignored and you can care for them later. Combine as many flags as needed to only migrate non-ambiguous rules in the first run. You will read more on conflict solving later. When you are happy with the result, run with the --write option to actually write the new rules, for example:

cmk-migrate-http migrate --write --ssl-incompatible skip --v2-checks-certificate skip

Now the migrated rules are written, but inactive. Scroll through those rules and check whether they look reasonable.

You have two possibilities of enabling the rules: Use the activate subcommand of the script to enable all freshly migrated rules or enable them one by one in the GUI. In both cases, you also have to activate changes to bring them into effect.

Remember, that enabling all in one run can result in a high number of CRIT services, depending on how careful the old rules were configured. Since the old check did not check the host name presented in the certificate, it posed no problem to perform a certificate lifetime check on the IP address. Thus, we changed the default behavior for an empty or unspecified Address field from IP address to host name.

Note: In case you have manually specified an IP address to connect to, you will have to modify the migrated rules. Feel free to modify anything. Remember, if you break something, you can always deactivate all migrated rules or even discard everything and start over again.

You will almost always run into situations where at least some rules migrated are not satisfactory. In this case you can roll back partially or completely. Partial rollbacks are executed by just deleting the v2 rules that should not be converted in this migration run. Full rollbacks are performed by using the deactivate and then the delete subcommand.

We already mentioned challenges you might encounter and recommended skipping rules that cannot be migrated without user interaction. Now is the time to migrate those rules. For a total eleven common conflicts we have created the possibility to automagically resolve the conflict. In many cases, this will result in v2 rules that work as intended, in some additional configuration might be needed.

Problems, their (partial) resolution via command line and possible adjustments required are only the most important ones. Always use the cmk-migrate-http migrate --help command as the definitive reference since we might extend the choices for existing migration options or add options as needed.

When using check_http for URL checks with HTTPS enabled, it defaulted to not check the certificate validity. The new v2 check defaults to checking certificates. Whether you want to migrate to the new behavior or stay closer to the old behavior can be specified with --v2-checks-certificates together with the keywords skip, keep (keep v2 more strict default) or disable (ignore certificate checks completely). To be able to merge certificate and URL checking later, we recommend to use keep.

Something similar applies to sole certificate checks: v2 always checks all aspects of a certificate, while v1 only checks remaining validity. Use --cant-ignore-certificate-validation to specify whether to skip migrating affected rules or accept the new default behavior. In case you migrated URL checks with the stricter defaults, you can easily add remaining lifetime validation to the URL check and thus save one active check per host.

One crucial aspect of certificate handling changed: The old check did use the host address as default for connection attempts also in the HTTP request header, while the new check uses the host name. This behavior is also mapped during migration. Together with the stricter behavior this should minimize the problems resulting from migration. However: in case you manually specified the $HOSTADDRESS$ macro it will not be replaced, and you might be confronted with failing checks.

Version 2 of the check only supports TLS 1.2 and 1.3. You might have specified rules forcing older versions that the new check does not support anymore. In this case you might use --ssl-incompatible negotiate to change the migrated rule to version negotiation.

In case you really need to monitor hosts with such outdated TLS/SSL versions, you probably want to follow the guide we published for the Checkmk 2.3.0 release where the OpenSSL update to 3.x caused incompatibilities with TLS 1.0 and earlier.

While the old check_http allowed for a free form definition of both request and response headers, the new check expects a certain set of field-value pairs. Rules that do not obey to the “Header: value” scheme need user decision. Use --add-headers-incompatible and --expect-response-header with either the skip or ignore keyword either skip migrating the rule or force migration with the option removed. Fix later if necessary.

With the old check you could specify arbitrary status codes. Not only three digit numbers like 320 (or 737…), but also strings (for details see Werk 17738). In some cases when the string specified was found somewhere in the response headers this led to no error. Usually you might want to ignore such wrong status codes. Use --only-status-codes-allowed with the ignore keyword to migrate such rules with the wrong status code removed and check carefully afterward.

The old check did not follow the redirect for checking other aspects of the response like strings within the body. The new check follows redirects first and then checks. Use --v1-skips-redirect-response acknowledge to confirm the new default. You might later fine tune redirect settings when testing and editing the rules.

The new check does not support OPTIONS, TRACE, CONNECT, CONNECT_POST, PROPFIND anymore. In case you configured them for the old check, you can use --method-unavailable to ignore these methods and switch to GET (when no post data is present) or POST (in case post data is present).

Furthermore, the old check lets you configure post data for non-post methods. In case such a configuration is found, you can use --cant-post-data post to change the method to POST or --cant-post-data prefermethod to migrate the method, but ignore the post data.