Skip to content

Update Documentation for Deprecating Plugin #490

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Snuffy2 merged 1 commit into from
Feb 8, 2026
Merged

Update Documentation for Deprecating Plugin #490

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 17 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,17 @@

Join `OPNsense` with `Home Assistant`!

`hass-opnsense` uses the OPNsense [REST API](https://docs.opnsense.org/development/api.html) and built-in `xmlrpc` service to integrate OPNsense with Home Assistant.
`hass-opnsense` uses the OPNsense [REST API](https://docs.opnsense.org/development/api.html) to integrate OPNsense with Home Assistant.

**With OPNsense Firmware 26.1.1+, a plugin is no longer needed on the OPNsense Router.**

__In most cases, a [plugin](#opnsense-plugin) is currently required to be installed on the <ins>OPNsense</ins> router for this to work properly.__

A Discord server to discuss the integration is available, please click the Discord badge at the beginning of the page for the invite link.

## Table of Contents

* [Installation](#installation)
* [OPNsense Plugin](#opnsense-plugin)
* [OPNsense Plugin (deprecated)](#opnsense-plugin)
* [Home Assistant Integration](#homeassistant-integration)
* [HACS Installation](#hacs-installation)
* [Manual Installation](#manual-installation)
Expand All @@ -48,9 +49,12 @@ A Discord server to discuss the integration is available, please click the Disco

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.

In most cases, use of the integration requires a plugin installed on <ins>OPNsense</ins>.
### OPNsense Plugin *(deprecated)*

With OPNsense Firmware 26.1.1+, a plugin is **no longer needed** on the OPNsense Router.

### OPNsense Plugin
<details>
<summary><h4>OPNsense Firmware < 26.1.1</h4></summary>

In most cases, use of the integration requires an <ins>OPNsense</ins> plugin made available on mimugmail repository: `https://www.routerperformance.net/opnsense-repo/`. See [Granular Sync Options](#granular-sync-options) below for more details.

Expand All @@ -73,6 +77,8 @@ OR

2. In an <ins>OPNsense</ins> SSH session: `pkg install os-homeassistant-maxit`

</details>

### HomeAssistant Integration

In Home Assistant, add this repository to the HACS installation or clone the directory manually.
Expand Down Expand Up @@ -116,20 +122,18 @@ In <ins>OPNsense</ins>, create a new admin role user (or choose an existing admi

### Granular Sync Options

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:
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 <ins>OPNsense</ins> user can have more narrow permissions.

* The <ins>OPNsense</ins> user can have more narrow permissions

* If a category that requires the <ins>OPNsense</ins> plugin isn't selected, the plugin on the <ins>OPNsense</ins> router isn't needed

At minimum, the following permissions are required. [The list of what other permissions are needed for the Granular Sync Options and for the Actions can be reviewed here.](granular_permissions.md)
At minimum, the following permissions are required:

* Lobby: Dashboard

* Status: Interfaces

* System: Firmware

[The list of what other permissions are needed for the Granular Sync Options and for the Actions can be reviewed here.](granular_permissions.md)

### Basic Configuration

| Option | Required | Default | Description |
Expand Down Expand Up @@ -192,11 +196,9 @@ Many entities are created by `hass-opnsense` for statistics etc. Due to the volu

All of the switches are disabled by default

* Filter Rules - enable/disable rules

* NAT Port Forward Rules - enable/disable rules
* Firewall Rules - enable/disable rules

* NAT Outbound Rules - enable/disable rules
* NAT Rules - enable/disable rules

* Services - start/stop services (services must be enabled before they can be started)

Expand Down
18 changes: 17 additions & 1 deletion granular_permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,29 @@
| Interfaces: Virtual IPs: Status | /api/diagnostics/interface/get_vip_status |
| Interfaces: Virtual IPs: Settings | /api/interfaces/vip_settings/get |

## Firewall filter and NAT switches
## Firewall rules and NAT rules switches

### OPNsense Firmware 26.1.1+

| OPNsense Permission | API Endpoints |
| ----- | ----- |
| Firewall: Rules [New] | /api/firewall/filter/search_rule<br>/api/firewall/filter/toggle_rule |
| Firewall: NAT: Destination NAT | /api/firewall/d_nat/search_rule<br>/api/firewall/d_nat/toggle_rule |
| Firewall: NAT: 1:1 | /api/firewall/one_to_one/search_rule<br>/api/firewall/one_to_one/toggle_rule |
| Firewall: NAT: Source NAT | /api/firewall/source_nat/search_rule<br>/api/firewall/source_nat/toggle_rule |
| Firewall: NAT: NPTv6 | /api/firewall/npt/search_rule<br>/api/firewall/npt/toggle_rule |

<details>
<summary><h3>OPNsense Firmware < 26.1.1</h3></summary>

> **\*\*OPNsense plugin required\*\***

| OPNsense Permission | API Endpoints |
| ----- | ----- |
| XMLRPC Library | _N/A – Operations are executed using the XMLRPC interface and OPNsense plugin_ |

</details>

## Service switches

| OPNsense Permission | API Endpoints |
Expand Down
Loading