OPNsense Dashboard Role

Overview

This role configures the OPNsense web UI dashboard widget layout via the REST API. It applies a defined widget layout including widget positions, sizes, and per-widget configurations (e.g., selected interfaces for traffic graph, thermal sensor selection). The layout is always applied to ensure consistency.

Purpose

• Dashboard as Code: Define dashboard layout in version-controlled configuration
• Consistency: Ensure the same dashboard layout after OPNsense upgrades or accidental changes
• Per-User: Dashboard is saved for the API user account
• API-Based: Reliable automation via OPNsense REST API

Requirements

• Ansible 2.9 or higher
• OPNsense firewall with API access enabled
• API key and secret stored in Ansible Vault
• Network connectivity to OPNsense (VLAN10)

Role Variables

Required Variables

Variable	Required	Description
vault_opnsense_bjoffrey_user_api_key	Yes	OPNsense API key (in vault)
vault_opnsense_bjoffrey_user_api_secret	Yes	OPNsense API secret (in vault)
opnsense_dashboard_widgets	Yes	List of widget definitions (in vars file)

Optional Variables

Variable	Default	Description
opnsense_dashboard_validate_certs	true	Validate SSL certificates
opnsense_dashboard_options	{}	Dashboard-level options

Widget Definition

Each widget in opnsense_dashboard_widgets has:

Field	Type	Description
id	string	Widget identifier (e.g., cpu, memory, traffic)
x	int	Horizontal grid position (0-11)
y	int	Vertical position in pixels
w	int/null	Width in grid columns (null = default)
h	int	Height in pixels
minW	int	Minimum width in grid columns
widget	dict	Widget-specific configuration
sizeToContent	int	Optional, auto-size height

Widget Configuration Examples

Traffic Graph with Selected Interfaces

- id: "traffic"
  x: 8
  y: 0
  w: 4
  h: 446
  minW: 2
  widget:
    interfaces:
      - "opt3"
      - "wan"

CPU with Total Graph

- id: "cpu"
  x: 2
  y: 0
  w: 2
  h: 177
  minW: 2
  widget:
    graphs:
      - "total"

Thermal Sensors with Selected Sensors

- id: "thermalsensors"
  x: 2
  y: 177
  w: 2
  h: 180
  minW: 2
  widget:
    sensors:
      - "dev.cpu.0.temperature"
      - "hw.acpi.thermal.tz0.temperature"

Simple Widget (No Configuration)

- id: "memory"
  x: 2
  y: 528
  w: null
  h: 143
  minW: 1
  widget: {}

Available Widgets

Widget ID	Description
announcements	OPNsense announcements feed
certificates	Certificate status and expiry
carp	CARP/VRRP status
cpu	CPU usage graph
disk	Disk usage gauge
dmidecode	DMI/hardware information
dnsmasqleases	Dnsmasq DHCP leases
firewall	Firewall live log
firewallstates	Firewall state table usage
gateways	Gateway status and RTT
interfacestatistics	Interface byte/packet counters
interfaces	Interface overview
ipsecleases	IPsec VPN leases
ipsectunnels	IPsec tunnel status
livelog	System live log
mbuf	Network buffer usage
memory	Memory usage gauge
monit	Monit service status
openvpnclients	OpenVPN client connections
openvpnservers	OpenVPN server connections
picture	System picture
services	Service status list
smart	SMART disk health
swap	Swap usage gauge
systeminformation	System info (hostname, uptime, etc.)
thermalsensors	CPU/system temperature
traffic	Traffic graph
Wireguard	WireGuard tunnel status

Dependencies

This role has no dependencies on other Ansible roles.

Example Playbook

---
- name: Configure OPNsense Dashboard
  hosts: mint-vm
  gather_facts: false

  vars_files:
    - ../../roles/opnsense_dashboard/vars/widgets.yml

  tasks:
    - name: Configure dashboard widget layout
      ansible.builtin.include_role:
        name: opnsense_dashboard

What This Role Does

1. POST widget layout to /api/core/dashboard/save_widgets
   • Sends the full widget list with positions, sizes, and configurations
   • API returns {"result": "saved"}

The role always applies the desired layout. This is a lightweight API call that ensures the dashboard matches the defined configuration.

OPNsense API Endpoints

Get Dashboard

GET /api/core/dashboard/get_dashboard
Authorization: Basic (API key:secret)

Returns available modules and current widget layout.

Save Widgets

POST /api/core/dashboard/save_widgets
Authorization: Basic (API key:secret)
Content-Type: application/json

Request body:

{
  "options": {},
  "widgets": [
    {
      "id": "cpu",
      "x": 0,
      "y": 0,
      "w": 2,
      "h": 177,
      "minW": 2,
      "widget": {
        "graphs": ["total"]
      }
    }
  ]
}

Response:

{
  "result": "saved"
}

Restore Defaults

POST /api/core/dashboard/restore_defaults
Authorization: Basic (API key:secret)

Resets dashboard to factory default layout.

Per-User Dashboard

The dashboard layout is stored per API user. If you log into the web UI with a different account (e.g., root) than the API key user, you will not see the changes. Ensure the API key belongs to the same user whose dashboard you want to configure.

Grid System

The dashboard uses a 12-column grid:

|  0  |  1  |  2  |  3  |  4  |  5  |  6  |  7  |  8  |  9  | 10  | 11  |

• x: Starting column (0-11)
• w: Number of columns to span (1-12, or null for default)
• y: Vertical position in pixels (widgets stack vertically)
• h: Height in pixels

Security Considerations

• API Credentials: Stored in Ansible Vault
• HTTPS: Uses SSL/TLS for API calls
• Basic Auth: API key/secret authentication
• Certificate Validation: Enabled by default
• No sensitive data: Dashboard layout contains no secrets

Troubleshooting

Dashboard not updating in web UI

Cause: API user differs from web UI login user

Solution: Log into the web UI with the same account that owns the API key.

Widget placement incorrect

Cause: Wrong x/y/w/h values in widget definition

Solution: Use the web UI to arrange widgets, then capture the layout via GET request:

curl -u "key:secret" \
  https://opnsense-ip/api/core/dashboard/get_dashboard | jq '.dashboard.widgets'

Update the vars file with the correct values.

Related Roles

This role is often used with:

• opnsense_conf_backup: Backup OPNsense configuration
• opnsense_firewall: Configure firewall rules
• opnsense_trust_certificates: Manage SSL/TLS certificates

License

MIT

Author

Created for homelab infrastructure management.