Overview

This guide walks through how to manually install and configure the Checkmk agent on macOS systems, including setting up pull-based monitoring using a LaunchDaemon on port 6556, as well as simulating push-based monitoring by sending agent output to the Checkmk server over SSH.

Configuring the Checkmk Agent on macOS in pull mode

This section covers how to configure the agent using the standard pull method over port 6556.

1. Download the macOS agent from your Checkmk Server

   Log into your Checkmk web UI and navigate to Setup → Agents → Other operating systems

   Download the check_mk_agent.macosx

   Open

   

   
   
   

2. Install optional dependencies
   Install Homebrew if it is not already installed.

   # https://brew.sh/ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   
   Install the recommended dependencies via Homebrew for full plugin support:

   user@myLinuxHost:~$ sudo brew install smartmontools osx-cpu-temp iproute2mac

    

3. Create the required directories

   user@myLinuxHost:~$ sudo mkdir -p /usr/local/lib/check_mk_agent/local user@myLinuxHost:~$ sudo mkdir -p /usr/local/bin user@myLinuxHost:~$ sudo mkdir -p /etc/check_mk

    

4. Install the Agent Script and Plugins
   
   Copy the agent to the correct locations:

   user@myLinuxHost:~$ sudo cp /path/to/agent/check_mk_agent.macosx /usr/local/lib/check_mk_agent/

   
   If you have plugins, copy them to the correct location:

   user@myLinuxHost:~$ sudo cp -r /path/to/plugins/ /usr/local/lib/check_mk_agent/

   
   Create a symlink for easy access:

   user@myLinuxHost:~$ sudo ln -s /usr/local/lib/check_mk_agent/check_mk_agent.macosx /usr/local/bin/check_mk_agent/check_mk_agent.macosx

    

5. Setup required log and runtime files

   user@myLinuxHost:~$ sudo touch /var/run/de.arts-others.softwareupdatecheck user@myLinuxHost:~$ sudo touch /var/log/check_mk.err user@myLinuxHost:~$ sudo chmod o+rw /var/run/de.arts-others.softwareupdatecheck user@myLinuxHost:~$ sudo chmod 666 /var/log/check_mk.err

    

6. Set correct permissions

   user@myLinuxHost:~$ sudo chmod +x /usr/local/lib/check_mk_agent/check_mk_agent.macosx user@myLinuxHost:~$ sudo chown -R root:admin /usr/local/lib/check_mk_agent

    

7. Create the LaunchDaemon to listen on port 6556
   
   macOS uses launchd instead of systemd or xinetd. You create a System LaunchDaemon plist file inside /Library/LaunchDaemons/ that responds to TCP port 6556, similar to how xinetd works on linux.
   
   Copy the following into your plist file.

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>check_mk</string> <key>ProgramArguments</key> <array> <string>/usr/local/lib/check_mk_agent/check_mk_agent.macosx</string> </array> <key>Sockets</key> <dict> <key>Listeners</key> <dict> <key>SockFamily</key> <string>IPv4v6</string> <key>SockServiceName</key> <string>6556</string> <key>SockType</key> <string>stream</string> </dict> </dict> <key>inetdCompatibility</key> <dict> <key>Wait></key> <false/> </dict> <key>RunAtLoad</key> <true/> </dict> </plist>

    

8. Set correct permission on the plist file

   user@myLinuxHost:~$ sudo chmod 644 /Library/LaunchDaemons/check_mk.plist

    

9. Load and enable the new LaunchDaemon

   user@myLinuxHost:~$ sudo launchctl load -w /Library/LaunchDaemons/check_mk.plist

    

10. Open port 6556 in the macOS Firewall

    # Check firewall status sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate # Allow the agent through sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/lib/check_mk_agent/check_mk_agent.macosx sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /usr/local/lib/check_mk_agent/check_mk_agent.macosx

     

11. Verify the agent is listening

    user@myLinuxHost:~$ sudo lsof -i :6556 # or user@myLinuxHost:~$ netstat -an | grep 6556

     

12. Check connectivity from the Checkmk Server

    user@myLinuxHost:~$ echo | nc <mac-ip-address> 6556

     

13. Add the macOS host to Checkmk and perform a service discovery

    Open

    

Configuring the Checkmk Agent on macOS in a simulated push mode

This method simulates push behavior by sending agent output to the server at regular intervals.

The legacy macOS agent (from the previous guide) does not include the cmk-agent-ctl component required for push mode. Since the Agent Controller is only officially available for Linux and Windows, push mode on macOS must be simulated by running the agent on a schedule and sending the output to the Checkmk server over SSH.

1. Create an SSH key for a user on macOS

   user@myLinuxHost:~$ ssh-keygen -t ed25519 -C "your_email@example.com"

    

2. Copy the public key to the Checkmk server

   Specifically to the site users "authorized_keys" file within the sites ".ssh" folder.

   OMD[SITE_USER]:~/.ssh$ ls authorized_keys

    

3. Create a folder on the Checkmk server to store the agent outputs.

   OMD[mysite]:~$ mkdir ~/var/agent_output/macos_output

    

4. Create a simple shell script

   This runs the Checkmk agent and writes the output to a file on the Checkmk server over ssh.

   #!/bin/sh #execute Checkmk agent and ssh results to server /usr/local/bin/check_mk_agent.macosx | ssh SITE_USER@CHECKMK_SERVER "cat > ~/var/agent_output/macos_output"

    

5. Create a plist file

   Execute this script every minute and place it in "/Library/LaunchDaemons" to load at start up and run system wide.

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>push-agent</string> <key>ProgramArguments</key> <array> <string>/bin/sh</string> <string>/usr/local/bin/push-agent.sh</string> </array> <key>StartInterval</key> <integer>60</integer> <key>RunAtLoad</key> <true/> <key>StandardOutPath</key> <string>/tmp/push-agent.log</string> <key>StandardErrorPath</key> <string>/tmp/push-agent.error.log</string> </dict> </plist>

    

6. Create the macOS host in Checkmk.

    

7. Configure the “Individual program call instead of agent access” rule to read the stored agent output file on the server.

   OMD[mysite]:~$ cat ~/var/agent_output/macos_output/macos_monterey
   Open

   

    

   Verify that data is being updated by checking the file timestamp and running a service discovery.
   
   

Related articles