→ Applies to: SynetoOS 6.x and above

Ensure the following prerequisites are met before starting:

– SynetoOS API key with read access to metrics and node endpoints ("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> with 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

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_vdev_status.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/vdev_status.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_protection_summary.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/protection_summary.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_system.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/system.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_node_health.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/node_health.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_network.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/network.py

cp /tmp/synetoos_package/synetoos_checkmk_package/check_synetoos_vm_resources.py ~/local/lib/python3/cmk_addons/plugins/synetoos/agent_based/vm_resources.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.

NOTE
The folder must contain 13 .py files. A __pycache__ folder may also appear and can be ignored.

Step 9. Get the absolute path of the special agent

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 | grep -E '^<<<|queried'

EXAMPLE OUTPUT

<<<synetoos_pool_status:sep(0)>>>
<<<synetoos_pool_usage:sep(0)>>>
<<<synetoos_replication_status:sep(0)>>>
<<<synetoos_protection_status:sep(0)>>>
<<<synetoos_disk_status:sep(0)>>>
<<<synetoos_vdev_status:sep(0)>>>
<<<synetoos_vm_state:sep(0)>>>
<<<synetoos_vm_cpu_time:sep(0)>>>
<<<synetoos_system_cpu:sep(0)>>>
<<<synetoos_vm_vcpus:sep(0)>>>
<<<synetoos_vm_mem_max:sep(0)>>>
<<<synetoos_vm_mem_available:sep(0)>>>
<<<synetoos_vm_mem_usable:sep(0)>>>
<<<synetoos_vm_mem_swap_out:sep(0)>>>
<<<synetoos_vm_disk_read:sep(0)>>>
<<<synetoos_vm_disk_write:sep(0)>>>
<<<synetoos_vm_net_rx:sep(0)>>>
<<<synetoos_vm_net_tx:sep(0)>>>
<<<synetoos_vm_net_errors:sep(0)>>>
<<<synetoos_system:sep(0)>>>
<<<synetoos_node_health:sep(0)>>>
<<<synetoos_network:sep(0)>>>
<<<synetoos_agent_info:sep(0)>>>
{"queried": 22, "errors": []}

NOTE
Confirm all 23 sections appear and the last line shows "errors": []. If errors are listed (e.g. HTTP 403 Forbidden), check the API key, its permissions and its allowed networks 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> and <site_name> with the correct information)

https://<your_ip_address_or_hostname>/<site_name>

EXAMPLE

https://1.2.3.4/monitoring

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 (replace <api-key> with the correct information)

/opt/omd/sites/monitoring/local/share/check_mk/agents/special/agent_synetoos --host $HOSTADDRESS$ --api-key <api-key> --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

Disk Health /dev/nvme0                   OK   Disk healthy (Seagate FireCuda 530 ZP500GM30023, 7VP00D8R) - not in any pool (OS/boot disk)
Disk Health /dev/sda                     OK   Disk healthy (NVMe INTEL SSDPF2KX03, PHAX220305X63P8CGN) - pool member (nvme)
NIC em3 Management Uplink                OK   connected, 1 Gbit/s, no IP
Pool Health nvme                         OK   Pool status: ONLINE (code 0)
Pool Member nvme/scsi-200055f5252e4d25c  OK   ONLINE (code 0) - /dev/sda, NVMe INTEL SSDPF2KX03, PHAX220305X63P8CGN
Pool Storage nvme                        OK   Pool usage: 6.80%
Protection Summary                       OK   5 protected objects (0 failed); 5 replications (0 failed)
Protection VM1                           OK   Last protection job succeeded
Replication VM1 -> test 73               OK   Last replication attempt succeeded
SynetoOS API                             OK   All 22 API queries succeeded
SynetoOS Health                          OK   System state: ready, SynetoOS 6.1.0.8952, 8 services running
SynetoOS Online Services                 OK   All 5 online services reachable
System CPU                               OK   Usage: 14.5% (5 min average) (16 CPUs, AMD EPYC 3251 8-Core Processor)
System Memory                            OK   Used: 46% - 27.8 GB of 62.2 GB
VM CPU VM1                               OK   CPU usage: 18% of 2 vCPUs (0.36 CPU-seconds/second, 5 min average)
VM Disk I/O VM1                          OK   Read: 0.44 MB/s, Write: 0.08 MB/s (5 min average)
VM Memory VM1                            OK   Used: 82.5% - 3.2 GB of 3.8 GB (4.0 GB assigned)
VM Memory VM2                            OK   VM not running - 4.0 GB assigned
VM Network VM1                           OK   In: 0.04 Mbit/s, Out: 0.01 Mbit/s (5 min average)
VM State VM1                             OK   VM state: the domain is running (code 1)

