Checkmk Raw Edition on AWS

This image delivers Checkmk Raw Edition (the free, 100% open source, GPL-2.0 edition), fully installed and reverse-proxied behind Apache with per-instance TLS. Checkmk is a leading IT infrastructure and application monitoring platform: it watches hosts, services and metrics against thresholds, raises notifications, and renders everything in a full web GUI backed by a large built-in check catalog.

Checkmk is packaged as an OMD (Open Monitoring Distribution) site named cmk, bundling the Nagios core, rrdcached, a site Apache and the agent receiver. The system apache2 reverse-proxies /cmk/ to the site and terminates TLS on port 443. All persistent site data - monitoring configuration, RRD metric history and the core state - lives on a dedicated, independently resizable EBS data volume mounted at /opt/omd (reached through the standard /omd symlink), separate from the operating system disk.

Edition and licence

This AMI ships Checkmk Raw Edition (CRE) only - the open source edition licensed under the GNU GPL-2.0. The installed package is check-mk-community and omd version reports the .community build. No commercial Checkmk Enterprise, Cloud or MSP component is bundled.

Secure by default - no shipped credentials

The image ships with no known administrator password. When the Checkmk site is created, the installer prints a random cmkadmin password; that password is discarded and never shipped. On first boot, a unique cmkadmin password is generated for this specific instance and written to /root/checkmk-credentials.txt. The GUI is served only over HTTPS, and plain HTTP returns a health check and redirects to HTTPS.

Connecting to your instance

Connect over SSH on port 22 using the default login user for your operating system variant and the EC2 key pair you launched with.

Replace <public-ip> with your instance's public IPv4 address (or its private address if you reach it over a VPN or Direct Connect).

Retrieve your per-instance admin password

The cmkadmin password is generated uniquely on this instance at first boot. Read it over SSH:

sudo grep '^CHECKMK_ADMIN_PASSWORD=' /root/checkmk-credentials.txt

The same file records the login URL and username:

sudo cat /root/checkmk-credentials.txt

Sign in to the Checkmk GUI

Open the GUI in your browser over HTTPS (the certificate is self-signed and regenerated per instance, so your browser will warn on first visit):

https://<public-ip>/cmk/

Sign in as cmkadmin with the password from the credentials file.

Once signed in you land on the main dashboard, which summarises host and service statistics, current problems and recent events:

Verify the security posture

The commands below run against the site's REST API on the instance itself. First confirm that an unauthenticated request and a wrong password are both refused, then confirm the real per-instance password authenticates:

SITE=cmk
API="https://127.0.0.1/${SITE}/check_mk/api/1.0"
PW=$(sudo grep '^CHECKMK_ADMIN_PASSWORD=' /root/checkmk-credentials.txt | cut -d= -f2-)
U=$(curl -ks -o /dev/null -w '%{http_code}' "${API}/version")
W=$(curl -ks -o /dev/null -w '%{http_code}' -H "Authorization: Bearer cmkadmin WRONGwrongWRONG" "${API}/version")
C=$(curl -ks -o /dev/null -w '%{http_code}' -H "Authorization: Bearer cmkadmin ${PW}" "${API}/version")
echo "unauthenticated=${U}  wrong-password=${W}  correct-per-instance-password=${C}"
[ "$U" = 401 ] && [ "$W" = 401 ] && [ "$C" = 200 ] || { echo "error: security posture assertion failed"; exit 1; }
echo "SECURITY_POSTURE_OK"

The first two return 401 and only the last returns 200 - the image ships no default or blank credential on the network-reachable GUI.

Create an automation user

The Checkmk REST API is best driven with a dedicated automation user. Create one as cmkadmin and commit it by activating changes. The generated secret is stored (root-only) so the following steps can use it:

