Skip to content

Commit

Permalink
Re-sort permissions in Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@Snuffy2
Snuffy2 committed Sep 5, 2024
1 parent e1feab7 commit 7c13141
Showing 1 changed file with 45 additions and 85 deletions.
130 changes: 45 additions & 85 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,47 +5,40 @@

Join `OPNsense` with `Home Assistant`!

`hass-opnsense` uses the built-in `xmlrpc` service (along with [the REST API](https://docs.opnsense.org/development/api.html)) of `OPNsense` for all
interactions. This project is currently a proof-of-concept and may fail to work
`hass-opnsense` uses the built-in `xmlrpc` service (along with [the REST API](https://docs.opnsense.org/development/api.html)) of `OPNsense` for all interactions. This project is currently a proof-of-concept and may fail to work
at any time.

Initial development was done againt `OPNsense` `21.7` and `Home Assistant` `2021.10`.

# Overview

- [Installation](#Installation)
- [OPNsense plugin](#OPNsense_plugin)
- [Home Assistant integration](#HomeAssistant_integration)
- [HACS installation](#HACS_installation)
- [Manual installation](#Manual_installation)
- [OPNsense plugin](#OPNsense-plugin)
- [Home Assistant integration](#HomeAssistant-integration)
- [HACS installation](#HACS-installation)
- [Manual installation](#Manual-installation)
- [Configuration](#Configuration)
- [OPNsense](#OPNsense_plugin)
- [OPNsense](#OPNsense-plugin)
- [HA Config](#config)
- [Options](#options)
- [Entities](#entities)
- [Binary Sensor](#binary_sensor)
- [Device Tracker](#device_tracker)
- [Binary Sensor](#binary-sensor)
- [Device Tracker](#device-tracker)
- [Sensor](#sensor)
- [Switch](#switch)
- [Services](#services)
- [Known Issues](#known-issues)
- [AdGuardHome](#AdGuardHome)

# installation

# Installation

This integration currenlty **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.
This integration currently **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.

The installation requires a plugin on `OPNsense` and a custom integration in `Home Assistant`.

## OPNsense_plugin
## OPNsense Plugin

To use the integration you need to install an `OPNsense` plugin made available
on mimugmail repository: `https://www.routerperformance.net/opnsense-repo/`
To use the integration you need to install an `OPNsense` plugin made available on mimugmail repository: `https://www.routerperformance.net/opnsense-repo/`

First you need to install the repository:

Expand All @@ -61,54 +54,36 @@ Now you need to install the plugin, you have two ways to do it:
- In `OPNsense` web UI, go to System:Firmware:Plugins and install plugin `os-homeassistant-maxit`
- From SSH shell: `pkg install os-homeassistant-maxit`

## HomeAssistant_integration
## HomeAssistant Integration

In `Home Assistant`, add this repository to your `HACS` installation or clone the directory manually.

### HACS_installation
### HACS Installation

In HACS, add this as a custom repository: https://github.com/travisghansen/hass-opnsense then go to the
HACS integrations page, search for `OPNsense integration for Home Assistant` and install it. Once the
integration is installed be sure to restart `Home Assistant`.
In HACS, add this as a custom repository: https://github.com/travisghansen/hass-opnsense then go to the HACS integrations page, search for `OPNsense integration for Home Assistant` and install it. Once the integration is installed be sure to restart `Home Assistant`.

### Manual_installation
### Manual Installation

Copy the contents of the custom_components folder to your `Home Assistant` config/custom_components
folder and restart `Home Assistant`.
Copy the contents of the custom_components folder to your `Home Assistant` config/custom_components folder and restart `Home Assistant`.

# Configuration

Configuration is managed entirely from the UI using `config_flow` semantics.
Simply go to `Configuration -> Integrations -> Add Integration` and search for `OPNsense`
in the search box. If you can't find it in the list (well-known HA issue) you need to do
a 'hard-refresh' of the browser (ctrl-F5) then open the list again, you'll find it there.
Configuration is managed entirely from the UI using `config_flow` semantics. Simply go to `Configuration -> Integrations -> Add Integration` and search for `OPNsense` in the search box. If you can't find it in the list (well-known HA issue) you need to do a 'hard-refresh' of the browser (ctrl-F5) then open the list again, you'll find it there.

## OPNsense

- Create a new user or choose an existing user, and create an API key associated to
to that user. When creating the API key, `OPNsense` will push the API file containing
the API key and API secret to your browser, you'll find it in the download folder.
- If using a non `admin` user account ensure the user has the following privileges:
- Create a new user or choose an existing user, and create an API key associated to to that user. When creating the API key, `OPNsense` will push the API file containing the API key and API secret to your browser, you'll find it in the download folder.
- If using a non `admin` user account, ensure the user has the following privileges:
- `Dashboard (all)`
- `Lobby: Login / Logout / Dashboard`
- `Status: Interfaces`
- `Status: OpenVPN`
- `System: Firmware`
- `VPN: OpenVPN: Client Export Utility`
- `XMLRPC Library` (note that this privilege effectively gives the user complete access to
the system via the `xmlrpc` feature)
- `System:Firmware`
- The integration also uses OPNsense REST API, and it requires these additional privileges:

| Endpoint | Permission |
| -------- | ------- |
| /api/diagnostics/system/system_mbuf | Dashboard (all) |
| /api/diagnostics/firewall/pfstates | Dashboard (all) |
| /api/routes/gateway/status | Dashboard (all) |
| /api/diagnostics/system/systemResources | Dashboard (all) |
| /api/diagnostics/system/systemSwap | Dashboard (all) |
| /api/diagnostics/cpu_usage/getCPUType | Dashboard (all) |
| /api/diagnostics/system/systemDisk | Dashboard (all) |
| /api/diagnostics/system/systemTime | Lobby: Login / Logout / Dashboard |
| /api/openvpn/export/providers | VPN: OpenVPN: Client Export Utility |
| /api/interfaces/overview/export | Status: Interfaces |
| /api/openvpn/service/searchSessions | Status: OpenVPN |

## config

## Config

- `URL` - the full URL to your `OPNsense` UI (ie: `https://192.168.1.1`),
supported format is `<scheme>://<ip or host>[:<port>]`
Expand All @@ -119,48 +94,34 @@ a 'hard-refresh' of the browser (ctrl-F5) then open the list again, you'll find
- `Firewall Name` - a custom name to be used for `entity` naming (default: use
the `OPNsense` `hostname`)

## options

- `Scan Interval (seconds)` - scan interval to use for state polling (default:
`30`)
- `Enable Device Tracker` - turn on the device tracker integration using
`OPNsense` arp table (default: `false`)
- `Device Tracker Scan Interval (seconds)` - scan interval to use for arp
updates (default: `60`)
- `Device Tracker Consider Home (seconds)` - seconds to wait until marking
a device as not home after not being seen.
(default: `0`)
- `0` - disabled (if device is not present during any given scan interval it
is considered away)
## Options

- `Scan Interval (seconds)` - scan interval to use for state polling (default: `30`)
- `Enable Device Tracker` - turn on the device tracker integration using `OPNsense` arp table (default: `false`)
- `Device Tracker Scan Interval (seconds)` - scan interval to use for arp updates (default: `60`)
- `Device Tracker Consider Home (seconds)` - seconds to wait until marking a device as not home after not being seen. (default: `0`)
- `0` - disabled (if device is not present during any given scan interval it is considered away)
- `> 0` - generally should be a multiple of the configured scan interval

# entities
# Entities

Many `entities` are created by `hass-opnsense` for stats etc. Due to to volume
of entities many are disabled by default. If something is missing be sure to
review the disabled entities as what you're looking for is probably there.
Many `entities` are created by `hass-opnsense` for stats etc. Due to to volume of entities many are disabled by default. If something is missing be sure to review the disabled entities as what you're looking for is probably there.

## binary_sensor
## Binary Sensor

- carp status (enabled/disabled)
- system notices present (the bell icon in the upper right of the UI)
- firmware updates available

## device_tracker
## Device Tracker

`ScannerEntity` entries are created for the `OPNsense` arp table. Disabled by
default. Not only is the feature disabled by default but created entities are
currently disabled by default as well. Search the disabled entity list for the
relevant mac addresses and enable as desired.
`ScannerEntity` entries are created for the `OPNsense` arp table. Disabled by default. Not only is the feature disabled by default but created entities are currently disabled by default as well. Search the disabled entity list for the relevant mac addresses and enable as desired.

Note that by default `FreeBSD`/`OPNsense` use a max age of 20 minutes for arp
entries (sysctl `net.link.ether.inet.max_age`). You may lower that using
`System -> Advanced -> System Tunables` if desired.
Note that by default `FreeBSD`/`OPNsense` use a max age of 20 minutes for arp entries (sysctl `net.link.ether.inet.max_age`). You may lower that using `System -> Advanced -> System Tunables` if desired.

Also note that if you are running `AdGuardHome` DNS queries may get throttled
causing issues with the tracker. See #22 for details.
Also note that if you are running `AdGuardHome` DNS queries may get throttled causing issues with the tracker. See #22 for details.

## sensor
## Sensor

- system details (name, version, ~~temp~~, boottime, etc)
- pfstate details (used, max, etc)
Expand All @@ -176,7 +137,7 @@ causing issues with the tracker. See #22 for details.
- OpenVPN server stats (per-server basis - connected client count, bytes
sent/received, kB/s sent/received)

## switch
## Switch

All of the switches below are disabled by default.

Expand All @@ -185,7 +146,7 @@ All of the switches below are disabled by default.
- nat outbound rules - enable/disable rules
- services - start/stop services (note that services must be enabled before they can be started)

# services
# Services

```
service: opnsense.close_notice
Expand Down Expand Up @@ -234,5 +195,4 @@ data:

## AdGuardHome

As mentioned [here](https://github.com/travisghansen/hass-opnsense/issues/22) using AdGuardHome can lead to problems with the plugin.
Setting the Ratelimit in AdGuardHome to 0 will resolve this problem.
As mentioned [here](https://github.com/travisghansen/hass-opnsense/issues/22) using AdGuardHome can lead to problems with the plugin. Setting the Ratelimit in AdGuardHome to 0 will resolve this problem.

0 comments on commit 7c13141

Please sign in to comment.