mirror of
https://github.com/alexbelgium/hassio-addons.git
synced 2026-03-18 02:32:11 +01:00
100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# Home assistant add-on: NetBird Server
|
|
|
|
I maintain this and other Home Assistant add-ons in my free time: keeping up with upstream changes, HA changes, and testing on real hardware takes a lot of time (and some money). I use around 5-10 of my >110 addons so regularly I install test machines (and purchase some test services such as vpn) that I don't use myself to troubleshoot and improve the addons.
|
|
|
|
If this add-on saves you time or makes your setup easier, I would be very grateful for your support!
|
|
|
|
[![Buy me a coffee][donation-badge]](https://www.buymeacoffee.com/alexbelgium)
|
|
[![Donate via PayPal][paypal-badge]](https://www.paypal.com/donate/?hosted_button_id=DZFULJZTP3UQA)
|
|
|
|
## Addon information
|
|
|
|
|
|
|
|
|
|
|
|
[donation-badge]: https://img.shields.io/badge/Buy%20me%20a%20coffee-%23d32f2f?logo=buy-me-a-coffee&style=flat&logoColor=white
|
|
[paypal-badge]: https://img.shields.io/badge/Donate%20via%20PayPal-0070BA?logo=paypal&style=flat&logoColor=white
|
|
|
|
## About
|
|
|
|
NetBird is a secure, WireGuard-based overlay network platform. This add-on packages the **management**, **signal**, and optional **dashboard** services in a single monolithic Home Assistant add-on (no ingress UI, no split services). It uses the upstream NetBird Docker images for the binaries and dashboard assets.
|
|
|
|
## Installation
|
|
|
|
The installation of this add-on is pretty straightforward and not different in
|
|
comparison to installing any other Hass.io add-on.
|
|
|
|
1. [Add my Hass.io add-ons repository][repository] to your Hass.io instance.
|
|
1. Install this add-on.
|
|
1. Click the `Save` button to store your configuration.
|
|
1. Start the add-on.
|
|
1. Check the logs of the add-on to see if everything went well.
|
|
|
|
## Configuration
|
|
|
|
> **Important**: NetBird requires OIDC configuration. The add-on will generate a starter `management.json` in `/data/netbird` if one does not exist. Replace the placeholder OIDC values with your IdP configuration before connecting clients.
|
|
|
|
Example add-on options:
|
|
|
|
```json
|
|
{
|
|
"domain": "netbird.example.com",
|
|
"management_port": 33073,
|
|
"signal_port": 10000,
|
|
"dashboard_port": 33080,
|
|
"enable_dashboard": true,
|
|
"auth_issuer": "https://accounts.example.com/",
|
|
"auth_audience": "netbird",
|
|
"auth_jwt_certs": "https://accounts.example.com/jwks.json",
|
|
"auth_oidc_configuration_endpoint": "https://accounts.example.com/.well-known/openid-configuration",
|
|
"auth_client_id": "netbird-dashboard",
|
|
"auth_client_secret": "your-secret",
|
|
"ssl_cert": "/ssl/fullchain.pem",
|
|
"ssl_key": "/ssl/privkey.pem"
|
|
}
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Description |
|
|
| --- | --- |
|
|
| `data_path` | Persistent data directory (default: `/data/netbird`). |
|
|
| `domain` | Public hostname used for NetBird endpoints. |
|
|
| `management_port` | Management API port. |
|
|
| `signal_port` | Signal service port. |
|
|
| `dashboard_port` | Dashboard port (only used if enabled). |
|
|
| `enable_dashboard` | Start the NetBird dashboard (requires OIDC settings). |
|
|
| `management_dns_domain` | DNS suffix handed to peers. |
|
|
| `single_account_domain` | Optional single-account mode domain. |
|
|
| `disable_anonymous_metrics` | Disable anonymous metrics. |
|
|
| `disable_default_policy` | Disable the default NetBird policy on first run. |
|
|
| `auth_*` | OIDC settings for the management server and dashboard. |
|
|
| `ssl_cert`, `ssl_key` | Optional TLS certificate/key paths. |
|
|
| `env_vars` | Extra environment variables passed into NetBird processes. |
|
|
|
|
### Files and persistent data
|
|
|
|
- `/data/netbird/management.json`: management server configuration (generated on first start).
|
|
- `/data/netbird`: runtime data for NetBird components.
|
|
|
|
### Ports
|
|
|
|
- `33073/tcp`: NetBird management API.
|
|
- `10000/tcp`: NetBird signal.
|
|
- `33080/tcp`: NetBird dashboard (optional).
|
|
|
|
## Logs and status
|
|
|
|
The add-on uses s6 supervision; if any NetBird component exits, the supervisor restarts the service and logs the failure to the Home Assistant add-on log stream.
|
|
|
|
## Local build/test
|
|
|
|
```bash
|
|
# From the repository root
|
|
ha addons build netbird
|
|
ha addons install ./netbird
|
|
```
|
|
|
|
[repository]: https://github.com/alexbelgium/hassio-addons
|