Le API REST (Application programming interface) sono un un insieme di procedure che permettono a sistemi e applicazioni differenti di comunicare attraverso richieste HTTP, scambiando informazioni generalmente in formato JSON. Attraverso specifici endpoint URL è possibile interrogare un servizio, recuperare informazioni sul suo stato ed eventualmente eseguire operazioni di modifica o controllo, in base ai permessi concessi.

Nel caso di OPNsense, le API REST consentono di raccogliere informazioni sullo stato del firewall, sul traffico delle interfacce, sui servizi attivi, andando oltre la semplice verifica della sua raggiungibilità tramite ICMP. Ad esempio, un firewall può rispondere ai ping pur presentando problemi a livello di gateway o interfacce di rete.

Similmente a quanto descritto per Proxmox VE, vediamo quindi come monitorare lo stato di OPNsense tramite le API in Zabbix.

Prerequisiti

  • Un server Zabbix alla versione 7.0 o superiore
  • Un’istanza OPNsense raggiungibile via HTTPS dal server Zabbix

Configurazione delle API

  • Accedere a OPNsense e creare l’utente per il monitoraggio dalla sezione System > Access > Users:
Campo Valore
Username zabbix-api
Login shell none
Full name Zabbix monitoring, read only
Group Memberships Nessuno

È importante lasciare vuota la shell di login: l’account non deve poter essere usato tramite SSH o dalla console.

  • Aggiungere una API key, cliccando il pulsane apposito. Il file scaricato contiene la chiave e il secret

api-key

  • Creare il gruppo zabbix-api-gp da System > Access > Groups:
Campo Valore
Username zabbix-api-gp
Privileges Vedere sezione Privilegi sottostante
Members zabbix-api

Privilegi

Per usare tutte le funzionalità servono privilegi che non sono di sola lettura. La API key può quindi arrestare servizi e modificare il routing del firewall.

Abbiamo conferito i seguenti privilegi, cercando di mantenere un compromesso tra utilità e sicurezza:

Privilegio Monitoraggio Read only
Lobby: Dashboard Informazioni generali sul sistema: risorse hardware, ora di sistema, utilizzo del disco, swap, temperatura, tipo di CPU e altri parametri Sì
Diagnostics: Firewall statistics Prestazioni e attività del firewall Sì
Diagnostics: Logs: Firewall: Summary View Riepilogo degli eventi registrati dal firewall, con informazioni sui blocchi Sì
Diagnostics: System Activity Utilizzo della CPU Sì
Reporting: Traffic Statistiche sul traffico di rete delle interfacce, con informazioni sui volumi di dati trasmessi e ricevuti Sì
System: Gateways Stato dei gateway, disponibilità e raggiungibilità No: espone anche API di configurazione, comprese quelle sotto api/routing/settings/*
Status: Services Stato dei servizi in esecuzione No: api/core/service/* consente di avviare e arrestare i servizi
System: Status Informazioni sullo stato generale del firewall Quasi: consente anche di nascondere un messaggio di stato
VPN: WireGuard: Status Stato delle istanze e peer WireGuard No: include anche funzionalità di controllo dei servizi. È tuttavia il privilegio più circoscritto tra quelli disponibili per il monitoraggio di WireGuard

L’omissione di un privilegio rende non supportati esclusivamente gli elementi che dipendono da esso; gli altri elementi del template non sono interessati.

privilege-error

Per una lista completa dei privilegi richiesti dal template, consultare la documentazione ufficiale.

Testing

Dal server Zabbix, che, ricordiamo, deve raggiungere OPNsense sulla porta 443, si possono eseguire le seguenti chiamate curl, verificando che tutto funzioni correttamente:

API_KEY=""
API_SECRET=""
IP_FW=""


curl -k -u "$API_KEY":"$API_SECRET" https://$IP_FW/api/routes/gateway/status | jq
curl -k -u "$API_KEY":"$API_SECRET" https://$IP_FW/api/interfaces/overview/interfacesInfo | jq
curl -k -u "$API_KEY":"$API_SECRET" https://$IP_FW/api/diagnostics/traffic/interface | jq
curl -k -u "$API_KEY":"$API_SECRET" https://$IP_FW/api/wireguard/service/show | jq
curl -k -u "$API_KEY":"$API_SECRET" https://$IP_FW/api/wireguard/service/status| jq

Importare il template in Zabbix

  • Una volta completati tutti i test con successo, scaricare il template opnsense-by-rest-api.yaml
  • In Zabbix, da Data collection > Templates > Import, importare il template precedentemente scaricato
  • Da Data collection > Host groups creare il gruppo Firewalls

Creare l’host OPNsense

Dalla sezione Monitoring > Hosts creare un nuovo host e compilare le macro come segue:

{$OPNS.KEY}: API key 
{$OPNS.SECRET}: secret
  • Collegare il template OPNsense by REST API e ICMP ping
  • Aggiungere un’interfaccia di tipo Agent che riporti l’indirizzo IP del firewall

host-opnsense

Inizieranno ora ad arrivare i dati dal firewall e verranno creati i grafici utili per il monitoraggio.

cpu-status-opnsense

interfaces-status

Riferimenti