NOTE
VM services (VM State, VM CPU, VM Memory, VM Disk I/O, VM Network) appear only on SynetoOS systems running Hyperion. VM Memory shows actual usage only if the guest reports it (balloon driver / guest tools). Otherwise it shows the assigned RAM. VM Disk I/O and VM Network are created for VMs that are running during discovery.
On VMware ESXi, monitor VMs with Checkmk's built-in VMware ESXi integration.

NOTE
A VM Network WARN with drops but no traffic usually means the guest's network interface is down or not configured inside the VM.

Configure Checkmk via SNMP and IPMI

Hardware data is monitored separately from the metrics above. It does not use the special agent. Instead, it connects directly to the appliance's BMC using Checkmk's built-in SNMP and IPMI support. IPMI provides the hardware sensors (fan speed, CPU/DIMM temperatures, voltage rails, and PSU status where the hardware reports it). SNMP provides information about the BMC itself. Configure one or both, as required.

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. Install ipmitool

sudo apt install -y ipmitool freeipmi-tools

NOTE
On RHEL-based Checkmk servers, use sudo dnf install -y ipmitool freeipmi

Step 5. Verify IPMI connectivity from the Checkmk server (replace <username>, <password> and <ipmi-ip> with the correct information)

ipmitool -I lanplus -H <ipmi-ip> -U <username> -P '<password>' sdr elist

EXAMPLE OUTPUT

CPU Temp         | 01h | ok  |  3.1 | 28 degrees C
System Temp      | 0Bh | ok  |  7.1 | 34 degrees C
DIMMA1 Temp      | B0h | ns  | 32.64 | No Reading
FAN2             | 42h | ok  | 29.2 | 8800 RPM
FANA             | 43h | ok  | 29.3 | 1700 RPM
12V              | 30h | ok  |  7.17 | 12.24 Volts

NOTE
IPMI over LAN is usually enabled by default, and the BMC web UI login can be used. If the command returns "Unable to establish IPMI v2 / RMCP+ session", check the credentials and confirm IPMI over LAN is enabled in the BMC GUI.

Step 6. 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 7. Login to CheckMk GUI (replace <your_ip_address_or_hostname> and <site_name> with the correct information)

https://<your_ip_address_or_hostname>/<site_name>

EXAMPLE

https://1.2.3.4/monitoring

Step 8. From Setup, Click on Hosts

Step 9. Select Add host to the monitoring

Step 10. 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 11. Click on Save & view folder

Step 12. From the Setup menu, select Other integrations

Step 13. Select IPMI sensors via Freeipmi or IPMItool

Step 14. Click on Add rule

Step 15. Give the rule a Description, Select Use IPMItool, insert your IPMI Credentials, select your Host to monitor, then click on Save

Step 16. Search for IPMI sensor discovery, then select it

Step 17. Click on Add rule

Step 18. Give the rule a Description, Select One service per sensor, select your Host to monitor, then click on Save

Step 19. From Setup, Click on Hosts

Step 20. Select your Host

Step 21. Click on Save & run service discovery

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

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