Monitoring with Nagios

Seven checks over HTTP, covering the whole fleet from a single service definition.

Overview

Content Caching Monitor answers checks at /check/<name> as JSON. Each check evaluates the entire fleet and returns one verdict, so you define one service rather than one per caching server.

Checks are served by the collector — the background service that receives your servers' reports — on the same port it uses for reporting, 17440 unless you changed it.

No plugin runs on the caching servers. They report to your Mac; Nagios queries your Mac. There is nothing to install on them, and no SSH or NRPE access to arrange.

Enable the Endpoint

In Settings > Monitoring, tick Nagios and compatible systems, then set a username and password under Access. The pane shows the check URL and offers to copy it.

Available Checks

CheckEvaluatesDefault thresholds
statusServers offline, not reporting, never reported, not registered with Apple, or whose agent was removed; a warning while servers only await their first report—
pressureWorst cache pressure in the fleet, 0–100Settings > Warnings (w=60 c=100 until changed)
efficiencyFleet cache hit rate over the last hour, per centw=60 c=40
throughputEach server's peak 15-minute throughput over the last hour, as a share of its own link; names the server nearest its limitSettings > Warnings (60% and 80% of the link until changed). A probe's own w=/c= are Gbps, against the busiest server
rejectedRequests refused for want of spacew=1 c=100
gapsReporting gaps detected in the last 24 hoursw=1 c=10
lostReports the caching service abandoned before the agent answered (agent-assisted reporting servers)w=1 c=10

A warning switched off in Settings > Warnings is off here too: pressure and throughput then answer OK, saying so, unless the probe passes its own ?w= and ?c=. The password must be at least 8 characters, and an address that gets the login wrong five times in a row is answered 429 for a minute.

efficiency inverts. Lower is worse, so warning is the higher number. A fleet that served nothing in the last hour returns OK rather than 0% — a cache with no traffic has not failed, and treating it as a failure pages somebody every quiet night.

Quick Test

curl -u monitor:your-password http://your-mac.local:17440/check/status
{
  "state": 0,
  "status": "OK",
  "message": "7 server(s) reporting",
  "performance": { "servers": 7 }
}

Override thresholds with w and c:

curl -u monitor:pw 'http://your-mac.local:17440/check/pressure?w=40&c=80'

Exit Codes

The state field is already the Nagios exit code:

statestatusMeaning
0OKWithin thresholds
1WARNINGWarning threshold reached
2CRITICALCritical threshold reached
3UNKNOWNNo servers enrolled, or an unrecognised check name
The HTTP status is always 200 when a check runs. The verdict travels in the body, so a plugin never has to distinguish “the check says CRITICAL” from “the request failed”. Treat a non-200 as UNKNOWN: 404 means the endpoint is disabled, 401 means bad credentials, 503 means none are configured.

Wrapper Script

Nagios needs an exit code and a status line. This turns the JSON into both — place it in your plugins directory as check_content_caching:

#!/bin/bash
# usage: check_content_caching <host:port> <check> [w] [c]
HOST="$1"; CHECK="$2"; W="$3"; C="$4"
URL="http://$HOST/check/$CHECK"
[ -n "$W" ] && URL="$URL?w=$W&c=$C"

# The login reaches curl on its standard input: printf is a shell built-in, so it
# never appears in a process list, as "-u user:password" would.
BODY=$(printf 'user = "%s:%s"\n' "$CCM_USER" "$CCM_PASSWORD" | curl -sf -K - "$URL") || {
    echo "UNKNOWN - collector unreachable or endpoint disabled"; exit 3; }

STATUS=$(echo "$BODY" | /usr/bin/python3 -c 'import json,sys;print(json.load(sys.stdin)["status"])')
MSG=$(echo "$BODY" | /usr/bin/python3 -c 'import json,sys;print(json.load(sys.stdin)["message"])')
CODE=$(echo "$BODY" | /usr/bin/python3 -c 'import json,sys;print(json.load(sys.stdin)["state"])')

echo "$STATUS - $MSG"
exit "$CODE"
Keep the credentials out of the command line. The script reads $CCM_USER and $CCM_PASSWORD from the environment and hands them to curl on its standard input; passing them as arguments, to the script or to curl -u, would put them in the process list of every check run. (A password containing " or \ needs those escaped with a backslash for curl -K.)

Command and Service Definitions

define command {
    command_name    check_content_caching
    command_line    $USER1$/check_content_caching $ARG1$ $ARG2$ $ARG3$ $ARG4$
}

define service {
    use                     generic-service
    host_name               monitor-mac
    service_description     Content Caching — fleet status
    check_command           check_content_caching!your-mac.local:17440!status
}

define service {
    use                     generic-service
    host_name               monitor-mac
    service_description     Content Caching — cache pressure
    check_command           check_content_caching!your-mac.local:17440!pressure!40!80
}

define service {
    use                     generic-service
    host_name               monitor-mac
    service_description     Content Caching — reports lost
    check_command           check_content_caching!your-mac.local:17440!lost
}

Note the host: every service is defined against the Mac running Content Caching Monitor, not against the caching servers.

Icinga 2

object CheckCommand "content_caching" {
  command = [ PluginDir + "/check_content_caching" ]
  arguments = {
    "(no key)" = {{ macro("$ccm_target$") }}
    "(no key2)" = {{ macro("$ccm_check$") }}
  }
  vars.ccm_target = "your-mac.local:17440"
}

apply Service "content-caching-status" {
  check_command = "content_caching"
  vars.ccm_check = "status"
  assign where host.name == "monitor-mac"
}

What to Watch

UNKNOWN with “No servers enrolled” is not a fault. Every check returns it before the first server is approved, so expect it on a fresh install rather than treating it as a broken endpoint.