SITE=cmk
API="https://127.0.0.1/${SITE}/check_mk/api/1.0"
PW=$(sudo grep '^CHECKMK_ADMIN_PASSWORD=' /root/checkmk-credentials.txt | cut -d= -f2-)
SECRET="CmkAuto$(openssl rand -hex 10)"
# create the automation user (idempotent: reset its secret if it already exists)
code=$(curl -ks -o /dev/null -w '%{http_code}' -X POST "${API}/domain-types/user_config/collections/all" \
  -H "Authorization: Bearer cmkadmin ${PW}" -H 'Content-Type: application/json' \
  -d "{\"username\":\"automation\",\"fullname\":\"cloudimg automation\",\"roles\":[\"admin\"],\"auth_option\":{\"auth_type\":\"automation\",\"secret\":\"${SECRET}\"}}")
if [ "$code" != "200" ]; then
  ETAG=$(curl -ks -D - -o /dev/null -H "Authorization: Bearer cmkadmin ${PW}" "${API}/objects/user_config/automation" | awk -F': ' 'tolower($1)=="etag"{gsub(/\r/,"");print $2}')
  curl -ks -o /dev/null -X PUT "${API}/objects/user_config/automation" \
    -H "Authorization: Bearer cmkadmin ${PW}" -H 'Content-Type: application/json' ${ETAG:+-H "If-Match: ${ETAG}"} \
    -d "{\"auth_option\":{\"auth_type\":\"automation\",\"secret\":\"${SECRET}\"}}"
fi
curl -ks -o /dev/null -w 'commit user (activate) -> HTTP %{http_code}\n' -X POST "${API}/domain-types/activation_run/actions/activate-changes/invoke" \
  -H "Authorization: Bearer cmkadmin ${PW}" -H 'Content-Type: application/json' -H 'If-Match: *' -d "{\"redirect\":false,\"sites\":[\"${SITE}\"]}"
sudo install -m 600 /dev/null /root/.cmk-automation-secret
printf '%s' "${SECRET}" | sudo tee /root/.cmk-automation-secret >/dev/null
AV=$(curl -ks -o /dev/null -w '%{http_code}' -H "Authorization: Bearer automation ${SECRET}" "${API}/version")
echo "automation secret authenticates -> HTTP ${AV}"
[ "$AV" = 200 ] || { echo "error: automation user secret did not authenticate"; exit 1; }
echo "AUTOMATION_USER_OK"

The final check returns 200, proving the per-instance automation secret works against the REST API.

Add your first host with the Checkmk agent

Install and register the bundled Checkmk agent on the instance, then add localhost as a monitored host and discover its services - all through the automation user's REST secret:

