Ansible/scripts/docs/CHECKMK.md

Checkmk deployment and UniFi settings

1. Controller maintenance versus host deployment

AIM's top-level Maintenance downloads agent packages and updates the external monitoring repository directly. No separate Bash helper is installed or required. These operations are separate from customer playbooks. The package directory and stable filenames remain:

/etc/ansible/roles/checkmk_agent/files/
  check_mk_agent.msi
  check-mk-agent.deb
  check-mk-agent.rpm

checkmk_install_agent.yml installs the selected platform package, then deploys checks/configuration and ensures the agent service is running. checkmk_update_scripts_config.yml does not install packages. checkmk_cleanup_scripts.yml previews obsolete managed paths by default.

AIM passes its two non-secret controller paths through environment variables used at role-default precedence. Inventory overrides still win. Manual execution uses the documented /etc/... defaults unless you configure the role variables.

Controller-wide Checkmk agent source

AIM stores controller-wide settings in /etc/ansible/scripts/aim.yml. The Checkmk agent source is structured rather than stored as a complete URL:

maintenance:
  checkmk_agent:
    protocol: https
    base_url: monitoring.domain.de
    site_name: monitoring
    version: 2.4.0
    patchlevel: 46
    revision: 1
    role_files_dir: /etc/ansible/roles/checkmk_agent/files

AIM builds the download root as https://monitoring.domain.de/monitoring/check_mk/agents and the package version as 2.4.0p46-1. /check_mk/agents is always appended automatically. These values are edited in the top-level Settings menu and reused by Maintenance without asking again.

2. Known external script sources

The repository remains /etc/checkmk_monitoring_scripts. AIM performs the Git update itself. Because this is a managed shadow checkout, AIM uses git fetch --prune followed by git reset --hard @{u} rather than invoking an external git pull wrapper. Tracked local drift is discarded after explicit confirmation; untracked files are retained.

File contents are not included in this bundle and were not supplied for this review; they are not rewritten, renamed, or executed by the build tests.

File	Selection
Scripts Windows/check-ping.ps1	Detected domain controller, as before
Scripts Windows/veeam_config_backup_status.ps1	Detected Veeam VBR, as before
Scripts Windows/veeam_backup_license_status.ps1	Detected Veeam VBR; local check → $CUSTOM_LOCAL_PATH$
Scripts Windows/veeam_o365_status.ps1	Detected Veeam VBO; custom plugin → $CUSTOM_PLUGINS_PATH$
Scripts Windows/citrix_sessions_customized.ps1	want_windows_citrix; custom plugin → $CUSTOM_PLUGINS_PATH$
Scripts Windows/veeam_surebackup_status.ps1	want_windows_surebackup
Scripts Windows/windows-backup.ps1	want_windows_backup
Scripts Windows/check-nsp-mailqueue.ps1	want_windows_nsp_mailqueue
Scripts Windows/win_check_cert.ps1	want_windows_certificate
Scripts Windows/veeam_cloud_connect_status.ps1	want_windows_veeam_cloud_connect
Scripts Windows/veeam_backup_status.ps1	want_windows_veeam_backup; custom plugin → $CUSTOM_PLUGINS_PATH$
Scripts Linux/check_certificate_directory.sh	want_linux_check_certificate
Scripts Linux/check_unifi-controller/check_unifi-controller.sh	UniFi network mode
Scripts Linux/check_unifi-controller/check_unifi-os.sh	UniFi OS mode

All optional switches default to false. Auto-detected existing behavior is retained. The repository Veeam backup local check is a separate opt-in from the built-in agent plugin to avoid silently duplicating it.

citrix_sessions_customized.ps1, veeam_o365_status.ps1, and veeam_backup_status.ps1 are custom plugins, not local checks. AIM enables their exact $CUSTOM_PLUGINS_PATH$ rules before the general custom-plugin deny rule. When selected, deployment removes the legacy AIM-managed copy from C:\ProgramData\checkmk\agent\local after the plugin copy is in place. Unknown files remain untouched.

Source-file preflight checks that each selected file exists before deployment. A filename does not establish the check's internal parameters, privileges or credentials: configure those according to the maintained script repository. No new script-specific credential format was guessed from the filenames.

3. Single UniFi configuration

# host_vars/<fqdn>/main.yml
checkmk_unifi_mode: network     # auto, network, os, disabled
checkmk_unifi_username: bf-monitoring
checkmk_unifi_password: "{{ vault_checkmk_unifi_password }}"

In the encrypted customer Vault, set:

vault_checkmk_unifi_password: "REPLACE_WITH_THE_REAL_MONITORING_PASSWORD"

This is the UniFi monitoring password, not the Ansible Windows/SSH login password. Existing Vaults are not silently modified. Vault creation/consolidation can prepare an empty optional key; an empty value or CHANGEME fails deployment preflight.

Different hosts can override the reference, without exposing the secret in AIM:

checkmk_unifi_password: "{{ vault_unifi_site_a_password }}"

The AIM run-option field accepts the variable name vault_unifi_site_a_password, not a password value. Persist long-lived per-host choices in host vars; run options are temporary extra variables for the selected execution only.

Mode and endpoint defaults

Mode	Check	Default BASEURL
network	check_unifi-controller.sh	https://127.0.0.1:8443
os	check_unifi-os.sh	https://127.0.0.1:11443
auto	Detected variant; OS wins if both are detected	Variant default
disabled	Neither selected for deployment	No config replacement

An explicit checkmk_unifi_baseurl overrides the endpoint. In selected network/OS mode, the role writes one /etc/check_mk/unifi.cfg, deploys the matching check, and removes only the opposite UniFi check. An explicitly disabled mode does not silently remove existing files during a normal update: review the cleanup action.

