→ Applies to: SynetoOS 6.x and above

Ensure the following prerequisites are met before starting:

– SynetoOS Prometheus API access configured ("How to Generate API Keys in SynetoOS 6.0")

Configure Checkmk via API

Step 1. Download Synetoos_Checkmk_Template binary file  download

Step 2. Upload Synetoos_Checkmk_Template file in Checkmk server /tmp folder

Step 3. Connect to Checkmk server via SSH (replace <user> withe the correct username and <your_checkmk_ip_address_or_hostname> with the correct ip address)

ssh <user>@<your_checkmk_ip_address_or_hostname>

Step 4. Unzip the downloaded file

unzip /tmp/synetoos_checkmk_template.zip -d /tmp/synetoos_package

NOTE
The zip contains a nested synetoos_checkmk_package folder — this is expected and reflected in the paths used in later steps. Unzipping directly into /tmp avoids the extra step of copying the files there afterwards.

Step 5. Give permissions to /tmp/synetoos_package

chmod -R a+r /tmp/synetoos_package

NOTE
Files are staged under /tmp because the Checkmk site user typically cannot read directly from another user's home directory.

Step 6. Switch into the Checkmk site

sudo su - <sitename>

EXAMPLE

sudo su - monitoring

Confirm the prompt changes to OMD[<sitename>]:~$ before continuing.

Step 7. Install the special agent

mkdir -p ~/local/share/check_mk/agents/special

cp /tmp/synetoos_package/synetoos_checkmk_package/agent_synetoos.py ~/local/share/check_mk/agents/special/agent_synetoos

chmod +x ~/local/share/check_mk/agents/special/agent_synetoos

Step 8. Install the check plugins

mkdir -p ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_pool_status.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/pool_status.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_pool_usage.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/pool_usage.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_disk_status.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/disk_status.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_replication_status.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/replication_status.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_protection_status.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/protection_status.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_vm_state.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/vm_state.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_vm_cpu.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/vm_cpu.py

IMPORTANT
Do not create any shared/imported helper file between check plugins (e.g. a _common.py imported by multiple files). Checkmk's plugin loader does not support this and fails with No module named '_xxx'. Each check file must be fully self-contained.

Step 9. Verify the special agent reaches the appliance directly

readlink -f ~/local/share/check_mk/agents/special/agent_synetoos

EXAMPLE OUTPUT

/opt/omd/sites/monitoring/local/share/check_mk/agents/special/agent_synetoos

Step 10. Check the connectivity (replace <synetoos-ip> and <api-key> with the correct information)

~/local/share/check_mk/agents/special/agent_synetoos --host <synetoos-ip> --api-key <api-key> --no-cert-check

EXAMPLE OUTPUT

<<<synetoos_pool_status:sep(0)>>>
[{"subject_name": "nvme", ..., "value": "0", ...}]
<<<synetoos_pool_usage:sep(0)>>>
[{"subject_name": "nvme", ..., "value": "3.67", ...}]
...

NOTE
Confirm all seven expected sections appear before continuing (synetoos_pool_status, synetoos_pool_usage, synetoos_disk_status, synetoos_replication_status, synetoos_protection_status, synetoos_vm_state, synetoos_vm_cpu_time). If any command errors out here, resolve it before touching the Checkmk UI.

Step 11. Restart the site (replace <sitename> with the correct information)

exit

sudo omd restart <sitename>

IMPORTANT
This step is mandatory after installing or updating any plugin file. cmk -d and cmk -I can succeed using a fresh one-off process even while the site's long-running core still uses stale, previously-loaded plugin code. Skipping the restart can cause services to register as "Unimplemented check plug-in" even though the files on disk are correct.

Step 12. Login to CheckMk GUI (replace <your_ip_address_or_hostname> with the correct ip/hostname)

https://<your_ip_address_or_hostname>

Step 13. From Setup, Click on Hosts

Step 14. Select Add host to the monitoring

Step 15. Fill in all the information, then click on Save & view folder

• Host name: a name distinct from the appliance's OS-level host (e.g. NODE2-API-MONITORING), to avoid mixing OS/API monitoring with hardware monitoring on the same host entry
• IPv4 address: the Host management IP
• API integrations if configured, else Checkmk agent

NOTE
A "Failed to connect to the Checkmk agent / Cannot resolve host name" message may still appear during connection testing — this refers to Checkmk's standard agent check running alongside the custom program, and can be ignored, since it explicitly states: "If not, you can ignore this message."

Step 16. From the Setup menu, select Other integrations

Step 17. Select Individual program call instead of agent access

Step 18. Click on Add rule

Step 19. Fill in the command below (replace <absolute-path-from-step-9> and <api-key> with the correct information)

<absolute-path-from-step-9> --host $HOSTADDRESS$ --api-key <api-key> --no-cert-check

This command will be used in the next Step 20.

Step 20. Give the rule a Description, under the Command line to execute line, insert the command from Step 19, select your Host to monitor, then click on Save

EXAMPLE

