🚀 OPNsense Gateway Healthcheck – A Dockerized Monitoring Helper Tool

📖 Table of Contents

• ✨ Description
• 🌟 Features
• 📡 Endpoints
  • /health
  • /health/<name>
  • /health/<address>
  • /health/healthy
  • /health/unhealthy
• ⚙️ Configuration
• 🔑 How to Create an API Key on OPNsense
• ⚠️ Important Notes
  • Gateway Monitoring
  • Offline State
• 🐳 Running with Docker
  • Build and Run Locally
  • Run from Docker Hub
• 📡 Integration with Gatus Monitoring System
• 📜 License
• 🤝 Contributing
• ⭐ Star History

✨ Description

A Python-based Flask application to monitor the health of gateways in an OPNsense network. The application provides endpoints to check the health status of all gateways, specific gateways by name or address, and lists of healthy or unhealthy gateways. These gateways can include both internet service provider (ISP) and VPN-based gateways.

🌟 Features

• Health Status: Check the health of all gateways in the OPNsense network.
• Gateway Lookup: Query the health of a specific gateway by name or address (case-insensitive).
• Healthy Gateways: List all healthy gateways.
• Unhealthy Gateways: List all unhealthy gateways.

📝 Release Notes

Version 1.0

• Initial release with basic health check functionality for OPNsense gateways.

📡 Endpoints

/health

Returns the health status of all gateways.

Example Response:

{
  "items": [
    {
      "address": "12.34.56.789",
      "name": "WAN",
      "status_translated": "Online",
      "healthy": true,
      "..."
    }
  ]
}

/health/<name>

Returns the health status of a specific gateway by name (case-insensitive).

Example:

GET /health/WAN

Example Response:

{
  "address": "12.34.56.789",
  "name": "WAN",
  "status_translated": "Online",
  "healthy": true,
  "..."
}

/health/<address>

Returns the health status of a specific gateway by address. This endpoint is particularly useful for gateways with static (public) IPs.

Example:

GET /health/12.34.56.789

Example Response:

{
  "address": "12.34.56.789",
  "name": "WAN",
  "status_translated": "Online",
  "healthy": true,
  "..."
}

/health/healthy

Returns a list of all healthy gateways.

/health/unhealthy

Returns a list of all unhealthy gateways.

⚙️ Configuration

The application is configured using environment variables:

Variable	Default Value	Description
API_KEY	None	The API key for OPNsense authentication.
API_SECRET	None	The API secret for OPNsense authentication.
OPNSENSE_PORT	443	The port used to connect to the OPNsense instance.
OPNSENSE_BASE_URL	https://opnsense.example.com	The base URL of the OPNsense instance.
PORT	5000	The port the application runs on.

🔑 How to Create an API Key on OPNsense

API keys are managed in the user manager (system_usermanager.php). Follow these steps to create an API key:

1. Navigate to the User Manager page in OPNsense.
2. Select a user for whom you want to create the API key.
3. Scroll down to the API section for this user.
4. Click on the + sign to add a new key.
5. Once the key is created, you will receive a single download containing the credentials in a text file (INI formatted).

The contents of this file will look like this:

[API]
key = your-api-key
secret = your-secret-key

For more details, refer to the OPNsense API Documentation.

⚠️ Important Notes

Gateway Monitoring

To monitor gateways, gateway monitoring must be enabled on the gateways you wish to monitor. This is a critical requirement for the healthcheck application to function correctly.

Offline State

The offline state of a gateway is determined based on the configured thresholds for packet loss and latency in the advanced settings of OPNsense. Ensure these thresholds are properly configured to reflect your monitoring needs.

🐳 Running with Docker

Build and Run Locally

1. Build the Docker Image:

   docker build -t laitco/opnsense-gateway-healthcheck .
   

2. Run the Docker Container:

   docker run -d -p 5000:5000 \
       -e API_KEY="your-api-key" \
       -e API_SECRET="your-api-secret" \
       -e OPNSENSE_BASE_URL="https://opnsense.example.com" \
       -e OPNSENSE_PORT="443" \
       --name opnsense-gateway-healthcheck laitco/opnsense-gateway-healthcheck
   

3. Access the Application: Open your browser and navigate to:

   http://IP-ADDRESS_OR_HOSTNAME:5000/health
   

Run from Docker Hub

1. Pull the Docker Image:

   docker pull laitco/opnsense-gateway-healthcheck:latest
   

2. Run the Docker Container:

   docker run -d -p 5000:5000 \
       -e API_KEY="your-api-key" \
       -e API_SECRET="your-api-secret" \
       -e OPNSENSE_BASE_URL="https://opnsense.example.com" \
       -e OPNSENSE_PORT="443" \
       --name opnsense-gateway-healthcheck laitco/opnsense-gateway-healthcheck:latest
   

3. Access the Application: Open your browser and navigate to:

   http://IP-ADDRESS_OR_HOSTNAME:5000/health
   

📡 Integration with Gatus Monitoring System

You can integrate this healthcheck application with the Gatus monitoring system to monitor the health of specific devices.

Example Configuration

endpoints:
  - name: example-gateway
    group: opnsense
    url: "http://IP-ADDRESS_OR_HOSTNAME:5000/health/examplegatewayname"
    interval: 5m
    conditions:
      - "[STATUS] == 200"
      - "[BODY].healthy == pat(*true*)"
    alerts:
      - type: email
        failure-threshold: 2
        success-threshold: 3
        description: "healthcheck failed"
        send-on-resolved: true

Explanation

• name: A descriptive name for the endpoint being monitored.
• group: A logical grouping for endpoints (e.g., gateways).
• url: The URL of the healthcheck endpoint for a specific gateway.
• interval: The frequency of the healthcheck (e.g., every 5 minutes).
• conditions:
  • [STATUS] == 200: Ensures the HTTP status code is 200.
  • [BODY].healthy == pat(*true*): Checks if the healthy field in the response body is true.
• alerts:
  • type: The type of alert (e.g., email).
  • failure-threshold: The number of consecutive failures before triggering an alert.
  • success-threshold: The number of consecutive successes before resolving an alert.
  • description: A description of the alert.
  • send-on-resolved: Whether to send a notification when the issue is resolved.

For more details on configuring Gatus, refer to the Gatus documentation.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

⭐ Star History