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:

```text
/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:

```yaml
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

```yaml
# 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:

```yaml
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:

```yaml
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

```yaml
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.

```bash
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:

```bash
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:

```yaml
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.