Nginx Open Source Active Health Check Integration

This guide explains how to integrate the nginx_upstream_check_module with Nginx Open Source 1.26.3 to enable active health checks — a feature normally available in the commercial Nginx Plus version.

Table of Contents

• Prerequisites
• Steps to Integrate Active Health Check
  • 1. Create a Working Directory
  • 2. Download Nginx Source and Health Check Module
  • 3. Extract Source and Install Dependencies
  • 4. Apply the Patch
  • 5. Configure, Compile, and Install Nginx
  • 6. Create a Systemd Service for Nginx
  • 7. Configure Nginx for Active Health Checks
• Health Check Parameters Explained
• Example Configurations
• Troubleshooting
• Useful Commands
• Testing
• Version Compatibility
• References

---

Prerequisites

• Ubuntu/Debian-based system
• sudo access
• Basic knowledge of building software from source

---

Steps to Integrate Active Health Check

1. Create a Working Directory

mkdir -p ~/nginx_build && cd ~/nginx_build

---

2. Download Nginx Source and Health Check Module

wget http://nginx.org/download/nginx-1.26.3.tar.gz
git clone https://github.com/yaoweibin/nginx_upstream_check_module.git

---

3. Extract Source and Install Dependencies

tar -xzf nginx-1.26.3.tar.gz
sudo apt-get update
sudo apt-get install -y build-essential libpcre3-dev zlib1g-dev libssl-dev

---

4. Apply the Patch

cd ~/nginx_build/nginx-1.26.3
patch -p1 < ../nginx_upstream_check_module/check_1.20.1+.patch

Note: check_1.20.1+.patch is compatible with Nginx 1.26.3.

---

5. Configure, Compile, and Install Nginx

./configure --with-http_ssl_module --with-http_stub_status_module --add-module=../nginx_upstream_check_module
make
sudo make install

---

6. Create a Systemd Service for Nginx

sudo bash -c 'cat > /etc/systemd/system/nginx.service << EOL
[Unit]
Description=nginx - high performance web server
Documentation=https://nginx.org/en/docs/
After=network-online.target remote-fs.target nss-lookup.target
Wants=network-online.target

[Service]
Type=forking
PIDFile=/usr/local/nginx/logs/nginx.pid
ExecStartPre=/usr/local/nginx/sbin/nginx -t -c /usr/local/nginx/conf/nginx.conf
ExecStart=/usr/local/nginx/sbin/nginx -c /usr/local/nginx/conf/nginx.conf
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s TERM $MAINPID

[Install]
WantedBy=multi-user.target
EOL'

Enable and start the Nginx service:

sudo systemctl daemon-reload
sudo systemctl enable nginx
sudo systemctl start nginx

---

7. Configure Nginx for Active Health Checks

Replace /usr/local/nginx/conf/nginx.conf with the following configuration:

user  nginx;
worker_processes  auto;

error_log  /usr/local/nginx/logs/error.log notice;
pid        /usr/local/nginx/logs/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /usr/local/nginx/conf/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /usr/local/nginx/logs/access.log  main;

    sendfile        on;
    keepalive_timeout  65;

    upstream backend {
        server 127.0.0.1:8080;
        server 127.0.0.1:8081;
        server 127.0.0.1:8082;

        # Active Health Check Configuration
        check interval=3000 rise=2 fall=3 timeout=1000 type=http;
        check_http_send "GET / HTTP/1.0\r\n\r\n";
        check_http_expect_alive http_2xx http_3xx;
    }

    server {
        listen 8000;
        server_name localhost;

        location /status {
            check_status;
            access_log off;
            allow 127.0.0.1;
            deny all;
        }
    }

    server {
        listen       80;
        server_name  localhost;

        location / {
            proxy_pass http://backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   /usr/local/nginx/html;
        }
    }
}

Validate the Configuration

After updating nginx.conf, always validate the syntax:

sudo /usr/local/nginx/sbin/nginx -t

If the configuration is valid, you will see:

nginx: the configuration file /usr/local/nginx/conf/nginx.conf syntax is ok
nginx: configuration file /usr/local/nginx/conf/nginx.conf test is successful

Then reload Nginx to apply changes:

