aim-web2.1.0rc9
This commit is contained in:
admin_rb
@@ -0,0 +1,247 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user