# Table of Contents - [Introduction to NetBird - NetBird Docs](#introduction-to-netbird-netbird-docs) - [iOS - NetBird Docs](#ios-netbird-docs) - [Windows Installation - NetBird Docs](#windows-installation-netbird-docs) - [Linux Installation - NetBird Docs](#linux-installation-netbird-docs) - [MacOS Installation - NetBird Docs](#macos-installation-netbird-docs) - [Docker Installation - NetBird Docs](#docker-installation-netbird-docs) - [Install NetBird on an Android - NetBird Docs](#install-netbird-on-an-android-netbird-docs) - [Report bugs and issues - NetBird Docs](#report-bugs-and-issues-netbird-docs) - [tvOS (Apple TV) - NetBird Docs](#tvos-apple-tv-netbird-docs) - [Troubleshooting - NetBird Docs](#troubleshooting-netbird-docs) - [Install NetBird on an Android TV - NetBird Docs](#install-netbird-on-an-android-tv-netbird-docs) - [Switching Between NetBird Accounts with Profiles - NetBird Docs](#switching-between-netbird-accounts-with-profiles-netbird-docs) - [Getting Started - NetBird Docs](#getting-started-netbird-docs) - [Visualize Remote Access with Control Center - NetBird Docs](#visualize-remote-access-with-control-center-netbird-docs) - [Troubleshooting client issues - NetBird Docs](#troubleshooting-client-issues-netbird-docs) - [NetBird Agent command line interface (CLI) - NetBird Docs](#netbird-agent-command-line-interface-cli-netbird-docs) - [Install NetBird - NetBird Docs](#install-netbird-netbird-docs) - [Use Cases - NetBird Docs](#use-cases-netbird-docs) - [Self-Hosting Quickstart Guide (5 min) - NetBird Docs](#self-hosting-quickstart-guide-5-min-netbird-docs) - [Advanced guide - NetBird Docs](#advanced-guide-netbird-docs) - [NetBird REST API - NetBird API](#netbird-rest-api-netbird-api) - [NetBird vs. Traditional VPN - NetBird Docs](#netbird-vs-traditional-vpn-netbird-docs) - [Self-hosted vs. Cloud-hosted NetBird - NetBird Docs](#self-hosted-vs-cloud-hosted-netbird-netbird-docs) - [Why Wireguard with NetBird? - NetBird Docs](#why-wireguard-with-netbird-netbird-docs) - [Understanding NAT and Connectivity - NetBird Docs](#understanding-nat-and-connectivity-netbird-docs) - [FAQ - NetBird Docs](#faq-netbird-docs) - [How NetBird Works - NetBird Docs](#how-netbird-works-netbird-docs) - [Browser Client Technical Architecture - NetBird Docs](#browser-client-technical-architecture-netbird-docs) - [Configuring Exit Nodes for Internet Traffic - NetBird Docs](#configuring-exit-nodes-for-internet-traffic-netbird-docs) - [Add users to your network - NetBird Docs](#add-users-to-your-network-netbird-docs) - [Managing Access with NetBird: Groups and Access Policies - NetBird Docs](#managing-access-with-netbird-groups-and-access-policies-netbird-docs) - [Network Routes - NetBird Docs](#network-routes-netbird-docs) - [Install NetBird on the Raspberry Pi - NetBird Docs](#install-netbird-on-the-raspberry-pi-netbird-docs) - [Synology Installation - NetBird Docs](#synology-installation-netbird-docs) - [Traffic Events Logging - NetBird Docs](#traffic-events-logging-netbird-docs) - [Post-quantum cryptography - NetBird Docs](#post-quantum-cryptography-netbird-docs) - [Use setup keys to run automated deployments and add machines to your network at scale - NetBird Docs](#use-setup-keys-to-run-automated-deployments-and-add-machines-to-your-network-at-scale-netbird-docs) - [pfSense Installation - NetBird Docs](#pfsense-installation-netbird-docs) - [Install NetBird on Proxmox VE - NetBird Docs](#install-netbird-on-proxmox-ve-netbird-docs) - [Migration Guide: From Coturn to Embedded STUN Server - NetBird Docs](#migration-guide-from-coturn-to-embedded-stun-server-netbird-docs) - [Back Up Your Self-Hosted NetBird Installation - NetBird Docs](#back-up-your-self-hosted-netbird-installation-netbird-docs) - [Upgrade Your Self-Hosted NetBird Installation - NetBird Docs](#upgrade-your-self-hosted-netbird-installation-netbird-docs) - [Block Inbound Connections - NetBird Docs](#block-inbound-connections-netbird-docs) - [Deploying NetBird with Acronis Cyber Protect Cloud - NetBird Docs](#deploying-netbird-with-acronis-cyber-protect-cloud-netbird-docs) - [OPNsense Installation - NetBird Docs](#opnsense-installation-netbird-docs) - [Authentik with NetBird Self-Hosted - NetBird Docs](#authentik-with-netbird-self-hosted-netbird-docs) - [PocketID with NetBird Self-Hosted - NetBird Docs](#pocketid-with-netbird-self-hosted-netbird-docs) - [Add peers to your NetBird network - NetBird Docs](#add-peers-to-your-netbird-network-netbird-docs) - [Migration Guide: Combined Container Setup - NetBird Docs](#migration-guide-combined-container-setup-netbird-docs) - [Microsoft and Entra ID SSO with NetBird Self-Hosted - NetBird Docs](#microsoft-and-entra-id-sso-with-netbird-self-hosted-netbird-docs) - [Install NetBird on TrueNAS - NetBird Docs](#install-netbird-on-truenas-netbird-docs) - [Migration Guide: Enable Reverse Proxy Feature - NetBird Docs](#migration-guide-enable-reverse-proxy-feature-netbird-docs) - [SSH Access - NetBird Docs](#ssh-access-netbird-docs) - [Auth0 SSO with NetBird Self-Hosted - NetBird Docs](#auth0-sso-with-netbird-self-hosted-netbird-docs) - [NetBird MSP Portal for Managed Service Providers - NetBird Docs](#netbird-msp-portal-for-managed-service-providers-netbird-docs) - [JumpCloud SSO with NetBird Self-Hosted - NetBird Docs](#jumpcloud-sso-with-netbird-self-hosted-netbird-docs) - [Homelab Use Cases - NetBird Docs](#homelab-use-cases-netbird-docs) - [Google Workspace SSO with NetBird Self-Hosted - NetBird Docs](#google-workspace-sso-with-netbird-self-hosted-netbird-docs) - [Okta SSO with NetBird Self-Hosted - NetBird Docs](#okta-sso-with-netbird-self-hosted-netbird-docs) - [Zitadel with NetBird Self-Hosted - NetBird Docs](#zitadel-with-netbird-self-hosted-netbird-docs) - [Understanding NetBird Posture Checks - NetBird Docs](#understanding-netbird-posture-checks-netbird-docs) - [Keycloak with NetBird Self-Hosted - NetBird Docs](#keycloak-with-netbird-self-hosted-netbird-docs) - [DNS in NetBird - NetBird Docs](#dns-in-netbird-netbird-docs) - [Implementing Zero Trust with NetBird - NetBird Docs](#implementing-zero-trust-with-netbird-netbird-docs) - [Splitting Your Self-Hosted Deployment - NetBird Docs](#splitting-your-self-hosted-deployment-netbird-docs) - [Local User Management - NetBird Docs](#local-user-management-netbird-docs) - [Remote Jobs - NetBird Docs](#remote-jobs-netbird-docs) - [Site-to-Site Connectivity - NetBird Docs](#site-to-site-connectivity-netbird-docs) - [Access Home Devices (VPN-to-Site) - NetBird Docs](#access-home-devices-vpn-to-site-netbird-docs) - [Expose from CLI - NetBird Docs](#expose-from-cli-netbird-docs) - [Self-Hosted Deployment Configuration Files Reference - NetBird Docs](#self-hosted-deployment-configuration-files-reference-netbird-docs) - [Authentication and Identity Providers (IdPs) - NetBird Docs](#authentication-and-identity-providers-idps-netbird-docs) - [External Reverse Proxy Setup for Self-Hosted NetBird - NetBird Docs](#external-reverse-proxy-setup-for-self-hosted-netbird-netbird-docs) - [Networks - NetBird Docs](#networks-netbird-docs) - [Cloud Use Cases - NetBird Docs](#cloud-use-cases-netbird-docs) - [Security Use Cases - NetBird Docs](#security-use-cases-netbird-docs) - [Provision Users and Groups From Your Identity Provider - NetBird Docs](#provision-users-and-groups-from-your-identity-provider-netbird-docs) - [Quickstart - NetBird API](#quickstart-netbird-api) - [Authentication - NetBird API](#authentication-netbird-api) - [Errors - NetBird API](#errors-netbird-api) - [Unknown](#unknown) - [Tokens - NetBird API](#tokens-netbird-api) - [Accounts - NetBird API](#accounts-netbird-api) - [Peers - NetBird API](#peers-netbird-api) - [Geo Locations - NetBird API](#geo-locations-netbird-api) - [Setup Keys - NetBird API](#setup-keys-netbird-api) - [Groups - NetBird API](#groups-netbird-api) - [Routes - NetBird API](#routes-netbird-api) - [Policies - NetBird API](#policies-netbird-api) - [DNS - NetBird API](#dns-netbird-api) - [Jobs - NetBird API](#jobs-netbird-api) - [Users - NetBird API](#users-netbird-api) - [Posture Checks - NetBird API](#posture-checks-netbird-api) - [Identity Providers - NetBird API](#identity-providers-netbird-api) - [Events - NetBird API](#events-netbird-api) - [Event Streaming Integrations - NetBird API](#event-streaming-integrations-netbird-api) - [EDR Peers - NetBird API](#edr-peers-netbird-api) - [Instance - NetBird API](#instance-netbird-api) - [DNS Zones - NetBird API](#dns-zones-netbird-api) - [Usage - NetBird API](#usage-netbird-api) - [Invoice - NetBird API](#invoice-netbird-api) - [Networks - NetBird API](#networks-netbird-api) - [IDP - NetBird API](#idp-netbird-api) - [EDR Intune Integrations - NetBird API](#edr-intune-integrations-netbird-api) - [EDR Falcon Integrations - NetBird API](#edr-falcon-integrations-netbird-api) - [EDR Huntress Integrations - NetBird API](#edr-huntress-integrations-netbird-api) - [MSP - NetBird API](#msp-netbird-api) - [Approve peers - NetBird Docs](#approve-peers-netbird-docs) - [Ingress Ports - NetBird API](#ingress-ports-netbird-api) - [EDR SentinelOne Integrations - NetBird API](#edr-sentinelone-integrations-netbird-api) - [Integrate NetBird with MDM & EDR Platforms - NetBird Docs](#integrate-netbird-with-mdm-edr-platforms-netbird-docs) - [Services - NetBird API](#services-netbird-api) - [Stream Network Activity to Third-Party SIEM Platforms - NetBird Docs](#stream-network-activity-to-third-party-siem-platforms-netbird-docs) - [Site-to-Site: Cloud Environments - NetBird Docs](#site-to-site-cloud-environments-netbird-docs) - [Configuring Routes with Access Control - NetBird Docs](#configuring-routes-with-access-control-netbird-docs) - [Approve users - NetBird Docs](#approve-users-netbird-docs) - [Reverse Proxy - NetBird Docs](#reverse-proxy-netbird-docs) - [Delete your NetBird account - NetBird Docs](#delete-your-netbird-account-netbird-docs) - [DNS Troubleshooting - NetBird Docs](#dns-troubleshooting-netbird-docs) - [Understanding Groups and Access Policies - NetBird Docs](#understanding-groups-and-access-policies-netbird-docs) - [Network Routes Use Cases - NetBird Docs](#network-routes-use-cases-netbird-docs) - [Resolving Overlapping Routes - NetBird Docs](#resolving-overlapping-routes-netbird-docs) - [Accessing entire domains within networks - NetBird Docs](#accessing-entire-domains-within-networks-netbird-docs) - [DNS Settings - NetBird Docs](#dns-settings-netbird-docs) - [Audit Events Logging - NetBird Docs](#audit-events-logging-netbird-docs) - [Browser Client - Web-based Remote Access - NetBird Docs](#browser-client-web-based-remote-access-netbird-docs) - [Internal DNS Servers - NetBird Docs](#internal-dns-servers-netbird-docs) - [Reverse Proxy Authentication - NetBird Docs](#reverse-proxy-authentication-netbird-docs) - [Provision Users and Groups From JumpCloud - NetBird Docs](#provision-users-and-groups-from-jumpcloud-netbird-docs) - [Backend Service Configuration - NetBird Docs](#backend-service-configuration-netbird-docs) - [Open Source Distributed AI Stack: ArgoCD, MicroK8s, vLLM, and NetBird - NetBird Docs](#open-source-distributed-ai-stack-argocd-microk8s-vllm-and-netbird-netbird-docs) - [Deploy routing peers to a Kubernetes cluster - NetBird Docs](#deploy-routing-peers-to-a-kubernetes-cluster-netbird-docs) - [Provision Users and Groups From Keycloak - NetBird Docs](#provision-users-and-groups-from-keycloak-netbird-docs) - [Provision Users and Groups From Google Workspace - NetBird Docs](#provision-users-and-groups-from-google-workspace-netbird-docs) - [Lazy Connections - NetBird Docs](#lazy-connections-netbird-docs) - [Networks Use Cases - NetBird Docs](#networks-use-cases-netbird-docs) - [Advanced Configuration - NetBird Docs](#advanced-configuration-netbird-docs) - [Connecting from the office - NetBird Docs](#connecting-from-the-office-netbird-docs) - [Running NetBird on serverless environments (FaaS) - NetBird Docs](#running-netbird-on-serverless-environments-faas-netbird-docs) - [Duo SSO with NetBird Self-Hosted - NetBird Docs](#duo-sso-with-netbird-self-hosted-netbird-docs) - [Reverse Proxy Access Logs - NetBird Docs](#reverse-proxy-access-logs-netbird-docs) - [Remove Your Self-Hosted NetBird Installation - NetBird Docs](#remove-your-self-hosted-netbird-installation-netbird-docs) - [Management SQLite store - NetBird Docs](#management-sqlite-store-netbird-docs) - [Set Up External Signal Server - NetBird Docs](#set-up-external-signal-server-netbird-docs) - [PocketID SSO with NetBird Self-Hosted (Advanced) - NetBird Docs](#pocketid-sso-with-netbird-self-hosted-advanced-netbird-docs) - [Set Up External Relay Servers - NetBird Docs](#set-up-external-relay-servers-netbird-docs) - [Disable Local Authentication - NetBird Docs](#disable-local-authentication-netbird-docs) - [Accessing restricted domain resources - NetBird Docs](#accessing-restricted-domain-resources-netbird-docs) - [Authentik SSO with NetBird Self-Hosted (Advanced) - NetBird Docs](#authentik-sso-with-netbird-self-hosted-advanced-netbird-docs) - [Management Geolocation - NetBird Docs](#management-geolocation-netbird-docs) - [Multi-Factor Authentication (MFA) - NetBird Docs](#multi-factor-authentication-mfa-netbird-docs) - [Secure Remote Web Server Access: SSH Without Port Exposure - NetBird Docs](#secure-remote-web-server-access-ssh-without-port-exposure-netbird-docs) - [Custom Zones - NetBird Docs](#custom-zones-netbird-docs) - [Microsoft and Entra ID SSO with NetBird Self-Hosted (Legacy) - NetBird Docs](#microsoft-and-entra-id-sso-with-netbird-self-hosted-legacy-netbird-docs) - [Okta SSO with NetBird Self-Hosted (Legacy) - NetBird Docs](#okta-sso-with-netbird-self-hosted-legacy-netbird-docs) - [Restrict Network Access with Huntress EDR - NetBird Docs](#restrict-network-access-with-huntress-edr-netbird-docs) - [JumpCloud SSO with NetBird Self-Hosted (Legacy) - NetBird Docs](#jumpcloud-sso-with-netbird-self-hosted-legacy-netbird-docs) - [Generic OIDC Provider with NetBird Self-Hosted - NetBird Docs](#generic-oidc-provider-with-netbird-self-hosted-netbird-docs) --- # Introduction to NetBird - NetBird Docs Introduction to NetBird ======================= NetBird is an Open Source Zero Trust Networking platform that allows you to create secure private networks for your organization or home. We designed NetBird to be simple and fast, requiring near-zero configuration effort and leaving behind the hassle of opening ports, complex firewall rules, VPN gateways, etc. NetBird is an **[open-source](https://github.com/netbirdio/netbird) ** project and can be self-hosted. See a comparison between the self-hosted and cloud-hosted versions [here](https://docs.netbird.io/about-netbird/self-hosted-vs-cloud) . There is no centralized VPN server with NetBird - your computers, devices, machines, and servers connect to each other directly over a fast encrypted tunnel. It creates a high-performance point-to-point [WireGuard®](https://www.wireguard.com/) overlay network that connects machines running anywhere in just a few clicks. It literally takes less than 5 minutes to deploy a secure point-to-point VPN with NetBird. [Try NetBird Cloud](https://app.netbird.io/install) [Deploy NetBird Self-Hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) [Guides](https://docs.netbird.io/introduction#guides) ------------------------------------------------------ ### [Onboarding Guide](https://docs.netbird.io/get-started) Get started with NetBird in under 5 minutes. Learn the basics of installation and setup. ### [Self-Host NetBird](https://docs.netbird.io/selfhosted/selfhosted-quickstart) Get started with self-hosted NetBird in 5 minutes. Learn how to deploy and configure your own NetBird instance. ### [Manage Network Access](https://docs.netbird.io/manage/access-control/manage-network-access) Learn how to use access control policies to manage and secure access to your machines and resources. ### [Add Users to Your Network](https://docs.netbird.io/manage/team/add-users-to-your-network) Discover how to add team members to your NetBird network and manage user access. ### [Route Traffic to Private Networks](https://docs.netbird.io/manage/network-routes) Learn how to provide secure access to LANs, VPS instances, and corporate private networks. ### [Configure Default Routes](https://docs.netbird.io/manage/network-routes/use-cases/by-scenario/exit-nodes) Set up default routes for internet traffic and configure exit nodes for your network. ### [Log and Monitor Network Activity](https://docs.netbird.io/manage/activity/traffic-events-logging) Learn how to track and monitor system and network activities in your NetBird account. ### [Manage DNS in Your Network](https://docs.netbird.io/manage/dns) Configure custom name servers and DNS settings for your private network. [About NetBird](https://docs.netbird.io/introduction#about-netbird) -------------------------------------------------------------------- ### [How NetBird Works](https://docs.netbird.io/about-netbird/how-netbird-works) Learn about NetBird concepts, architecture, protocols, and how it creates secure networks. ### [NetBird vs. Traditional VPN](https://docs.netbird.io/about-netbird/netbird-vs-traditional-vpn) Discover how NetBird compares to traditional VPNs and understand the advantages of Zero Trust networking. ### [Why WireGuard with NetBird](https://docs.netbird.io/about-netbird/why-wireguard-with-netbird) Explore why NetBird uses WireGuard and how it provides fast, secure, and modern networking. ### [Browser Client Architecture](https://docs.netbird.io/about-netbird/browser-client-architecture) Understand how the Browser Client enables secure remote access directly from web browsers using WebAssembly. 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/introduction.mdx) --- # iOS - NetBird Docs iOS === NetBird has an official iOS application that you can download from the App Store: [![appstore](https://docs.netbird.io/docs-static/img/get-started/ios/app-store-badge.svg)](https://apps.apple.com/de/app/netbird-p2p-vpn/id6469329339?l=en-GB) 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/install/ios.mdx) --- # Windows Installation - NetBird Docs Windows Installation ==================== The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available. 1. Download the latest Windows release: * [EXE Installer](https://pkgs.netbird.io/windows/x64) * [MSI Installer](https://pkgs.netbird.io/windows/msi/x64) 2. Execute the installer and proceed with the installation steps 3. This will install the UI client in the `C:\Program Files\NetBird` and add the daemon service 4. After installing, you can follow the steps from [Running NetBird with SSO Login](https://docs.netbird.io/get-started/install/windows#running-net-bird-with-sso-login) . To uninstall the client and service, you can use Add/Remove programs [Running NetBird with SSO Login](https://docs.netbird.io/get-started/install/windows#running-net-bird-with-sso-login) ---------------------------------------------------------------------------------------------------------------------- ### [Desktop UI Application](https://docs.netbird.io/get-started/install/windows#desktop-ui-application) If you installed the Desktop UI client, you can launch it and click on Connect. > It will open your browser, and you will be prompt for email and password. Follow the instructions. ![high-level-dia](https://docs.netbird.io/docs-static/img/get-started/netbird-sso-login-ui.gif) ### [CLI](https://docs.netbird.io/get-started/install/windows#cli) Alternatively, you could use command line. Simply run netbird up CopyCopied! > It will open your browser, and you will be prompt for email and password. Follow the instructions. ![high-level-dia](https://docs.netbird.io/docs-static/img/get-started/netbird-sso-login-cmd.gif) Check connection status: netbird status CopyCopied! [Running NetBird with a Setup Key](https://docs.netbird.io/get-started/install/windows#running-net-bird-with-a-setup-key) -------------------------------------------------------------------------------------------------------------------------- In case you are activating a server peer, you can use a [setup key](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) as described in the steps below. > This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform. 1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) ). For all systems: netbird up --setup-key CopyCopied! Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service: netbird up --setup-key --management-url http://localhost:33073 CopyCopied! > You could also omit the `--setup-key` property. In this case, the tool will prompt for the key. 2. Check connection status: netbird status CopyCopied! 3. Check your IP: netsh interface ip show config name="wt0" CopyCopied! 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/install/windows.mdx) --- # Linux Installation - NetBird Docs Linux Installation ================== The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available. [Linux Install Script](https://docs.netbird.io/get-started/install/linux#linux-install-script) ----------------------------------------------------------------------------------------------- curl -fsSL https://pkgs.netbird.io/install.sh | sh CopyCopied! ### [Ubuntu/Debian (APT)](https://docs.netbird.io/get-started/install/linux#ubuntu-debian-apt) 1. Add the repository: sudo apt-get update sudo apt-get install ca-certificates curl gnupg -y curl -sSL https://pkgs.netbird.io/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/netbird-archive-keyring.gpg echo 'deb [signed-by=/usr/share/keyrings/netbird-archive-keyring.gpg] https://pkgs.netbird.io/debian stable main' | sudo tee /etc/apt/sources.list.d/netbird.list CopyCopied! 2. Update APT's cache sudo apt-get update CopyCopied! 3. Install the package # for CLI only sudo apt-get install netbird # for GUI package sudo apt-get install netbird-ui CopyCopied! ### [RHEL/Amazon Linux 2 (RPM)](https://docs.netbird.io/get-started/install/linux#rhel-amazon-linux-2-rpm) 1. Add the repository: sudo tee /etc/yum.repos.d/netbird.repo <.tar.gz https://github.com/netbirdio/netbird/releases/download/v/netbird___.tar.gz CopyCopied! You need to replace some variables from the URL above: * Replace **VERSION** with the latest released version. * Replace **OS** with "linux", "darwin" for MacOS or "windows" * Replace **Arch** with your target system CPU architecture 3. Decompress tar xzf ./netbird_.tar.gz sudo mv netbird /usr/bin/netbird sudo chown root:root /usr/bin/netbird sudo chmod +x /usr/bin/netbird CopyCopied! After that you may need to add /usr/bin in your PATH environment variable: export PATH=$PATH:/usr/bin CopyCopied! 4. Install and run the service sudo netbird service install sudo netbird service start CopyCopied! [Updating](https://docs.netbird.io/get-started/install/linux#updating) ----------------------------------------------------------------------- If your NetBird client was installed through a package manager, use that to update. If you used the one-command script to install, you can follow this to update: netbird down curl -fsSLO https://pkgs.netbird.io/install.sh chmod +x install.sh ./install.sh --update netbird up CopyCopied! [Running NetBird with SSO Login](https://docs.netbird.io/get-started/install/linux#running-net-bird-with-sso-login) -------------------------------------------------------------------------------------------------------------------- ### [Desktop UI Application](https://docs.netbird.io/get-started/install/linux#desktop-ui-application) If you installed the Desktop UI client, you can launch it and click on Connect. > It will open your browser, and you will be prompt for email and password. Follow the instructions. ![high-level-dia](https://docs.netbird.io/docs-static/img/get-started/netbird-sso-login-ui.gif) ### [CLI](https://docs.netbird.io/get-started/install/linux#cli) Alternatively, you could use command line. Simply run netbird up CopyCopied! > It will open your browser, and you will be prompt for email and password. Follow the instructions. ![high-level-dia](https://docs.netbird.io/docs-static/img/get-started/netbird-sso-login-cmd.gif) Check connection status: netbird status CopyCopied! [Running NetBird with a Setup Key](https://docs.netbird.io/get-started/install/linux#running-net-bird-with-a-setup-key) ------------------------------------------------------------------------------------------------------------------------ In case you are activating a server peer, you can use a [setup key](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) as described in the steps below. > This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform. 1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) ). netbird up --setup-key CopyCopied! Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service: netbird up --setup-key --management-url http://localhost:33073 CopyCopied! > You could also omit the `--setup-key` property. In this case, the tool will prompt for the key. 2. Check connection status: netbird status CopyCopied! 3. Check your IP: ip addr show wt0 CopyCopied! 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/install/linux.mdx) --- # MacOS Installation - NetBird Docs MacOS Installation ================== The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available. [Install with one command](https://docs.netbird.io/get-started/install/macos#install-with-one-command) ------------------------------------------------------------------------------------------------------- curl -fsSL https://pkgs.netbird.io/install.sh | sh CopyCopied! ### [Package install](https://docs.netbird.io/get-started/install/macos#package-install) 1. Download the latest MacOS release installer for your [processor](https://support.apple.com/en-us/HT211814) : * Intel: [Download NetBird for Intel](https://pkgs.netbird.io/macos/amd64) * M1 & M2: [Download NetBird for Apple Silicon](https://pkgs.netbird.io/macos/arm64) _If you require an older version checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest) _ 2. Proceed with the installation steps 3. This will install the NetBird app into /Applications and add the daemon service 4. After installing, you can follow the steps from [Running NetBird with SSO Login](https://docs.netbird.io/get-started/install/macos#Running-NetBird-with-SSO-Login) steps. > To uninstall the client remove the app from /Applications ### [Homebrew install](https://docs.netbird.io/get-started/install/macos#homebrew-install) 1. Download and install homebrew at [https://brew.sh/](https://brew.sh/) 2. If netbird was previously installed with homebrew, you will need to run: # Stop and uninstall daemon service: sudo netbird service stop sudo netbird service uninstall # unlink the app brew unlink netbird CopyCopied! > netbird will copy any existing configuration from the netbird's default configuration paths to the new NetBird's default location 3. Install the client # for CLI only brew install netbirdio/tap/netbird # for GUI package brew install --cask netbirdio/tap/netbird-ui CopyCopied! 4. If you installed CLI only, you need to install and start the client daemon service: sudo netbird service install sudo netbird service start CopyCopied! ### [Binary Install](https://docs.netbird.io/get-started/install/macos#binary-install) **Installation from binary (CLI only)** 1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest) 2. Download the latest release: curl -L -o ./netbird_.tar.gz https://github.com/netbirdio/netbird/releases/download/v/netbird___.tar.gz CopyCopied! You need to replace some variables from the URL above: * Replace **VERSION** with the latest released version. * Replace **OS** with "linux", "darwin" for MacOS or "windows" * Replace **Arch** with your target system CPU architecture 3. Decompress tar xzf ./netbird_.tar.gz sudo mv netbird /usr/bin/netbird sudo chown root:root /usr/bin/netbird sudo chmod +x /usr/bin/netbird CopyCopied! After that you may need to add /usr/bin in your PATH environment variable: export PATH=$PATH:/usr/bin CopyCopied! 4. Install and run the service sudo netbird service install sudo netbird service start CopyCopied! [Running NetBird with SSO Login](https://docs.netbird.io/get-started/install/macos#running-net-bird-with-sso-login) -------------------------------------------------------------------------------------------------------------------- ### [Desktop UI Application](https://docs.netbird.io/get-started/install/macos#desktop-ui-application) If you installed the Desktop UI client, you can launch it and click on Connect. > It will open your browser, and you will be prompt for email and password. Follow the instructions. ![high-level-dia](https://docs.netbird.io/docs-static/img/get-started/netbird-sso-login-ui.gif) ### [CLI](https://docs.netbird.io/get-started/install/macos#cli) Alternatively, you could use command line. Simply run netbird up CopyCopied! > It will open your browser, and you will be prompt for email and password. Follow the instructions. ![high-level-dia](https://docs.netbird.io/docs-static/img/get-started/netbird-sso-login-cmd.gif) Check connection status: netbird status CopyCopied! ### [Running NetBird with a Setup Key](https://docs.netbird.io/get-started/install/macos#running-net-bird-with-a-setup-key) In case you are activating a server peer, you can use a [setup key](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) as described in the steps below. > This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform. 1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) ). netbird up --setup-key CopyCopied! Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service: netbird up --setup-key --management-url http://localhost:33073 CopyCopied! > You could also omit the `--setup-key` property. In this case, the tool will prompt for the key. 2. Check connection status: netbird status CopyCopied! 3. Check your IP: sudo ifconfig utun100 CopyCopied! 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/install/macos.mdx) --- # Docker Installation - NetBird Docs Docker Installation =================== The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available. [Docker Run Command](https://docs.netbird.io/get-started/install/docker#docker-run-command) -------------------------------------------------------------------------------------------- Set the `NB_SETUP_KEY` environment variable and run the command. You can pass other settings as environment variables. See [Environment variables](https://docs.netbird.io/get-started/cli#environment-variables) for details. NetBird makes use of eBPF and raw sockets, therefore to guarantee the client software functionality, we recommend adding the flags `--cap-add=SYS_ADMIN` and `--cap-add=SYS_RESOURCE` for docker clients. The experience may vary depending on the docker daemon, operating system, or kernel version. docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d -e NB_SETUP_KEY= -v netbird-client:/var/lib/netbird netbirdio/netbird:latest CopyCopied! See [Docker example](https://docs.netbird.io/use-cases/examples#net-bird-client-in-docker) for details. ### [Troubleshooting](https://docs.netbird.io/get-started/install/docker#troubleshooting) 1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL which is `https://api.netbird.io:443`. 2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting) to override it you can do the following: netbird down netbird up --management-url https:/// CopyCopied! To override it see the solution #1 above. [Docker Compose](https://docs.netbird.io/get-started/install/docker#docker-compose) ------------------------------------------------------------------------------------ If you prefer to run NetBird as a Docker compose stack below is an example. Configure to your specific needs. services: netbird-client: container_name: netbird-client hostname: cap_add: - NET_ADMIN - SYS_ADMIN - SYS_RESOURCE devices: # Required when using userspace mode or when kernel module is not available - /dev/net/tun network_mode: host environment: - NB_SETUP_KEY= volumes: - netbird-client:/var/lib/netbird image: netbirdio/netbird:latest volumes: netbird-client: name: netbird-client CopyCopied! [Running NetBird with a Setup Key](https://docs.netbird.io/get-started/install/docker#running-net-bird-with-a-setup-key) ------------------------------------------------------------------------------------------------------------------------- In case you are activating a server peer, you can use a [setup key](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) as described in the steps below. > This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform. 1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) ). docker run --network host --privileged --rm -d -e NB_SETUP_KEY= -v netbird-client:/var/lib/netbird netbirdio/netbird: CopyCopied! You could also omit the `--setup-key` property. In this case, the tool will prompt for the key. 2. Check connection status: netbird status CopyCopied! 3. Check your IP: sudo ifconfig utun100 CopyCopied! [Rootless Image](https://docs.netbird.io/get-started/install/docker#rootless-image) ------------------------------------------------------------------------------------ In some cases you may want to run our [rootless image](https://hub.docker.com/layers/netbirdio/netbird/rootless-latest) . Rootless mode operates within a user namespace, reducing the attack surface compared to standard rootful Docker. The rootless mode leverages netstack from the gVisor Go package, enabling the WireGuard stack to run entirely in userspace, circumventing the need for kernel-level access. docker run --rm --name PEER_NAME --hostname PEER_NAME -d \ -e NB_SETUP_KEY= \ -v netbird-client:/var/lib/netbird \ netbirdio/netbird:rootless-latest CopyCopied! `rootless` is well supported and works without any privileges. However, it will only be useful for inbound access or as routing peer (no outbound connections except via socks proxy) 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/install/docker.mdx) --- # Install NetBird on an Android - NetBird Docs Install NetBird on an Android ============================= The Android supports mobile devices, tablets and [Android TV](https://docs.netbird.io/get-started/install/android-tv) devices running Android 8.0 or later. [Where to Download](https://docs.netbird.io/get-started/install/android#where-to-download) ------------------------------------------------------------------------------------------- NetBird has an official Android application that you can download at Google Play Store: [![playstore](https://docs.netbird.io/docs-static/img/get-started/android/google-play-badge.png)](https://play.google.com/store/apps/details?id=io.netbird.client) APK releases are also available to install directly on your Android device via the [NetBird Android GitHub repository](https://github.com/netbirdio/android-client/releases) . [Configure Netbird on Android](https://docs.netbird.io/get-started/install/android#configure-netbird-on-android) ----------------------------------------------------------------------------------------------------------------- ### [First Launch](https://docs.netbird.io/get-started/install/android#first-launch) Upon first launch, NetBird will inform you that it's using the default managemet server. ![firstinstall](https://docs.netbird.io/docs-static/img/get-started/android/first-install-dialog.png) Select 'Continue' to ackownledge and you'll be greeted with the app's main screen. ![mainscreen](https://docs.netbird.io/docs-static/img/get-started/android/main-screen.png) ### [Management Server Configuration](https://docs.netbird.io/get-started/install/android#management-server-configuration) This step only applies to self-hosted users, or cloud users enrolling the device with a setup key. If you're a cloud user and are _not_ enrolling the device with a setup key, you can safely skip to [Connecting to Your Network](https://docs.netbird.io/get-started/install/android#connecting-to-your-network) Select the hamburger menu on the top left of the main screen and navigate to the 'Change Server' menu. ![changeserver](https://docs.netbird.io/docs-static/img/get-started/android/change-server-menu-item.png) Changing servers erases the device's current NetBird config, so you'll need to confirm the action before proceeding: ![confirmeraseconfig](https://docs.netbird.io/docs-static/img/get-started/android/confirm-erase-config.png) Enter your management server endpoint. For cloud users, this is `https://api.netbird.io:443`. For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to the `exposedAddress` field in your `config.yaml` (or `management.json` for older multi-container setups) if you're unsure. If enrolling the device with a setup key, select '+ Add this device with a setup key' and enter your setup key. Select 'change' to apply your new management server config, and if successful you'll see the following: ![serverchanged](https://docs.netbird.io/docs-static/img/get-started/android/server-changed.png) You're now ready to connect to your Netbird network! #### [Connecting to Your Network](https://docs.netbird.io/get-started/install/android#connecting-to-your-network) Select the NetBird logo button to connect. The app will request permission to create a VPN connection: ![vpnconnectionrequest](https://docs.netbird.io/docs-static/img/get-started/android/vpn-connection-request.png) Select 'OK'. If you didn't enter a setup key in the 'Change Server' menu, then you'll need to authenticate with your SSO provider. NetBird will open a browser window where you'll be instructed to sign in to your SSO provider. After logging in, NetBird will confirm your authentication. Once you close the browser window, your device should be connected! [What's next?](https://docs.netbird.io/get-started/install/android#whats-next) ------------------------------------------------------------------------------- * Configure the device's [group & policy](https://docs.netbird.io/get-started/install/example.com) memberships 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/install/android.mdx) --- # Report bugs and issues - NetBird Docs Report bugs and issues ====================== NetBird offers different ways to report bugs and issues. For prompt and effective assistance, please provide detailed information as outlined in our bug/issue [reporting template](https://docs.netbird.io/help/report-bug-issues#reporting-template) . For cloud users, you can report bugs and issues via email by sending an email to [support@netbird.io](mailto:support@netbird.io) , via [Github issues](https://github.com/netbirdio/netbird/issues/new/choose) or by joining our [Slack Channel](https://docs.netbird.io/slack-url) . For on-premise users, you can report bugs and issues via [Github issues](https://github.com/netbirdio/netbird/issues/new/choose) or by joining our [Slack Channel](https://docs.netbird.io/slack-url) . [Reporting Template](https://docs.netbird.io/help/report-bug-issues#reporting-template) ---------------------------------------------------------------------------------------- When reporting bugs and issues, please ensure you provide the following information: **Describe the problem** A clear and concise description of what the problem is. **To Reproduce** Steps to reproduce the behavior: 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' 4. See error **Have you performed any debugging steps?** Learn more at [troubleshooting guide](https://docs.netbird.io/help/troubleshooting-client) **Expected behavior** A clear and concise description of what you expected to happen. **Are you using NetBird Cloud?** Please specify whether you use NetBird Cloud or self-host NetBird's control plane. **NetBird version** `netbird version` **Is any other VPN software installed?** If yes, which one? **Debug output** To help us resolve the problem, please attach the following anonymized status output netbird status -d Create and upload a debug bundle, and share the returned file key: netbird debug for 1m -S -U _Uploaded files are automatically deleted after 30 days._ Alternatively, create the file only and attach it here manually: netbird debug for 1m -S **Screenshots** If applicable, add screenshots to help explain your problem. **Additional context** Add any other context about the problem here. 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/help/report-bug-issues.mdx) --- # tvOS (Apple TV) - NetBird Docs tvOS (Apple TV) =============== The tvOS app supports all Apple TV devices running tvOS 17.0 or later. It's available to download in the Apple TV app store. tvOS support is currently in beta. [Configure NetBird on tvOS](https://docs.netbird.io/get-started/install/tvos#configure-net-bird-on-tv-os) ---------------------------------------------------------------------------------------------------------- ### [First Launch](https://docs.netbird.io/get-started/install/tvos#first-launch) ![tvos-confirm-add-vpn-config](https://docs.netbird.io/docs-static/img/get-started/tvos/confirm-add-vpn-config.png) Upon first launch, NetBird will request permission to create a new VPN configuration. Select 'Allow' to continue. ### [Management Server Configuration](https://docs.netbird.io/get-started/install/tvos#management-server-configuration) This step only applies to self-hosted users, or cloud users enrolling the device with a setup key. If you're a cloud user and are _not_ enrolling the device with a setup key, you can safely skip to [Connecting & Authenticating](https://docs.netbird.io/get-started/install/tvos#connecting-and-authenticating) By default, the app is configured to connect to NetBird's cloud management server. If you're a self-hosted user, or you'd like to enroll the device with a setyo key, you'll need to change the management server settings. Navigate to **'Settings > Change Server'**, and the app will warn you that changing management server settings will erase your current config and disconnect if a connection is currently active: ![tvos-confirm-change-server](https://docs.netbird.io/docs-static/img/get-started/tvos/confirm-change-server.png) After confirming, you'll be presented with a dialog to enter your management server URL. Cloud users who want to enroll the device with a setup key should enter the URL For cloud users, this is `https://api.netbird.io:443`. For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to the `exposedAddress` field in your `config.yaml` (or `management.json` for older multi-container setups) if you're unsure. If enrolling the device with a setup key, select '+ Add this device with a setup key' and enter your setup key. Select 'Change' to apply your new management server config. NetBird will run a brief verification step on the details you've entered, after which you can move on to connecting. ### [Connecting & Authenticating](https://docs.netbird.io/get-started/install/tvos#connecting-and-authenticating) On the main 'Connection' screen, select the 'Connect' button to initiate a connection to your NetBird network. For self-hosted users _not_ enrolling the device with a setup key, Device Authentication needs to be enabled in the management server config. If you're not using a setup key, you'll be presented a QR code and device ID: ![tvos-authentication](https://docs.netbird.io/docs-static/img/get-started/tvos/authentication-screen.png) Scan the QR code with a mobile device and you'll be able to sign in to your SSO provider there. If asked to confirm your device code, confirm that the code underneath the QR code matches the one presented by your SSO provider. Once you've completed the SSO flow, after a few seconds the authentication dialog in the NetBird app will automatically dismiss itself. Select the 'Connect' button once more, and your device should now be connected! ![tvos-main-screen-connected](https://docs.netbird.io/docs-static/img/get-started/tvos/main-screen-connected.png) [What's next?](https://docs.netbird.io/get-started/install/tvos#whats-next) ---------------------------------------------------------------------------- * Manage your device's [access](https://docs.netbird.io/manage/access-control/manage-network-access) to the network * Use your device for [remote access access to your home network](https://docs.netbird.io/manage/networks/use-cases/by-scenario/access-home-devices) * Use your device as an [exit node](https://docs.netbird.io/manage/network-routes/use-cases/by-scenario/exit-nodes#make-the-peer-an-exit-node-routing-peer) 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/install/tvos.mdx) --- # Troubleshooting - NetBird Docs Troubleshooting =============== This page will help with various issues when self-hosting NetBird. [Embedded IdP Issues](https://docs.netbird.io/selfhosted/troubleshooting#embedded-id-p-issues) ----------------------------------------------------------------------------------------------- ### [Setup page not accessible](https://docs.netbird.io/selfhosted/troubleshooting#setup-page-not-accessible) **Problem**: You can't access the `/setup` page to create the first user. **Solutions**: * The `/setup` page is only available when no users exist. If you've already created a user, use the regular login page. * Check that the embedded IdP is enabled in your configuration. * Verify the Management service is running: `docker compose logs management` ### ["Setup already completed" error (HTTP 412)](https://docs.netbird.io/selfhosted/troubleshooting#setup-already-completed-error-http-412) **Problem**: The setup endpoint returns a 412 error. **Solution**: Setup has already been completed. The first user was already created. Use the regular login page to sign in. ### [Password not working after user creation](https://docs.netbird.io/selfhosted/troubleshooting#password-not-working-after-user-creation) **Problem**: You created a user but the password doesn't work. **Solutions**: * Passwords are shown only once during user creation. If you didn't save it, you'll need to delete and recreate the user. * Via API, you can create a new user with a new password. * For the owner account, you may need to reset the database if no other admins exist. ### [SSO connector not appearing on login page](https://docs.netbird.io/selfhosted/troubleshooting#sso-connector-not-appearing-on-login-page) **Problem**: You configured an identity provider but it doesn't show on the login page. **Solutions**: 1. Verify the connector was saved: Go to **Settings** → **Identity Providers** 2. Check that the redirect URL is correctly configured in your IdP 3. Review Management service logs for configuration errors: `docker compose logs management` 4. Ensure the IdP application has the correct redirect URI from NetBird ### ["Invalid redirect URI" error from IdP](https://docs.netbird.io/selfhosted/troubleshooting#invalid-redirect-uri-error-from-id-p) **Problem**: When clicking an SSO button, the IdP returns an invalid redirect URI error. **Solutions**: 1. Copy the exact redirect URL from NetBird (shown after saving the connector) 2. Add it to your IdP's allowed redirect URIs 3. Check for trailing slashes or typos 4. Some IdPs are case-sensitive ### [Identity Providers tab not visible](https://docs.netbird.io/selfhosted/troubleshooting#identity-providers-tab-not-visible) **Problem**: You don't see the Identity Providers tab in Settings. **Solution**: This tab is only visible when the embedded IdP is enabled. Check your deployment configuration: * For quickstart deployments, the embedded IdP should be enabled by default * For the combined setup, the embedded IdP is always enabled * For older multi-container deployments, ensure `EmbeddedIdP.Enabled` is set to `true` in `management.json` ### [Users not syncing from SSO provider](https://docs.netbird.io/selfhosted/troubleshooting#users-not-syncing-from-sso-provider) **Problem**: Users who authenticate via SSO don't appear in the user list. **Solutions**: * Users appear after their first successful login, not immediately after connector configuration * Check that the SSO flow completes successfully (user should land on Dashboard) * Review Management logs for any token validation errors [Debugging TURN connections](https://docs.netbird.io/selfhosted/troubleshooting#debugging-turn-connections) ------------------------------------------------------------------------------------------------------------ In the case that the peer-to-peer connection is not an option then the peer will use the TURN server for the secure connection establishment. If the connection is not possible even with TURN (Relay), then we need to confirm that your turn configuration is correct and that it is available. To test your TURN configuration you can access the [online tester](https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice) . There you will find a ICE servers input box, where you can select and remove the existing server, then add your turn server configuration as follows: Please replace **netbird.DOMAIN.com** and **PASSWORD** with your STUN/TURN server details from your configuration (**config.yaml** for the combined setup, or the **TURNConfig** section in **management.json** for older multi-container setups), then click on **Add server**. ![turn](https://docs.netbird.io/docs-static/img/selfhosted/troubleshooting/turn.png) You should see an output similar to the following: ![turn](https://docs.netbird.io/docs-static/img/selfhosted/troubleshooting/turn-test-out.png) Where you have the following types: `host` (local address), `srflx` (STUN reflexive address), `relay` (TURN relay address). If `srflx` and `relay` are not present then the TURN server is not working or not accessible and you should review the required ports in the [requirements section](https://docs.netbird.io/selfhosted/selfhosted-guide#requirements) . [Dashboard Issues](https://docs.netbird.io/selfhosted/troubleshooting#dashboard-issues) ---------------------------------------------------------------------------------------- ### [Dashboard shows blank page](https://docs.netbird.io/selfhosted/troubleshooting#dashboard-shows-blank-page) **Problem**: The Dashboard loads but shows a blank page or errors. **Solutions**: 1. Check browser console for JavaScript errors (F12 → Console) 2. Verify the Dashboard can reach the Management API 3. Check CORS configuration if running behind a custom reverse proxy 4. Clear browser cache and try again ### ["Unauthorized" or "403" errors](https://docs.netbird.io/selfhosted/troubleshooting#unauthorized-or-403-errors) **Problem**: API calls return unauthorized or forbidden errors. **Solutions**: 1. Verify your authentication token is valid 2. Check that the user has appropriate permissions 3. For API access, ensure you're using a valid Personal Access Token (PAT) 4. Review Management service logs for detailed error information [Certificate Issues](https://docs.netbird.io/selfhosted/troubleshooting#certificate-issues) -------------------------------------------------------------------------------------------- ### [Let's Encrypt certificate not renewing](https://docs.netbird.io/selfhosted/troubleshooting#lets-encrypt-certificate-not-renewing) **Problem**: SSL certificate expires and doesn't auto-renew. **Solutions**: 1. Ensure port 80 is accessible for ACME challenge 2. Check Caddy logs: `docker compose logs caddy` 3. Verify the domain points to the correct IP 4. Manually trigger renewal: `docker exec -it netbird-caddy caddy reload` ### [Certificate errors with custom reverse proxy](https://docs.netbird.io/selfhosted/troubleshooting#certificate-errors-with-custom-reverse-proxy) **Problem**: SSL errors when using your own reverse proxy. **Solutions**: 1. Ensure your reverse proxy terminates SSL correctly 2. Set `NETBIRD_DISABLE_LETSENCRYPT=true` in your configuration 3. Configure proper headers (X-Forwarded-For, X-Forwarded-Proto) 4. Verify HTTP/2 support is enabled for gRPC endpoints [Connection Issues](https://docs.netbird.io/selfhosted/troubleshooting#connection-issues) ------------------------------------------------------------------------------------------ ### [Peers can't connect to each other](https://docs.netbird.io/selfhosted/troubleshooting#peers-cant-connect-to-each-other) **Problem**: Peers are registered but can't establish connections. **Solutions**: 1. Check that UDP port 3478 is accessible (STUN/TURN) 2. Verify the TURN server is working (see [TURN debugging](https://docs.netbird.io/selfhosted/troubleshooting#debugging-turn-connections) ) 3. Check firewall rules on both peers 4. Review peer logs: `netbird status -d` ### [Management service unreachable](https://docs.netbird.io/selfhosted/troubleshooting#management-service-unreachable) **Problem**: Clients can't connect to the Management service. **Solutions**: 1. Verify port 443 is accessible 2. Check DNS resolution for your domain 3. Review Management logs: `docker compose logs management` 4. Test with curl: `curl -v https://your-domain.com/api/health` [Database Issues](https://docs.netbird.io/selfhosted/troubleshooting#database-issues) -------------------------------------------------------------------------------------- ### [Management service won't start after upgrade](https://docs.netbird.io/selfhosted/troubleshooting#management-service-wont-start-after-upgrade) **Problem**: After upgrading, the Management service fails to start. **Solutions**: 1. Check logs for migration errors: `docker compose logs management` 2. Ensure you followed the [upgrade path](https://docs.netbird.io/selfhosted/selfhosted-quickstart#upgrade) for your version 3. Restore from backup if needed 4. For major version jumps, you may need intermediate upgrades ### [Data corruption after power loss](https://docs.netbird.io/selfhosted/troubleshooting#data-corruption-after-power-loss) **Problem**: Services don't start properly after unexpected shutdown. **Solutions**: 1. Check for database lock files 2. Review all service logs 3. Consider restoring from backup 4. For SQLite databases, you may need to run integrity checks [Getting Help](https://docs.netbird.io/selfhosted/troubleshooting#getting-help) -------------------------------------------------------------------------------- If you're still experiencing issues: 1. **Check logs**: `docker compose logs` for all services 2. **Search existing issues**: [GitHub Issues](https://github.com/netbirdio/netbird/issues) 3. **Join our community**: [Slack Channel](https://docs.netbird.io/slack-url) 4. **Open an issue**: Include logs, configuration (without secrets), and steps to reproduce 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/selfhosted/troubleshooting.mdx) --- # Install NetBird on an Android TV - NetBird Docs Install NetBird on an Android TV ================================ The Android TV app supports devices running Android 8.0 or later. Android TV support is currently in beta. [Where to Download](https://docs.netbird.io/get-started/install/android-tv#where-to-download) ---------------------------------------------------------------------------------------------- NetBird has an official Android application that you can download at Google Play Store: [![playstore](https://docs.netbird.io/docs-static/img/get-started/android/google-play-badge.png)](https://play.google.com/store/apps/details?id=io.netbird.client) APK releases are also available to install directly on your Android device via the [NetBird Android GitHub repository](https://github.com/netbirdio/android-client/releases) . [Configure Netbird on Android TV](https://docs.netbird.io/get-started/install/android-tv#configure-netbird-on-android-tv) -------------------------------------------------------------------------------------------------------------------------- ### [First Launch](https://docs.netbird.io/get-started/install/android-tv#first-launch) Upon first launch, NetBird will inform you that it's using the default managemet server. ![firstinstall](https://docs.netbird.io/docs-static/img/get-started/android/first-install-dialog.png) Select 'Continue' to ackownledge and you'll be greeted with the app's main screen. ![android-tv-main-screen](https://docs.netbird.io/docs-static/img/get-started/android-tv/main-screen.png) ### [Management Server Configuration](https://docs.netbird.io/get-started/install/android-tv#management-server-configuration) This step only applies to self-hosted users, or cloud users enrolling the device with a setup key. If you're a cloud user and are _not_ enrolling the device with a setup key, you can safely skip to [Connecting to Your Network](https://docs.netbird.io/get-started/install/android-tv#connecting-to-your-network) Select the hamburger menu on the top left of the main screen (or hold the left directional button) and navigate to the 'Change Server' menu. ![android-tv-main-menu](https://docs.netbird.io/docs-static/img/get-started/android-tv/main-menu-change-server.png) Changing servers erases the device's current NetBird config, so you'll need to confirm the action before proceeding: ![confirm-erase-cponfig](https://docs.netbird.io/docs-static/img/get-started/android-tv/change-server.png) Enter your management server endpoint. For cloud users, this is `https://api.netbird.io:443`. For self-hosted users, it's usually `https://your_management_server_url:443`, but you can refer to the `exposedAddress` field in your `config.yaml` (or `management.json` for older multi-container setups) if you're unsure. If enrolling the device with a setup key, select '+ Add this device with a setup key' and enter your setup key. Select 'change' to apply your new management server config, and if successful you'll see the following: ![serverchanged](https://docs.netbird.io/docs-static/img/get-started/android/server-changed.png) You're now ready to connect to your Netbird network! #### [Connecting to Your Network](https://docs.netbird.io/get-started/install/android-tv#connecting-to-your-network) Select the NetBird logo button to connect. The app will request permission to create a VPN connection: ![vpnconnectionrequest](https://docs.netbird.io/docs-static/img/get-started/android/vpn-connection-request.png) Select 'OK'. If you didn't enter a setup key in the 'Change Server' menu, then you'll need to authenticate with your SSO provider. NetBird will open a browser window where you'll be instructed to sign in to your SSO provider. After logging in, NetBird will confirm your authentication. Once you close the browser window, your device should be connected! #### [Authenticating](https://docs.netbird.io/get-started/install/android-tv#authenticating) For self-hosted users _not_ enrolling the device with a setup key, Device Authentication needs to be enabled in the management server config. Since Android TV doesn't ship with a built-in browser, and entering credentials with a remote may be less than ideal, the TV client uses a slightly different authentication flow to the mobile app. If you're not using a setup key, then after you grant the app permission to create a VPN connection, you'll be presented a QR code and device ID: ![tvssoqr](https://docs.netbird.io/docs-static/img/get-started/android/tv-sso-qr-dialog.png) Scan the QR code with your phone and you'll be able to sign in to your SSO provider there. If asked to confirm your device code, confirm that the code underneath the QR code matches the one presented by your SSO provider. Once you've completed the SSO flow, the QR code dialog in the NetBird app will automatically dismiss itself, and your device should now be connected! [What's next?](https://docs.netbird.io/get-started/install/android-tv#whats-next) ---------------------------------------------------------------------------------- * Manage your device's [access](https://docs.netbird.io/manage/access-control/manage-network-access) to the network * Use your device for [remote access access to your home network](https://docs.netbird.io/manage/networks/use-cases/by-scenario/access-home-devices) * Use your device as an [exit node](https://docs.netbird.io/manage/network-routes/use-cases/by-scenario/exit-nodes#make-the-peer-an-exit-node-routing-peer) 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/install/android-tv.mdx) --- # Switching Between NetBird Accounts with Profiles - NetBird Docs Switching Between NetBird Accounts with Profiles ================================================ NetBird supports multiple profiles on a single device, making it easy to switch between work, home, or other networks. Only one profile is active at a time, and switching takes just a click. This feature also allows you to switch between self-hosted and cloud-hosted NetBird accounts seamlessly without needing to juggle multiple config files. ![profiles](https://docs.netbird.io/docs-static/img/client/profiles/profiles.png) Watch a short demo GIF demonstrating how profile switching works [here](https://docs.netbird.io/docs-static/img/client/profiles/profiles.gif) . [NetBird Profiles GUI Quickstart](https://docs.netbird.io/client/profiles#net-bird-profiles-gui-quickstart) ------------------------------------------------------------------------------------------------------------ To get started with NetBird profiles: * Upgrade your client application to the latest NetBird version. * Run the GUI app You will see a `default` profile created automatically. Add more profiles by hovering over the default profile and clicking "Manage Profiles". After adding a new profile, select it to make it active. You can now change the NetBird settings, e.g., providing a self-hosted instance URL or allowing SSH. The new settings will be saved in the new profile. Click "Connect" to bring up the new profile. The consequent selection of your profiles from the menu will automatically trigger the NetBird client to connect to the network and authentication if needed. [Manage Profiles in the GUI](https://docs.netbird.io/client/profiles#manage-profiles-in-the-gui) ------------------------------------------------------------------------------------------------- * **Add** a new profile with a friendly name input. * **Delete** any inactive profile (trash icon). * **Active and default** profiles cannot be removed. ![profiles](https://docs.netbird.io/docs-static/img/client/profiles/manage-profiles.png) [What Is a Profile?](https://docs.netbird.io/client/profiles#what-is-a-profile) -------------------------------------------------------------------------------- A **profile** is your NetBird configuration bundle: WireGuard keys, login state, and network settings all in one file. Think of it as a separate "NetBird account" on your machine: * **Default profile** Created automatically on first run or after upgrade. * **Custom profiles** Any number of additional profiles you add yourself (e.g. `work`, `home`, `test`). Profiles live in your system or user config folders: | OS | Config path | | --- | --- | | Linux | `/var/lib/netbird/...` | | macOS | `/var/lib/netbird...` | | Windows | `%ProgramData%\Netbird\profiles\` | * * * [Why Use Profiles?](https://docs.netbird.io/client/profiles#why-use-profiles) ------------------------------------------------------------------------------ * **Seamless switching** between multiple NetBird networks/accounts * **No manual config files updates**: all configs are managed through the CLI or GUI * **Persistent state**: your last active profile reconnects on startup * **Safe defaults**: you cannot remove the active/default profile by accident * * * [Upgrading From an Older Version](https://docs.netbird.io/client/profiles#upgrading-from-an-older-version) ----------------------------------------------------------------------------------------------------------- If you're upgrading from NetBird below version `0.52.0` that did not support profiles, here's what happens: * During the first launch after the upgrade, your existing config `/etc/netbird/config.json` (or Windows equivalent) is automatically copied to a new profile named `default`. * The `default` profile is set as active, and you can start using it immediately. [Disabling Profiles Feature](https://docs.netbird.io/client/profiles#disabling-profiles-feature) ------------------------------------------------------------------------------------------------- In some environments, you may want to disable the profiles feature entirely. This can be useful for: * **Managed environments** where users should not be able to switch between different NetBird accounts * **Security policies** that require a single, fixed configuration * **Automated deployments** where profile switching could interfere with operations To disable the profiles feature, you can use the `--disable-profiles` flag when installing the service: sudo netbird service install --disable-profiles CopyCopied! Alternatively, you can set the `NB_DISABLE_PROFILES` environment variable: export NB_DISABLE_PROFILES=true sudo netbird service install CopyCopied! When profiles are disabled: * Users cannot create, switch, or remove profiles * The profile management UI is disabled * All profile-related CLI commands are disabled * The client operates with a single, fixed configuration * Profile switching is completely prevented You can also disable update settings functionality using the `--disable-update-settings` flag or `NB_DISABLE_UPDATE_SETTINGS` environment variable. This prevents users from modifying any configuration settings, providing an additional layer of control in managed environments. * * * [Profile CLI Commands](https://docs.netbird.io/client/profiles#profile-cli-commands) ------------------------------------------------------------------------------------- With the CLI, you can manage profiles easily. The main command is: netbird profile [name] CopyCopied! ### [Add a New Profile](https://docs.netbird.io/client/profiles#add-a-new-profile) To create a new profile, use the command: netbird profile add CopyCopied! For example, the command below creates a new profile named `work`: netbird profile add work CopyCopied! This command does the following in the background: * Creates a `work.json` file in your config folder. * Keeps the client disconnected until you run `netbird up` or `netbird login`. * Will throw an error if the profile with the same name already exists. ### [List Profiles](https://docs.netbird.io/client/profiles#list-profiles) The command below lists all available profiles along with their status: netbird profile list CopyCopied! For example, running this command might output: Found 3 profiles: ✓ work ✗ default ✗ home CopyCopied! * **✓** = active * **✗** = inactive ### [Select (Switch) a Profile](https://docs.netbird.io/client/profiles#select-switch-a-profile) To switch to a specific profile, use: netbird profile select CopyCopied! For example, to switch to the `home` profile: netbird profile select home CopyCopied! The successful command will output: Profile switched successfully to: home CopyCopied! If `home` hasn't been used before, you will need to run `netbird up` or `netbird login` to authenticate. If the profile does not exist, you'll see an error message: Error: profile home does not exist CopyCopied! ### [Remove a Profile](https://docs.netbird.io/client/profiles#remove-a-profile) To remove a profile, use: netbird profile remove CopyCopied! For example, to remove the `home` profile: netbird profile remove home CopyCopied! If successful, you'll see: Profile removed successfully: home CopyCopied! You can't remove an active profile. If the profile your are trying to remove is active, you'll see an error: Cannot remove active profile: home CopyCopied! If the profile does not exist, you'll see an error message: Error: profile home does not exist CopyCopied! The command does the following in the background: * Removes `home.json` and `home.state.json` files from your config folder. * * * ### [Using `--profile` Flags](https://docs.netbird.io/client/profiles#using-profile-flags) You can use the `--profile` flag with any NetBird CLI command to specify which profile to use for that command. This is useful for running commands in a specific context without switching profiles manually. netbird up --profile work netbird login --profile home CopyCopied! NetBird switches to the named profile then runs the command under the hood. If the profile is new and hasn't been used yet, you'll be prompted to authenticate. 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/client/profiles.mdx) --- # Getting Started - NetBird Docs Getting Started =============== [Quickstart Guide](https://docs.netbird.io/get-started#quickstart-guide) ------------------------------------------------------------------------- Welcome to NetBird! This guide will walk you through our new onboarding process to create your account, connect your first devices, and build a secure peer-to-peer overlay network in less than ten minutes. [Create Your Account](https://docs.netbird.io/get-started#create-your-account) ------------------------------------------------------------------------------- First, let's create your NetBird account. ![NetBird IdP SSO and MFA](https://docs.netbird.io/docs-static/img/get-started/onboarding/01_netbird-sso.jpeg) 1. Navigate to [netbird.io](https://netbird.io/) and click Get Started in the top-right corner. Or simply click [here](https://app.netbird.io/) . 2. You’ll be redirected to the sign-in page, where NetBird uses your identity provider (IdP) for secure authentication. It supports any OIDC-compliant provider, including social logins like Gmail and GitHub for personal use. 3. Follow the authentication steps for your chosen provider. If you have multi-factor authentication (MFA) enabled on your IdP account, it will work automatically. Upon your first login, you'll be greeted by a short onboarding survey. This helps us tailor your experience. [Peer-to-Peer Network](https://docs.netbird.io/get-started#peer-to-peer-network) --------------------------------------------------------------------------------- One way of using NetBird is to create a peer-to-peer network, where you run the NetBird client on your devices to connect them directly. ![Onboarding Method Selection](https://docs.netbird.io/docs-static/img/get-started/onboarding/02_p2p-network.jpeg) The onboarding process will now guide you to connect your first device, also known as a peer. For this guide, we'll select Peer-to-Peer Network. If you’re selecting the Remote Network Access option, you can see that process [here](https://docs.netbird.io/get-started#remote-network-access) . ### [Install Your First Peer](https://docs.netbird.io/get-started#install-your-first-peer) ![Download NetBird](https://docs.netbird.io/docs-static/img/get-started/onboarding/03_download-netbird.jpeg) 1. On the "Let's get your first device online" screen, click the Install NetBird button. 2. An [installation modal](https://app.netbird.io/install) will appear. Select your operating system (e.g., macOS, Windows, Linux). For this example, we're installing it on a macOS machine. 3. Download the installer and run it. Follow the on-screen prompts to complete the installation. ### [Connect Your First Peer](https://docs.netbird.io/get-started#connect-your-first-peer) With the client installed, you now need to connect it to your network. ![Connect NetBird Client](https://docs.netbird.io/docs-static/img/get-started/onboarding/04_connect-client.jpeg) 1. After installation, find the NetBird icon in your system tray or menu bar. 2. Click the icon and select **Connect**. 3. This will open a new browser tab, prompting you to authorize the new device. Authenticate using the same IdP you used to sign up. 4. Once authorized, you will see a "Login successful" message. The onboarding UI will update to show that your first peer is connected, displaying its name and assigned NetBird IP address. ### [Add a Second Peer (Headless Linux Server)](https://docs.netbird.io/get-started#add-a-second-peer-headless-linux-server) Next, let's add a second, headless peer, like a Linux server or a Raspberry Pi. For devices without a graphical interface, we use a [Setup Key](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) . ![Install NetBird Headless](https://docs.netbird.io/docs-static/img/get-started/onboarding/05_headless-installed.jpeg) 1. In the web UI, the onboarding flow will now prompt you to "bring in your second device." Click the link that says Install with a setup key. 2. A pop-up will explain that a one-off setup key will be created, which you can also learn more about here. Click Continue.. 3. The onboarding UI will now provide two commands to run on your Linux server: * **Install NetBird**: A curl command to download and run the installation script. * **Run NetBird**: A [netbird up command](https://docs.netbird.io/get-started/cli) that includes your unique setup key. 4. SSH into your Linux server and run the commands: First, copy the curl command, paste it into your server's terminal, and press **Enter**. You may be prompted for your sudo password. curl -fsSL https://pkgs.netbird.io/install.sh | sh CopyCopied! Next, copy the netbird up --setup-key ... command and paste it into the terminal. netbird up --setup-key CopyCopied! After running the second command, the terminal will confirm Connected. Your headless device is now part of your NetBird network. ![Headless install connected](https://docs.netbird.io/docs-static/img/get-started/onboarding/06_headless-install-connected.jpeg) ### [Verify the Connection](https://docs.netbird.io/get-started#verify-the-connection) The onboarding UI will now display both of your connected peers. The onboarding wizard provides a simple way to test that they can communicate directly. ![Testing ping on NetBird](https://docs.netbird.io/docs-static/img/get-started/onboarding/07_ping-test.jpeg) 1. Copy the provided ping command from the onboarding UI. This command uses the NetBird IP address of your second peer (the Ubuntu server). 2. Open a terminal on your first peer and paste the command. Replace the example below with the NetBird IP for your machine. ping 100.74.76.17 CopyCopied! 3. You should see successful ping replies, confirming that the two devices are connected over the NetBird network. Click It works! - Continue in the onboarding UI. ### [Understanding Access Control](https://docs.netbird.io/get-started#understanding-access-control) The final onboarding step introduces NetBird's powerful Access Control policies. ![NetBird policy disabled](https://docs.netbird.io/docs-static/img/get-started/onboarding/08_policy-disabled-example.jpeg) 1. By default, a policy is active that allows connections between all your devices. This is why the ping command in the previous step worked. 2. The wizard demonstrates this by allowing you to toggle the policy. If you disable the "Default Policy," the ping between your devices will immediately fail with a "Request timeout" error. 3. Re-enabling the policy instantly restores the connection. This gives you a basic understanding of how you can control traffic within your network. You can learn much more about policies [here](https://docs.netbird.io/manage/access-control/manage-network-access) . 4. Click Continue to finish. ![Policy Example](https://docs.netbird.io/docs-static/img/get-started/onboarding/09_policy-example.jpeg) In the policy example above, we allowed _IT Admins_ port specific access to peers under the _AWS Servers_ group. Policies are a key building block to access in NetBird. You can learn more about the power of policies [here](https://docs.netbird.io/manage/access-control/manage-network-access) . If you manage users and groups with your identity provider, you can provision and sync them with NetBird. Learn more [here](https://docs.netbird.io/manage/team/idp-sync) including the supported platforms. [Remote Network Access](https://docs.netbird.io/get-started#remote-network-access) ----------------------------------------------------------------------------------- The second way to use NetBird is for remote network access by running NetBird on a single machine within your private network. This machine acts as a routing peer, routing traffic to internal resources that don't have the NetBird client installed. The onboarding process will now guide you to build our first network resource. For this guide, we'll select Remote Network Access. ![NetBird Onboarding](https://docs.netbird.io/docs-static/img/get-started/onboarding/10_remote-access-onboarding.jpeg) ### [Define Your Network Resource](https://docs.netbird.io/get-started#define-your-network-resource) Next, you'll define the private network you want your users to be able to access. 1. The onboarding UI will prompt you to "Add your first resource." There are a few options here, but the easiest way to get started is with full access to an entire Network. Select the Entire Subnet option. 2. Enter the CIDR range of your private network. For example, `10.0.0.0/32`. 3. Click Create Resource. A "Network" will be created in your dashboard to contain this resource and its access rules. ![NetBird Subnet Setup](https://docs.netbird.io/docs-static/img/get-started/onboarding/11_entire-subnet.jpeg) ### [Add and Configure a Routing Peer](https://docs.netbird.io/get-started#add-and-configure-a-routing-peer) A [routing peer](https://docs.netbird.io/manage/network-routes) is a NetBird peer that lives inside your private network and acts as a gateway, forwarding traffic between your remote users and the internal resources. ![Adding a routing peer](https://docs.netbird.io/docs-static/img/get-started/onboarding/12_add-routing-peer.jpeg) 1. The dashboard will now prompt you to "Add a routing peer." First, click Generate Setup Key. This creates a one-time key used to enroll the gateway machine into your NetBird account. 2. Next, click Install Routing Peer. Select the operating system of your gateway machine (the video uses Linux). 3. The installation modal will provide two commands: a curl script to install the NetBird agent and a netbird up command that includes your setup key. 4. SSH into your gateway machine (which must be inside the 10.0.0.0/24 subnet) and run the commands: 5. SSH into your Linux server and run the commands: curl -fsSL https://pkgs.netbird.io/install.sh | sh CopyCopied! Next, copy the netbird up --setup-key ... command and paste it into the terminal. netbird up --setup-key CopyCopied! After running the second command, the terminal will confirm Connected. Your headless device is now part of your NetBird network. ### [Connect a Client Device](https://docs.netbird.io/get-started#connect-a-client-device) Now, set up the device you will use to connect to your private network. 1. Back in the web UI, the wizard will prompt you to "Time to add your client device." Click Install NetBird. 2. Download and run the installer for your client machine's OS (e.g., macOS). 3. Once installed, find the NetBird icon in your system tray or menu bar, click it, and select Connect. 4. Authorize this new device in the browser tab that opens. ### [Test the Connection](https://docs.netbird.io/get-started#test-the-connection) With both the routing peer and your client device online, you can now test your connection to the private network. To properly test connectivity you should move the client device to a different network, for example, connecting the device using your phone's hotspot. ![Switching Network](https://docs.netbird.io/docs-static/img/get-started/onboarding/13_switching-network.jpeg) 1. Open a terminal on your client device and run the test command (e.g., `ping 10.0.0.100`). Due note, the IP you ping needs to be a device on the same network that the routing peer is installed on. 2. You should see successful replies, confirming that your client device can reach internal resources through the routing peer. 3. Click It works! - Continue in the UI. ### [Understanding Your Access Policy](https://docs.netbird.io/get-started#understanding-your-access-policy) The final step of the onboarding wizard explains the access rule that was automatically created for you. ![Testing Worked](https://docs.netbird.io/docs-static/img/get-started/onboarding/14_it-worked.jpeg) 1. A policy, named "Users to My Subnet," is enabled by default. This policy allows all authenticated users to access the resources within the subnet you define. 2. To demonstrate this, you can toggle this policy off. When disabled, the ping from your client device will begin to fail with a "Request timeout" error, showing that the connection is now blocked. 3. Re-enabling the policy will immediately restore access. 4. Click Continue to complete the setup. ![Understanding Your Access Policy](https://docs.netbird.io/docs-static/img/get-started/onboarding/16_onboarding-policies.jpeg) Click Go to Dashboard to access the main NetBird admin panel. From here, you can: * [Control Center](https://docs.netbird.io/manage/control-center) : Visualize your network topology and access relationships with an interactive graph. * [Peers](https://docs.netbird.io/manage/peers/add-machines-to-your-network) : View and manage all connected devices and their properties. * [Setup Keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) : Create and manage keys for adding new headless or ephemeral devices. * [Access Control](https://docs.netbird.io/manage/access-control/manage-network-access) : Define granular firewall rules to control which peers can access what. * [Team](https://docs.netbird.io/manage/team/add-users-to-your-network) : Manage users and create groups for easier policy management. You are now ready to explore the full capabilities of NetBird. [Support Us](https://docs.netbird.io/get-started#support-us) ------------------------------------------------------------- * Star us on [GitHub](https://github.com/netbirdio/netbird) * Follow us [on X](https://x.com/netbird) * Join our [Slack Channel](https://docs.netbird.io/slack-url) * NetBird release page on GitHub: [releases](https://github.com/netbirdio/netbird/releases/latest) 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/get-started/index.mdx) --- # Visualize Remote Access with Control Center - NetBird Docs Visualize Remote Access with Control Center =========================================== Control Center is a topological view in the NetBird dashboard that visualizes who can access what across your environment. It maps **Peers**, **Groups**, and **Networks** to the resources they can reach and shows the access control policies that permit those connections. **Availability**: NetBird Cloud (all plans) and self-hosted. **Permissions:** The Admin and Network Admin user roles can edit policies from Control Center. Learn more about [user roles](https://docs.netbird.io/manage/team/add-users-to-your-network#manage-user-roles) . [How it helps](https://docs.netbird.io/manage/control-center#how-it-helps) --------------------------------------------------------------------------- * **Faster audits:** Confirm a device, group, or network's effective access at a glance. * **Quicker troubleshooting:** Follow the policy path that grants access to a resource. * **Safer changes:** Click through to the exact policy to refine sources, destinations, or ports without hunting across pages. [Views](https://docs.netbird.io/manage/control-center#views) ------------------------------------------------------------- ### [Peers view](https://docs.netbird.io/manage/control-center#peers-view) Use this to understand what a specific machine can reach. ![Control Center Peer View](https://docs.netbird.io/docs-static/img/manage/control-center/control-center-peer-view.png) * Click the peer node, then search or choose another peer from the dropdown to switch focus. * The graph shows the peer's access control policy nodes and the reachable resources. * Click a policy chip to open the standard policy editor. Changes you save are reflected in the graph immediately. ### [Users view](https://docs.netbird.io/manage/control-center#users-view) Use this view to see what resources a specific user can access. ![Control Center User View](https://docs.netbird.io/docs-static/img/manage/control-center/control-center-user-view.png) * Click the user node, then search or choose another user from the dropdown to switch focus. * The graph shows the users peers, access control policy nodes and the reachable resources. * Click a peer to switch focus only to that specific peer. * Click a policy chip to open the standard policy editor. Changes you save are reflected in the graph immediately. ### [Groups view](https://docs.netbird.io/manage/control-center#groups-view) Use this to validate team-level access. ![Control Center Groups View](https://docs.netbird.io/docs-static/img/manage/control-center/control-center-groups-view.png) * Click a group node, then search or choose from the dropdown to switch groups. * The layout shows which resources that group can reach and via which policies. * View-only for topology here; create or delete groups in the Groups section outside Control Center. Group-based access is the recommended way to manage permissions. Common checks: * Confirm that "DevOps" can reach RDS on TCP 5432, or that "Support" only reaches SSH on TCP 22. ### [Networks view](https://docs.netbird.io/manage/control-center#networks-view) Use this to see who can access resources in your routed [networks](https://docs.netbird.io/manage/networks) . ![Control Center Network View](https://docs.netbird.io/docs-static/img/manage/control-center/control-center-network-view.png) * Toggle **All Networks** or select a specific network. * The network node shows its resources. Connecting lines display the port allowed by the policy and which groups have access. * Click any policy chip to edit it in the standard editor. NetBird Networks and routing peers enable access to private subnets and IP resources. [Editing policies from the graph](https://docs.netbird.io/manage/control-center#editing-policies-from-the-graph) ----------------------------------------------------------------------------------------------------------------- * **Open editor:** Click an access control policy chip in any view to open the standard policy editor. * **What you can change:** Use the editor to modify the usual policy fields as documented in [Access Control](https://docs.netbird.io/manage/access-control/manage-network-access) , including sources, destinations, protocols, ports, and posture checks. * **Create vs edit:** You can edit existing policies from Control Center. Creating a new policy still happens in the Access Control section. [Quick start](https://docs.netbird.io/manage/control-center#quick-start) ------------------------------------------------------------------------- 1. Open **Control Center** in the NetBird dashboard. 2. Pick a tab: **Peers**, **Groups**, or **Networks**. 3. Click a node to focus, then follow the policy chips to the target resource. 4. Click a policy chip to edit it, then save. The graph updates right away. [Use cases](https://docs.netbird.io/manage/control-center#use-cases) --------------------------------------------------------------------- * **Sanity-check a team:** In **Groups** view, select a group and verify the resources and ports granted by its policies match your intent. Adjust policies in place if needed. * **Prepare a change:** In **Networks** view, review which groups reach a sensitive subnet before tightening ports or destinations. * **Investigate access:** In **Peers** view, confirm why a host can reach a database by following the policy path and port labels, then narrow the rule if required. * **MSPs:** Switch tenants in the MSP portal to repeat the same checks per customer environment. [Related docs](https://docs.netbird.io/manage/control-center#related-docs) --------------------------------------------------------------------------- * [Manage network access with Groups and Access Policies](https://docs.netbird.io/manage/access-control/manage-network-access) * [Apply posture checks to policies](https://docs.netbird.io/manage/access-control/posture-checks) * [Networks and routing peers](https://docs.netbird.io/manage/networks) * [MSP portal overview](https://docs.netbird.io/manage/for-partners/msp-portal) 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/manage/control-center/index.mdx) --- # Troubleshooting client issues - NetBird Docs Troubleshooting client issues ============================= This document offers practical tips and insights to help you debug various problems, ensuring a seamless user experience. [NetBird agent status](https://docs.netbird.io/help/troubleshooting-client#net-bird-agent-status) -------------------------------------------------------------------------------------------------- The netbird agent is a daemon service that runs in the background; it provides information about peers connected and about the NetBird control services. You can check the status of the agent with the following command: netbird status --detail CopyCopied! This will output the following information: Peers detail: server-a.netbird.cloud: NetBird IP: 100.75.232.118/32 Public key: kndklnsakldvnsld+XeRF4CLr/lcNF+DSdkd/t0nZHDqmE= Status: Connected -- detail -- Connection type: P2P Direct: true ICE candidate (Local/Remote): host/host ICE candidate endpoints (Local/Remote): 10.128.0.35:51820/10.128.0.54:51820 Last connection update: 20 seconds ago Last Wireguard handshake: 19 seconds ago Transfer status (received/sent) 6.1 KiB/20.6 KiB Quantum resistance: false Routes: 10.0.0.0/24 Latency: 37.503682ms server-b.netbird.cloud: NetBird IP: 100.75.226.48/32 Public key: Mi6jtrK5Tokndklnsakldvnsld+XeRF4CLr/lcNF+DSdkd= Status: Connected -- detail -- Connection type: Relayed Direct: false ICE candidate (Local/Remote): relay/host ICE candidate endpoints (Local/Remote): 108.54.10.33:60434/10.128.0.12:51820 Last connection update: 20 seconds ago Last Wireguard handshake: 18 seconds ago Transfer status (received/sent) 6.1 KiB/20.6 KiB Quantum resistance: false Routes: - Latency: 37.503682ms OS: darwin/amd64 Daemon version: 0.27.4 CLI version: 0.27.4 Management: Connected to https://api.netbird.io:443 Signal: Connected to https://signal.netbird.io:443 Relays: [stun:turn.netbird.io:5555] is Available [turns:turn.netbird.io:443?transport=tcp] is Available Nameservers: [8.8.8.8:53, 8.8.4.4:53] for [.] is Available FQDN: maycons-mbp-2.netbird.cloud NetBird IP: 100.75.143.239/16 Interface type: Kernel Quantum resistance: false Routes: - Peers count: 2/2 Connected CopyCopied! As you can see, the output shows the peers connected, the NetBird IP address, the public key, the connection status, and the connection type. The status will also report if there is an issue connecting to the relay servers, the management server, or the signal server. As for Peers, the status will show the following information: * `Connection type`: P2P, Relayed, where relayed connections indicate a limitation in the network that prevents a direct connection between the peers. * `Direct`: true/false, where true indicates a direct connection between the peers without a local proxy. This case is common when the local peer is allocating the relay connection. * `ICE candidate (Local/Remote)`: relay/host, where relay indicates that the local peer is using a relay connection and host indicates that the remote peer is using a direct connection. * `Last Wireguard handshake`: Indicating the last time the Wireguard handshake was performed. Usually, this is performed every 2 minutes, and if you don't see an update here or if the value is empty, that indicates that the connection wasn't possible yet. * `Transfer status (received/sent)`: Indicating the amount of data received and sent by the peer. This is useful to check if the connection is being used. See more details about the status command [here](https://docs.netbird.io/get-started/cli#status) . [Getting client logs](https://docs.netbird.io/help/troubleshooting-client#getting-client-logs) ----------------------------------------------------------------------------------------------- By default, client logs are located in the `/var/log/netbird/client.log` file on macOS and Linux and in the `C:\ProgramData\netbird\client.log` file on Windows. You can analyze the logs to identify the root cause of the problem. If you need help, open a [github issue](https://github.com/netbirdio/netbird/issues/new/choose) and attach the logs. ### [Debug bundle](https://docs.netbird.io/help/troubleshooting-client#debug-bundle) A debug archive containing the recent logs and the status at the time of execution can be generated with the following command. Adding the `--anonymize (-A)` flag will anonymize the logs, removing sensitive information such as public IP addresses and domain names. In case you have tunneling issues, omitting the `--anonymize` flag might help our analysis. Adding the `--system-info (-S)` flag will add system information like network routes and interfaces netbird debug bundle --anonymize --system-info CopyCopied! This will output the path of the generated file. The output file is owned by and can only be accessed by the user NetBird is running as, by default it is: `Administrator` on Windows, `root` on MacOS/Linux or the operating system's equivalent. ### [Debug for a specific time](https://docs.netbird.io/help/troubleshooting-client#debug-for-a-specific-time) To capture logs for a specific time period, you can use the `debug for` command. This will generate a debug bundle after the specified time has elapsed. netbird debug for 5m --system-info CopyCopied! The flag `--anonymize (-A)` can be used to anonymize IP addresses and non-netbird.io domains in logs and status output when needed. To capture any issues arising during the `up` and `down` processes, this will set the log level to `TRACE` and bring netbird `up` and `down` up to a few times. After 5 minutes the netbird status will be restored to the previous state and the debug bundle will be generated. ### [Debug bundle uploads](https://docs.netbird.io/help/troubleshooting-client#debug-bundle-uploads) Since version `0.43.1`, you can share debug bundle with the NetBird development team without local administrative privileges by using the `--upload-bundle (-U)` flag. It will securely generate and upload the debug bundle to our servers for access by the NetBird development team. See examples below: Run debug for a specific time and upload the bundle: netbird debug for 1m --system-info --upload-bundle CopyCopied! To generate a bundle without restarting the client and then uploading: netbird debug bundle --system-info --upload-bundle CopyCopied! This will output an `Upload file key`, which is effectively a random filename in our internal storage system and can be safely shared with us through public channels such as GitHub Issues or Slack. netbird debug bundle --system-info --upload-bundle Local file: /tmp/netbird.debug.2611377582.zip Upload file key: 1234567890ab27fb37c88b3b4be7011e22aa2e5ca6f38ffa9c4481884941f726/12345678-90ab-cdef-1234-567890abcdef CopyCopied! The flag `--anonymize` can be used to anonymize IP addresses and non-netbird.io domains in logs and status output when needed. ### [Debug bundle uploads with GUI](https://docs.netbird.io/help/troubleshooting-client#debug-bundle-uploads-with-gui) Since version `0.43.2` users can upload their debug bundle via the GUI client. To generate a bundle via GUI, you can access the application then go to `Settings` > `Create Debug Bundle` and follow the wizard to upload the bundle: ![service-user-overview](https://docs.netbird.io/docs-static/img/help/troubleshooting-client/ui-settings.png) If needed, you can update the upload URL and select to anonymize sensitive information like IP addresses and non-netbird.io domains in logs and status output. ![service-user-overview](https://docs.netbird.io/docs-static/img/help/troubleshooting-client/ui-bundle-wizard.png) By default running with trace log enable before generating the bundle is selected. This will restart the client connections and provide a `disconnect to connected` information for our engineers. If you uncheck this option, a bundle will be generated without running this step. Which is very useful when you have an issue that recovers when restarting the client. ![service-user-overview](https://docs.netbird.io/docs-static/img/help/troubleshooting-client/ui-bundle-success.png) Once the bundle generation is complete, you can click on `Copy Key` to get the uploaded key and share with NetBird's team. ### [Remote debug bundle generation](https://docs.netbird.io/help/troubleshooting-client#remote-debug-bundle-generation) Administrators can remotely request debug bundles from peer clients through the Management API or Dashboard. For a complete overview of remote job capabilities, permissions, and configuration, see the [Remote Jobs documentation](https://docs.netbird.io/manage/peers/remote-jobs) . This is particularly useful when troubleshooting issues on remote machines where local access is limited or when working with end-users who may not be familiar with command-line tools. When a remote debug bundle is requested: 1. The management server sends a job request to the target peer 2. The peer client receives the job and generates the debug bundle automatically 3. The generated bundle is uploaded to a centralized location 4. The administrator receives the upload key to access the bundle #### [Using the Management API](https://docs.netbird.io/help/troubleshooting-client#using-the-management-api) You can also trigger remote debug bundles programmatically via the Management API. See the [Peers API documentation](https://docs.netbird.io/ipa/resources/peers#create-peer-debug-bundle-job) for complete API reference, including: * Creating debug bundle jobs * Listing all jobs for a peer * Getting job status and upload keys #### [Using the Dashboard](https://docs.netbird.io/help/troubleshooting-client#using-the-dashboard) You can trigger remote debug bundles directly from the NetBird Dashboard without requiring CLI access. **To generate a remote debug bundle:** 1. Navigate to **Peers** in the dashboard 2. Click on the peer you want to troubleshoot 3. Click the **Run Remote Job** button (the peer must be online and connected) 4. Select **Debug Bundle** from the dropdown menu 5. Configure the debug bundle options: * **Log File Count**: Number of log files to include (1-50, default: 10) * **Enable Bundle Duration** (optional): Collect logs for a specific time period (1-5 minutes) before generating the bundle * **Anonymize Log Data**: Remove sensitive information like IP addresses and domains 6. Click **Create Debug Bundle** **Viewing job status and results:** Once triggered, the job appears in the **Remote Jobs** section on the peer details page. The table shows: * **Type**: The job type (Debug Bundle) * **Status**: Pending (yellow), Completed (green), or Failed (red) * **Created/Updated**: Timestamps for job lifecycle * **Output**: Once completed, displays the upload key that you can copy and share with NetBird support The upload key is automatically copyable by clicking on it. Share this key through GitHub Issues, Slack, or support channels. #### [Limitations](https://docs.netbird.io/help/troubleshooting-client#limitations) * The peer must be online and connected to the management server to receive the job * Debug bundle generation may take a few seconds to a few minutes depending on log size and system information * Bundles are automatically uploaded to NetBird's secure storage (or your configured upload endpoint for self-hosted deployments) * Upload keys expire after 30 days for security [Enabling debug logs on agent](https://docs.netbird.io/help/troubleshooting-client#enabling-debug-logs-on-agent) ----------------------------------------------------------------------------------------------------------------- Logs can be temporarily set using the following command. netbird debug log level debug CopyCopied! or netbird debug log level trace CopyCopied! The next time the daemon is restarted, the log level will return to the configured level. Using `netbird down` and `netbird up` will not reset the log level. To permanently set the log level, see the following sections. The default logging level is `info`. To revert back to the original state, you can repeat the procedure with `info` instead of `debug` or `trace`. ### [On Linux with systemd](https://docs.netbird.io/help/troubleshooting-client#on-linux-with-systemd) The default systemd unit file reads a set of environment variables from the path `/etc/sysconfig/netbird`. You can add the following line to the file to enable debug logs: sudo mkdir -p /etc/sysconfig echo 'NB_LOG_LEVEL=debug' | sudo tee -a /etc/sysconfig/netbird sudo systemctl restart netbird CopyCopied! ### [On Other Linux and MacOS](https://docs.netbird.io/help/troubleshooting-client#on-other-linux-and-mac-os) sudo netbird service stop sudo netbird service uninstall sudo netbird service install --log-level debug # or trace sudo netbird service start CopyCopied! ### [On Windows](https://docs.netbird.io/help/troubleshooting-client#on-windows) You need to run the following commands with an elevated PowerShell or `cmd.exe` window. [Environment]::SetEnvironmentVariable("NB_LOG_LEVEL", "debug", "Machine") netbird service restart CopyCopied! ### [On Docker](https://docs.netbird.io/help/troubleshooting-client#on-docker) You can set the environment variable `NB_LOG_LEVEL` to `debug` to enable debug logs. docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d \ -e NB_SETUP_KEY= -e NB_LOG_LEVEL=debug -v netbird-client:/var/lib/netbird netbirdio/netbird:latest CopyCopied! ### [On Android](https://docs.netbird.io/help/troubleshooting-client#on-android) Enable the ADB in the developer menu on the Android device. In the app set the the Trace log level setting - it is a checkbox in the advanced menu. With the ADB tool, you can get the logs from your device. The ADB is part of the SDK platform tools pack (zip file). You can download it from [here](https://developer.android.com/tools/releases/platform-tools) . Please extract it and run the next command in the case of Linux: sudo adb logcat -v time | grep GoLog CopyCopied! [Running the agent in foreground mode](https://docs.netbird.io/help/troubleshooting-client#running-the-agent-in-foreground-mode) --------------------------------------------------------------------------------------------------------------------------------- You can run the agent in foreground mode to see the logs in the terminal. This is useful to debugging issues with the agent. ### [Linux and MacOS](https://docs.netbird.io/help/troubleshooting-client#linux-and-mac-os) sudo netbird service stop sudo netbird up -F CopyCopied! ### [Windows](https://docs.netbird.io/help/troubleshooting-client#windows) On Windows, the agent depends on the Wireguard's `wintun.dll` and can only be executed as a system account. To run the agent in foreground mode, you need to use a tool called [PSExec](https://learn.microsoft.com/en-us/sysinternals/downloads/psexec) . Once you have downloaded and extracted `psexec` open an elevated Powershell window: netbird service stop .\PsExec64.exe -s cmd.exe /c "netbird up -F --log-level debug > c:\windows\temp\netbird.out.log 2>&1" CopyCopied! In case you need to configure environment variables, you need to add them as system variables so they get picked up by the agent on the next psexec run: [Environment]::SetEnvironmentVariable("PIONS_LOG_DEBUG", "all", "Machine") CopyCopied! [Enabling WireGuard in user space](https://docs.netbird.io/help/troubleshooting-client#enabling-wire-guard-in-user-space) -------------------------------------------------------------------------------------------------------------------------- Sometimes, you want to test NetBird running on userspace mode instead of a kernel module. That can be a check to see if there is a problem with NetBird's firewall management in kernel mode. You must run the agent in foreground mode and set the environment variable `NB_WG_KERNEL_DISABLED` to `true`. sudo netbird service stop sudo bash -c 'NB_WG_KERNEL_DISABLED=true netbird up -F' > /tmp/netbird.log CopyCopied! [Debugging GRPC](https://docs.netbird.io/help/troubleshooting-client#debugging-grpc) ------------------------------------------------------------------------------------- The NetBird agent communicates with the Management and Signal servers using the GRPC framework. With these parameters, you can set verbose logging for this service. sudo netbird service stop sudo bash -c 'GRPC_GO_LOG_VERBOSITY_LEVEL=99 GRPC_GO_LOG_SEVERITY_LEVEL=info netbird up -F' > /tmp/netbird.log CopyCopied! [Debugging ICE connections](https://docs.netbird.io/help/troubleshooting-client#debugging-ice-connections) ----------------------------------------------------------------------------------------------------------- The Netbird agent communicates with other peers through the Interactive Connectivity Establishment (ICE) protocol described in the [RFC 8445](https://datatracker.ietf.org/doc/html/rfc8445) . To debug the connection procedure, set verbose logging for the the [Pion/ICE](https://github.com/pion/ice) library with the `PIONS_LOG_DEBUG` or `PIONS_LOG_TRACE` variable. ### Environment variable PIONS_LOG_DEBUG=all NB_LOG_LEVEL=debug CopyCopied! sudo netbird service stop sudo bash -c 'PIONS_LOG_DEBUG=all NB_LOG_LEVEL=debug netbird up -F' > /tmp/netbird.log CopyCopied! [Host-based firewall issues](https://docs.netbird.io/help/troubleshooting-client#host-based-firewall-issues) ------------------------------------------------------------------------------------------------------------- NetBird automatically adds firewall rules on all platforms to allow traffic on the NetBird interface (`wt0`). However, conflicts can occur with other firewall management tools or security software. ### [Symptoms](https://docs.netbird.io/help/troubleshooting-client#symptoms) * Peers show as "Connected" in `netbird status` but cannot ping or reach each other * Connection works on some machines but not others with the same network configuration * Connection works after disabling the host firewall but fails when re-enabled * P2P connections work but routed traffic does not ### [Understanding the issue](https://docs.netbird.io/help/troubleshooting-client#understanding-the-issue) NetBird manages firewall rules directly via iptables/nftables (Linux/macOS) or Windows Firewall APIs. When another tool also manages firewall rules, conflicts can occur: | Tool | Conflict Type | | --- | --- | | UFW (Linux) | Chain ordering - UFW may evaluate its deny rules before NetBird's allow rules | | firewalld (Linux) | Zone conflicts - NetBird interface may be in wrong zone | | Windows Group Policy | Policy may override or remove NetBird's firewall rule | | Third-party security software | May block traffic independently of OS firewall | ### [UFW (Linux)](https://docs.netbird.io/help/troubleshooting-client#ufw-linux) UFW is a frontend for iptables commonly used on Ubuntu. Its default policy denies all incoming traffic, which can block NetBird traffic before it reaches NetBird's iptables rules. **Check UFW status**: sudo ufw status verbose CopyCopied! If UFW is active with a default deny incoming policy, add a rule for the NetBird interface: **Allow NetBird interface**: sudo ufw allow in on wt0 CopyCopied! **Verify the rule was added**: sudo ufw status | grep wt0 CopyCopied! Expected output: Anywhere on wt0 ALLOW Anywhere Anywhere (v6) on wt0 ALLOW Anywhere (v6) CopyCopied! **Alternative - Allow specific NetBird subnet**: If you prefer a more restrictive rule: sudo ufw allow in on wt0 from 100.64.0.0/10 CopyCopied! ### [firewalld (Linux)](https://docs.netbird.io/help/troubleshooting-client#firewalld-linux) On distributions using firewalld (RHEL, CentOS, Fedora), ensure the `wt0` interface is in a trusted zone: **Check current zone for wt0**: sudo firewall-cmd --get-zone-of-interface=wt0 CopyCopied! **Add wt0 to trusted zone**: sudo firewall-cmd --permanent --zone=trusted --add-interface=wt0 sudo firewall-cmd --reload CopyCopied! ### [Windows Firewall](https://docs.netbird.io/help/troubleshooting-client#windows-firewall) NetBird creates a Windows Firewall rule automatically that allows traffic on the NetBird IP address (the `wt0` interface). This covers traffic after WireGuard decryption. **Check if the NetBird rule exists**: Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*NetBird*" } | Format-List DisplayName, Enabled, Direction, Action CopyCopied! **Check if the rule is being applied**: Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*NetBird*" } | Get-NetFirewallAddressFilter CopyCopied! **Manually create the rule if missing**: New-NetFirewallRule -DisplayName "NetBird" -Direction Inbound -InterfaceAlias "wt0" -Action Allow CopyCopied! **Check for Group Policy overrides**: If the rule exists but traffic is still blocked, Group Policy may be overriding local firewall rules. Check with your IT administrator or review: Get-NetFirewallProfile | Format-List Name, Enabled, DefaultInboundAction CopyCopied! ### [Environments without NAT (flat networks, routed VLANs)](https://docs.netbird.io/help/troubleshooting-client#environments-without-nat-flat-networks-routed-vlans) In most environments, NAT provides stateful connection tracking. When Peer A sends UDP to Peer B, the return traffic is allowed because the NAT device tracks it as part of an established connection. However, in environments **without NAT between peers** (e.g., flat office networks, routed VLANs without masquerading), Windows Firewall may block incoming WireGuard P2P traffic because: 1. There is no NAT state tracking the "connection" 2. Windows Firewall sees the incoming UDP packets as unsolicited inbound traffic 3. The default NetBird rule only covers traffic on the `wt0` interface (after decryption), not the raw WireGuard packets arriving on the physical interface **Symptoms**: * P2P works when one peer is behind NAT but fails when both peers are on the same flat network * `netbird status -d` shows connection type as "Relayed" instead of "P2P" for local peers * P2P works after disabling Windows Firewall **Solution**: Add a firewall rule to allow inbound UDP for WireGuard P2P traffic, scoped to the NetBird process: New-NetFirewallRule -DisplayName "NetBird P2P" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 49152-65535 -Program "C:\Program Files\Netbird\netbird.exe" CopyCopied! This rule: * Allows inbound UDP on the ephemeral port range (used for WireGuard) * Is scoped to only the NetBird process for security * Does not expose any other services **Note**: This is only needed in environments without NAT between peers. If your peers connect through NAT (typical for remote access scenarios), the default rules are sufficient. **Linux in non-NAT environments**: The same principle applies. If UFW or firewalld is blocking inbound UDP on the physical interface, you may need to allow it. However, Linux cannot scope firewall rules to a specific process like Windows can. A broader rule would be required: # UFW - allows inbound UDP on ephemeral ports (less restrictive than Windows equivalent) sudo ufw allow in proto udp to any port 49152:65535 CopyCopied! Consider whether this is acceptable for your security posture, or use NetBird's relay fallback instead. ### [Third-party security software](https://docs.netbird.io/help/troubleshooting-client#third-party-security-software) Antivirus and endpoint protection software often includes its own firewall that operates independently of the OS firewall. Common culprits include: * Symantec Endpoint Protection * McAfee * Kaspersky * ESET * CrowdStrike Falcon If you suspect third-party software is blocking NetBird: 1. Temporarily disable the third-party firewall component (not the entire product) 2. Test NetBird connectivity 3. If it works, add an exception for the NetBird process or the `wt0` interface The NetBird process locations: * **Windows**: `C:\Program Files\NetBird\netbird.exe` * **Linux**: `/usr/bin/netbird` * **macOS**: `/usr/local/bin/netbird` ### [Collecting firewall diagnostics](https://docs.netbird.io/help/troubleshooting-client#collecting-firewall-diagnostics) When reporting firewall-related issues, include a debug bundle with system information: netbird debug bundle --system-info CopyCopied! The `--system-info` flag captures: * Network routes * Interface configuration * Firewall rules (where accessible) **Additional diagnostics for Linux**: # Current iptables rules sudo iptables -L -n -v # nftables rules (if applicable) sudo nft list ruleset # UFW status sudo ufw status verbose CopyCopied! **Additional diagnostics for Windows** (run as Administrator): # All firewall rules for wt0 Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*NetBird*" -or $_.DisplayName -like "*wt0*" } # Firewall profile status Get-NetFirewallProfile CopyCopied! ### [Quick reference](https://docs.netbird.io/help/troubleshooting-client#quick-reference) | Platform | Check Command | Fix Command | | --- | --- | --- | | UFW (Linux) | `sudo ufw status` | `sudo ufw allow in on wt0` | | firewalld (Linux) | `sudo firewall-cmd --get-zone-of-interface=wt0` | `sudo firewall-cmd --permanent --zone=trusted --add-interface=wt0 && sudo firewall-cmd --reload` | | Windows | `Get-NetFirewallRule \| Where-Object { $_.DisplayName -like "*NetBird*" }` | Check Group Policy or third-party software | | Windows (no NAT) | P2P shows as Relayed for local peers | `New-NetFirewallRule -DisplayName "NetBird P2P" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 49152-65535 -Program "C:\Program Files\Netbird\netbird.exe"` | [Client login failures](https://docs.netbird.io/help/troubleshooting-client#client-login-failures) --------------------------------------------------------------------------------------------------- A single machine can only connect to one NetBird account as the same user/login method throughout the lifetime of the `config.json` file: * `/var/lib/netbird/default.json` for Linux/MacOS * `C:\ProgramData\netbird\default.json` for Windows You might get errors like below when trying to use Setup Key/different SSO user account during login: 2025-04-08T15:03:04+01:00 ERRO management/client/grpc.go:351: failed to login to Management Service: rpc error: code = PermissionDenied desc = peer login has expired, please log in once more 2025-04-08T15:03:04+01:00 ERRO management/client/grpc.go:351: failed to login to Management Service: rpc error: code = PermissionDenied desc = invalid user 2025-04-08T15:03:04+01:00 ERRO client/internal/login.go:145: failed registering peer rpc error: code = PermissionDenied desc = invalid user,00000000-0000-0000-0000-000000000000 2025-04-08T15:03:04+01:00 WARN client/server/server.go:267: failed login: rpc error: code = PermissionDenied desc = invalid user CopyCopied! Starting with the release `0.50.0` the `invalid user` message is more descriptive: `peer is already registered by a different User or a Setup Key` The most notable examples of encountering the issue are: * a shared machine and/or machine previously logged in by somebody else, * a machine that was previously logged in using Setup Key, but now attempts SSO login, * the user makes a mistake and selects * the user uses different browser/profile or selects the wrong account during SSO login at the start of the workday, If you know the exact previous Peer which was logged in, you can just delete it from Dashboard without doing anything else and attempt login again. Otherwise, to resolve the issue, you will need to remove the file manually to use the machine as a different user/Setup Key while the NetBird client daemon is stopped: 1. `netbird service stop` 2. `sudo rm /var/lib/netbird/default.json` (\*nix) or `rm C:\ProgramData\netbird\config.json` (Windows) 3. `netbird service start` [Debugging access to network resources](https://docs.netbird.io/help/troubleshooting-client#debugging-access-to-network-resources) ----------------------------------------------------------------------------------------------------------------------------------- In this section we will be presenting methodology of troubleshooting access issues involving Netbird. We will start by presenting a glossary of all machines and services involved. A sub-section will describe a specific use case. Each will start with a concise summary of usual troubleshooting steps then expand into more detailed step-by-step guides. ### [Glossary](https://docs.netbird.io/help/troubleshooting-client#glossary) We will be using the following names for resources outside the Netbird network: * `int-net1`: an internal network `10.123.45.0/24`, * `srv-c`: an internal HTTP server running at `10.123.45.17`, * `int-dns1`: an internal DNS server running at `10.123.45.6`, * `int-dns2`: an internal DNS server nunning at `10.7.8.9`, * `cf-dns`: an Internet-accessible CloudFlare DNS server at `1.1.1.1` and `1.0.0.1`, and following Netbird network resources: * `peer-a`: end user's device running Netbird Client, * `peer-b`: a linux server inside the internal network running Netbird Client, * it has direct access to the whole `int-net1` IP range, * `users:employees`: a Netbird Group containing `peer-a`, * `routers:int-net1`: a Netbird Group containing `peer-b`, * `access:srv-c`: a Netbird Groups used as a target of ACL rules for `srv-c` only, * `access:int-net1`: a Netbird Groups used as a target of ACL rules for the whole subnet, * `net-a`: a Netbird Network * `net-a:srv-c`: a Network Resource handling traffic to `10.123.45.17/32` (`srv-c`), * `net-a:int-net1`: a Network Resource handling traffic to `10.123.45.0/24` (`int-net1`), * `route:int-net1`: a Netbird Network Route handling traffic to `10.123.45.0/24` (`int-net1`), * `route:srv-c`: a Netbird Network Route handling traffic to `10.123.45.17/32` (`srv-c`), ### [Access from `peer-a` to `srv-c`](https://docs.netbird.io/help/troubleshooting-client#access-from-peer-a-to-srv-c) In short: 1. Does `peer-b` have direct access to `srv-c`'s port `80`? 2. Can a routing peer `peer-b` forward traffic to `srv-c`? 3. Are Netbird's network routing resources configured? 4. Do Netbird's Access Control rules allow access from `peer-a` to the target's ACL Group? 5. Is `peer-a`'s operating system configured to use the route? Access Control rule is not required for connectivity from `peer-a` to `peer-b` #### [Does `peer-b` have direct access to `srv-c`'s port `80`?](https://docs.netbird.io/help/troubleshooting-client#does-peer-b-have-direct-access-to-srv-cs-port-80) After logging in to `peer-b` you can confirm/troubleshoot the HTTP port `80` connection by issuing any of the following commands: curl -v "http://10.123.45.17" curl --fail -v --max-time=2 "http://10.123.45.17:80" wget -O - --timeout=2 "http://10.123.45.17:80" nc -nvz -w 2 10.123.45.17 80 CopyCopied! You can also try `ping` (an ICMP packet), but the firewall might have a different configuration for ICMP and TCP ports: ping --numeric --count=1 --timeout=2 10.123.45.17 CopyCopied! #### [Can a routing peer `peer-b` forward traffic to `srv-c`?](https://docs.netbird.io/help/troubleshooting-client#can-a-routing-peer-peer-b-forward-traffic-to-srv-c) This is more complicated to test, but usually boils down to confirming `net.ipv4.ip_forward` is set to `1` on `peer-b`'s Linux operating system: > sysctl net.ipv4.ip_forward net.ipv4.ip_forward = 1 CopyCopied! It should be set up automatically by the Netbird client unless it runs inside a container (which would not be able to modify `sysctl`), then it requires manual setup. For setting up the value persistently (across reboots) please consult your operating system's documentation. It is often handled by either `/etc/sysctl.conf` or `/etc/sysctl.d/*.conf` files. Testing the functionality in practice involves: * connecting to another machine with direct access to `peer-b`, * adding a routing table entry to route `int-net1` (`10.123.45.0/24`) traffic through it, * trying to at least `ping 10.123.45.17` (`srv-c`) #### [Are Netbird's network routing resources configured?](https://docs.netbird.io/help/troubleshooting-client#are-netbirds-network-routing-resources-configured) For Netbird network routing resources configurations you can use either (new) _Networks_ or (old) _Network Routes_. A Network `net-a` should have at minimum: * _Network Resource_: `net-a:srv-c` with either of: * an _Address_ set to `10.123.45.17/32` to configure route to `srv-c` exclusively and nothing else, * _Assigned Groups_ set to `access:srv-c` * _Routing Peer Group_ assigned to `routers:int-net1` A _Network Route_ `route:srv-c` should have at least: * a _Network Range_ set to `10.123.45.17/32` to configure route to `srv-c` exclusively and nothing else, * _Routing Peer Group_ assigned to `routers:int-net1`, * _Distribution Group_ assigned to `users:employees`, * (optional) _Access Control Groups_ assigned to `access:srv-c`, You can loosen the rules and replace following to grant access to the whole `int-net1` network range: * _Address_: `10.123.45.17/32` -> `10.123.45.0/24`, * _Assigned Groups_ / _Access Control Groups_: `access:srv-c` -> `access:int-net1` #### [Do Netbird's Access Control rules allow access from `peer-a` to the target's ACL Group?](https://docs.netbird.io/help/troubleshooting-client#do-netbirds-access-control-rules-allow-access-from-peer-a-to-the-targets-acl-group) You can skip this check, when you are using (old) Network Route feature without filling in _Access Control Groups ( optional)_ section. Otherwise, there should be an _Access Control Policy_ present allowing traffic from one of `peer-a`'s Groups to: * _Networks Resource_'s _Assigned Groups_: `access:srv-c` or `access:int-net1`, * _Network Route_'s _Access Control Groups_: `access:srv-c` or `access:int-net1`, You can confirm the _Policy_ is working by: 1. logging in to `peer-a`, 2. issuing `netbird status -d` command, 3. finding `peer-b.netbird.cloud` under `Peers detail`, 4. finding `10.123.45.0/24` or `10.123.45.17/32` under `peer-b.netbird.cloud`'s _Networks_ field, In the most specific setup it should have at: * have `TCP` protocol selected, * a blue arrow should point from left to right and a second right-to-left arrow should be greyed out, * a _Source group_ set to `users:employees`, * a _Destination group_ set to `access:srv-c`, * have `80` in the Ports section, Just like with the previous section you can loosen the above example by: * replacing `access:srv-c` _Group_ with `access:int-net1` _Group_, * allowing `ALL` protocol, _Ports_ will become greyed out because all traffic will be allowed, * creating a bidirectional rule (both arrows should be green), always true for the protocol `ALL`, * selecting a different source group from the pool assigned to `peer-a`, * it could be built-in `All` group, but it is discouraged, * selecting a different destination group from the pool assigned to `peer-b`, * it could be built-in `All` group, but it is discouraged, #### [Is `peer-a`'s operating system configured to use the route?](https://docs.netbird.io/help/troubleshooting-client#is-peer-as-operating-system-configured-to-use-the-route) After all resources are configured in the Netbird management you should check whether they are properly registered with your operating system. You can start by checking Netbird client's configuration with `netbird status -d` command: % netbird status -d Peers detail: brys-vm-nbt-ubuntu-isolated-01.netbird.cloud: ... Status: Connected -- detail -- Connection type: P2P ... Networks: 10.123.45.0/24 ... Peers count: 1/1 Connected CopyCopied! You should be primarily looking for _Networks_ section under each _Peers detail_, but you can also check: * _Peer_'s name, * _Peer_'s _Status_: it should be `Connected`, * _Peer_'s _Connection type_: it can be either `P2P` (direct) or `Relayed` (over the Internet), * _Peers count_ near the end of the output, If it's missing you can search for clues with `netbird networks ls` command: % netbird networks ls Available Networks: ... - ID: net-a:int-net1 Network: 10.123.45.0/24 Status: Selected ... CopyCopied! The _Status_ could be `Not Selected`, which you can fix with `netbird networks select ` or `netbird networks select all` ##### [Verifying routing configuration on the Windows operating system](https://docs.netbird.io/help/troubleshooting-client#verifying-routing-configuration-on-the-windows-operating-system) Below commands assume running a PowerShell prompt with administrator's privileges. The easiest way is to read output of `Get-NetRoute` command: PS C:\Users\user> Get-NetRoute ifIndex DestinationPrefix NextHop RouteMetric ifMetric PolicyStore ------- ----------------- ------- ----------- -------- ----------- ... 17 10.123.45.255/32 0.0.0.0 256 5 ActiveStore 17 10.123.45.0/24 0.0.0.0 1 5 ActiveStore ... 17 100.83.255.255/32 0.0.0.0 256 5 ActiveStore 17 100.83.183.133/32 0.0.0.0 256 5 ActiveStore 17 100.83.0.0/16 0.0.0.0 256 5 ActiveStore ... CopyCopied! You should be looking for your specific subnet's IP ranges (`10.123.45.0/24` in case of `int-net1`) and anything from `100.*.0.0/16` range. Some other alternatives are `route print` & `Get-NetIPConfiguration`. ##### [Verifying routing configuration on the MacOS operating system](https://docs.netbird.io/help/troubleshooting-client#verifying-routing-configuration-on-the-mac-os-operating-system) The easiest way to verify system configuration is `netstat -nr` command: % netstat -nr Routing tables Internet: Destination Gateway Flags Netif Expire ... 100.83/16 utun100 USc utun100 100.83.19.63 100.83.19.63 UH utun100 ... 10.123.45 utun100 USc utun100 ... Internet6: Destination Gateway Flags Netif Expire ... CopyCopied! You should be looking for `utun*` interface in 4th column and searching the rows for your specific subnet's clamped IP ranges (`10.123.45` in case of `int-net1`) and anything from `100.*/16` range. ##### [Verifying routing configuration on the Linux operating system](https://docs.netbird.io/help/troubleshooting-client#verifying-routing-configuration-on-the-linux-operating-system) Depending on specifics of your Linux distribution (or even your configuration of it) you should be able to use either `iproute2` or `net-tools` family of network commands. Netbird client stores it's custom routes in the routing table `7120` (or `0x1BD0`) when it's available (through `iproute2` interface). For `iproute2` (`ip`, `ss` tools): * `ip route` to find built-in `100.*.0.0/16` route, * `ip route show table 7120` or `ip route show table all` to find the specific routed networks, For `net-tools` (`ifconfig`, `route`, `netstat` tools): * `route -n` to find built-in `100.*.0.0/16` route, * neither `route` nor `netstat` support viewing content of custom routing tables, 1. Copy link 2. [Edit on Github](https://github.com/netbirdio/docs/tree/main/src/pages/help/troubleshooting-client.mdx) --- # NetBird Agent command line interface (CLI) - NetBird Docs NetBird Agent command line interface (CLI) ========================================== The NetBird client installation adds a binary called `netbird` to your system. This binary runs as a daemon service to connect your computer or server to the NetBird network as a peer. But it can also be used as a client to control the daemon service. This section will explore the commands available in `netbird`. [Syntax](https://docs.netbird.io/get-started/cli#syntax) --------------------------------------------------------- Use the following syntax to run `netbird` commands from your terminal window: netbird [command] [subcommand] [flags] CopyCopied! * `command`: Specifies the operation that you want to perform or a top-level command: `up`, `login`, `down`, `status`, `ssh`, `expose`, `version`, and `service` * `subcommand`: Specifies the operation to be executed for a top-level command like `service`: `install`, `uninstall`, `start`, and `stop` * `flags`: Specifies optional flags. For example, you can use the `--setup-key` flag to specify the setup key to be used in the commands `login` and `up` To see detailed command information, use the flag `--help` after each command [Configuration precedence](https://docs.netbird.io/get-started/cli#configuration-precedence) --------------------------------------------------------------------------------------------- This is the CLI configuration precedence (highest to lowest priority): 1. environment variables (eg: `NB_WIREGUARD_PORT`) 2. command line flags (eg: `--wireguard-port`) 3. configuration file entries `.json` (formerly: `config.json`), eg: `WgPort` key We are preserving the unusual priority of environment variables for backwards compatibility with existing deployments. [Global flags](https://docs.netbird.io/get-started/cli#global-flags) --------------------------------------------------------------------- `netbird` has a set of global flags that are available in every command. They specify settings that are core or shared between two or more commands, e.g. `--setup-key` is used by `login` and `up` to authenticate the client against a management service. Below is the list of global flags: --admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io") -A, --anonymize anonymize IP addresses and non-netbird.io domains in logs and status output --daemon-addr string Daemon service address to serve CLI requests [unix|tcp]://[path|host:port] (default "unix:///var/run/netbird.sock") --log-file string sets NetBird log path. If console is specified the the log will be output to stdout (default "/var/log/netbird/client.log") -l, --log-level string sets NetBird log level (default "info") -m, --management-url string Management Service URL [http|https]://[host]:[port] (default "https://api.netbird.io:443") -p, --preshared-key string Sets Wireguard PreSharedKey property. If set, then only peers that have the same key can communicate. -k, --setup-key string Setup key obtained from the Management Service Dashboard (used to register peer) CopyCopied! ### [Environment Variables](https://docs.netbird.io/get-started/cli#environment-variables) Every flag of a `netbird` command can be passed as an environment variable. We are using the following rule for the environment variables composition: * `PREFIX_FLAGNAME` and for flags with multiple parts: `PREFIX_FLAGNAMEPART1_FLAGNAMEPART2` * The prefix is always **NB** * The flag parts are separated by a dash ("-") when passing as flags and with an underscore ("\_") when passing as an environment variable For example, let's check how we can pass `--config` and `--management-url` as environment variables: export NB_CONFIG="/opt/netbird/config.json" export NB_MANAGEMENT_URL="https://api.self-hosted.com:443" netbird up CopyCopied! The `up` command would process the variables, read the configuration file on `/opt/netbird/config.json` and attempt to connect to the management service running at `https://api.self-hosted.com:443`. Here are some additional examples of environment variables: # Disable profiles feature export NB_DISABLE_PROFILES=true # Disable update settings functionality export NB_DISABLE_UPDATE_SETTINGS=true # Set custom log level export NB_LOG_LEVEL=debug # Set custom daemon address export NB_DAEMON_ADDR="tcp://localhost:8080" CopyCopied! [Commands](https://docs.netbird.io/get-started/cli#commands) ------------------------------------------------------------- ### [up](https://docs.netbird.io/get-started/cli#up) Single command to log in and start the NetBird client. It can send a signal to the daemon service or run in the foreground with the flag `--foreground-mode`. The command will check if the peer is logged in and connect to the management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow. #### [Flags](https://docs.netbird.io/get-started/cli#flags) --allow-server-ssh Allow SSH server on peer. If enabled, the SSH server will be permitted --disable-auto-connect Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts. --disable-ssh-auth Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication --dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best ip and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address "" --ssh-jwt-cache-ttl int SSH JWT token cache TTL in seconds. Set to 0 to disable caching (default). E.g. --ssh-jwt-cache-ttl 3600 for 1-hour cache --enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass. --enable-ssh-local-port-forwarding Enable local port forwarding on SSH server. Requires --allow-server-ssh --enable-ssh-remote-port-forwarding Enable remote port forwarding on SSH server. Requires --allow-server-ssh --enable-ssh-root Enable root user login on SSH server. Requires --allow-server-ssh --enable-ssh-sftp Enable SFTP subsystem on SSH server. Requires --allow-server-ssh --external-ip-map strings Sets external IPs maps between local addresses and interfaces.You can specify a comma-separated list with a single IP and IP/IP or IP/Interface Name. An empty string "" clears the previous configuration. E.g. --external-ip-map 12.34.56.78/10.0.0.1 or --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1 or --external-ip-map "" --extra-dns-labels strings Sets DNS labels. You can specify a comma-separated list of up to 32 labels. An empty string "" clears the previous configuration. E.g. --extra-dns-labels vpc1 or --extra-dns-labels vpc1,mgmt1 or --extra-dns-labels "" -F, --foreground-mode start service in foreground -h, --help help for up --interface-name string Wireguard interface name (default "utun100") --rosenpass-permissive [Experimental] Enable Rosenpass in permissive mode to allow this peer to accept WireGuard connections without requiring Rosenpass functionality from peers that do not have Rosenpass enabled. --wireguard-port uint16 Wireguard interface listening port (default 51820) --block-inbound Block inbound connections. If enabled, the client will not allow any inbound connections to the local machine nor routed networks. This overrides any policies received from the management service. CopyCopied! #### [Usage](https://docs.netbird.io/get-started/cli#usage) The minimal form of running the command is: netbird up CopyCopied! If you are running on a self-hosted environment, you can pass your management url by running the following: netbird up --management-url https://api.self-hosted.com:443 CopyCopied! if you want to run in the foreground, you can use "console" as the value for `--log-file` and run the command with sudo: sudo netbird up --log-file console CopyCopied! On Windows, you may need to run the command from an elevated terminal session. In case you need to use a setup key, use the `--setup-key` flag : netbird up --setup-key AAAA-BBB-CCC-DDDDDD CopyCopied! You can set extra DNS labels with the `--extra-dns-labels` flag: netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels vpc1,mgmt1 CopyCopied! This feature requires a setup-key with permissions to add peers with the extra labels. Multiple peers with the same extra labels will generate grouped DNS labels on the client side, and this feature can be used for DNS round-robing load balancing. ### [login](https://docs.netbird.io/get-started/cli#login) Command to authenticate the NetBird client to a management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow. #### [Usage](https://docs.netbird.io/get-started/cli#usage-2) The minimal form of running the command is: netbird login CopyCopied! If you are running on a self-hosted environment, you can pass your management url by running the following: netbird login --management-url https://api.self-hosted.com:443 CopyCopied! In case you need to use a setup key, use the `--setup-key` flag: netbird login --setup-key AAAA-BBB-CCC-DDDDDD CopyCopied! Passing a management url and a setup key: netbird login --setup-key AAAA-BBB-CCC-DDDDDD --management-url https://api.self-hosted.com:443 CopyCopied! ### [down](https://docs.netbird.io/get-started/cli#down) Command to stop a connection with the management service and other peers in a NetBird network. After running this command, the daemon service will enter an `Idle` state. #### [Usage](https://docs.netbird.io/get-started/cli#usage-3) The minimal form of running the command is: netbird down CopyCopied! ### [status](https://docs.netbird.io/get-started/cli#status) Retrieves the peer status from the daemon service. #### [Flags](https://docs.netbird.io/get-started/cli#flags-2) -d, --detail display detailed status information in human-readable format --filter-by-ips strings filters the detailed output by a list of one or more IPs, e.g., --filter-by-ips 100.64.0.100,100.64.0.200 --filter-by-names strings filters the detailed output by a list of one or more peer FQDN or hostnames, e.g., --filter-by-names peer-a,peer-b.netbird.cloud --filter-by-status string filters the detailed output by connection status(connected|disconnected), e.g., --filter-by-status connected -A, --anonymize anonymize IP addresses and non-netbird.io domains in the status output -h, --help help for status --ipv4 display only NetBird IPv4 of this peer, e.g., --ipv4 will output 100.64.0.33 --json display detailed status information in json format --yaml display detailed status information in yaml format CopyCopied! #### [Usage](https://docs.netbird.io/get-started/cli#usage-4) The minimal form of running the command is: netbird status CopyCopied! This will output: OS: linux/amd64 Daemon version: 0.27.4 CLI version: 0.27.4 Management: Connected Signal: Connected Relays: 2/2 Available Nameservers: 1/1 Available NetBird IP: 100.119.62.6/16 Interface type: Kernel Quantum resistance: false Routes: - Peers count: 2/3 Connected CopyCopied! If you want to see more details about the peer connections, you can use the `--detail` or `-d` flag: netbird status -d CopyCopied! This will output: Peers detail: Peer: NetBird IP: 100.119.85.4 Public key: 2lI3F+fDUWh58g5oRN+y7lPHpNcEVWhiDv/wr1/jiF8= Status: Disconnected -- detail -- Connection type: - Direct: false ICE candidate (Local/Remote): -/- ICE candidate endpoints (Local/Remote): -/- Last connection update: 26 seconds ago Last Wireguard handshake: - Transfer status (received/sent) 0 B/0 B Quantum resistance: false Routes: - Latency: 10.74ms Peer: NetBird IP: 100.119.201.225 Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10= Status: Connected -- detail -- Connection type: P2P Direct: true ICE candidate (Local/Remote): host/host ICE candidate endpoints (Local/Remote): -/- Last connection update: 26 seconds ago Last Wireguard handshake: 25 seconds ago Transfer status (received/sent) 2.0 KiB/355 B Quantum resistance: false Routes: 10.0.0.0/24 Latency: 20.14ms Peer: NetBird IP: 100.119.230.104 Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw= Status: Connected -- detail -- Connection type: P2P Direct: true ICE candidate (Local/Remote): host/host ICE candidate endpoints (Local/Remote): -/- Last connection update: 26 seconds ago Last Wireguard handshake: 24 seconds ago Transfer status (received/sent) 2.4 MiB/532 KiB Quantum resistance: false Routes: - Latency: 16.24ms OS: linux/amd64 Daemon version: 0.27.4 CLI version: 0.27.4 Management: Connected to https://api.netbird.io:443 Signal: Connected to https://signal.netbird.io:443 Relays: [stun:stun.netbird.io:5555] is Available [turns:turn.netbird.io:443?transport=tcp] is Available Nameservers: [8.8.8.8:53, 8.8.4.4:53] for [.] is Available NetBird IP: 100.119.62.6/16 Interface type: Kernel Quantum resistance: false Routes: - Peers count: 2/3 Connected CopyCopied! To filter the peers' output by connection status, you can use the `--filter-by-status` flag with either "connected" or "disconnected" as value: netbird status -d --filter-by-status connected CopyCopied! This will output: Peers detail: Peer: NetBird IP: 100.119.201.225 Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10= Status: Connected -- detail -- Connection type: P2P Direct: true ICE candidate (Local/Remote): host/host ICE candidate endpoints (Local/Remote): -/- Last connection update: 28 seconds ago Last Wireguard handshake: 27 seconds ago Transfer status (received/sent) 2.0 KiB/355 B Quantum resistance: false Routes: 10.0.0.0/24 Latency: 20.14ms Peer: NetBird IP: 100.119.230.104 Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw= Status: Connected -- detail -- Connection type: P2P Direct: true ICE candidate (Local/Remote): host/host ICE candidate endpoints (Local/Remote): -/- Last connection update: 28 seconds ago Last Wireguard handshake: 26 seconds ago Transfer status (received/sent) 2.4 MiB/532 KiB Quantum resistance: false Routes: - Latency: 16.24ms OS: linux/amd64 Daemon version: 0.27.4 CLI version: 0.27.4 Management: Connected to https://api.netbird.io:443 Signal: Connected to https://signal.netbird.io:443 Relays: [stun:stun.netbird.io:5555] is Available [turns:turn.netbird.io:443?transport=tcp] is Available Nameservers: [8.8.8.8:53, 8.8.4.4:53] for [.] is Available NetBird IP: 100.119.62.6/16 Interface type: Kernel Quantum resistance: false Routes: - Peers count: 2/3 Connected CopyCopied! To filter the peers' output by peer IP addresses, you can use the `--filter-by-ips` flag with one or more IPs separated by a comma as a value: netbird status -d --filter-by-ips 100.119.201.225 CopyCopied! This will output: Peers detail: Peer: NetBird IP: 100.119.201.225 Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10= Status: Connected -- detail -- Connection type: P2P Direct: true ICE candidate (Local/Remote): host/host ICE candidate endpoints (Local/Remote): -/- Last connection update: 32 seconds ago Last Wireguard handshake: 30 seconds ago Transfer status (received/sent) 2.0 KiB/355 B Quantum resistance: false Routes: 10.0.0.0/24 Latency: 20.14ms OS: linux/amd64 Daemon version: 0.27.4 CLI version: 0.27.4 Management: Connected to https://api.netbird.io:443 Signal: Connected to https://signal.netbird.io:443 Relays: [stun:stun.netbird.io:5555] is Available [turns:turn.netbird.io:443?transport=tcp] is Available Nameservers: [8.8.8.8:53, 8.8.4.4:53] for [.] is Available NetBird IP: 100.119.62.6/16 Interface type: Kernel Quantum resistance: false Routes: - Peers count: 2/3 Connected CopyCopied! You can combine both filters and get the peers that are both connected and with specific IPs: netbird status -d --filter-by-status connected --filter-by-ips 100.119.85.4,100.119.230.104 CopyCopied! This will output: Peers detail: Peer: NetBird IP: 100.119.230.104 Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw= Status: Connected -- detail -- Connection type: P2P Direct: true ICE candidate (Local/Remote): host/host ICE candidate endpoints (Local/Remote): -/- Last connection update: 35 seconds ago Last Wireguard handshake: 33 seconds ago Transfer status (received/sent) 2.4 MiB/532 KiB Quantum resistance: false Routes: - Latency: 16.24ms OS: linux/amd64 Daemon version: 0.27.4 CLI version: 0.27.4 Management: Connected to https://api.netbird.io:443 Signal: Connected to https://signal.netbird.io:443 Relays: [stun:stun.netbird.io:5555] is Available [turns:turn.netbird.io:443?transport=tcp] is Available Nameservers: [8.8.8.8:53, 8.8.4.4:53] for [.] is Available NetBird IP: 100.119.62.6/16 Interface type: Kernel Quantum resistance: false Routes: - Peers count: 2/3 Connected CopyCopied! The peer with IP `100.119.85.4` wasn't returned because it was not connected ### [ssh](https://docs.netbird.io/get-started/cli#ssh) Command to connect via SSH to a remote peer in your NetBird network. The `ssh` command has several subcommands for different operations. Before using this command, make sure that SSH Access is enabled both on the target peer and in the NetBird Dashboard. Learn more about [enabling SSH access](https://docs.netbird.io/manage/peers/ssh) . #### [ssh (connect)](https://docs.netbird.io/get-started/cli#ssh-connect) Connect to a remote peer via SSH with an interactive shell or execute a command. **Flags:** -L, --local-forward string Local port forwarding (e.g., 8080:localhost:80) -R, --remote-forward string Remote port forwarding (e.g., 8080:localhost:3000) -p, --port int Remote SSH port (default: 22) CopyCopied! **Arguments:** * `user@host`: The remote user and NetBird peer IP address * `[command]`: Optional command to execute on the remote peer **Usage:** Interactive shell: netbird ssh user@100.119.230.104 CopyCopied! Execute a single command: netbird ssh user@100.119.230.104 "uptime" CopyCopied! Local port forwarding (forward local port 8080 to remote port 80): netbird ssh -L 8080:localhost:80 user@100.119.230.104 CopyCopied! Remote port forwarding (forward remote port 8080 to local port 3000): netbird ssh -R 8080:localhost:3000 user@100.119.230.104 CopyCopied! Port forwarding must be enabled on the SSH server using `--enable-ssh-local-port-forwarding` and/or `--enable-ssh-remote-port-forwarding` flags. For SFTP and SCP, use native clients (`sftp` and `scp` commands) which work with NetBird SSH automatically. #### [Troubleshooting](https://docs.netbird.io/get-started/cli#troubleshooting) **Connection fails:** * Ensure SSH is enabled on the target peer: netbird up --allow-server-ssh CopyCopied! * Verify SSH Access is enabled in the dashboard (Peers > your\_peer > SSH Access) * Check that an ACL policy allows TCP port 22022 **Authentication fails:** * Complete the OIDC flow when prompted (browser window will open) * Verify your IdP is properly configured * To disable JWT authentication: `netbird up --allow-server-ssh --disable-ssh-auth` **Port forwarding not working:** * Ensure the server has the appropriate flags: netbird up --allow-server-ssh \ --enable-ssh-local-port-forwarding \ --enable-ssh-remote-port-forwarding CopyCopied! ![netbird ssh dashboard](https://docs.netbird.io/docs-static/img/manage/peers/ssh/ssh-dashboard.png) ### [expose](https://docs.netbird.io/get-started/cli#expose) Command to expose a local port to the public internet via the NetBird reverse proxy. The service remains active as long as the command is running and is automatically removed when you stop it. Before using this command, make sure the NetBird client is connected (`netbird up`), and that the **Peer Expose** feature is enabled by your account administrator in **Settings** > **Clients**. See [Expose from CLI](https://docs.netbird.io/manage/reverse-proxy/expose-from-cli) for the complete guide. #### [Flags](https://docs.netbird.io/get-started/cli#flags-3) --with-pin string Protect the exposed service with a 6-digit PIN (e.g. --with-pin 123456) --with-password string Protect the exposed service with a password (e.g. --with-password my-secret) --with-user-groups strings Restrict access to specific user groups (e.g. --with-user-groups devops,Backend) --with-custom-domain string Custom domain for the exposed service, must be configured to your account (e.g. --with-custom-domain myapp.example.com) --with-name-prefix string Prefix for the generated service name (e.g. --with-name-prefix my-app) --protocol string Protocol to use: 'http' or 'https' (e.g. --protocol http) (default "http") CopyCopied! #### [Usage](https://docs.netbird.io/get-started/cli#usage-5) Expose a local HTTP server running on port 8080: netbird expose 8080 CopyCopied! This will output: Service exposed successfully! Name: my-service-abc123 URL: https://my-service-abc123.proxy.example.com Domain: my-service-abc123.proxy.example.com Protocol: http Port: 8080 Press Ctrl+C to stop exposing. CopyCopied! Expose with PIN protection (must be exactly 6 digits): netbird expose 3000 --with-pin 123456 CopyCopied! Expose with password protection and a custom name prefix: netbird expose 8080 --with-password my-secret --with-name-prefix my-app CopyCopied! Expose with SSO user group restriction: netbird expose 8080 --with-user-groups engineering,devops CopyCopied! Expose using a custom domain (must be pre-configured in your account): netbird expose 8080 --with-custom-domain app.example.com CopyCopied! Press `Ctrl+C` to stop exposing the service. The service is automatically removed from the reverse proxy when the command exits. Each peer can have up to 10 active expose sessions simultaneously. The session is kept alive with automatic renewals every 30 seconds and expires after 90 seconds if the client disconnects unexpectedly. ### [version](https://docs.netbird.io/get-started/cli#version) Outputs the `netbird` command version. #### [Usage](https://docs.netbird.io/get-started/cli#usage-6) The minimal form of running the command is: netbird version CopyCopied! This will output: 0.8.2 CopyCopied! ### [service](https://docs.netbird.io/get-started/cli#service) The service command is a top-level command with subcommands to perform operations related to the daemon service. You should run the service command with elevated permissions. ### [service install](https://docs.netbird.io/get-started/cli#service-install) The install installs the daemon service on the system. #### [Usage](https://docs.netbird.io/get-started/cli#usage-7) The minimal form of running the command is: sudo netbird service install CopyCopied! You can use the global flags to configure the daemon service. For instance, you can set a debug log level with the flag `--log-level` sudo netbird service install --log-level debug CopyCopied! You can set a custom configuration path with the flag `--config` sudo netbird service install --config /opt/netbird/config.json CopyCopied! #### [Service-specific flags](https://docs.netbird.io/get-started/cli#service-specific-flags) --disable-profiles Disables profiles feature. If enabled, the client will not be able to change or edit any profile. To persist this setting, use: netbird service install --disable-profiles --disable-update-settings Disables update settings feature. If enabled, the client will not be able to change or edit any settings. To persist this setting, use: netbird service install --disable-update-settings CopyCopied! The `--disable-profiles` flag can also be set using the `NB_DISABLE_PROFILES` environment variable. Set it to any value (e.g., `true`, `1`, `yes`) to enable this feature. The `--disable-update-settings` flag can also be set using the `NB_DISABLE_UPDATE_SETTINGS` environment variable. Set it to any value (e.g., `true`, `1`, `yes`) to enable this feature. ### [service uninstall](https://docs.netbird.io/get-started/cli#service-uninstall) The uninstall uninstalls the daemon service from the system. #### [Usage](https://docs.netbird.io/get-started/cli#usage-8) The minimal form of running the command is: sudo netbird service uninstall CopyCopied! ### [service start](https://docs.netbird.io/get-started/cli#service-start) Starts the daemon service #### [Usage](https://docs.netbird.io/get-started/cli#usage-9) The minimal form of running the command is: sudo netbird service start CopyCopied! If you installed the service with `--disable-profiles` or `--disable-update-settings`, these settings will persist and the respective features will remain disabled when the service starts. ### [service stop](https://docs.netbird.io/get-started/cli#service-stop) Stops the daemon service #### [Usage](https://docs.netbird.io/get-started/cli#usage-10) The minimal form of running the command is: sudo netbird service stop CopyCopied! ### [service restart](https://docs.netbird.io/get-started/cli#service-restart) Restarts the daemon service #### [Usage](https://docs.netbird.io/get-started/cli#usage-11) The minimal form of running the command is: sudo netbird service restart CopyCopied! ### [service status](https://docs.netbird.io/get-started/cli#service-status) Shows the status of the daemon service #### [Usage](https://docs.netbird.io/get-started/cli#usage-12) The minimal form of running the command is: sudo netbird service status CopyCopied! ### [service reconfigure](https://docs.netbird.io/get-started/cli#service-reconfigure) Reconfigures the daemon service with current settings #### [Usage](https://docs.netbird.io/get-started/cli#usage-13) The minimal form of running the command is: sudo netbird service reconfigure CopyCopied! If you installed the service with `--disable-profiles` or `--disable-update-settings`, these settings will persist and the respective features will remain disabled after reconfiguration. ### [debug](https://docs.netbird.io/get-started/cli#debug) The `debug` command provides tools for diagnosing and understanding the internal operations of the NetBird daemon. #### [Usage](https://docs.netbird.io/get-started/cli#usage-14) To access debugging options: netbird debug [command] CopyCopied! #### [Subcommands](https://docs.netbird.io/get-started/cli#subcommands) * `bundle`: Create a debug bundle that includes logs and system information for troubleshooting. * `for`: Run the daemon with trace logging for a specified duration and create a debug bundle. * `log`: Manage logging levels for the NetBird daemon. #### [Flags](https://docs.netbird.io/get-started/cli#flags-4) -h, --help help for debug CopyCopied! ### [debug bundle](https://docs.netbird.io/get-started/cli#debug-bundle) Generates a compressed archive containing diagnostic information, which can be used for troubleshooting. The file will be generated in the a temporary directory and the path will be printed to the console. The file is only accessible as root/Administrator. #### [Usage](https://docs.netbird.io/get-started/cli#usage-15) To create a debug bundle: netbird debug bundle [-A] [-S] CopyCopied! #### [Examples](https://docs.netbird.io/get-started/cli#examples) Create a debug bundle: netbird debug bundle CopyCopied! This will output: /tmp/netbird.debug.676945815.zip CopyCopied! #### [Flags](https://docs.netbird.io/get-started/cli#flags-5) -h, --help help for bundle -A, --anonymize anonymize IP addresses and non-netbird.io domains in the debug output -S, --system-info Adds system information to the debug bundle CopyCopied! ### [debug for](https://docs.netbird.io/get-started/cli#debug-for) Sets the logging level to trace, runs for the specified duration, and then generates a debug bundle. This is useful for capturing detailed logs over a period where issues are occurring. #### [Usage](https://docs.netbird.io/get-started/cli#usage-16) To run debugging for a specific time period: netbird debug for