mirror of
https://github.com/netbirdio/docs.git
synced 2026-08-24 16:51:26 +02:00
Settings docs accuracy audit: gap fixes and three new pages (#936)
* Enforce periodic user authentication * Multi-Factor Authentication * IPv6 minor fixes * Delete account clarification * Notifications, perms, and billing * Update metrics, auto-update, lazy connections * Settings docs audit fixes plus two new pages * Update self-hosted notications * rework client page and navigation * Matching naming to product * Coberabbit suggested fixes * Peer Session Expiration title * Remove dash
This commit is contained in:
Brandon Hopkins
BIN
public/docs-static/img/manage/settings/client-settings-tab.png
Normal file
BIN
public/docs-static/img/manage/settings/client-settings-tab.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 170 KiB |
@@ -406,21 +406,46 @@ export const docsNavigation = [
|
||||
links: [
|
||||
{
|
||||
title: 'Authentication',
|
||||
href: '/manage/settings/enforce-periodic-user-authentication',
|
||||
},
|
||||
{
|
||||
title: 'Multi-Factor Authentication',
|
||||
href: '/manage/settings/multi-factor-authentication',
|
||||
isOpen: false,
|
||||
links: [
|
||||
{
|
||||
title: 'Peer Session Expiration',
|
||||
href: '/manage/settings/enforce-periodic-user-authentication',
|
||||
},
|
||||
{
|
||||
title: 'Multi-Factor Authentication',
|
||||
href: '/manage/settings/multi-factor-authentication',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Permissions',
|
||||
href: '/manage/settings/permissions',
|
||||
},
|
||||
{ title: 'IPv6 Overlay Addressing', href: '/manage/settings/ipv6' },
|
||||
{ title: 'Auto Update', href: '/manage/peers/auto-update' },
|
||||
{ title: 'Lazy Connections', href: '/manage/peers/lazy-connection' },
|
||||
{
|
||||
title: 'Client Metrics',
|
||||
title: 'Groups',
|
||||
href: '/manage/settings/groups',
|
||||
},
|
||||
{
|
||||
title: 'Networks',
|
||||
isOpen: false,
|
||||
links: [
|
||||
{
|
||||
title: 'Network Settings',
|
||||
href: '/manage/settings/networks',
|
||||
},
|
||||
{
|
||||
title: 'IPv6 Overlay Addressing',
|
||||
href: '/manage/settings/ipv6',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Clients',
|
||||
href: '/manage/settings/clients',
|
||||
},
|
||||
{
|
||||
title: 'Metrics',
|
||||
href: '/manage/client-metrics',
|
||||
},
|
||||
{
|
||||
|
||||
@@ -24,6 +24,10 @@ When Block Inbound Connections is enabled, the client will not add any inbound f
|
||||
- **Routed network traffic**: If this peer acts as a routing peer, inbound traffic to its routed networks is also blocked.
|
||||
- **SSH access**: NetBird SSH connections to this peer are blocked.
|
||||
|
||||
<Note>
|
||||
[`netbird expose`](/manage/reverse-proxy/expose-from-cli) requires inbound connections, so the command fails while this setting is enabled.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
This setting overrides all policies from the management service. Even if an access control policy explicitly allows traffic to this peer, inbound connections will still be blocked.
|
||||
</Note>
|
||||
|
||||
@@ -52,7 +52,7 @@ A colored status dot sits next to the tray icon so you can read the state of you
|
||||
<img src="/docs-static/img/client/desktop-app/tray-status.png" alt="NetBird system tray status indicator" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
The tray menu also provides profile switching, session-renewal access, exit-node selection, Settings, Help & Support, and **Quit NetBird**. Closing the main window only hides it while the daemon and network connection continue running. Choosing **Quit NetBird** disconnects the daemon before the desktop app exits.
|
||||
The tray menu also provides profile switching, session-renewal access, exit-node selection, Settings, Help & Support, and **Quit NetBird**. Closing the main window only hides it while the daemon and network connection continue running. Choosing **Quit NetBird** disconnects the daemon before the desktop app exits, unless **Stay Connected After Quitting** is enabled in **Settings → General** (requires client v0.76.2 or later). That setting is off by default; with it enabled, the connection keeps running after quitting and only stops when you disconnect it yourself.
|
||||
|
||||
## Exit Nodes
|
||||
|
||||
@@ -62,7 +62,7 @@ The compact view shows the active exit node. Open the exit-node selector in the
|
||||
|
||||
The settings page uses a tabbed layout that groups options by what they control. The tabs you see depend on your role and on any [MDM policy](#mdm-driven-ui) in effect. The full set is:
|
||||
|
||||
* **General** for everyday toggles: Connect on Startup, Launch NetBird UI at Login, notifications, and display language.
|
||||
* **General** for everyday toggles: Connect on Startup, Launch NetBird UI at Login, Stay Connected After Quitting, notifications, and display language.
|
||||
* **Network** for connectivity, DNS, routes, and IPv6 settings.
|
||||
* **Security** for inbound traffic, LAN access, and quantum-resistant encryption settings.
|
||||
* **Profiles** for managing the accounts the app knows about. See [Profiles](/client/profiles).
|
||||
|
||||
@@ -694,6 +694,7 @@ sudo netbird service install --config /opt/netbird/config.json
|
||||
|
||||
#### Service-specific flags
|
||||
```shell
|
||||
--disable-networks Disables network selection.
|
||||
--disable-profiles Disables profiles feature.
|
||||
--disable-update-settings Disables update settings feature.
|
||||
--service-env strings Sets extra environment variables for the service. You can specify a comma-separated list of KEY=VALUE pairs. E.g. --service-env NB_LOG_LEVEL=debug,CUSTOM_VAR=value
|
||||
@@ -701,6 +702,7 @@ sudo netbird service install --config /opt/netbird/config.json
|
||||
|
||||
These flags are intended for managed or shared machines where non-admin users should not be able to alter the client configuration through the CLI or UI:
|
||||
|
||||
- `--disable-networks` prevents users from listing, selecting, or deselecting networks (including exit nodes) via CLI or UI. The flag is persisted in the service's `service.json` state file; there is no `NB_DISABLE_NETWORKS` environment-variable equivalent.
|
||||
- `--disable-profiles` prevents users from adding, removing, or switching profiles. The client stays locked to the profile that was active at install time. Any attempt to switch profiles via CLI or UI is rejected.
|
||||
- `--disable-update-settings` prevents users from changing daemon settings (management URL, log level, DNS resolver address, etc.) via CLI or UI. The configuration can only be changed by an administrator who reinstalls the service or uses `service reconfigure`.
|
||||
|
||||
|
||||
@@ -275,7 +275,7 @@ The archive collects the most useful diagnostics into one file, and every bundle
|
||||
| `service_params.json` | Service-install parameters when available; sensitive environment values are masked |
|
||||
| `metrics.txt` | Buffered client metrics when available; peer identifiers are anonymized |
|
||||
|
||||
With `--anonymize`, IP addresses, domains, and interface names are replaced consistently across every file, so the bundle stays readable while sensitive values are masked. Private keys and SSH keys are never included, and the packet capture (`capture.pcap`) is left out of anonymized bundles because it holds raw decrypted packets.
|
||||
With `--anonymize`, public IP addresses, domains, and MAC addresses are replaced consistently across every file, so the bundle stays readable while sensitive values are masked; private, CGNAT, and link-local IP ranges are kept, and interface names are not anonymized. Adding `--anonymize-level strict` (which implies `--anonymize`) also masks those internal IP ranges, peer names, and WireGuard public keys. Private keys and SSH keys are never included, and the packet capture (`capture.pcap`) is left out of anonymized bundles because it holds raw decrypted packets.
|
||||
|
||||
### Debug for a specific time
|
||||
|
||||
|
||||
@@ -63,6 +63,10 @@ When a user signs into NetBird on a device (such as a Windows computer using the
|
||||
2. **Automatic Assignment:** When a user signs into NetBird with SSO on their device, that device (peer) automatically inherits the user's group memberships
|
||||
3. **Dynamic Updates:** If a user's group membership changes in the IdP, their device's access permissions update accordingly
|
||||
|
||||
<Note>
|
||||
This automatic inheritance is controlled by the account-level `Enable user group propagation` setting, which is on by default. See [Groups Settings](/manage/settings/groups) for details.
|
||||
</Note>
|
||||
|
||||
**Methods for assigning user groups to peers:**
|
||||
|
||||
- **Automatic via SSO:** The recommended method. When users authenticate through your IdP, their device automatically receives the appropriate group assignments
|
||||
|
||||
@@ -5,13 +5,15 @@ import {Note} from "@/components/mdx";
|
||||
Client metrics allow you to collect performance data from your NetBird clients, such as connection timing,
|
||||
sync duration, and login latency. This data helps identify connectivity issues and optimize your deployment.
|
||||
|
||||
When enabled, clients periodically push metrics to a collection server.
|
||||
Metrics push is disabled by default. When enabled, clients periodically push metrics to a collection server.
|
||||
Clients always collect these metrics locally and include them in [debug bundles](/help/troubleshooting-client#debug-bundle)
|
||||
regardless of this setting. The setting only controls whether the metrics are pushed.
|
||||
|
||||
## What is collected
|
||||
|
||||
- **Connection stages** — Time taken for each stage of a peer connection: signaling, connection establishment, and WireGuard handshake.
|
||||
- **Sync duration** — How long it takes to process management server sync messages.
|
||||
- **Login duration** — How long the login to the management server takes, including success or failure status.
|
||||
- **Connection stages**: Time taken for each stage of a peer connection, covering signaling, connection establishment, and WireGuard handshake.
|
||||
- **Sync duration**: How long it takes to process management server sync messages, including individual processing phases.
|
||||
- **Login duration**: How long the login to the management server takes, including success or failure status.
|
||||
|
||||
Each metric includes metadata such as the client version, operating system, architecture, and deployment type (cloud or self-hosted). Peer identifiers are hashed before transmission.
|
||||
|
||||
@@ -24,7 +26,14 @@ Each metric includes metadata such as the client version, operating system, arch
|
||||
1. Navigate to **Settings** > **Metrics**.
|
||||
2. Toggle **Share performance metrics** to enable or disable metrics push for all peers in your account.
|
||||
|
||||
When enabled, all connected clients will start pushing metrics on their next sync with the management server.
|
||||
Changing the toggle requires the **Owner** or **Admin** role. For other roles the toggle is disabled.
|
||||
Connected clients apply the change within seconds through a management update; offline clients pick it up on their
|
||||
next login. Enabling or disabling the setting is recorded in the account activity log.
|
||||
|
||||
<Note>
|
||||
Controlling metrics push from the dashboard requires client version `0.74.0` or later. Older clients ignore the
|
||||
account setting and only push metrics when `NB_METRICS_PUSH_ENABLED=true` is set (supported since version `0.67.0`).
|
||||
</Note>
|
||||
|
||||
## Environment variable override
|
||||
|
||||
@@ -38,5 +47,8 @@ The `NB_METRICS_PUSH_ENABLED` environment variable on the client takes precedenc
|
||||
|
||||
<Note>
|
||||
When `NB_METRICS_PUSH_ENABLED` is explicitly set on the client, changes to the dashboard toggle will have no effect on that client.
|
||||
Setting it to `false` is an explicit opt-out from metrics collection for that client.
|
||||
Setting it to `false` is an explicit opt-out from metrics push for that client.
|
||||
</Note>
|
||||
|
||||
You can additionally set `NB_METRICS_INTERVAL` to a duration value (e.g., `30m`, `1h`) to override how often metrics
|
||||
are pushed.
|
||||
|
||||
@@ -14,28 +14,27 @@ The Automatic Updates feature allows the NetBird client to notify users when a n
|
||||
If you're self-hosting NetBird, ensure your server is updated to version <strong>v0.61.0</strong>, which adds support for Automatic Updates.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
This feature is currently under active development and will continue to evolve. Future releases will add Linux support, and handling for long-running peers.
|
||||
</Note>
|
||||
|
||||
## Enable Automatic Updates
|
||||
|
||||
|
||||
|
||||
To enable client auto updates, navigate to [Settings » Clients](https://app.netbird.io/settings) and enable 'Automatic Updates'.
|
||||
To enable client auto updates, navigate to **Settings » Clients** in your NetBird dashboard ([app.netbird.io/settings](https://app.netbird.io/settings) on NetBird Cloud, or your own Management dashboard when self-hosting) and select an update method under **Automatic Updates**:
|
||||
|
||||
You can either:
|
||||
|
||||
* Update to latest stable version.
|
||||
* Update to a specific version.
|
||||
* **Disabled** - turn off automatic updates. This is the default.
|
||||
* **Latest Version** - update clients to the latest stable release.
|
||||
* **Custom Version** - pin clients to a specific version, entered without the `v` prefix (e.g., `0.61.0`).
|
||||
|
||||
<Note>
|
||||
Once enabled, NetBird clients will prompt the user to install the specified version when connecting via the UI, if the current version is older than the specified version.
|
||||
Once enabled, NetBird clients will prompt the user to install the specified version if their current version is older. Clients are never downgraded: pinning a version older than a client's current version has no effect on that client.
|
||||
</Note>
|
||||
|
||||
### Force Automatic Updates
|
||||
|
||||
When you need updates to be installed without user interaction, enable the **Force Automatic Updates** toggle. With this option, updates are installed automatically in the background without prompting the user.
|
||||
When you need updates to be installed without user interaction, enable the **Force Automatic Updates** toggle. With this option, updates are installed automatically in the background without prompting the user, even when the NetBird UI is not running.
|
||||
|
||||
<Note>
|
||||
Force Automatic Updates requires NetBird version <strong>v0.67.0</strong> or later on both the Management server and the clients.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
Enabling Force Automatic Updates will restart the NetBird client during updates, which can temporarily disrupt active connections. Use with caution in production environments.
|
||||
@@ -44,10 +43,10 @@ When you need updates to be installed without user interaction, enable the **For
|
||||
|
||||
## How it works
|
||||
|
||||
1. **User-Initiated Connection**: When a Peer connects to Management, it will receive the current Automatic Updates settings.
|
||||
2. **Version Check**: The Peer will compare its current version with the version specified in the Automatic Updates settings.
|
||||
1. **Settings Sync**: When a Peer connects to Management, it receives the current Automatic Updates settings. Connected Peers also receive setting changes immediately, without reconnecting.
|
||||
2. **Version Check**: The Peer will compare its current version with the version specified in the Automatic Updates settings. Peers following the latest version also re-check for new releases periodically (every 30 minutes) while running.
|
||||
3. **Update Process**:
|
||||
1. If the Peer is running an older version than specified, it will prompt the user to install the update.
|
||||
1. If the Peer is running an older version than specified, it will prompt the user to install the update via a system notification and an install entry in the NetBird tray menu.
|
||||
2. Client will then download the update package from the official NetBird repository.
|
||||
3. The Peer will then install the update and restart itself to apply the changes.
|
||||
|
||||
@@ -56,8 +55,8 @@ When **Force Automatic Updates** is enabled, step 3.1 is skipped, the update is
|
||||
## Supported Platforms
|
||||
|
||||
Automatic Updates are supported on the following platforms only:
|
||||
- Windows
|
||||
- macOS (with PKG installer)
|
||||
- Windows (EXE and MSI installers)
|
||||
- macOS (PKG installer only; Homebrew installations are not auto-updated)
|
||||
|
||||
Linux support is not available at this time due to the variety of distributions and package managers. A future release may include support for popular distributions.
|
||||
|
||||
@@ -69,9 +68,8 @@ Linux support is not available at this time due to the variety of distributions
|
||||
## Notes
|
||||
|
||||
1. Automatic Updates will be set to "disabled" by default.
|
||||
2. If the Peer is unable to download or install the update (e.g., due to network issues), it will show an error notification but will not retry until the next restart.
|
||||
3. For long-running Peers, a future release may include support for periodic update checks during runtime.
|
||||
4. All notifications related to Automatic Updates will be shown only if NetBird UI is running and Notifications are enabled.
|
||||
2. If a peer cannot download or install the update (e.g., due to network issues), the client shows an error notification. Forced updates are retried automatically on subsequent update checks; prompted updates can be retried by the user from the tray menu.
|
||||
3. Update prompts and notifications require the NetBird UI to be running with Notifications enabled. Forced updates are installed by the NetBird service even when the UI is not running.
|
||||
|
||||
## Get started
|
||||
<div>
|
||||
|
||||
@@ -12,12 +12,14 @@ Lazy connections reduce resource use in large NetBird networks by opening peer c
|
||||
|
||||
When lazy connections are enabled, the client:
|
||||
|
||||
- Starts a connection to a peer when traffic is sent to it.
|
||||
- Tears down an established peer connection after it has been idle for the configured inactivity threshold.
|
||||
- Starts a connection to a peer when traffic is sent to it, or when the remote peer signals a connection attempt.
|
||||
- Tears down an established peer connection after it has been idle for the configured inactivity threshold. Idle detection runs on clients using userspace WireGuard; a client running kernel WireGuard relies on the remote peer to detect inactivity and close the connection.
|
||||
- Keeps routing peers in the same high-availability group awake together while any one of them is active, so failover targets stay usable.
|
||||
- Keeps peers used for ingress forwarding connected so forwarding targets remain reachable.
|
||||
- Opens permanent connections to peers whose client version does not support lazy connections.
|
||||
- Reopens all applicable peer connections when lazy connections are disabled.
|
||||
|
||||
The default inactivity threshold is `15m`. Change it with `NB_LAZY_CONN_INACTIVITY_THRESHOLD`, using a [Go duration](https://pkg.go.dev/time#ParseDuration) such as `30m` or `1h`.
|
||||
The default inactivity threshold is `15m`. Change it with `NB_LAZY_CONN_INACTIVITY_THRESHOLD`, using a [Go duration](https://pkg.go.dev/time#ParseDuration) such as `30m` or `1h`. The minimum is `1m`; shorter or invalid values fall back to the default.
|
||||
|
||||
<Note>
|
||||
The first request to an idle peer can take slightly longer while NetBird establishes the connection.
|
||||
@@ -31,10 +33,16 @@ Set `NB_DNS_LAZY_WARMUP_TIMEOUT` on the daemon to change this per-query wait. Th
|
||||
|
||||
## Enable Lazy Connections in Management
|
||||
|
||||
The account setting in the NetBird Dashboard is the normal source of truth. When it is enabled, compatible clients activate their lazy connection manager. When it is disabled, clients stop lazy mode and immediately attempt to connect to all applicable peers.
|
||||
The account setting in the NetBird Dashboard is the normal source of truth: go to `Settings` > `Clients` and turn on the `Enable Lazy Connections` toggle. When it is enabled, compatible clients activate their lazy connection manager. When it is disabled, clients stop lazy mode and immediately attempt to connect to all applicable peers.
|
||||
|
||||
Accounts created on NetBird v0.74.0 or later have lazy connections enabled by default. Accounts created before that keep the setting disabled until an administrator turns it on.
|
||||
|
||||
Existing active connections are not interrupted merely because lazy mode is enabled. They become eligible for teardown after the inactivity threshold.
|
||||
|
||||
<Note>
|
||||
Clients with [Rosenpass post-quantum cryptography](/client/post-quantum-cryptography) enabled do not start the lazy connection manager and keep permanent connections regardless of this setting.
|
||||
</Note>
|
||||
|
||||
## Override the Management Setting on a Client
|
||||
|
||||
Set `NB_LAZY_CONN` on the NetBird daemon when one client must override the account setting:
|
||||
@@ -47,7 +55,7 @@ sudo netbird service reconfigure --service-env NB_LAZY_CONN=on
|
||||
sudo netbird service reconfigure --service-env NB_LAZY_CONN=off
|
||||
```
|
||||
|
||||
`on` and `off` override Management in both directions. Leave the variable unset to follow the Management setting. See [Client Environment Variables](/client/environment-variables#ice-and-connectivity) for service configuration details.
|
||||
`on` and `off` override Management in both directions; boolean values such as `true`/`false` or `1`/`0` are also accepted. Leave the variable unset to follow the Management setting. See [Client Environment Variables](/client/environment-variables#ice-and-connectivity) for service configuration details.
|
||||
|
||||
On MDM-managed clients, the boolean `lazyConnection` policy key provides the same local override: `true` forces lazy connections on, `false` forces them off, and an absent key defers to Management. If both are configured, `NB_LAZY_CONN` takes precedence over MDM.
|
||||
|
||||
|
||||
@@ -44,6 +44,7 @@ From there, you can add new keys or revoke existing ones.
|
||||
## Expiration
|
||||
|
||||
You can set an expiration date when creating a key. Once expired, the key can no longer be used.
|
||||
The create-key dialog pre-fills an expiration of 7 days. Leave the field empty to create a key that never expires.
|
||||
|
||||
## Usage Limit
|
||||
|
||||
@@ -71,6 +72,7 @@ Every peer registered with this key is automatically added to those groups, and
|
||||
|
||||
To configure `Auto-assign groups`, open `Settings` → `Setup Keys` and create or update a setup key.
|
||||
Then use this key to enroll new machines.
|
||||
You can also edit the auto-assigned groups of an existing key directly from the `Groups` column of the setup keys table, provided your role allows updating setup keys.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/peers/register-machines-using-setup-keys/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
|
||||
@@ -96,6 +96,7 @@ You can optionally restrict access to specific **distribution groups** from your
|
||||
- Sessions last **24 hours** before re-authentication is required
|
||||
- Optionally restrict access to specific distribution groups synced from your IdP
|
||||
- When no groups are selected, any authenticated user in your organization can access the service
|
||||
- Users who are blocked or still [pending approval](/manage/team/approve-users) in NetBird are denied access even after successfully authenticating with the IdP
|
||||
|
||||
<Note>
|
||||
**Self-hosted deployments:** SSO authentication uses whichever OIDC provider is configured in your management server. If you use the built-in embedded IdP, SSO works automatically. If you use an external identity provider (Auth0, Okta, Keycloak, etc.) without the embedded IdP, you must register the reverse proxy callback URL with your IdP before SSO will work. See the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy#configure-sso-for-external-identity-providers) for step-by-step instructions.
|
||||
|
||||
@@ -17,6 +17,10 @@ Before using `netbird expose`, make sure:
|
||||
- The **Peer Expose** feature is enabled by your account administrator (see [Enable peer expose](#enable-peer-expose) below).
|
||||
- If peer group restrictions are configured, your peer must be in one of the allowed groups.
|
||||
|
||||
<Note>
|
||||
`netbird expose` requires inbound connections: if [Block Inbound Connections](/client/block-inbound-connections) is enabled on the peer, the command fails until you disable that setting.
|
||||
</Note>
|
||||
|
||||
## Enable peer expose
|
||||
|
||||
An account administrator must enable peer expose before any peer can use the `netbird expose` command.
|
||||
|
||||
34
src/pages/manage/settings/clients.mdx
Normal file
34
src/pages/manage/settings/clients.mdx
Normal file
@@ -0,0 +1,34 @@
|
||||
export const description =
|
||||
'Configure account-wide client behavior: automatic updates, lazy connections, and exposing services from the CLI.'
|
||||
|
||||
# Client Settings
|
||||
|
||||
The `Clients` tab under [Settings](https://app.netbird.io/settings) holds account-wide settings that control how NetBird clients behave. Changing these settings requires a role with permission to update settings, such as `Owner` or `Admin`. Roles with read-only access to settings can view the tab, but the controls are disabled.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/settings/client-settings-tab.png" alt="Client settings tab showing Automatic Updates, Expose Services from CLI, and Lazy Connections" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
## Automatic Updates
|
||||
|
||||
Choose an update method for your clients: keep them on the latest stable release, pin them to a specific version, or disable updates. The `Force Automatic Updates` toggle installs updates in the background without user interaction.
|
||||
|
||||
See [Client Automatic Updates](/manage/peers/auto-update) for the full behavior, platform support, and version requirements.
|
||||
|
||||
## Expose Services from CLI
|
||||
|
||||
The `Enable Peer Expose` toggle allows peers to expose local HTTP services through the NetBird reverse proxy using the `netbird expose` command. This requires NetBird v0.66.0 or later.
|
||||
|
||||
When enabled, you must select at least one peer group under `Allowed peer groups`. Only peers in the selected groups can expose services.
|
||||
|
||||
See [Expose Services from the CLI](/manage/reverse-proxy/expose-from-cli) for command usage and examples.
|
||||
|
||||
## Lazy Connections
|
||||
|
||||
Instead of maintaining always-on connections, NetBird can activate peer connections on demand based on activity or signaling. Enable the `Enable Lazy Connections` toggle to turn this on for compatible clients. This requires NetBird client v0.50.1 or higher.
|
||||
|
||||
See [Lazy Connections](/manage/peers/lazy-connection) for how activation works, inactivity thresholds, and per-client overrides.
|
||||
|
||||
## Agent Network-focused view
|
||||
|
||||
Accounts using [Agent Network](/agent-network) see an additional `Agent Network focused view` toggle. When enabled, the dashboard shows only the Agent Network-related sections and hides parts that are not relevant for it, such as Networks, DNS, and Reverse Proxy. Disable it to bring back the full dashboard.
|
||||
@@ -1,13 +1,13 @@
|
||||
import {Note} from "@/components/mdx";
|
||||
|
||||
# Delete your NetBird account
|
||||
To delete your NetBird organization account, you must be a user with the [owner role](/manage/team/user-roles#owner). You can ask the owner to delete the organization account if you are not the account owner.
|
||||
To delete your NetBird organization account, you must be a user with the [owner role](/manage/team/user-roles#owner). The `Danger zone` tab is only visible to the account owner, so you can ask the owner to delete the organization account if you are not the account owner. If your account is managed by an MSP (Managed Service Provider) parent account, the `Danger zone` tab is not available.
|
||||
## Delete your account
|
||||
<Note>
|
||||
Before proceeding to delete your Netbird account, please be aware that this action is irreversible. Once your account is deleted, you will permanently lose access to all associated data, including your peers, users, groups, policies, and routes.
|
||||
</Note>
|
||||
|
||||
Go to the `Settings` tab, then click on `Danger Zone`. Review the message and click on the `Delete Account` button.
|
||||
Go to the `Settings` tab, then click on `Danger zone`. Review the message and click on the `Delete Account` button.
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/settings/account-settings-danger-zone.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
|
||||
# Enforce periodic user authentication
|
||||
# Peer Session Expiration
|
||||
|
||||
To ensure a high level of security, NetBird offers a peer login expiration feature that requires users to periodically reauthenticate their devices.
|
||||
Every new network has this feature enabled, and the expiration period is set to 24 hours by default. You can disable this feature and configure the expiration period in the account settings in the web UI https://app.netbird.io/settings.
|
||||
To ensure a high level of security, NetBird offers a peer session expiration feature (shown as **Peer Session Expiration** in the dashboard) that requires users to periodically reauthenticate their devices.
|
||||
Every new account has this feature enabled, and the expiration period is set to 24 hours by default. You can disable this feature and configure the expiration period in the account settings in the web UI https://app.netbird.io/settings.
|
||||
|
||||
<Note>
|
||||
This feature is only applied to peers added with the [interactive SSO login feature](/get-started/install#running-net-bird-with-sso-login). Peers, added with a setup key, won't be affected.
|
||||
@@ -16,8 +16,8 @@ Expired peers will appear in the peers' view with the status `Login required`.
|
||||
|
||||
## Configure and disable expiration
|
||||
The expiration period can be set to anything between one hour and 180 days.
|
||||
Go to the Web UI `Settings` tab and set the desired period in the Authentication section.
|
||||
You can also disable the expiration for the whole network in the same section.
|
||||
Go to the Web UI `Settings` page, open the `Authentication` tab, enable the `Peer Session Expiration` toggle, and set the desired period in the `Session Expiration` field below it (in hours or days).
|
||||
You can also disable the expiration for the whole account in the same section.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/team/peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper-big"/>
|
||||
@@ -29,11 +29,25 @@ You can also disable the expiration for the whole network in the same section.
|
||||
and re-authentication will be required.
|
||||
</Note>
|
||||
|
||||
## Require login after disconnect
|
||||
In addition to the periodic expiration, you can require re-authentication when a peer loses its connection to the management service.
|
||||
Enable the `Require login after disconnect` toggle under `Peer Session Expiration` in the `Authentication` tab.
|
||||
When enabled, peers added with SSO login that stay disconnected from management for 10 minutes will require re-authentication before reconnecting.
|
||||
This is useful for tightly controlled environments where a device that goes offline, such as a laptop that is shut down or leaves the network, should prove the user's identity again before rejoining.
|
||||
|
||||
This option is only available while `Peer Session Expiration` is enabled, and it can also be toggled individually per peer in the peer's detail view.
|
||||
|
||||
## Session expiration warnings
|
||||
Starting with NetBird client v0.75, the desktop client warns users before their session expires instead of silently disconnecting them.
|
||||
A system notification appears 10 minutes before expiration, letting the user extend the session by re-authenticating right away.
|
||||
If the user hasn't acted on it, a final warning dialog opens 2 minutes before the session expires.
|
||||
This gives users a chance to re-authenticate without interrupting their work or losing connectivity.
|
||||
|
||||
## Disable expiration individually per peer
|
||||
Sometimes, you might want to disable peer expiration for some peers.
|
||||
With NetBird you can disable login expiration per peer without disabling expiration globally.
|
||||
In `Peers` click on the peer you want to disable expiration for and use the Login Expiration switch. (Session expiration only applies to peers with a user behind them; peers enrolled with a setup key are already exempt.)
|
||||
Peers with `Expiration disabled` will be marked with a corresponding label in the Peers table.
|
||||
With NetBird you can disable session expiration per peer without disabling expiration globally.
|
||||
In `Peers` click on the peer you want to disable expiration for and use the `Session Expiration` toggle. (Session expiration only applies to peers with a user behind them; peers enrolled with a setup key are already exempt.)
|
||||
Peers with disabled expiration are marked with a timer icon in the Peers table, and hovering over it shows a note that expiration is disabled for this peer.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/team/individual-peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper-big"/>
|
||||
|
||||
58
src/pages/manage/settings/groups.mdx
Normal file
58
src/pages/manage/settings/groups.mdx
Normal file
@@ -0,0 +1,58 @@
|
||||
export const description = 'Control how user group memberships propagate to peers, and configure JWT group sync on self-hosted deployments, in the Groups tab of your account settings.'
|
||||
|
||||
# Groups Settings
|
||||
|
||||
The `Groups` tab in your account settings (the page itself is titled `User Groups`) controls how group memberships flow from users to their devices. Its main setting is `Enable user group propagation`. On self-hosted deployments it also holds the JWT group sync configuration.
|
||||
|
||||
To find it, log in to your NetBird dashboard and navigate to `Settings` > `Groups`.
|
||||
|
||||
<Note>
|
||||
This tab is only about account-wide group behavior. To view and manage the groups themselves, go to `Access Control` > `Groups`. See [Access Control](/manage/access-control) for how groups are used in policies.
|
||||
</Note>
|
||||
|
||||
## Enable user group propagation
|
||||
|
||||
When this setting is enabled, the groups assigned to a user (their auto-groups) are automatically applied to every peer that user owns. If you add a group to a user or remove one, whether manually or through your identity provider, all of that user's peers are updated to match, and their access permissions change accordingly.
|
||||
|
||||
This is what makes user groups work as described in [Access Control](/manage/access-control#user-groups): assign a group like `engineering-team` to a user once, and every device they log into carries that membership.
|
||||
|
||||
<Note>
|
||||
This setting is **enabled by default** on new accounts.
|
||||
</Note>
|
||||
|
||||
### What changes when you enable it
|
||||
|
||||
If the setting was off and you turn it on, NetBird runs a one-time sync across the whole account: every user's peers are added to that user's groups where they are not already members. Existing group memberships are kept, nothing is removed. If the sync changes memberships that policies depend on, the affected peers receive an updated network map right away, so access changes take effect without waiting for the next login.
|
||||
|
||||
While the setting is on, any later change to a user's groups is propagated to their peers immediately, in both directions: groups added to the user are added to their peers, and groups removed from the user are removed from their peers.
|
||||
|
||||
### What changes when you disable it
|
||||
|
||||
Turning the setting off does not remove any group memberships that were already propagated. Peers keep the groups they have. From that point on, changes to a user's groups no longer affect their peers, and you manage peer group membership yourself, either on the individual peers or in `Access Control` > `Groups`.
|
||||
|
||||
## JWT group sync
|
||||
|
||||
<Note>
|
||||
JWT group sync is configured on self-hosted deployments only. On NetBird Cloud these controls are not shown, and groups are synchronized through the [IdP integrations](/manage/team/idp-sync) instead.
|
||||
</Note>
|
||||
|
||||
If your self-hosted deployment uses an external identity provider, `Enable JWT group sync` lets NetBird extract group names from a claim in the user's JWT access token, create matching NetBird groups automatically, and assign them to the user. With user group propagation enabled as well, those groups then reach the user's peers.
|
||||
|
||||
Enabling the toggle reveals two fields:
|
||||
|
||||
- `JWT claim`: the claim in the token that contains the list of group names, for example `groups` or `roles`.
|
||||
- `JWT allow groups`: an optional allow list. When set, only users whose token contains one of the listed groups can access NetBird at all.
|
||||
|
||||
<Warning>
|
||||
`JWT allow groups` can lock you out. If you save an allow group that your own user is not part of, you lose access to NetBird along with everyone else outside that group. The dashboard shows a confirmation dialog before saving for this reason. Make sure your own user is a member of the allow group in your IdP before saving.
|
||||
</Warning>
|
||||
|
||||
For setup instructions, including how to configure the groups claim in specific identity providers, see [JWT group sync](/selfhosted/identity-providers#jwt-group-sync) in the identity provider documentation.
|
||||
|
||||
## Changing the settings
|
||||
|
||||
1. Go to `Settings` > `Groups`.
|
||||
2. Toggle `Enable user group propagation`, and on self-hosted, configure JWT group sync if needed.
|
||||
3. Click `Save Changes`.
|
||||
|
||||
You need permission to update account settings to change anything on this tab, which in practice means an owner or administrator. Roles with read-only settings access, such as `Network Admin` and `Auditor`, can open the tab but the controls are disabled for them.
|
||||
@@ -10,13 +10,13 @@ NetBird supports dual-stack overlay networking, where each peer can receive both
|
||||
|
||||
New accounts have IPv6 enabled by default for the **All** group, so every peer receives an IPv6 address out of the box. Existing accounts can enable it from the dashboard.
|
||||
|
||||
Navigate to **Settings > Network** and select which groups should have IPv6 enabled. Only peers that belong to at least one selected group will receive an IPv6 address.
|
||||
Navigate to **Settings > Networks** and select which groups should have IPv6 enabled. Only peers that belong to at least one selected group will receive an IPv6 address.
|
||||
|
||||
|
||||
|
||||
When a peer belongs to an IPv6-enabled group, it receives an overlay address from the account's IPv6 range. Peers that do not belong to any IPv6-enabled group only receive an IPv4 address.
|
||||
|
||||
The IPv6 network range is configured alongside your IPv4 range. Valid prefix lengths are `/48` through `/120`, and the default `/64` prefix provides enough addresses for most deployments.
|
||||
The IPv6 network range is configured alongside your IPv4 range. The dashboard accepts prefix lengths from `/48` through `/112`, while the API accepts up to `/120`. The default `/64` prefix provides enough addresses for most deployments. Changing the range re-allocates the IPv6 addresses of all affected peers.
|
||||
|
||||
## Disabling IPv6 on a Client
|
||||
|
||||
@@ -34,7 +34,7 @@ The flag is also available in the desktop UI under **Settings > Disable IPv6**,
|
||||
|
||||
### Address Assignment
|
||||
|
||||
Each peer receives at most one IPv4 and one IPv6 overlay address. Management assigns the IPv6 address when the peer first connects with a client that supports IPv6 and belongs to an IPv6-enabled group.
|
||||
Each peer receives at most one IPv4 and one IPv6 overlay address. Management allocates the IPv6 address based on group membership: when you save the setting for peers that are already registered, or at registration time for new peers. The address only becomes active on peers whose client advertises IPv6 support.
|
||||
|
||||
|
||||
|
||||
@@ -96,7 +96,7 @@ The following API fields relate to IPv6:
|
||||
|
||||
### Peers report no IPv6 address after enabling the setting
|
||||
|
||||
Peers only get an IPv6 address if they belong to at least one group listed in **IPv6 Enabled Groups** and if the client version supports the IPv6 overlay capability (v0.71.0+). Older agents don't advertise the capability and management skips IPv6 assignment for them.
|
||||
Peers only get an IPv6 address if they belong to at least one group listed in **IPv6 Enabled Groups** and if the client version supports the IPv6 overlay capability (v0.71.0+). Older agents don't advertise the capability, so management leaves them out of IPv6 distribution: they don't get the address on their interface, and other peers don't receive AAAA records or IPv6 firewall rules for them.
|
||||
|
||||
### Routing peer has an IPv6 address but traffic doesn't reach the backend
|
||||
|
||||
|
||||
@@ -9,13 +9,17 @@ NetBird MFA is primarily for users with **email / password login**. It is availa
|
||||
You may not need NetBird MFA. Your SSO Provider (Google, Microsoft etc.) may already have MFA enabled. Enabling this setting could result in duplicated MFA checks.
|
||||
</Note>
|
||||
<Note>
|
||||
This feature is only available in the cloud version of NetBird. <br />Self-Hosted users can use their own Identity Provider for MFA.
|
||||
This feature is only available in the cloud version of NetBird. <br />Self-Hosted users can use their own Identity Provider for MFA, or enable [MFA for local users](/selfhosted/identity-providers/enable-local-mfa) when using the embedded identity provider.
|
||||
</Note>
|
||||
|
||||
## Enabling and Disabling MFA
|
||||
Navigate to the Dashboard's `Settings` page and the `Authentication` tab and enable or disable MFA. <br />
|
||||
After enabling, you can `Logout` and log back in to see the MFA prompt.
|
||||
|
||||
<Note>
|
||||
Accounts that use NetBird's embedded identity provider for local users see an additional `Enable Local MFA` toggle (currently in beta) in the same tab. This enforces a TOTP challenge for all local (email/password) users. See [Enable MFA for local users](/selfhosted/identity-providers/enable-local-mfa).
|
||||
</Note>
|
||||
|
||||
- When disabling MFA, the current active MFA devices of all users will not be removed and will be reused when MFA is enabled again. To remove MFA devices from users, check the [Reset MFA](#reset-mfa) section below.
|
||||
- If a user is not part of the account and MFA is enabled, the first-time `Sign Up` will not require MFA. <br /> Only subsequent logins will require MFA.
|
||||
|
||||
@@ -34,7 +38,7 @@ Once enabled you will see a checkbox to remember your browser for 30 days while
|
||||
You can check individual user MFA status by going to the `Users` page of the Dashboard.<br />
|
||||
Click on a specific user to see their MFA status.
|
||||
- `Active` - MFA is enabled and user **has completed** the MFA setup.
|
||||
- `Not enrolled` - MFA is enabled but user **has not completed** the MFA setup yet.
|
||||
- `Not Enrolled` - MFA is enabled but user **has not completed** the MFA setup yet.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/settings/mfa/mfa-not-enrolled.png" alt="MFA Status" className="imagewrapper-big"/>
|
||||
|
||||
53
src/pages/manage/settings/networks.mdx
Normal file
53
src/pages/manage/settings/networks.mdx
Normal file
@@ -0,0 +1,53 @@
|
||||
export const description = 'Configure account-wide network settings such as a custom IPv4 network range, a custom peer DNS domain, and routing peer DNS resolution.'
|
||||
|
||||
# Network Settings
|
||||
|
||||
The `Networks` tab in your account settings holds network-wide configuration that applies to every peer in your account: the DNS domain peers are named under, the IP ranges peers get their addresses from, and DNS resolution behavior for routed domains.
|
||||
|
||||
To find it, log in to your NetBird dashboard and navigate to `Settings` > `Networks`.
|
||||
|
||||
## DNS Domain
|
||||
|
||||
Every peer gets a DNS name made up of its peer DNS label and the account's DNS domain, for example `server-1.netbird.cloud`. The `DNS Domain` setting replaces the default domain with one of your own, so peers resolve as, for example, `server-1.vpn.example.com` instead.
|
||||
|
||||
When the field is empty, the account uses the server default: `netbird.cloud` on NetBird Cloud and `netbird.selfhosted` on self-hosted deployments (self-hosted servers can also set a different default in the management configuration).
|
||||
|
||||
The value must be a valid domain name without wildcards, such as `example.com` or `intra.example.com`. It also cannot be a domain you already use as a [custom DNS zone](/manage/dns/custom-zones) in the same account; the update is rejected with a conflict error in that case.
|
||||
|
||||
<Note>
|
||||
Use a domain that does not resolve on the public internet, for example a dedicated subdomain like `vpn.example.com` that has no public records. NetBird clients answer queries for this domain themselves, so pointing it at a real, publicly resolvable domain would override its DNS results for your peers.
|
||||
</Note>
|
||||
|
||||
## Network Range
|
||||
|
||||
Peers get their NetBird IPv4 address from the account's network range. New accounts are assigned a random `/16` subnet from the `100.64.0.0/10` carrier-grade NAT block, for example `100.77.0.0/16`, so the overlay network does not collide with common private LAN ranges.
|
||||
|
||||
The `Network Range` setting lets you replace that with a custom IPv4 range in CIDR notation, for example `10.100.0.0/16`. The range must satisfy the following:
|
||||
|
||||
- It must be a valid IPv4 CIDR prefix. Loopback, multicast, and link-local ranges are not allowed.
|
||||
- The prefix can be at most `/28` (16 addresses). Larger prefixes such as `/29` are rejected as too small.
|
||||
- It must be big enough for your current peers plus a 50% buffer, with a minimum of 10 usable addresses. For example, with 100 peers the range needs at least 150 addresses, so `/24` or larger.
|
||||
|
||||
<Warning>
|
||||
Changing the network range immediately re-allocates the NetBird IP of **every peer** in the account. Peers receive new addresses from the new range, connected clients are updated with the new network map, and reverse proxy services are reloaded to pick up the new IPs. Anything that references the old NetBird IPs directly, such as firewall rules or scripts outside of NetBird, needs to be updated. Where possible, reference peers by DNS name or by group instead of by IP.
|
||||
</Warning>
|
||||
|
||||
## IPv6 settings
|
||||
|
||||
The `IPv6 Network Range` and `IPv6 Enabled Groups` settings on the same tab control dual-stack overlay addressing. See [IPv6 Overlay Addressing](/manage/settings/ipv6) for how to enable IPv6 and configure the IPv6 range.
|
||||
|
||||
## Enable Routing Peer DNS Resolution
|
||||
|
||||
When enabled, DNS lookups for routed domain resources are performed on the routing peer instead of on each client, so clients do not need to be able to resolve those names themselves. It requires NetBird client v0.35 or higher, and changes take effect after clients restart. See [Routing Peer DNS Resolution](/manage/networks/how-routing-peers-work#routing-peer-dns-resolution) for details on how it affects domain resources.
|
||||
|
||||
## Traffic events
|
||||
|
||||
On NetBird Cloud, the tab also contains an experimental `Enable Traffic Events` section for logging connection events between peers. See [Traffic Events Logging](/manage/activity/traffic-events-logging) for plan requirements and configuration.
|
||||
|
||||
## Changing the settings
|
||||
|
||||
1. Go to `Settings` > `Networks`.
|
||||
2. Adjust the settings. Invalid values, such as a malformed CIDR range or domain, are flagged inline.
|
||||
3. Click `Save Changes`. The `Enable Routing Peer DNS Resolution` toggle saves immediately without the button.
|
||||
|
||||
You need permission to update account settings to change these values, which in practice means an owner or administrator. Roles with read-only settings access, such as `Network Admin` and `Auditor`, can open the tab but the fields are disabled for them.
|
||||
@@ -5,10 +5,10 @@ export const description =
|
||||
|
||||
# Notifications
|
||||
|
||||
NetBird can notify you when important events occur in your account, such as peers waiting for approval, routing peer disconnections, or new users joining. You can configure it under `Settings` > `Notifications` in the NetBird dashboard.
|
||||
NetBird can notify you when important events occur in your account, such as peers waiting for approval, routing peer disconnections, or new users joining. You can configure it under `Settings` > `Notifications` in the NetBird dashboard. Notifications are currently in beta. Users who can view account settings, such as administrators and owners, can see the configuration, and only users with permission to update settings can change it.
|
||||
|
||||
<Note>
|
||||
This feature is currently only available in the cloud version of NetBird.
|
||||
This feature is available in the cloud version of NetBird and in self-hosted deployments with an [enterprise license](/selfhosted/enterprise). The open-source self-hosted version does not include notifications.
|
||||
</Note>
|
||||
|
||||
<p>
|
||||
@@ -23,7 +23,7 @@ NetBird supports three notification channels:
|
||||
| `Webhook` | Send notifications as HTTP POST requests to a custom endpoint |
|
||||
| `Slack` | Send notifications to a Slack channel via an Incoming Webhook |
|
||||
|
||||
Each channel can be independently enabled or disabled and configured with its own set of event types.
|
||||
Each channel can be independently enabled or disabled and configured with its own set of event types. New channels start disabled with all event types selected.
|
||||
|
||||
## Supported Events
|
||||
|
||||
@@ -35,7 +35,7 @@ All notification channels support the following events:
|
||||
| **Peer** | `Peer Added` | A new peer is added to the network |
|
||||
| **Peer** | `Routing Peer Disconnected` | A routing peer loses its connection |
|
||||
| **Peer** | `Routing Peer Deleted` | A routing peer is deleted from the network |
|
||||
| **User** | `Pending Approval` | A user is waiting for approval to join the network |
|
||||
| **User** | `User Pending Approval` | A user is waiting for approval to join the network |
|
||||
| **User** | `User Joined` | A new user joins the account |
|
||||
| **User** | `Service User Created` | A new service user is created |
|
||||
| **Integration** | `IdP Sync Token Expired` | The IdP sync token has expired and needs renewal |
|
||||
@@ -51,7 +51,7 @@ The email channel lets you send notifications to one or more email recipients.
|
||||
|
||||
1. Navigate to `Settings` > `Notifications` and click on the `Email` channel.
|
||||
2. Use the `Enable Email Channel` toggle to enable or disable all email notifications.
|
||||
3. Under `Email Addresses`, enter the email address you want to receive notifications and click `Add`. You can add multiple recipients.
|
||||
3. Under `Email Addresses`, enter the email address you want to receive notifications and click `Add`. You can add multiple recipients. When you open the email channel for the first time, your own email address is added as a recipient automatically.
|
||||
4. Toggle individual events on or off under the `Peer Notifications`, `User Notifications`, and `Integration Notifications` sections.
|
||||
|
||||
<p>
|
||||
@@ -73,7 +73,7 @@ The webhook channel sends notification events as HTTP `POST` requests to a URL y
|
||||
<img src="/docs-static/img/manage/settings/notifications/netbird-notifications-webhook-channel.png" alt="Webhook channel page with Connect button" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
3. In the `General` tab, enter the full HTTP(S) URL of your endpoint. Notification events will be sent as `POST` requests to this URL. Optionally, select an `Authentication` method for the endpoint.
|
||||
3. In the `General` tab, enter the full HTTP(S) URL of your endpoint. Notification events will be sent as `POST` requests to this URL. Optionally, select an `Authentication` method for the endpoint: `No Authentication`, `Basic Auth`, `Bearer Token`, or `Custom Authentication`. When using an authentication method, we strongly recommend an HTTPS endpoint, since the credentials are sent with every request.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/settings/notifications/netbird-notifications-webhook-create-general-tab.png" alt="Connect Webhook modal showing the General tab with endpoint URL and authentication options" className="imagewrapper"/>
|
||||
@@ -91,8 +91,8 @@ Once connected, you can toggle individual events on or off, just like with the e
|
||||
|
||||
### Edit or Delete a Webhook
|
||||
|
||||
To update the webhook URL, authentication, or headers, click `Edit` on the webhook channel page. <br/>
|
||||
To remove the webhook entirely, click `Delete`.
|
||||
To update the webhook URL, authentication, or headers, open the menu next to the connected webhook and select `Edit`. <br/>
|
||||
To remove the webhook entirely, select `Delete` and confirm.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/settings/notifications/netbird-notifications-webhook-edit-delete.png" alt="Webhook channel page showing Edit and Delete options for a connected webhook" className="imagewrapper"/>
|
||||
|
||||
@@ -25,10 +25,10 @@ The restriction applies to users with the following roles:
|
||||
- `User` (regular users)
|
||||
- `Billing Admin`
|
||||
|
||||
Owners and administrators are never affected, and neither are service users acting through an access token with the appropriate permissions.
|
||||
Users with the `Owner`, `Admin`, `Network Admin`, or `Auditor` [role](/manage/team/user-roles) are never affected, and neither are service users acting through an access token.
|
||||
|
||||
<Note>
|
||||
Despite the name, the setting also restricts billing admins. If you have billing admins who need to see peers, this setting has to be off.
|
||||
Despite the name, the setting also applies to billing admins. Since a `Billing Admin`'s dashboard access is limited to billing pages regardless, in practice the setting mainly affects users with the `User` role.
|
||||
</Note>
|
||||
|
||||
### What changes when it is enabled
|
||||
@@ -54,4 +54,4 @@ Turning the setting off does not give regular users visibility of the whole netw
|
||||
2. Toggle `Restrict dashboard for regular users` on or off.
|
||||
3. Click `Save Changes`.
|
||||
|
||||
You need permission to update account settings to change this, which in practice means an owner or administrator.
|
||||
You need permission to update account settings to change this, which in practice means an owner or administrator. Roles with read-only settings access, such as `Network Admin` and `Auditor`, can open the tab but the toggle is disabled for them.
|
||||
@@ -60,6 +60,12 @@ automatically adjust the machine costs as detailed in the following sections.
|
||||
|
||||
To start or change your current plan, navigate to `Settings` > `Plans & Billing` and choose the plan you wish to upgrade or downgrade to.
|
||||
|
||||
<Note>
|
||||
The `Plans & Billing` tab is available on NetBird Cloud only and is shown to users with billing permissions, such as the account `Owner`, `Admin`s, and `Billing Admin`s. See [user roles](/manage/team/user-roles) for details.
|
||||
</Note>
|
||||
|
||||
If your account is eligible for a free trial, the `Plans & Billing` tab also shows a `Start 14-Day Free Trial` button that temporarily unlocks NetBird's full set of features and integrations. After the trial ends, you return to your previous plan unless you choose to upgrade. Only the account `Owner` or an `Admin` can start a free trial: `Billing Admin`s can see the `Plans & Billing` tab, but the trial button is disabled for them.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/settings/plans-and-billing/chose-plan.png" alt="chose-plan" width="780" className="imagewrapper-big"/>
|
||||
</p>
|
||||
@@ -89,7 +95,7 @@ Please note that changes to the number of peers and user counts are updated in o
|
||||
|
||||
## Changing a Subscription
|
||||
|
||||
Based on your current plan, you have the flexibility to upgrade or downgrade at any time as your needs change.
|
||||
Based on your current plan, you have the flexibility to upgrade or downgrade as your needs change. After changing your plan, you need to wait 48 hours from the last update before you can change it again.
|
||||
|
||||
<Note>
|
||||
Your subscription cycle starts on the first day of your original subscription. If you adjust your plan during the billing cycle, and since billing occurs at the end of the subscription month, you will be charged for the plan you are on at the end of the billing cycle.
|
||||
@@ -119,6 +125,11 @@ Changes to your billing details apply to invoices issued after the update. Exist
|
||||
</Note>
|
||||
|
||||
|
||||
## Viewing Invoices
|
||||
|
||||
In addition to the Stripe billing portal, you can view your invoices directly in the NetBird dashboard. Navigate to `Settings` > `Invoices` to see your paid invoices and download them as PDF or CSV files. Invoices are created at the end of each billing period; PDF downloads redirect through Stripe, while CSV files download directly from the dashboard. For MSPs and distributors, the `Type` column distinguishes invoices for your own account from those for your tenants or customers. The `Invoices` tab is not shown for accounts managed by an MSP.
|
||||
|
||||
|
||||
## Deleting an Account
|
||||
|
||||
If you [delete your account](/manage/settings/delete-account), the final charge for your usage will be processed during the next daily statistics update cycle at 2 AM UTC.
|
||||
|
||||
@@ -2,6 +2,7 @@ import {Note} from "@/components/mdx";
|
||||
|
||||
# Approve users
|
||||
The user approval feature enhances security by requiring manual administrator approval before a user can join your NetBird organization via domain matching.
|
||||
New NetBird Cloud accounts have user approval enabled by default.
|
||||
|
||||
## Require user approval
|
||||
Navigate to the Dashboard's `Settings` page and the `Authentication` tab and enable or disable `User Approval Required`.
|
||||
|
||||
@@ -72,9 +72,11 @@ NetBird supports any OIDC-compliant identity providers. Here are some popular pr
|
||||
- **Name** - Display name for the login button
|
||||
- **Client ID** - From your identity provider
|
||||
- **Client Secret** - From your identity provider
|
||||
- **Issuer** - From your identity provider
|
||||
6. Copy the **Redirect URL** and configure it in your identity provider
|
||||
7. Click **Save**
|
||||
- **Issuer URL** - From your identity provider (not shown for the `google` and `microsoft` provider types; all other types, including `entra`, require it)
|
||||
6. Copy the **Redirect URL** and configure it in your identity provider. The modal also shows a **Logout URL** (`https://netbird.example.com/oauth2/logout/callback`) that you can register with your identity provider, though not all identity providers support logout.
|
||||
7. Click **Add Provider**
|
||||
|
||||
When editing an existing provider, the **Provider Type** cannot be changed after creation. Leaving the **Client Secret** field empty keeps the existing secret; entering a new secret becomes required if you change the **Client ID**. Click **Save Changes** to apply your edits.
|
||||
|
||||
<Note>
|
||||
Make sure you are creating a confidential OIDC client in your identity provider. The secret will be stored privately in
|
||||
@@ -202,7 +204,7 @@ NetBird supports provisioning users and groups through SCIM. However, this funct
|
||||
|
||||
#### "Invalid redirect URI" error
|
||||
|
||||
- Copy the exact Redirect URL from NetBird after creating the provider
|
||||
- Copy the exact Redirect URL shown in the provider dialog (also available when editing the provider)
|
||||
- Ensure no trailing slashes or typos
|
||||
- Some providers are case-sensitive
|
||||
|
||||
|
||||
@@ -300,6 +300,10 @@ Users created through the embedded IdP can be assigned roles:
|
||||
| **Admin** | Manage users, peers, policies, and settings |
|
||||
| **User** | Connect devices, view assigned resources |
|
||||
|
||||
<Note>
|
||||
[JWT group sync](/selfhosted/identity-providers#jwt-group-sync) does not apply to local users managed by the embedded IdP. Their groups are managed directly in NetBird.
|
||||
</Note>
|
||||
|
||||
## Instance Setup (First Run)
|
||||
|
||||
When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
|
||||
|
||||
@@ -61,6 +61,16 @@ To upgrade NetBird to the latest version:
|
||||
docker compose up -d --force-recreate netbird-server dashboard proxy
|
||||
```
|
||||
|
||||
<Note>
|
||||
Keep the Management and proxy versions in sync. Starting with v0.76.1, if the [Reverse Proxy](/manage/reverse-proxy) component runs a newer version than Management, Agent Network LLM cost metering is silently disabled (the proxy skips cost computation and only logs a warning). Upgrade Management before or together with the proxy.
|
||||
|
||||
Because the `netbirdio/reverse-proxy:latest` image tag does not tell you what is actually running, check the resolved proxy version with:
|
||||
```bash
|
||||
docker compose exec proxy /go/bin/netbird-proxy --version
|
||||
```
|
||||
Compare it with the `management_current_version` field returned by `GET /api/instance/version` before upgrading.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
For upgrades from older versions (pre-v0.26.0), see the [Legacy upgrade notes](#legacy-self-hosting-with-zitadel-idp) below.
|
||||
</Note>
|
||||
|
||||
@@ -201,7 +201,7 @@ If throughput lands well below a few Gbps, check these before resizing hardware:
|
||||
## IPv6 Support
|
||||
|
||||
<Note>
|
||||
IPv6 overlay addressing requires NetBird v0.68.0 or later on both the routing peer and the clients.
|
||||
IPv6 overlay addressing requires NetBird v0.71.0 or later on both the routing peer and the clients.
|
||||
</Note>
|
||||
|
||||
When IPv6 is enabled in your account settings and the exit node peer supports it, the management server automatically generates a `::/0` route alongside the `0.0.0.0/0` route. No additional configuration is needed.
|
||||
|
||||
Reference in New Issue
Block a user