# bsmithio/opnsense-dashboard architecture

> Architecture diagram of the GitHub repository bsmithio/opnsense-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bsmithio/opnsense-dashboard
- Repository: https://github.com/bsmithio/opnsense-dashboard

## Overview

##### Project Type and Purpose
- This is an open-source monitoring/dashboard project for OPNsense (a firewall) that integrates Suricata IDS data.
- It uses Telegraf to collect metrics, InfluxDB as a time-series store, Graylog for log aggregation, and Grafana for visualization.
- Deployment is managed via Docker Compose and Ansible; custom plugins and configuration files extend Telegraf and the dashboards.

##### Main Architectural Components
A. Data Sources
- OPNsense firewall (system metrics & interface stats)
- Suricata IDS (alert and event logs)
B. Metric Collector
- Telegraf agent
– Built from Docker Compose, including custom plugins (telegraf_pfifgw.php, telegraf_temperature.sh)
– Reads OPNsense API, SNMP, ACPI sensors, Suricata stats
C. Log Aggregator
- Graylog
– Ingests RFC5424 logs (firewall events, Suricata alerts)
D. Time-Series Database
- InfluxDB 2.x
– Stores metrics sent by Telegraf (Flux queries in dashboards)
E. Visualization Layer
- Grafana
– Hosts two JSON dashboards (OPNsense and Suricata)
– Queries InfluxDB and Graylog via data sources
F. Deployment & Configuration
- Docker Compose
– Defines Grafana, InfluxDB, Graylog, Telegraf containers
- Ansible
– inventory.yml, playbook.yml for provisioning hosts, installing Docker, deploying compose stack
- config/ directory
– OPNsense API pack, Suricata YAML, custom.conf

##### Data Flows and Relationships
- OPNsense → Telegraf → InfluxDB
- OPNsense & Suricata logs → Graylog
- Grafana → queries InfluxDB (metrics) & Graylog (logs) → renders dashboards
- Ansible & Docker Compose → deploy & configure all services

##### Architectural Patterns and Design Principles
- “Separation of Concerns”:
→ Collection vs. Storage vs. Visualization vs. Logging
- Micro-services-like: each service in its own container
- Extensibility points: custom Telegraf plugins, JSON dashboards, config folder

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    OPNsense["OPNsense Firewall"]:::external
    Suricata["Suricata IDS"]:::external

    %% Monitoring Stack
    subgraph "Monitoring Stack"
        direction TB
        subgraph "Collector"
            direction TB
            Telegraf["Telegraf Agent"]:::collector
            subgraph "Plugins"
                direction TB
                PFIFGW["telegraf_pfifgw.php"]:::collector
                TEMP["telegraf_temperature.sh"]:::collector
            end
        end
        DB["InfluxDB 2.x"]:::storage
        Graylog["Graylog"]:::storage
        Grafana["Grafana"]:::viz
        subgraph "Dashboards"
            direction TB
            MainDB["OPNsense Dashboard"]:::viz
            SurDash["Suricata Dashboard"]:::viz
        end
    end

    %% Deployment & Config
    subgraph "Deployment & Config"
        direction TB
        DockerCompose["Docker Compose"]:::deployment
        subgraph "Ansible"
            direction TB
            Inventory["inventory.yml"]:::deployment
            Playbook["playbook.yml"]:::deployment
            AR["README.md"]:::deployment
        end
        subgraph "Config Directory"
            direction TB
            Pack["OPNsense-pack.json"]:::config
            CustomConf["custom.conf"]:::config
            subgraph "Suricata Config"
                direction TB
                SurYAML["custom.yaml"]:::config
                SurConf["suricata.conf"]:::config
            end
        end
    end

    %% Documentation
    subgraph "Project Documentation"
        direction TB
        RD["README.md"]:::docs
        CD["configure.md"]:::docs
        PRD["plugins/README.md"]:::docs
    end

    %% Data Flows
    OPNsense -->|"metrics"| Telegraf
    Telegraf -->|"Flux writes"| DB
    OPNsense -->|"RFC5424 logs"| Graylog
    Suricata -->|"RFC5424 logs"| Graylog
    Grafana -->|"queries metrics"| DB
    Grafana -->|"queries logs"| Graylog

    %% Deployment Flows
    DockerCompose --> Telegraf
    DockerCompose --> DB
    DockerCompose --> Graylog
    DockerCompose --> Grafana
    Ansible --> DockerCompose
    Ansible --> Pack
    Ansible --> Inventory
    Ansible --> Playbook

    %% Dashboards to Grafana
    MainDB --> Grafana
    SurDash --> Grafana

    %% Click Events
    click PFIFGW "https://github.com/bsmithio/opnsense-dashboard/blob/master/plugins/telegraf_pfifgw.php"
    click TEMP "https://github.com/bsmithio/opnsense-dashboard/blob/master/plugins/telegraf_temperature.sh"
    click DockerCompose "https://github.com/bsmithio/opnsense-dashboard/blob/master/docker-compose.yaml"
    click Graylog "https://github.com/bsmithio/opnsense-dashboard/blob/master/docker-compose.yaml"
    click DB "https://github.com/bsmithio/opnsense-dashboard/blob/master/docker-compose.yaml"
    click Grafana "https://github.com/bsmithio/opnsense-dashboard/blob/master/docker-compose.yaml"
    click MainDB "https://github.com/bsmithio/opnsense-dashboard/blob/master/OPNsense-Grafana-Dashboard.json"
    click SurDash "https://github.com/bsmithio/opnsense-dashboard/blob/master/OPNsense-Grafana-Dashboard-Suricata.json"
    click Inventory "https://github.com/bsmithio/opnsense-dashboard/blob/master/ansible/inventory.yml"
    click Playbook "https://github.com/bsmithio/opnsense-dashboard/blob/master/ansible/playbook.yml"
    click AR "https://github.com/bsmithio/opnsense-dashboard/blob/master/ansible/README.md"
    click Pack "https://github.com/bsmithio/opnsense-dashboard/blob/master/config/OPNsense-pack.json"
    click CustomConf "https://github.com/bsmithio/opnsense-dashboard/blob/master/config/custom.conf"
    click SurYAML "https://github.com/bsmithio/opnsense-dashboard/blob/master/config/suricata/custom.yaml"
    click SurConf "https://github.com/bsmithio/opnsense-dashboard/blob/master/config/suricata/suricata.conf"
    click RD "https://github.com/bsmithio/opnsense-dashboard/blob/master/README.md"
    click CD "https://github.com/bsmithio/opnsense-dashboard/blob/master/configure.md"
    click PRD "https://github.com/bsmithio/opnsense-dashboard/blob/master/plugins/README.md"

    %% Styles
    classDef external fill:#cce5ff,stroke:#3399ff,color:#000
    classDef collector fill:#d4edda,stroke:#28a745,color:#000
    classDef storage fill:#fff3cd,stroke:#ffcd39,color:#000
    classDef viz fill:#e2e3e5,stroke:#6f42c1,color:#000
    classDef deployment fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef config fill:#f8f9fa,stroke:#adb5bd,color:#000
    classDef docs fill:#f1f3f5,stroke:#868e96,color:#000
```