Supplied config schema preserved

checkmk_unifi_curl_options: " --insecure --tlsv1.2"
checkmk_unifi_status_provisioning: 1
checkmk_unifi_status_upgrading: 1
checkmk_unifi_status_upgradable: 0
checkmk_unifi_status_heartbeat_missed: 1
checkmk_unifi_status_noautobackup: 0

Statuses are 0 OK, 1 WARN, 2 CRIT, 3 UNKNOWN. The template emits USERNAME, PASSWORD, BASEURL, CURLOPTS and the five STATUS_* settings with shell-safe quoting, validates shell syntax and sets mode 0600. Secret-bearing tasks have no_log: true and diff: false. The source repository's unifi.cfg is no longer copied to the host. The supplied insecure TLS option remains unchanged; enabling certificate validation is a separate operational decision, not hidden in this refactor.

4. Read current Windows user configuration

Before or after a rollout, checkmk_read_windows_config.yml can display the host's current check_mk.user.yml without changing it. This is intended for verifying existing global, local, mrpe, plugin, or custom sections before AIM touches the managed plugins: section.

ansible-playbook -i inventories/CUSTOMER/hosts.yml \
  playbooks/checkmk_read_windows_config.yml --limit HOST \
  --vault-id CUSTOMER@prompt

The default path is C:\ProgramData\checkmk\agent\check_mk.user.yml. Set checkmk_windows_user_cfg only for hosts using a different location. The playbook reports a missing file without creating it and makes no Checkmk changes.

5. Cleanup

AIM always starts cleanup in preview mode. It requires explicit deletion enablement and a second confirmation before running with checkmk_cleanup_enabled=true. Only the known managed filenames are considered; unrelated custom files stay. The preview is a list of paths considered obsolete by the selected desired state, not proof each path currently exists. This is distinct from the approved opposite- UniFi removal during normal mode replacement.

Manual examples:

ansible-playbook -i inventories/CUSTOMER/hosts.yml \
  playbooks/checkmk_cleanup_scripts.yml --limit HOST \
  --vault-id CUSTOMER@prompt

# Destructive: enable only after reviewing the intended checks/mode.
ansible-playbook -i inventories/CUSTOMER/hosts.yml \
  playbooks/checkmk_cleanup_scripts.yml --limit HOST \
  --vault-id CUSTOMER@prompt -e '{"checkmk_cleanup_enabled": true}'

6. Windows execution policy

AIM now treats C:\ProgramData\checkmk\agent\check_mk.user.yml as a shared operator configuration file, not as an AIM-owned file. On Windows, AIM owns only the top-level plugins: section. The existing global, winperf, fileinfo, logwatch, local, mrpe, unknown top-level sections, and their comments are preserved. This is important for older or manually customized Checkmk agents where those sections may contain host-specific behavior.

AIM keeps an ownership notice on the first line and places another ownership comment immediately before the plugins: section. Only the marked plugins: section may be replaced on later runs. If no plugins: section exists, AIM appends one without rewriting the rest of the file.

The effective AIM plugin timeout remains 120 seconds. Settings live in role defaults so host/group overrides work. Optional plugin rules are typed list entries such as:

checkmk_extra_plugin_patterns:
  - pattern: '$CUSTOM_PLUGINS_PATH$\example.ps1'
    run: true
    async: true
    timeout: 90
    cache_age: 600

AIM deliberately does not manage local: or mrpe:. Existing local-check execution policy and MRPE definitions remain exactly under operator/Checkmk control. The same applies to any other non-plugin user configuration.

The plugins: section retains the standard AIM ordering: explicit/custom rules first, then known built-in rules, custom-plugin catch-alls, the built-in deny rule, and the final safety deny. Checkmk reads the user configuration after default and Bakery configuration, so section-scoped ownership avoids unintentionally overriding unrelated settings.

Actual behavior of the Windows agent and external checks still requires a representative pilot.

Structured reports in 3.3.0rc8

Install reports query registry/package database version and current service state after the existing management roles. Config-update reports list changed sections/check files and the narrowly approved opposite-UniFi deletion. They do not expose raw config diffs, guess unknown-file counts or alter unmanaged sections. The reporting-only checkmk_report role does not install/configure services itself.

The read playbook now limits paths to basename check_mk.user.yml and 512 KiB. Native terminal readout remains explicit; API reports parse sections and redact recognized secret/command fields, including MRPE commands. Comments are not parsed YAML data. See OPERATION_RESULTS.md for exact semantics and VALIDATION.md for acceptance limits.

Windows AIM-managed file ACLs

AIM normalizes ACLs only on persistent files it manages directly: selected Windows Checkmk scripts in $CUSTOM_LOCAL_PATH$ / $CUSTOM_PLUGINS_PATH$ and check_mk.user.yml. Unknown files are not touched and directory trees are not rewritten recursively.

For each AIM-managed persistent file, checkmk_windows_acl enables parent inheritance and guarantees these well-known SID permissions independent of Windows display language:

SID	Principal	Rights
S-1-5-18	SYSTEM	FullControl
S-1-5-32-544	local Administrators	FullControl
S-1-15-2-1	ALL APPLICATION PACKAGES	ReadAndExecute
S-1-15-2-2	ALL RESTRICTED APPLICATION PACKAGES	ReadAndExecute

AIM does not add customer-specific administrator/user ACEs. Parent or explicit ACEs that already exist are not blindly purged; the goal is to guarantee the standard Checkmk-style administrative/application access while preserving operator ACL intent.