Join OPNsense with Home Assistant!
hass-opnsense uses the OPNsense REST API to integrate OPNsense with Home Assistant.
With OPNsense Firmware 26.1.1+, a plugin is no longer needed on the OPNsense Router.
For OPNsense Firmware 26.1.1+, hass-opnsense uses aiopnsense as its backend client library.
Source and releases for aiopnsense:
For OPNsense Firmware < 26.1.1, the legacy, built-in pyopnsense path remains in place for compatibility.
A Discord server to discuss the integration is available, please click the Discord badge at the beginning of the page for the invite link.
This integration replaces the built-in OPNsense integration which only provides device_tracker functionality. Be sure to remove any associated configuration for the built-in integration before installing this replacement.
With OPNsense Firmware 26.1.1+, a plugin is no longer needed on the OPNsense Router.
In most cases, use of the integration requires an OPNsense plugin made available on mimugmail repository: https://www.routerperformance.net/opnsense-repo/. See Granular Sync Options below for more details.
- Open an SSH session on OPNsense and issue the following commands:
fetch -o /usr/local/etc/pkg/repos/mimugmail.conf https://www.routerperformance.net/mimugmail.conf
pkg update
There are two ways to do it:
- In OPNsense web UI, go to
System -> Firmware -> Pluginsand install pluginos-homeassistant-maxit
OR
- In an OPNsense SSH session:
pkg install os-homeassistant-maxit
In Home Assistant, add this repository to the HACS installation or clone the directory manually.
In HACS, add this as a custom repository:
https://github.com/travisghansen/hass-opnsense.
| STEP 1 | STEP 2 |
|---|---|
 |
 |
Then go to the HACS integrations page, search for OPNsense integration for Home Assistant and install it by clicking on 3 dots on the right side and select Download and click on Download on popup window.
Once the integration is installed be sure to restart Home Assistant. Restart option available under Developer tools.
| Developer Tools Page | Restart Home Assistant Popup |
|---|---|
 |
 |
Copy the contents of the custom_components folder to the Home Assistant config/custom_components folder and restart Home Assistant.
Configuration is managed entirely from the Home Assistant UI. Simply go to Configuration -> Integrations -> Add Integration and search for OPNsense in the search box. If it isn't in the list (well-known HA issue), do a 'hard-refresh' of the browser (ctrl-F5) then open the list again.
The official and simplest recommendation is that the service user to be created has the admin role.
In OPNsense, create a new admin role user (or choose an existing admin user) and create an API key associated to the user. When creating the API key, OPNsense will download the file containing the API key and API secret to the computer. It will be in the download folder.
Either at the time of install or in the integration options, Granular Sync Options can be enabled. There, choose the categories to sync with HA as desired. If enabled, the OPNsense user can have more narrow permissions.
At minimum, the following permissions are required:
- Lobby: Dashboard
- Status: Interfaces
- System: Firmware
| Option | Required | Default | Description |
|---|---|---|---|
| URL | ✅ | The full URL to the OPNsense UI (ie: https://192.168.1.1). Supported format is <scheme>://<ip or host>[:<port>] |
|
| Verify SSL Certificate | True | If the SSL certificate should be verified or not (if receiving an SSL error, try unchecking this) | |
| API Key | ✅ | The API key of the OPNsense user created previously | |
| API Secret | ✅ | The API secret of the API key | |
| Firewall Name | Uses the OPNsense hostname |
A custom name to be used for device and entity naming | |
| Enable Granular Sync Options | False | See Granular Sync Options |
| Option | Default | Description |
|---|---|---|
| Scan Interval (seconds) | 30 | Scan interval to use for state polling |
| Device Tracker Mode | Disabled | • Disabled • Track all detected devices • Track only selected devices |
| Device Tracker Scan Interval (seconds) | 60 | Scan interval to use for ARP updates |
| Device Tracker Consider Home (seconds) | 0 | Seconds to wait until marking a device as not home after not being seen: • 0 : Disabled (if device is not present during any given scan interval it is considered away) • > 0 : Should be a multiple of the Device Tracker Scan Interval |
| Enable Granular Sync Options | False | See Granular Sync Options |
Many entities are created by hass-opnsense for statistics etc. Due to the volume of entities, many are disabled by default. If something is missing, be sure to review the disabled entities as it is probably there.
- System Notices present (the circle icon in the upper right of the UI)
- Firmware updates available
- System details (name, version, temp, boottime, etc.)
- pfstate details
- CPU details (usage, load, cores)
- mbuf details
- Memory details
- Filesystem usage
- Interface details (status, stats, pps, kbs, etc.) [speeds are based on the
Scan Interval (seconds)config option] - Gateways details (status, delay, stddev, loss)
- CARP Status (aggregate)
- CARP Interface status
- DHCP Leases
- OpenVPN and Wireguard server and client stats
- Certificates
- vnStat Metrics
- Speedtest last and average results (download, upload, latency)
All switches are disabled by default
- Firewall Rules - enable/disable rules
- NAT Rules - enable/disable rules
- Services - start/stop services
- VPN Servers and Clients - enable/disable instances
- Unbound blocklists - enable/disable blocklists
Entities are created for selected devices to track whether they are connected to the network. This feature is disabled by default and can be enabled in the Options.
The options flow supports three modes:
- Disabled
- Track all detected devices
- Track only selected devices
The selectable device list is built from the current OPNsense ARP table, so only recently seen devices appear automatically. Devices that are not currently visible can still be added manually by MAC address.
See Device Tracker Guide for setup details, ARP behavior, and troubleshooting.
- opnsense.close_notice: Close any open notices
- opnsense.system_halt: Halt the OPNsense system
- opnsense.system_reboot: Reboot the OPNsense system
- opnsense.start_service: Start an OPNsense service
- opnsense.stop_service: Stop an OPNsense service
- opnsense.restart_service: Restart an OPNsense service
- opnsense.send_wol: Send a Wake-on-LAN magic packet
- opnsense.reload_interface: Reload an OPNsense interface
- opnsense.kill_states: Kill all states for an IP address
- opnsense.run_speedtest: Run a speed test and return action response data
- opnsense.get_vnstat_metrics: Get vnStat metrics and return action response data
- opnsense.generate_vouchers: Generate Captive Portal vouchers
- opnsense.toggle_alias: Toggle, enable, or disable an alias
How to use action response data in an HA script or automation
If you partially or fully change the OPNsense hardware, it will require a removal and reinstall of this integration. This is to ensure changed interfaces, services, gateways, etc. are accounted for and don't leave duplicate or non-functioning entities.