diff --git a/netbird-server/DOCS.md b/netbird-server/DOCS.md index c29e6b1dd..ab9aa89c0 100644 --- a/netbird-server/DOCS.md +++ b/netbird-server/DOCS.md @@ -1,6 +1,6 @@ # NetBird Server (monolithic) -This add-on runs the NetBird self-hosted server stack in a single container (Management + Signal + Dashboard + Coturn; Relay optional). It does **not** use Home Assistant ingress. Access the Dashboard directly via the configured port. +This add-on runs the NetBird self-hosted server stack in a single container (Management + Signal + Dashboard + Coturn). It does **not** use Home Assistant ingress. Access the Dashboard directly via the configured port. NetBird relies on gRPC. If you place the Management/Signal endpoints behind a reverse proxy, it **must** support HTTP/2 + gRPC proxying. See the NetBird reverse-proxy guide for supported configurations: . @@ -11,22 +11,20 @@ The Dashboard container requires the `NETBIRD_MGMT_API_ENDPOINT` environment var ## Quick start 1. Install the add-on. -2. Configure your Identity Provider (IdP) and set the required `auth_*` options (or edit the generated `management.json`). -3. Start the add-on and verify all services are running in the log output. -4. Access the dashboard at `http://:`. - -> **Tip:** If you are using your own reverse proxy, set `external_base_url` to the public URL and keep TLS termination in your proxy. +2. Start the add-on and verify all services are running in the log output. +3. Stop the add-on, edit the generated `management.json` to configure your Identity Provider (IdP). +4. Update `/config/netbird/dashboard/env` with the `NETBIRD_MGMT_API_ENDPOINT` and `AUTH_*` values for the dashboard. +5. Start the add-on again and access the dashboard at `http://:8080`. ## Configuration -### Required options -- `data_dir`: Where NetBird stores persistent data. Default: `/config/netbird`. -- `auth_authority`, `auth_client_id`, `auth_audience`, `auth_jwt_certs`, `auth_oidc_configuration_endpoint`: OIDC values used by the Management service and Dashboard. +This add-on starts with zero configuration options. It writes default configs into `/config/netbird` and runs on the standard NetBird ports. -### Optional options -- `disable_dashboard`: Disable the dashboard service entirely. -- `enable_relay`: Enable the NetBird relay service (requires `relay_exposed_address` and `relay_auth_secret`). -- `turn_external_ip`: Public IP to advertise when Coturn is behind NAT. +### Dashboard environment overrides +Edit `/config/netbird/dashboard/env` to configure the dashboard UI: + +- `NETBIRD_MGMT_API_ENDPOINT`: Public URL of the management API (for example, `https://netbird.example.com`). +- `AUTH_AUTHORITY`, `AUTH_CLIENT_ID`, `AUTH_CLIENT_SECRET`, `AUTH_AUDIENCE`, `AUTH_SUPPORTED_SCOPES`, `USE_AUTH0`: OIDC settings for the dashboard UI. ### Generated configuration On first start, the add-on creates: @@ -43,14 +41,9 @@ Default ports exposed by this add-on: - `10000/tcp`: Signal gRPC - `8080/tcp`: Dashboard - `3478/udp`: Coturn STUN/TURN -- `33080/tcp`: Relay (optional) If you have legacy (< v0.29) clients, review the legacy port notes in the NetBird self-hosted guide and ensure your firewall/forwarding rules are compatible. -## Logs - -Use `log_level: debug` for more verbose logging. - ## Notes - This add-on does **not** handle TLS certificates. Place it behind your existing reverse proxy if you need HTTPS. diff --git a/netbird-server/config.yaml b/netbird-server/config.yaml index efb454930..d0abe3f8d 100644 --- a/netbird-server/config.yaml +++ b/netbird-server/config.yaml @@ -8,84 +8,18 @@ ingress: false map: - addon_config:rw name: NetBird Server -options: - data_dir: /config/netbird - domain: "" - external_base_url: "" - management_listen: "0.0.0.0:33073" - signal_listen: "0.0.0.0:10000" - dashboard_listen: "0.0.0.0:8080" - turn_listen_port: 3478 - turn_realm: "netbird" - turn_external_ip: "" - turn_min_port: 49152 - turn_max_port: 65535 - turn_user: "netbird" - turn_password: "" - idp_manager_type: "none" - auth_authority: "" - auth_client_id: "" - auth_client_secret: "" - auth_audience: "" - auth_supported_scopes: "openid profile email api offline_access email_verified" - auth_jwt_certs: "" - auth_user_id_claim: "sub" - auth_oidc_configuration_endpoint: "" - auth_token_endpoint: "" - use_auth0: false - idp_client_id: "" - idp_client_secret: "" - disable_default_policy: false - log_level: info - disable_dashboard: false - enable_relay: false - relay_exposed_address: "" - relay_auth_secret: "" -schema: - data_dir: str - domain: str? - external_base_url: str? - management_listen: str - signal_listen: str - dashboard_listen: str - turn_listen_port: port - turn_realm: str - turn_external_ip: str? - turn_min_port: port - turn_max_port: port - turn_user: str - turn_password: str? - idp_manager_type: str - auth_authority: str? - auth_client_id: str? - auth_client_secret: str? - auth_audience: str? - auth_supported_scopes: str? - auth_jwt_certs: str? - auth_user_id_claim: str - auth_oidc_configuration_endpoint: str? - auth_token_endpoint: str? - use_auth0: bool - idp_client_id: str? - idp_client_secret: str? - disable_default_policy: bool - log_level: list(info|debug) - disable_dashboard: bool - enable_relay: bool - relay_exposed_address: str? - relay_auth_secret: str? +options: {} +schema: {} slug: netbird-server ports: 33073/tcp: 33073 10000/tcp: 10000 8080/tcp: 8080 3478/udp: 3478 - 33080/tcp: 33080 ports_description: 33073/tcp: Management API (HTTP/gRPC) 10000/tcp: Signal gRPC 8080/tcp: NetBird Dashboard (HTTP) 3478/udp: Coturn STUN/TURN - 33080/tcp: Relay (WebSocket/QUIC) url: https://github.com/alexbelgium/hassio-addons version: 0.64.5-1 diff --git a/netbird-server/rootfs/etc/cont-init.d/00-config.sh b/netbird-server/rootfs/etc/cont-init.d/00-config.sh index 1a393f269..b463bc276 100755 --- a/netbird-server/rootfs/etc/cont-init.d/00-config.sh +++ b/netbird-server/rootfs/etc/cont-init.d/00-config.sh @@ -33,45 +33,39 @@ extract_port() { echo "${address##*:}" } -DATA_DIR=$(bashio::config 'data_dir') -DOMAIN=$(bashio::config 'domain') -EXTERNAL_BASE_URL=$(bashio::config 'external_base_url') -MANAGEMENT_LISTEN=$(bashio::config 'management_listen') -SIGNAL_LISTEN=$(bashio::config 'signal_listen') -DASHBOARD_LISTEN=$(bashio::config 'dashboard_listen') -TURN_LISTEN_PORT=$(bashio::config 'turn_listen_port') -TURN_REALM=$(bashio::config 'turn_realm') -TURN_EXTERNAL_IP=$(bashio::config 'turn_external_ip') -TURN_MIN_PORT=$(bashio::config 'turn_min_port') -TURN_MAX_PORT=$(bashio::config 'turn_max_port') -TURN_USER=$(bashio::config 'turn_user') -TURN_PASSWORD=$(bashio::config 'turn_password') -IDP_MANAGER_TYPE=$(bashio::config 'idp_manager_type') -AUTH_AUTHORITY=$(bashio::config 'auth_authority') -AUTH_AUDIENCE=$(bashio::config 'auth_audience') -AUTH_JWT_CERTS=$(bashio::config 'auth_jwt_certs') -AUTH_USER_ID_CLAIM=$(bashio::config 'auth_user_id_claim') -AUTH_OIDC_CONFIGURATION_ENDPOINT=$(bashio::config 'auth_oidc_configuration_endpoint') -AUTH_TOKEN_ENDPOINT=$(bashio::config 'auth_token_endpoint') -IDP_CLIENT_ID=$(bashio::config 'idp_client_id') -IDP_CLIENT_SECRET=$(bashio::config 'idp_client_secret') -DISABLE_DEFAULT_POLICY=$(bashio::config 'disable_default_policy') -DISABLE_DASHBOARD=$(bashio::config 'disable_dashboard') -ENABLE_RELAY=$(bashio::config 'enable_relay') -RELAY_EXPOSED_ADDRESS=$(bashio::config 'relay_exposed_address') -RELAY_AUTH_SECRET=$(bashio::config 'relay_auth_secret') +DATA_DIR="/config/netbird" +DOMAIN="localhost" +MANAGEMENT_LISTEN="0.0.0.0:33073" +SIGNAL_LISTEN="0.0.0.0:10000" +DASHBOARD_LISTEN="0.0.0.0:8080" +TURN_LISTEN_PORT=3478 +TURN_REALM="netbird" +TURN_EXTERNAL_IP="" +TURN_MIN_PORT=49152 +TURN_MAX_PORT=65535 +TURN_USER="netbird" +TURN_PASSWORD="" +IDP_MANAGER_TYPE="none" +AUTH_AUTHORITY="" +AUTH_AUDIENCE="" +AUTH_JWT_CERTS="" +AUTH_USER_ID_CLAIM="sub" +AUTH_OIDC_CONFIGURATION_ENDPOINT="" +AUTH_TOKEN_ENDPOINT="" +IDP_CLIENT_ID="" +IDP_CLIENT_SECRET="" +DISABLE_DEFAULT_POLICY=false +DISABLE_DASHBOARD=false +ENABLE_RELAY=false +RELAY_EXPOSED_ADDRESS="" +RELAY_AUTH_SECRET="" MANAGEMENT_PORT=$(extract_port "$MANAGEMENT_LISTEN") SIGNAL_PORT=$(extract_port "$SIGNAL_LISTEN") DASHBOARD_PORT=$(extract_port "$DASHBOARD_LISTEN") -if [[ -z "$DOMAIN" ]]; then - DOMAIN="localhost" - bashio::log.warning "domain is empty; defaulting to localhost in generated configs." -fi - if [[ -z "$AUTH_AUTHORITY" || -z "$AUTH_AUDIENCE" || -z "$AUTH_JWT_CERTS" ]]; then - bashio::log.warning "OIDC configuration is incomplete. Update auth_* options or edit ${DATA_DIR}/management/management.json." + bashio::log.warning "OIDC configuration is incomplete. Edit ${DATA_DIR}/management/management.json to finish setup." fi mkdir -p "$DATA_DIR" \ @@ -216,3 +210,21 @@ sed "s/__DASHBOARD_PORT__/${DASHBOARD_PORT}/g" \ mkdir -p /run/nginx chmod +x /usr/local/bin/init_react_envs.sh + +# Generate dashboard env file if missing +DASHBOARD_ENV_FILE="$DATA_DIR/dashboard/env" +if [[ ! -f "$DASHBOARD_ENV_FILE" ]]; then + bashio::log.info "Generating dashboard env file at ${DASHBOARD_ENV_FILE}." + cat <<'ENV' > "$DASHBOARD_ENV_FILE" +# NetBird dashboard environment overrides. +# Example: NETBIRD_MGMT_API_ENDPOINT="https://netbird.example.com" +NETBIRD_MGMT_API_ENDPOINT="" +AUTH_AUTHORITY="" +AUTH_CLIENT_ID="" +AUTH_CLIENT_SECRET="" +AUTH_AUDIENCE="" +AUTH_SUPPORTED_SCOPES="openid profile email api offline_access email_verified" +USE_AUTH0="false" +ENV + chmod 600 "$DASHBOARD_ENV_FILE" +fi diff --git a/netbird-server/rootfs/etc/services.d/coturn/run b/netbird-server/rootfs/etc/services.d/coturn/run index e446f2852..140060fd7 100644 --- a/netbird-server/rootfs/etc/services.d/coturn/run +++ b/netbird-server/rootfs/etc/services.d/coturn/run @@ -7,7 +7,7 @@ set -euo pipefail # Runs Coturn # ============================================================================== -DATA_DIR=$(bashio::config 'data_dir') +DATA_DIR="/config/netbird" TURN_CONFIG="$DATA_DIR/turn/turnserver.conf" if [[ ! -f "$TURN_CONFIG" ]]; then diff --git a/netbird-server/rootfs/etc/services.d/dashboard/run b/netbird-server/rootfs/etc/services.d/dashboard/run index cc3778dc0..ac20ab3d9 100644 --- a/netbird-server/rootfs/etc/services.d/dashboard/run +++ b/netbird-server/rootfs/etc/services.d/dashboard/run @@ -7,19 +7,30 @@ set -euo pipefail # Runs the NetBird Dashboard # ============================================================================== -DOMAIN=$(bashio::config 'domain') -EXTERNAL_BASE_URL=$(bashio::config 'external_base_url') -MANAGEMENT_LISTEN=$(bashio::config 'management_listen') -AUTH_AUTHORITY=$(bashio::config 'auth_authority') -AUTH_CLIENT_ID=$(bashio::config 'auth_client_id') -AUTH_CLIENT_SECRET=$(bashio::config 'auth_client_secret') -AUTH_AUDIENCE=$(bashio::config 'auth_audience') -AUTH_SUPPORTED_SCOPES=$(bashio::config 'auth_supported_scopes') -USE_AUTH0=$(bashio::config 'use_auth0') +DOMAIN="localhost" +EXTERNAL_BASE_URL="" +MANAGEMENT_LISTEN="0.0.0.0:33073" +AUTH_AUTHORITY="" +AUTH_CLIENT_ID="" +AUTH_CLIENT_SECRET="" +AUTH_AUDIENCE="" +AUTH_SUPPORTED_SCOPES="openid profile email api offline_access email_verified" +USE_AUTH0="false" +NETBIRD_MGMT_API_ENDPOINT="" MANAGEMENT_PORT="${MANAGEMENT_LISTEN##*:}" -if [[ -n "$EXTERNAL_BASE_URL" ]]; then +ENV_FILE="/config/netbird/dashboard/env" +if [[ -f "$ENV_FILE" ]]; then + set -a + # shellcheck disable=SC1090 + . "$ENV_FILE" + set +a +fi + +if [[ -n "$NETBIRD_MGMT_API_ENDPOINT" ]]; then + NETBIRD_MGMT_API_ENDPOINT="$NETBIRD_MGMT_API_ENDPOINT" +elif [[ -n "$EXTERNAL_BASE_URL" ]]; then NETBIRD_MGMT_API_ENDPOINT="$EXTERNAL_BASE_URL" elif [[ -n "$DOMAIN" ]]; then NETBIRD_MGMT_API_ENDPOINT="http://${DOMAIN}:${MANAGEMENT_PORT}" diff --git a/netbird-server/rootfs/etc/services.d/management/run b/netbird-server/rootfs/etc/services.d/management/run index a5e2981ab..93516bab0 100644 --- a/netbird-server/rootfs/etc/services.d/management/run +++ b/netbird-server/rootfs/etc/services.d/management/run @@ -7,8 +7,8 @@ set -euo pipefail # Runs the NetBird Management service # ============================================================================== -DATA_DIR=$(bashio::config 'data_dir') -LOG_LEVEL=$(bashio::config 'log_level') +DATA_DIR="/config/netbird" +LOG_LEVEL="info" MANAGEMENT_CONFIG="$DATA_DIR/management/management.json" if [[ ! -f "$MANAGEMENT_CONFIG" ]]; then diff --git a/netbird-server/rootfs/etc/services.d/relay/run b/netbird-server/rootfs/etc/services.d/relay/run index 570878083..1a060d10c 100644 --- a/netbird-server/rootfs/etc/services.d/relay/run +++ b/netbird-server/rootfs/etc/services.d/relay/run @@ -7,9 +7,9 @@ set -euo pipefail # Runs the NetBird Relay (optional) # ============================================================================== -LOG_LEVEL=$(bashio::config 'log_level') -RELAY_EXPOSED_ADDRESS=$(bashio::config 'relay_exposed_address') -RELAY_AUTH_SECRET=$(bashio::config 'relay_auth_secret') +LOG_LEVEL="info" +RELAY_EXPOSED_ADDRESS="" +RELAY_AUTH_SECRET="" bashio::log.info "Starting NetBird Relay..." exec /usr/local/bin/netbird-relay \ diff --git a/netbird-server/rootfs/etc/services.d/signal/run b/netbird-server/rootfs/etc/services.d/signal/run index fe6a0f708..778ea43de 100644 --- a/netbird-server/rootfs/etc/services.d/signal/run +++ b/netbird-server/rootfs/etc/services.d/signal/run @@ -7,8 +7,8 @@ set -euo pipefail # Runs the NetBird Signal service # ============================================================================== -SIGNAL_LISTEN=$(bashio::config 'signal_listen') -LOG_LEVEL=$(bashio::config 'log_level') +SIGNAL_LISTEN="0.0.0.0:10000" +LOG_LEVEL="info" SIGNAL_PORT="${SIGNAL_LISTEN##*:}" bashio::log.info "Starting NetBird Signal on port ${SIGNAL_PORT}..."