DOCSEARCHbyAlgolia
Submit Docs

NetBird Documentation

website·Indexed 36 days ago

https://docs.netbird.io

Documentation for NetBird, an open-source networking tool. Includes guides on self-hosting, REST API usage, gRPC and HTTP/JSON daemon sockets, Kubernetes integration, remote access scenarios, and managing users, peers, and network activity.

Tokens
305.1K
Snippets
1K
Records
2.2K
Agent score
65%

What's inside NetBird

  1. Overview of the NetBird gRPC Daemon Socket

    The NetBird daemon exposes a local gRPC API used by the NetBird CLI and desktop app. This socket allows integrations to check status, manage connections, inspect configurations, and work with profiles and networks. It controls the local daemon and is distinct from the NetBird Management API. If gRPC or Protocol Buffer bindings cannot be used, the HTTP/JSON daemon socket is the alternative.

  2. Overview of the NetBird self-hosted admin CLI

    The self-hosted admin CLI allows administrators to perform maintenance tasks directly against the NetBird Management data store and embedded IdP store. It is intended for self-hosted control planes when the Dashboard or public API are insufficient.

    Key Constraints:

    • Only manages users in the embedded IdP; it cannot manage users in external providers (e.g., Google Workspace, Okta, Microsoft Entra ID).
    • Commands should be run using the same NetBird version as the server.
    • After a server upgrade, start the server once before using the CLI to ensure database migrations and IdP clients are initialized.
    • Always back up configuration and data stores before running state-changing commands.

  3. Overview of NetBird Notification Channels

    NetBird provides notifications for important account events. This feature is available in the NetBird cloud version and self-hosted deployments with an enterprise license (not available in the open-source self-hosted version). Notifications are configured under Settings > Notifications in the dashboard.

    Supported channels include:

    • Email: Sends notifications to one or more email addresses.
    • Webhook: Sends notifications as HTTP POST requests to a custom endpoint.
    • Slack: Sends notifications to a Slack channel via an Incoming Webhook.

  4. Overview of NetBird on MikroTik RouterOS

    Running NetBird in a MikroTik container allows for cost-effective remote access to RouterOS devices and their networks without additional hardware. This is particularly useful for branch offices with limited space or field routers in remote areas.

    Key Limitations:

    • Performance: Routing through RouterOS containers is CPU-bound and relatively slow; it is not recommended for massive file transfers or high-bandwidth streaming.
    • Features: NetBird in RouterOS containers cannot use an exit node (due to legacy routing mode) and cannot perform NAT internally (NAT must be configured on RouterOS itself).
    • Support: This setup uses MikroTik's beta container features and NetBird's legacy routing, making it unsupported by both vendors.

  5. Overview of NetBird Network Routes

    Network Routes allow NetBird peers to access private networks (such as LANs, VPCs, or data centers) via a 'routing peer' that forwards packets between the NetBird mesh and the internal network.

    Important Deprecation Notice: As of August 2026, Routes are deprecated. All use cases except for exit nodes have moved to the 'Networks' feature. Use 'Networks' for all new configurations.

    Key Constraints:

    • Requires NetBird v0.9.0 or later.
    • By default, Routes bypass Access Control rules unless explicitly configured.
    • A network route grants access to the network behind the routing peer, not the routing peer machine itself.

  6. Overview of NetBird and Huntress EDR integration

    NetBird integrates with Huntress to ensure only devices meeting specific security standards can access the protected network. Devices that fail to meet the configured Huntress security requirements (such as Defender Policy Status, Managed Microsoft Defender, or Firewall state) will automatically lose network access. Access is restored once the device meets all compliance criteria. NetBird matches the Huntress agent to the peer using the device's unique Serial Number.

  7. Overview of NetBird Google Workspace Integration

    NetBird integrates with Google Workspace to synchronize users and groups, allowing administrators to use these groups for network configuration and access policies. The integration uses Google Workspace as the Identity Provider (IdP) for SSO and Google Cloud Platform (GCP) to host a service account that accesses Workspace data via the Admin SDK API using OAuth 2.0.

  8. Overview of NetBird Remote Access Scenarios

    NetBird provides four primary scenarios for connecting devices and networks across locations. Most scenarios utilize a 'Routing Peer' (a device running the NetBird client) to forward traffic to 'Clientless Devices' (devices without NetBird installed, such as printers or IoT devices).

  9. Overview of NetBird Reverse Proxy authentication methods

    NetBird Reverse Proxy provides two primary authentication families for HTTP (Layer 7) services. For L4 services (TCP, UDP, TLS), authentication methods are unavailable, and access must be controlled via access restrictions (IP CIDR/Country).

    1. Operator auth: Designed for public services. It allows gating internal apps with credentials of your choosing. Multiple methods can be enabled simultaneously (SSO, password, PIN, and header authentication), and users can choose which one to use.
    2. NetBird-Only Access: Designed for private services. It restricts access to peers within the NetBird network. This method is mutually exclusive with Operator auth; when enabled, the trust boundary is the WireGuard tunnel rather than a credential.

  10. Overview of NetBird Draft Mode

    Draft Mode provides a local working copy of the Control Center canvas, allowing users to sketch network changes, review the resulting API requests, and apply them as a single batch. This prevents immediate production impact when making complex changes (e.g., onboarding a new server with associated groups and policies).

    Key Workflow:

    1. Build: Create and modify components on the canvas.
    2. Review: Inspect the list of changes.
    3. Deploy: Apply all changes simultaneously via 'Approve & Deploy'.

    Availability: Beta; available on NetBird Cloud (all plans) and self-hosted instances.

    Important Constraints:

    • Drafts exist only in the browser tab. Reloading or closing the page discards the draft.
    • Deploying a draft requires the same permissions as making the changes manually on the dashboard.

  11. Overview of NetBird Agent Network

    NetBird Agent Network is an access control layer for AI agents and their operators. It assigns a real identity to every agent (tied to an Identity Provider/IdP) and governs access to LLM APIs, AI gateways, and internal resources. All traffic flows through an encrypted NetBird tunnel scoped by policy, eliminating the need for shared API keys or broad network paths.

  12. Overview of the NetBird Distributor Portal

    The NetBird Distributor Portal allows distributors to create and manage customer accounts from a single dashboard, assign NetBird plans, and consolidate billing under one invoice. Every customer created via the portal is provisioned as a NetBird MSP account, enabling them to onboard their own tenants.

    Hierarchy: Distributor account → Customer account (MSP-enabled) → Tenants (end customers).