/opt/omd/sites/monitoring/local/share/check_mk/agents/special/agent_synetoos --host $HOSTADDRESS$ --api-key WqJZ80ZNt54FWfhgEZLxHtUWd0_CGliUfTJhMQRI6FA --no-cert-check

IMPORTANT

• Ensure "Do not apply this rule" is left unchecked (i.e. the rule is active).
• Use the full absolute path.
• Set the rule's condition to the target host (explicit host name is simplest).

Step 21. From the Changes menu, click on Activate pending changes

Step 22. From Setup, Click on Hosts

Step 23. Select your Host

Step 24. Click on Save & run service discovery

Step 25. Click on Monitor undecided services

NOTE
If any services show as "Vanished — Unimplemented check plug-in not implemented", this means discovery ran before the site was restarted with the corrected plugin code. Click Remove vanished services, then Rescan.

Step 26. From the Changes menu, click on Activate pending changes

Step 27. Once completed, the host should show all monitored services

EXAMPLE OUTPUT

Pool Health nvme            OK   Pool status: ONLINE (code 0)
Pool Storage nvme           OK   Pool usage: 3.68%
Disk Health /dev/sda        OK   Disk healthy (...)
Replication VM2 -> NODE1    CRIT Last replication attempt FAILED or was canceled
Protection VM1              OK   Last protection job succeeded
VM State VM1                OK   VM state: the domain is running (code 1)
VM CPU VM1                  OK   CPU usage: 0.09 CPU-seconds/second

NOTE
On the very first check run, VM CPU services will show "Collecting initial CPU rate sample" rather than a value — this is expected, since CPU usage is calculated as a rate between two samples. A real value appears after the next check cycle.

Configure Checkmk via SNMP

Hardware sensor data (fan speed, CPU/DIMM temperatures, PSU status, voltage rails) is monitored separately from the metrics above. It does not use the special agent — it connects directly to the appliance's BMC/IPMI interface over SNMP, using Checkmk's built-in SNMP support.

IMPORTANT
The BMC/IPMI has its own dedicated management IP address, separate from the appliance's normal network/OS IP. Confirm this IP before starting — it is typically found in the appliance's IPMI/BMC web UI itself, or in the hardware's initial setup documentation.

Step 1. Login to IPMI GUI (replace <your_ip_address_or_hostname> with the correct ip/hostname)

https://<your_ip_address_or_hostname>

Step 2. Go to Configuration → SNMP, Enable and configure it, then click on Save (or, on newer G4/G5 appliances: Configuration → Notifications → SNMP)

• Enable SNMP (top-level toggle)
• SNMPv3 → Enable
• User Name: choose a dedicated read-only username, e.g. snmpuser
• Auth Protocol: SHA1
• Private Protocol: AES
• Auth Key: set a strong passphrase
• Private Key: set a strong passphrase

IMPORTANT
Record the exact username, auth key, and private key — these must be entered identically into Checkmk.

Step 3. Connect to Checkmk server via SSH

ssh <user>@<your_checkmk_ip_address_or_hostname>

Step 4. Verify SNMP connectivity from the Checkmk server (replace <username>, <auth-key>, <private-key> and <ipmi-ip> with the correct information)

snmpget -v3 -l authPriv -u <username> \
    -a SHA -A "<auth-key>" \
    -x AES -X "<private-key>" \
    <ipmi-ip> .1.3.6.1.2.1.1.1.0

EXAMPLE OUTPUT

iso.3.6.1.2.1.1.1.0 = STRING: "Linux (none) 3.18.0 #1 Tue Jan 18 14:45:13 CST 2022 armv6l"

NOTE
If this returns "Unknown user name" or times out, confirm the SNMP configuration was actually saved on the BMC side, and that the same credentials are used exactly as entered there.

Step 5. Login to CheckMk GUI (replace <your_ip_address_or_hostname> with the correct ip/hostname)

https://<your_ip_address_or_hostname>

Step 6. From Setup, Click on Hosts

Step 7. Select Add host to the monitoring

Step 8. Configure as below

• Host name: a name distinct from the appliance's OS-level host (e.g. NODE2-BMC), to avoid mixing hardware monitoring with OS/API monitoring on the same host entry
• IPv4 address: the BMC's management IP

Under Monitoring agents:

• SNMP: enable, then select "Credentials for SNMPv3 with authentication and privacy (authPriv)"
• Authentication protocol: SHA-1
• Security name: the username from Step 2
• Authentication password: the auth key from Step 2
• Privacy protocol: AES (or AES-128 — match whatever the BMC actually uses; some BMCs do not support AES-256)
• Privacy pass phrase: the private key from Step 2

IMPORTANT
Do not configure the BMC under the "Management board" section of the OS-level host. Checkmk flags this as deprecated — monitor the BMC as its own dedicated host instead.

Step 9. Click on Save & run service discovery

Step 10. Select Monitor undecided services, then click on Accept all

Step 11. From the Changes menu, click on Activate pending changes