A lightweight bash script for monitoring Docker containers with **Nagios**, **Icinga**, or any NRPE-based monitoring setup. This script checks the operational state of a Docker container and returns standard Nagios exit codes (OK, WARNING, CRITICAL, UNKNOWN). It supports Docker *substates* such as restarting, paused, dead, OOMKilled, and more. This version includes modifications and enhancements (substate support) which are licensed under **GPLv3**.

---

Docker Container Check for Nagios

A lightweight bash script for monitoring Docker containers with Nagios, Icinga, or any NRPE-based monitoring setup.

This script checks the operational state of a Docker container and returns standard Nagios exit codes (OK, WARNING, CRITICAL, UNKNOWN). It supports Docker substates such as restarting, paused, dead, OOMKilled, and more.

This version includes modifications and enhancements (substate support) which are licensed under GPLv3.

---

Features

• Detects if a container is running
• Detects if a container is restarting
• Detects paused containers
• Detects dead or OOMKilled containers
• Detects containers being removed
• Provides container IP and start time
• Returns correct Nagios exit codes
• Works via NRPE or directly on a Nagios host
• Requires no modifications to Docker configuration

---

Exit Code Summary

Status	Meaning	Nagios Code
Running	Container OK	0
Restarting	Container is restarting	1
Paused / Removing	Warning state	1
Exited / Dead / OOMKilled	Critical	2
Missing / Docker unreachable	Unknown	3

---

Script Example

The script expects a container name or ID:

./check_docker_container.sh nginx

Output example:

OK - nginx is running. IP: 172.18.0.3, StartedAt: 2025-01-01T12:00:00Z

---

Installation

1. Copy the script

Place the script on your Nagios or NRPE client machine:

/usr/local/bin/check_docker_container.sh

Make it executable:

chmod +x /usr/local/bin/check_docker_container.sh

---

Required Sudo Permissions

Nagios usually runs as user nagios. Docker often requires root or group permissions.

Add this to /etc/sudoers:

nagios ALL=(ALL) NOPASSWD:/usr/bin/docker

Important: Do not add wildcards like /usr/bin/docker * — they are unsafe.

---

NRPE Configuration

Add this to your nrpe.cfg on the monitored host:

command[check_docker_container]=/usr/local/bin/check_docker_container.sh $ARG1$

Restart NRPE:

systemctl restart nrpe

---

Nagios Server Configuration

In your Nagios service definition:

define service{
    use                     generic-service
    host_name               docker-server
    service_description     Docker Container nginx
    check_command           check_nrpe!check_docker_container!nginx
}

Or for multiple containers:

check_command check_nrpe!check_docker_container!mysql
check_command check_nrpe!check_docker_container!redis
check_command check_nrpe!check_docker_container!myapp

Reload Nagios:

systemctl reload nagios

---

Testing

Run locally:

sudo -u nagios /usr/local/bin/check_docker_container.sh nginx

Test NRPE from Nagios server:

/usr/lib/nagios/plugins/check_nrpe -H <host> -c check_docker_container -a nginx

---

Troubleshooting

“UNKNOWN – Unable to talk to the docker daemon”

Fix permissions:

sudo usermod -aG docker nagios

Then restart services:

systemctl restart docker
systemctl restart nrpe

“UNKNOWN – Missing docker binary”

Install Docker:

apt install docker.io

---

License

• Original script by Erik Kristensen: MIT License Source: https://gist.github.com/ekristen/11254304
• Modifications (substate support, enhancements): GPLv3

---