sudo systemctl reload nginx

Notes

• Backend Servers:

  • Add or modify backend servers inside the upstream backend {} block.
  • Example: Replace 127.0.0.1:8080 etc., with your real application servers.

• Health Check Status Access:

  • Only allow trusted IP addresses to access the /status endpoint by modifying the allow and deny directives.
  • Example: Replace allow 127.0.0.1; with your management server's IP if needed.

---

Health Check Parameters Explained

The health check module provides several parameters to control how health checks behave:

Parameter	Description	Example
interval	Time in milliseconds between health checks	interval=3000 (3 seconds)
rise	Number of consecutive successful checks before marking a server as healthy	rise=2
fall	Number of consecutive failed checks before marking a server as unhealthy	fall=3
timeout	Response timeout in milliseconds	timeout=1000 (1 second)
type	Health check type (http, tcp, ssl_hello, mysql, etc.)	type=http
port	Optional port to check (defaults to server port)	port=8080

HTTP Check Options

When using type=http, you can specify what to send and what responses to accept:

check_http_send "GET /health HTTP/1.0\r\nHost: example.com\r\n\r\n";
check_http_expect_alive http_2xx http_3xx;

Valid response codes to check for: http_2xx, http_3xx, http_4xx, http_5xx

---

Example Configurations

TCP Health Check for Database Server

upstream database {
    server db1.example.com:5432;
    server db2.example.com:5432;
    
    check interval=5000 rise=1 fall=2 timeout=1000 type=tcp;
}

HTTPS Health Check with Authentication

upstream secure_api {
    server api1.example.com:443;
    server api2.example.com:443;
    
    check interval=10000 rise=2 fall=3 timeout=2000 type=http;
    check_http_send "GET /health HTTP/1.1\r\nHost: api.example.com\r\nAuthorization: Bearer token123\r\nConnection: close\r\n\r\n";
    check_http_expect_alive http_2xx;
}

Custom Status Page with JSON Format

server {
    listen 8000;
    server_name localhost;
    
    location /status {
        check_status json;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

Available status formats: html (default), csv, json

---

Troubleshooting

Patch Application Fails

If the patch fails to apply with errors, check that you're using the correct patch version:

cd ~/nginx_build/nginx_upstream_check_module
git checkout master
cd ../nginx-1.26.3
patch -p1 < ../nginx_upstream_check_module/check_1.20.1+.patch

If issues persist, review the patch errors and fix any conflicts manually.

Health Checks Not Working

1. Verify module was successfully compiled and loaded:

   grep -i check /usr/local/nginx/logs/error.log

2. Ensure the health check configuration is in the correct upstream block.

3. Check that the path you're testing with check_http_send is accessible on the backend servers.

Permission Issues

If you encounter permission issues, ensure the Nginx user has proper access:

sudo chown -R nginx:nginx /usr/local/nginx/logs

---

Useful Commands

• Start Nginx: sudo systemctl start nginx
• Stop Nginx: sudo systemctl stop nginx
• Reload Nginx: sudo systemctl reload nginx
• Check Status: sudo systemctl status nginx
• View Health Check Logs: sudo tail -f /usr/local/nginx/logs/error.log | grep check

---

Testing

• Access health check status page:

curl http://127.0.0.1:8000/status

• Simulate backend failure by stopping one of your services:

# If using Docker for backends
docker stop backend1

# Verify Nginx detected the failure
curl http://127.0.0.1:8000/status

• Nginx will automatically mark unhealthy servers based on the configured criteria and avoid routing traffic to them.

---

Version Compatibility

This module has been tested with the following Nginx versions:

• Nginx 1.26.x: Use check_1.20.1+.patch
• Nginx 1.22.x - 1.24.x: Use check_1.20.1+.patch
• Nginx 1.20.x: Use check_1.20.1+.patch
• Nginx 1.18.x: Use check_1.16.1+.patch
• Nginx 1.16.x: Use check_1.16.1+.patch

For older versions, check the module's GitHub repository for appropriate patches.

---

References

• Nginx Open Source
• nginx_upstream_check_module GitHub Repository
• Nginx HTTP Upstream Module Documentation

---