Health Endpoint

The bouncer always provides a health check endpoint. Prometheus metrics can be disabled, but /health remains available for Docker, systemd, Kubernetes, and external uptime checks.

Endpoint

GET http://<listen_addr>:<listen_port>/health

Default: http://localhost:2112/health

Response format

The version value represents the running release.

{
  "status": "ok",
  "routeros_connected": true,
  "version": "<current version>"
}

HTTP status codes

| Code | Status | Meaning | | ----- | ------------------------------------- | -------------------------------------------------------------------------- | | 200 | OK | Health endpoint responded; inspect routeros_connected for RouterOS state |

A timeout, connection refused error, or other TCP connection failure means the process or listener is unreachable. Monitoring systems should treat those connection failures as process-down signals; the /health endpoint itself returns 200 when reachable.

Use the JSON body to distinguish process liveness from RouterOS readiness. routeros_connected: false means the process is alive but the RouterOS API connection is currently down or reconnecting.

Integration examples

Docker

services:
  cs-routeros-bouncer:
    image: ghcr.io/jmrplens/cs-routeros-bouncer:latest
    healthcheck:
      # Process liveness only; inspect routeros_connected for RouterOS state.
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:2112/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

To restart the container when RouterOS connectivity is lost, inspect the JSON body instead:

healthcheck:
  test:
    - CMD-SHELL
    - >-
      wget -qO- http://localhost:2112/health | grep -q '"routeros_connected":[[:space:]]*true'
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 15s

Kubernetes

livenessProbe:
  httpGet:
    path: /health
    port: 2112
  initialDelaySeconds: 15
  periodSeconds: 30
  timeoutSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 2112
  initialDelaySeconds: 5
  periodSeconds: 10

These probes confirm that the process and endpoint are responding. Use a custom exec probe if you want readiness to depend on RouterOS connectivity:

readinessProbe:
  exec:
    command:
      - sh
      - -c
      - wget -qO- http://localhost:2112/health | grep -q '"routeros_connected":[[:space:]]*true'
  initialDelaySeconds: 5
  periodSeconds: 10

Prometheus Alert

groups:
  - name: cs-routeros-bouncer
    rules:
      - alert: BouncerUnhealthy
        expr: up{job="cs-routeros-bouncer"} == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "CrowdSec RouterOS bouncer is down"

Docker troubleshooting

If a Docker health check only runs wget --spider, it verifies process liveness only. The container remains healthy even if RouterOS is disconnected because /health still returns HTTP 200.

Use the JSON-body check when you want the container to become unhealthy on RouterOS loss. This example requires jq in the container or health-check environment:

healthcheck:
  test:
    - CMD-SHELL
    - >-
      wget -qO- http://localhost:2112/health | jq -e '.routeros_connected == true' >/dev/null

Be cautious with automatic restarts on RouterOS connectivity loss. If the router is rebooting or temporarily unreachable, restart loops can make logs noisier without fixing the underlying network issue.