SITE=cmk
API="https://127.0.0.1/${SITE}/check_mk/api/1.0"
SECRET=$(sudo cat /root/.cmk-automation-secret)
AUTH="Authorization: Bearer automation ${SECRET}"
# install the bundled Checkmk agent on this host
AGENT=$(ls /opt/omd/versions/*/share/check_mk/agents/check-mk-agent_*_all.deb | head -1)
sudo dpkg --install "${AGENT}" >/dev/null 2>&1; echo "agent installed"
sudo systemctl enable --now check-mk-agent.socket >/dev/null 2>&1
# add the host, then register the agent (TLS) so the server can read it
curl -ks -o /dev/null -w 'add host localhost -> HTTP %{http_code}\n' -X POST "${API}/domain-types/host_config/collections/all" \
  -H "${AUTH}" -H 'Content-Type: application/json' -d '{"folder":"/","host_name":"localhost","attributes":{"ipaddress":"127.0.0.1"}}'
sudo cmk-agent-ctl register --server localhost --site ${SITE} --user automation --password "${SECRET}" --hostname localhost --trust-cert >/dev/null 2>&1 && echo "agent registered"
# discover services and activate the changes
curl -ks -o /dev/null -w 'service discovery -> HTTP %{http_code}\n' -X POST "${API}/domain-types/service_discovery_run/actions/start/invoke" \
  -H "${AUTH}" -H 'Content-Type: application/json' -d '{"host_name":"localhost","mode":"tabula_rasa"}'
for i in $(seq 1 20); do
  s=$(curl -ks -H "${AUTH}" "${API}/objects/service_discovery_run/localhost" | python3 -c "import json,sys;print(json.load(sys.stdin).get('extensions',{}).get('state',''))" 2>/dev/null)
  [ "$s" = "finished" ] && { echo "discovery finished"; break; }; sleep 3
done
curl -ks -o /dev/null -w 'activate changes -> HTTP %{http_code}\n' -X POST "${API}/domain-types/activation_run/actions/activate-changes/invoke" \
  -H "${AUTH}" -H 'Content-Type: application/json' -H 'If-Match: *' -d "{\"redirect\":false,\"sites\":[\"${SITE}\"]}"

You can see the host and its discovered services in Setup > Hosts:

Confirm real monitoring data

After activation the Checkmk core schedules the first checks. Poll the REST API until a known service has been checked and reports a real state:

SITE=cmk
API="https://127.0.0.1/${SITE}/check_mk/api/1.0"
SECRET=$(sudo cat /root/.cmk-automation-secret)
AUTH="Authorization: Bearer automation ${SECRET}"
for i in $(seq 1 30); do
  OUT=$(curl -ks -H "${AUTH}" "${API}/domain-types/service/collections/all?host_name=localhost&columns=description&columns=state&columns=has_been_checked&columns=plugin_output")
  DONE=$(printf '%s' "$OUT" | python3 -c "
import json,sys
m={0:'OK',1:'WARN',2:'CRIT',3:'UNKNOWN'}
d=json.load(sys.stdin); hit=False
for s in d.get('value',[]):
    e=s.get('extensions',{})
    if e.get('has_been_checked')==1 and (e.get('description') in ('Check_MK','Check_MK Agent','Memory','Uptime') or 'Filesystem' in str(e.get('description',''))):
        print('SERVICE %-16s STATE=%-4s | %s' % (e.get('description'), m.get(e.get('state'),e.get('state')), str(e.get('plugin_output',''))[:60]))
        hit=True
print('ROUNDTRIP_OK' if hit else 'waiting')
" 2>/dev/null)
  echo "$DONE" | grep -q ROUNDTRIP_OK && { echo "$DONE"; break; }
  sleep 5
done
echo "$DONE" | grep -q ROUNDTRIP_OK || { echo "error: no known service reported a real state in time"; exit 1; }

When it prints ROUNDTRIP_OK alongside services such as Check_MK Agent, Memory or Uptime in an OK state with real plugin output, your monitoring round-trip is complete. The live service list, with states and metric graphs, is under Monitor > All hosts > localhost:

Managing the services

Two systemd units keep the appliance running:

systemctl status apache2 --no-pager
sudo omd status cmk

• apache2.service - the system reverse proxy that terminates TLS on port 443 and proxies /cmk/.
• omd.service - Checkmk's native unit that starts the monitoring site at boot.

Using a CA-signed certificate

The image ships a per-instance self-signed certificate at /etc/ssl/cloudimg/checkmk.crt (key checkmk.key). To use your own CA-signed or ACM-issued certificate, replace those two files with your certificate and private key and reload Apache:

sudo cp your-fullchain.pem /etc/ssl/cloudimg/checkmk.crt
sudo cp your-privatekey.pem /etc/ssl/cloudimg/checkmk.key
sudo systemctl reload apache2

For a public domain, point a DNS record at your instance (or a load balancer in front of it) and issue the certificate for your-domain before installing it.

Support

cloudimg provides 24/7 technical support for this AMI by email and live chat, covering deployment, upgrades, TLS termination, agent registration and notification integrations. Email support@cloudimg.co.uk with your AWS Marketplace subscription details.

Checkmk is a trademark of Checkmk GmbH. cloudimg is not affiliated with, endorsed by, or sponsored by Checkmk GmbH; the name is used nominatively to identify the open source software packaged in this image.