NetBird

https://docs.netbird.io
Admin
NetBird is an open-source Zero Trust Networking platform that creates secure, high-performance,...
Tokens:383,685
Snippets:4,396
Trust Score:8.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Create Setup Key Response

Source: https://docs.netbird.io/api/resources/setup-keys

Example JSON response returned after successfully creating a setup key.

```JSON
{
  "id": 2531583362,
  "name": "Default key",
  "expires": "2023-06-01T14:47:22.291057Z",
  "type": "reusable",
  "valid": true,
  "revoked": false,
  "used_times": 2,
  "last_used": "2023-05-05T09:00:35.477782Z",
  "state": "valid",
  "auto_groups": [
    "ch8i4ug6lnn4g9hqv7m0"
  ],
  "updated_at": "2023-05-05T09:00:35.477782Z",
  "usage_limit": 0,
  "ephemeral": true,
  "allow_extra_dns_labels": true,
  "key": "A616097E-FCF0-48FA-9354-CA4A61142761"
}
```

--------------------------------

### GET /api/instance

Source: https://docs.netbird.io/selfhosted/identity-providers/local

Checks if the instance requires initial setup.

```APIDOC
## GET /api/instance

### Description
Checks the current setup status of the instance to determine if an owner account needs to be created.

### Method
GET

### Endpoint
/api/instance

### Response
#### Success Response (200)
- **setup_required** (boolean) - Indicates if the instance setup wizard is required.
```

--------------------------------

### Automated Deployment with Setup Key

Source: https://docs.netbird.io/get-started/install/windows

Combine silent installation with a setup key for fully automated peer registration.

```bash
netbird_installer_<VERSION>_windows_amd64.exe /S
netbird up --setup-key <SETUP KEY>
```

```bash
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet
netbird up --setup-key <SETUP KEY>
```

--------------------------------

### Install and start daemon service manually

Source: https://docs.netbird.io/get-started/install/macos

Registers and starts the launchd daemon for the manually installed binary.

```bash
  sudo netbird service install
  sudo netbird service start
```

--------------------------------

### Setup Key Response Schema

Source: https://docs.netbird.io/api/resources/setup-keys

Example JSON response structure for a setup key object.

```JSON
[
  {
    "id": 2531583362,
    "name": "Default key",
    "expires": "2023-06-01T14:47:22.291057Z",
    "type": "reusable",
    "valid": true,
    "revoked": false,
    "used_times": 2,
    "last_used": "2023-05-05T09:00:35.477782Z",
    "state": "valid",
    "auto_groups": [
      "ch8i4ug6lnn4g9hqv7m0"
    ],
    "updated_at": "2023-05-05T09:00:35.477782Z",
    "usage_limit": 0,
    "ephemeral": true,
    "allow_extra_dns_labels": true,
    "key": "A6160****"
  }
]
```

--------------------------------

### Deploy Managed NetBird Service

Source: https://docs.netbird.io/get-started/cli

Example of installing the service with a setup key and restricted configuration features.

```bash
sudo netbird service install \
  --setup-key AAAA-BBB-CCC-DDDDDD \
  --disable-profiles \
  --disable-update-settings
```

--------------------------------

### GET /api/setup-keys

Source: https://docs.netbird.io/api/resources/setup-keys

Retrieves a list of all setup keys associated with the account.

```APIDOC
## GET /api/setup-keys

### Description
Returns a list of all Setup Keys.

### Method
GET

### Endpoint
/api/setup-keys

### Response
#### Success Response (200)
- **id** (integer) - Key ID
- **name** (string) - Key name
- **expires** (string) - Expiration timestamp
- **type** (string) - Key type (reusable/one-off)
- **valid** (boolean) - Validity status
- **revoked** (boolean) - Revocation status
- **used_times** (integer) - Number of times used
- **last_used** (string) - Last usage timestamp
- **state** (string) - Current state
- **auto_groups** (array) - List of group IDs
- **updated_at** (string) - Last update timestamp
- **usage_limit** (integer) - Usage limit
- **ephemeral** (boolean) - Ephemeral status
- **allow_extra_dns_labels** (boolean) - DNS label permission
- **key** (string) - The setup key value
```

--------------------------------

### List all Setup Keys

Source: https://docs.netbird.io/api/resources/setup-keys

Retrieves a list of all existing setup keys.

```cURL
curl -X GET https://api.netbird.io/api/setup-keys \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>'
```

--------------------------------

### GET /api/setup-keys/{keyId}

Source: https://docs.netbird.io/api/resources/setup-keys

Retrieve information about a specific setup key using its unique identifier.

```APIDOC
## GET /api/setup-keys/{keyId}

### Description
Retrieve information about a setup key.

### Method
GET

### Endpoint
/api/setup-keys/{keyId}

### Parameters
#### Path Parameters
- **keyId** (string) - Required - The unique identifier of a setup key

### Response
#### Success Response (200)
- **id** (number) - Unique identifier
- **name** (string) - Key name
- **expires** (string) - Expiration timestamp
- **type** (string) - Key type
- **valid** (boolean) - Validity status
- **revoked** (boolean) - Revocation status
- **used_times** (number) - Number of times used
- **last_used** (string) - Last used timestamp
- **state** (string) - Current state
- **auto_groups** (string[]) - List of auto-assigned group IDs
- **updated_at** (string) - Last update timestamp
- **usage_limit** (number) - Usage limit
- **ephemeral** (boolean) - Ephemeral status
- **allow_extra_dns_labels** (boolean) - DNS label status
- **key** (string) - The setup key string
```

--------------------------------

### Install NetBird on Solus

Source: https://docs.netbird.io/get-started/install/linux

Install the client and desktop app using eopkg.

```bash
sudo eopkg update-repo
sudo eopkg upgrade
sudo eopkg install netbird
sudo systemctl enable --now netbird.service
```

```bash
sudo eopkg install netbird-ui
```

--------------------------------

### Start NetBird service on Homebrew

Source: https://docs.netbird.io/get-started/install/linux

Install and start the NetBird daemon service using the Homebrew path.

```bash
  sudo /home/linuxbrew/.linuxbrew/bin/netbird service install
  sudo /home/linuxbrew/.linuxbrew/bin/netbird service start
```

--------------------------------

### Create a Setup Key

Source: https://docs.netbird.io/api/resources/setup-keys

Creates a new setup key with the specified configuration parameters.

```cURL
curl -X POST https://api.netbird.io/api/setup-keys \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "name": "Default key",
  "type": "reusable",
  "expires_in": 86400,
  "auto_groups": [
    "ch8i4ug6lnn4g9hqv7m0"
  ],
  "usage_limit": 0,
  "ephemeral": true,
  "allow_extra_dns_labels": true
}'
```

--------------------------------

### View NetBird Configuration File Directory Structure

Source: https://docs.netbird.io/selfhosted/maintenance/configuration-files

Displays the standard file layout in the installation directory after running the setup script.

```bash
./
├── docker-compose.yml
├── config.yaml
├── dashboard.env
└── nginx-netbird.conf      # Only when using Nginx reverse proxy
    npm-advanced-config.txt  # Only when using Nginx Proxy Manager
    caddyfile-netbird.txt    # Only when using Caddy reverse proxy
```

--------------------------------

### Install CLI-only binary via script

Source: https://docs.netbird.io/get-started/install/macos

Downloads and installs the standalone binary without the desktop UI, with options for initial installation and updates.

```bash
curl -fsSL https://pkgs.netbird.io/install.sh | USE_BIN_INSTALL=true SKIP_UI_APP=true sh
```

```bash
curl -fsSL https://pkgs.netbird.io/install.sh | USE_BIN_INSTALL=true SKIP_UI_APP=true UPDATE_NETBIRD=true sh
```

--------------------------------

### Run Installation Script

Source: https://docs.netbird.io/selfhosted/selfhosted-quickstart

Downloads and executes the NetBird installation script to set up a production-ready environment.

```bash
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash
```

--------------------------------

### Install jq or curl

Source: https://docs.netbird.io/selfhosted/selfhosted-quickstart

Commands to install necessary utilities on Linux systems.

```bash
sudo apt install jq
```

```bash
sudo yum install jq
```

```bash
sudo apt install curl
```

```bash
sudo yum install curl
```

--------------------------------

### Install NetBird via Binary

Source: https://docs.netbird.io/get-started/install/linux

Download, decompress, and install the NetBird binary manually.

```bash
  curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
```

```bash
  tar xzf ./netbird_<VERSION>.tar.gz
  sudo mv netbird /usr/bin/netbird
  sudo chown root:root /usr/bin/netbird
  sudo chmod +x /usr/bin/netbird
```

```bash
  export PATH=$PATH:/usr/bin
```

```bash
  sudo netbird service install
  sudo netbird service start
```

--------------------------------

### Install NetBird on Ubuntu/Debian

Source: https://docs.netbird.io/get-started/install/linux

Configure the APT repository and install the CLI or desktop application.

```bash
 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
```

```bash
 sudo apt-get update
```

```bash
 # for CLI only
 sudo apt-get install netbird
 # for the desktop app (Ubuntu 24.04+ / Debian 13+)
 sudo apt-get install netbird-ui libgtk-4-1 libwebkitgtk-6.0-4 xdg-utils
```

--------------------------------

### newsyslog configuration example

Source: https://docs.netbird.io/help/troubleshooting-client

Example entry for /etc/newsyslog.d/netbird.conf to manage NetBird logs on macOS or BSD.

```text
# logfilename                  [owner:group]  mode count size when flags
/var/log/netbird/client.log    root:wheel     600  10    15360 *   Z
```

--------------------------------

### Install NetBird on openSUSE

Source: https://docs.netbird.io/get-started/install/linux

Add the repository and install NetBird using zypper or transactional-update for MicroOS.

```bash
sudo zypper addrepo https://pkgs.netbird.io/yum/ netbird
```

```bash
# MicroOS (immutable OS with selinux)
transactional-update pkg in netbird
reboot

# Tumbleweed / Leap
zypper in netbird
```

--------------------------------

### Trace Output Examples

Source: https://docs.netbird.io/get-started/cli

Examples of command output for allowed, denied, and routed packet scenarios.

```bash
$ netbird debug trace in 100.64.1.1 self -p tcp --dport 22 --syn

Packet trace 100.64.1.1:54728 → self:22 (TCP)

Received:            Received TCP packet: 100.64.1.1:54728 -> 100.64.0.1:22
Inbound Port DNAT:   TCP port DNAT applied: 100.64.0.1:22 -> 100.64.0.1:22022
Inbound 1:1 NAT:     1:1 NAT not enabled
Connection Tracking: No existing connection found
Routing:             Packet destined for local delivery
Peer ACL:            Allowed by peer ACL rules (d2kab80l3is5mqgsj2b0)
Completed:           Processing completed

Final disposition: ALLOWED
```

```bash
$ netbird debug trace in 100.64.2.1 self -p tcp --dport 80 --syn

Packet trace 100.64.2.1:58026 → self:80 (TCP)

Received:            Received TCP packet: 100.64.2.1:58026 -> 100.64.0.1:80
Inbound Port DNAT:   No matching port DNAT rule
Inbound 1:1 NAT:     1:1 NAT not enabled
Connection Tracking: No existing connection found
Routing:             Packet destined for local delivery
Peer ACL:            Blocked by peer ACL rules
Completed:           Packet dropped - ACL denied

Final disposition: DENIED
```

```bash
$ netbird debug trace in 100.64.1.1 10.10.0.1 -p tcp --dport 443 --syn

Packet trace 100.64.1.1:49659 → 10.10.0.1:443 (TCP)

Received:            Received TCP packet: 100.64.1.1:49659 -> 10.10.0.1:443
Inbound Port DNAT:   No matching port DNAT rule
Inbound 1:1 NAT:     1:1 NAT not enabled
Connection Tracking: No existing connection found
Routing:             Routing enabled, checking ACLs
Route ACL:           Allowed by route ACLs (d1se3g0l3is3n6ucpmt0)
Forwarding:          Forwarding to proxy-remote [proxy-remote to 10.10.0.1:443]
Completed:           Processing completed

Final disposition: ALLOWED
```

--------------------------------

### POST /api/setup

Source: https://docs.netbird.io/selfhosted/identity-providers/local

Completes the initial instance setup by creating the owner account.

```APIDOC
## POST /api/setup

### Description
Creates the initial owner account for the instance. This endpoint is typically used for automated deployments.

### Method
POST

### Endpoint
/api/setup

### Request Body
- **email** (string) - Required - The owner email address.
- **password** (string) - Required - The owner password (minimum 8 characters).
- **name** (string) - Optional - The owner name.

### Response
#### Success Response (200)
- **user_id** (string) - The created owner user ID.
- **account_id** (string) - The created account ID.
```

--------------------------------

### Automated Instance Setup via API

Source: https://docs.netbird.io/selfhosted/identity-providers/local

Check if setup is required and complete the initial instance configuration programmatically.

```bash
# Check if setup is required
curl "https://netbird.example.com/api/instance"

# Response when setup is needed:
{
  "setup_required": true
}

# Complete setup
curl -X POST "https://netbird.example.com/api/setup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "securepassword123",
    "name": "Admin User"
  }'

# Response:
{
  "user_id": "user-abc123",
  "account_id": "account-xyz789"
}
```

--------------------------------

### Configure Basic Setup

Source: https://docs.netbird.io/selfhosted/environment-variables

Defines the primary domain and Let's Encrypt email for the deployment.

```bash
# setup.env
NETBIRD_DOMAIN="netbird.example.com"
NETBIRD_LETSENCRYPT_EMAIL="admin@example.com"
```

--------------------------------

### Connect with Setup Key and Custom Management URL

Source: https://docs.netbird.io/get-started/install

Authenticate using a setup key while specifying a custom management service URL.

```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```

--------------------------------

### Start daemon service after CLI-only Homebrew install

Source: https://docs.netbird.io/get-started/install/macos

Required steps to initialize the daemon service when installing the CLI-only package.

```bash
 sudo netbird service install
 sudo netbird service start
```

--------------------------------

### Start and verify proxy instance

Source: https://docs.netbird.io/selfhosted/maintenance/scaling/multiple-proxy-instances

Commands to initialize the containers and monitor logs for successful registration.

```bash
docker compose pull
docker compose up -d

# Verify the proxy is running
docker compose logs -f proxy
```

--------------------------------

### POST /api/setup-keys

Source: https://docs.netbird.io/api/resources/setup-keys

Creates a new setup key for registering peers.

```APIDOC
## POST /api/setup-keys

### Description
Creates a new setup key.

### Method
POST

### Endpoint
/api/setup-keys

### Parameters
#### Request Body
- **name** (string) - Required - Setup Key name
- **type** (string) - Required - Setup key type (one-off or reusable)
- **expires_in** (integer) - Required - Expiration time in seconds (86400 to 31536000)
- **auto_groups** (string[]) - Required - List of group IDs to auto-assign
- **usage_limit** (integer) - Required - Number of times this key can be used (0 for unlimited)
- **ephemeral** (boolean) - Optional - Indicate if the peer will be ephemeral
- **allow_extra_dns_labels** (boolean) - Optional - Allow extra DNS labels

### Request Example
{
  "name": "Default key",
  "type": "reusable",
  "expires_in": 86400,
  "auto_groups": ["ch8i4ug6lnn4g9hqv7m0"],
  "usage_limit": 0,
  "ephemeral": true,
  "allow_extra_dns_labels": true
}

### Response
#### Success Response (200)
- **id** (integer) - Key ID
- **name** (string) - Key name
- **expires** (string) - Expiration timestamp
- **type** (string) - Key type
- **valid** (boolean) - Validity status
- **revoked** (boolean) - Revocation status
- **used_times** (integer) - Number of times used
- **last_used** (string) - Last usage timestamp
- **state** (string) - Current state
- **auto_groups** (array) - List of group IDs
- **updated_at** (string) - Last update timestamp
- **usage_limit** (integer) - Usage limit
- **ephemeral** (boolean) - Ephemeral status
- **allow_extra_dns_labels** (boolean) - DNS label permission
- **key** (string) - The created setup key value
```

--------------------------------

### NetBird Windows EXE Installation Script

Source: https://docs.netbird.io/manage/for-partners/acronis-integration

Automates the download and silent installation of the NetBird EXE installer. Requires Administrator privileges and supports optional setup keys and management URLs.

```powershell
# NetBird Windows Installation Script
# Requires Administrator privileges

param(
    [string]$SetupKey = "",
    [string]$ManagementUrl = "",
    [switch]$Silent = $true
)

# Check if running as Administrator
if (-NOT ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) {
    Write-Error "This script requires Administrator privileges. Please run as Administrator."
    exit 1
}

try {
    # Define variables
    $TempDir = $env:TEMP
    $NetBirdInstaller = "$TempDir\netbird-installer.exe"
    
    # Get the latest release URL from GitHub API
    Write-Host "Fetching latest NetBird release information..."
    $ReleaseInfo = Invoke-RestMethod -Uri "https://api.github.com/repos/netbirdio/netbird/releases/latest"
    
    # Find Windows installer (look for .exe file)
    $WindowsAsset = $ReleaseInfo.assets | Where-Object { $_.name -like "*windows*" -and $_.name -like "*.exe" }
    
    if (-not $WindowsAsset) {
        Write-Error "Could not find Windows installer in latest release"
        exit 1
    }
    
    $DownloadUrl = $WindowsAsset.browser_download_url
    Write-Host "Found installer: $($WindowsAsset.name)"
    
    # Download the installer
    Write-Host "Downloading NetBird installer..."
    Invoke-WebRequest -Uri $DownloadUrl -OutFile $NetBirdInstaller
    
    # Install NetBird
    Write-Host "Installing NetBird..."
    if ($Silent) {
        $InstallArgs = "/S"  # Silent installation flag for NSIS-based installers
        Start-Process -FilePath $NetBirdInstaller -ArgumentList $InstallArgs -Wait -NoNewWindow
    } else {
        Start-Process -FilePath $NetBirdInstaller -Wait
    }
    
    # Verify installation
    $NetBirdPath = "C:\Program Files\NetBird\netbird.exe"
    if (Test-Path $NetBirdPath) {
        Write-Host "NetBird installed successfully at: $NetBirdPath" -ForegroundColor Green
        
        # Start NetBird service if it exists
        $Service = Get-Service -Name "NetBird*" -ErrorAction SilentlyContinue
        if ($Service) {
            Write-Host "Starting NetBird service..."
            Start-Service $Service.Name
        }
        
        # Connect with setup key if provided
        if ($SetupKey) {
            Write-Host "Connecting NetBird with setup key..."
            $ConnectArgs = @("up", "--setup-key", $SetupKey)
            if ($ManagementUrl) {
                $ConnectArgs += @("--management-url", $ManagementUrl)
            }
            & $NetBirdPath $ConnectArgs
        }
        
    } else {
        Write-Error "Installation verification failed. NetBird not found at expected location."
        exit 1
    }
    
} catch {
    Write-Error "Installation failed: $($_.Exception.Message)"
    exit 1
} finally {
    # Cleanup
    if (Test-Path $NetBirdInstaller) {
        Remove-Item $NetBirdInstaller -Force
    }
}

Write-Host "NetBird installation completed successfully!" -ForegroundColor Green
```

--------------------------------

### Install NetBird on Routing Peers

Source: https://docs.netbird.io/manage/network-routes/use-cases/site-to-site

Use these commands to install the NetBird agent and authenticate the routing peer using a setup key.

```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_SETUP_KEY
```

--------------------------------

### Connect Using a Setup Key

Source: https://docs.netbird.io/get-started/install/macos

Authenticates the client using a setup key, suitable for unattended or automated deployments.

```bash
netbird up --setup-key <SETUP KEY>
```

```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```

--------------------------------

### Setup Instance

Source: https://docs.netbird.io/api/resources/instance

Creates the initial admin user for the instance. This endpoint is only available when setup is required and no accounts exist.

```bash
curl -X POST https://api.netbird.io/api/setup \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Token <TOKEN>' \
--data-raw '{
  "email": "admin@example.com",
  "password": "securepassword123",
  "name": "Admin User",
  "create_pat": true,
  "pat_expire_in": 30
}'
```

```json
{
  "user_id": "abc123def456",
  "email": "admin@example.com",
  "personal_access_token": "nbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

--------------------------------

### Account Response Schema

Source: https://docs.netbird.io/api/resources/accounts

Example JSON response structure for the GET /api/accounts endpoint.

```json
[
  {
    "id": "ch8i4ug6lnn4g9hqv7l0",
    "settings": {
      "peer_login_expiration_enabled": true,
      "peer_login_expiration": 43200,
      "peer_inactivity_expiration_enabled": true,
      "peer_inactivity_expiration": 43200,
      "regular_users_view_blocked": true,
      "groups_propagation_enabled": true,
      "jwt_groups_enabled": true,
      "jwt_groups_claim_name": "roles",
      "jwt_allow_groups": [
        "Administrators"
      ],
      "routing_peer_dns_resolution_enabled": true,
      "dns_domain": "my-organization.org",
      "network_range": {
        "description": "Allows to define a custom network range for the account in CIDR format",
        "type": "string",
        "format": "cidr"
      },
      "network_range_v6": "fd00:1234:5678::/64",
      "peer_expose_enabled": false,
      "peer_expose_groups": [
        "ch8i4ug6lnn4g9hqv7m0"
      ],
      "extra": {
        "peer_approval_enabled": true,
        "user_approval_required": false,
        "network_traffic_logs_enabled": true,
        "network_traffic_logs_groups": [
          "ch8i4ug6lnn4g9hqv7m0"
        ],
        "network_traffic_packet_counter_enabled": true
      },
      "lazy_connection_enabled": true,
      "auto_update_version": "0.51.2",
      "auto_update_always": false,
      "metrics_push_enabled": false,
      "agent_network_only": false,
      "dashboard_features": {
        "agent_network": true
      },
      "embedded_idp_enabled": false,
      "local_auth_disabled": false,
      "local_mfa_enabled": false,
      "ipv6_enabled_groups": [
        "ch8i4ug6lnn4g9hqv7m0"
      ]
    },
    "domain": "netbird.io",
    "domain_category": "private",
    "created_at": "2023-05-05T09:00:35.477782Z",
    "created_by": "google-oauth2|277474792786460067937",
    "onboarding": {
      "signup_form_pending": true,
      "onboarding_flow_pending": false
    }
  }
]
```

--------------------------------

### Get invite information response schema

Source: https://docs.netbird.io/api/resources/users

Example JSON response structure containing invite details.

```json
{
  "email": "user@example.com",
  "name": "John Doe",
  "expires_at": "2024-01-25T10:00:00Z",
  "valid": true,
  "invited_by": "Admin User"
}
```

--------------------------------

### User API Response Schema

Source: https://docs.netbird.io/api/resources/users

Example JSON response structure returned by the GET /api/users endpoint.

```json
[
  {
    "id": "google-oauth2|277474792786460067937",
    "email": "demo@netbird.io",
    "password": "super_secure_password",
    "name": "Tom Schulz",
    "role": "admin",
    "status": "active",
    "last_login": "2023-05-05T09:00:35.477782Z",
    "auto_groups": [
      "ch8i4ug6lnn4g9hqv7m0"
    ],
    "is_current": true,
    "is_service_user": false,
    "is_blocked": false,
    "pending_approval": false,
    "issued": "api",
    "idp_id": "okta-abc123",
    "permissions": {
      "is_restricted": {
        "type": "boolean",
        "description": "Indicates whether this User's Peers view is restricted"
      },
      "modules": {
        "networks": {
          "read": true,
          "create": false,
          "update": false,
          "delete": false
        },
        "peers": {
          "read": false,
          "create": false,
          "update": false,
          "delete": false
        }
      }
    }
  }
]
```

--------------------------------

### GET /api/instance

Source: https://docs.netbird.io/api/resources/instance

Returns the instance status including whether initial setup is required. This endpoint does not require authentication.

```APIDOC
## GET /api/instance

### Description
Returns the instance status including whether initial setup is required. This endpoint does not require authentication.

### Method
GET

### Endpoint
/api/instance

### Response
#### Success Response (200)
- **setup_required** (boolean) - Indicates if initial setup is required.

#### Response Example
{
  "setup_required": true
}
```

--------------------------------

### POST /api/setup

Source: https://docs.netbird.io/api/resources/instance

Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required.

```APIDOC
## POST /api/setup

### Description
Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required (no accounts exist and embedded IDP is enabled).

### Method
POST

### Endpoint
/api/setup

### Parameters
#### Request Body
- **email** (string) - Required - Email address for the admin user
- **password** (string) - Required - Password for the admin user (minimum 8 characters)
- **name** (string) - Required - Display name for the admin user
- **create_pat** (boolean) - Optional - If true, create a Personal Access Token for the new owner user
- **pat_expire_in** (integer) - Optional - Expiration of the Personal Access Token in days (1-365)

### Request Example
{
  "email": "admin@example.com",
  "password": "securepassword123",
  "name": "Admin User",
  "create_pat": true,
  "pat_expire_in": 30
}

### Response
#### Success Response (200)
- **user_id** (string) - The ID of the created user.
- **email** (string) - The email of the created user.
- **personal_access_token** (string) - The generated Personal Access Token (if requested).

#### Response Example
{
  "user_id": "abc123def456",
  "email": "admin@example.com",
  "personal_access_token": "nbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

--------------------------------

### Create Postinstall Script

Source: https://docs.netbird.io/manage/peers/mdm-deployment/macos-cli-pkg-deployment

Generates a postinstall script to install the launchd service and perform initial peer enrollment.

```bash
cat > scripts/postinstall << 'POSTINSTALL'
#!/bin/sh

LOG_FILE=/var/log/netbird/client_post_install.log
AGENT=/usr/local/bin/netbird

mkdir -p /var/log/netbird/

{
    echo "=== NetBird CLI postinstall: $(date) ==="

    # Install and start the daemon service
    $AGENT service install 2>/dev/null || true
    $AGENT service start || {
        echo "ERROR: Failed to start NetBird service"
        exit 1
    }

    # Enroll the peer if not already configured.
    # The config file exists once the peer has been enrolled at least once.
    CONFIG_FILE="/var/lib/netbird/config.json"
    if [ ! -f "$CONFIG_FILE" ]; then
        echo "First install detected — enrolling with setup key"
        # Replace YOUR_SETUP_KEY with your actual reusable setup key.
        # For self-hosted deployments, add: --management-url https://your-management.example.com
        $AGENT up --setup-key YOUR_SETUP_KEY
    else
        echo "Existing configuration found — skipping enrollment"
    fi

    echo "Postinstall complete"
    exit 0
} >> "$LOG_FILE" 2>&1
POSTINSTALL

chmod +x scripts/postinstall
```

--------------------------------

### NetBird Post-install Shell Script

Source: https://docs.netbird.io/manage/peers/mdm-deployment/kandji-netbird-integration

Finalizes installation by creating symlinks, starting the service, and initiating the NetBird authentication flow.

```bash
#!/bin/sh

set -x

APP=/Applications/NetBird.app
AGENT=/usr/local/bin/netbird
LOG_FILE=/var/log/netbird/client_post_install.log

mkdir -p /var/log/netbird/
mkdir -p /usr/local/bin/

{
    echo "Installing NetBird..."

    if test -d $APP; then
        echo "NetBird app copied successfully."
    else
        echo "NetBird app could not be copied to the Applications folder."
        exit 1
    fi

    ln -fs $APP/Contents/MacOS/netbird $AGENT
    if test -f $AGENT; then
        echo "NetBird binary linked successfully."
    else
        echo "NetBird could not create symlink to /usr/local/bin"
        exit 1
    fi

    $AGENT service install || true
    $AGENT service start || true
    $AGENT up --hostname YOUR_CUSTOM_HOSTNAME_HERE
    open $APP

    echo "Finished Netbird installation successfully"
    exit 0 # all good
} &> $LOG_FILE
```

--------------------------------

### Get Instance Status

Source: https://docs.netbird.io/api/resources/instance

Retrieves the current status of the instance, including whether initial setup is required. This endpoint does not require authentication.

```bash
curl -X GET https://api.netbird.io/api/instance \
-H 'Accept: application/json' \
-H 'Authorization: Token <TOKEN>' 
```

```json
{
  "setup_required": true
}
```

--------------------------------

### Example Login Failure Error Logs

Source: https://docs.netbird.io/help/troubleshooting-client

Sample error messages encountered when attempting to log in with a different user or setup key.

```text
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

```

--------------------------------

### Place certificates on the host

Source: https://docs.netbird.io/selfhosted/enterprise/getting-started

Prepare the certificate and key files with appropriate permissions in the host directory.

```bash
sudo mkdir -p /etc/netbird/certs
sudo cp /path/to/fullchain.pem /etc/netbird/certs/cert.pem
sudo cp /path/to/privkey.pem   /etc/netbird/certs/key.pem
sudo chmod 600 /etc/netbird/certs/key.pem
```

--------------------------------

### Example Integration Events

Source: https://docs.netbird.io/manage/activity/event-streaming/amazon-s3

These JSON objects represent the sample events generated in the S3 bucket upon successful integration setup.

```json
{
    "timestamp": "2024-04-11T19:01:05.381074+02:00",
    "message": "integration test",
    "id": 0,
    "initiator_id": "netbird",
    "target_id": "netbird",
    "meta": null,
    "reference": ""
}
```

```json
{
    "timestamp": "2024-04-11T19:01:08.769292+02:00",
    "message": "integration created",
    "id": 0,
    "initiator_id": "netbird",
    "target_id": "netbird",
    "meta": null,
    "reference": ""
}
```

--------------------------------

### Activate NetBird with a Setup Key

Source: https://docs.netbird.io/get-started/install/synology

Use a setup key to activate a server peer, optionally specifying a custom management URL.

```bash
  netbird up --setup-key <SETUP KEY>

```

```bash
  netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073

```

--------------------------------

### Start NetBird connection

Source: https://docs.netbird.io/get-started/cli

Commands to initialize the NetBird daemon with various configuration options like management URLs, setup keys, and logging.

```bash
netbird up
```

```bash
netbird up --management-url https://api.self-hosted.com:443
```

```bash
sudo netbird up --log-file console
```

```bash
netbird up --setup-key AAAA-BBB-CCC-DDDDDD
```

```bash
netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels vpc1,mgmt1
```

--------------------------------

### POST /api/setup

Source: https://docs.netbird.io/selfhosted/automated-setup

Initializes the NetBird instance by creating the first owner user and optionally generating a personal access token.

```APIDOC
## POST /api/setup

### Description
Creates the first owner user for the NetBird instance. Optionally generates a personal access token (PAT) if enabled in the server configuration.

### Method
POST

### Endpoint
/api/setup

### Parameters
#### Request Body
- **email** (string) - Required - Email address for the first owner user.
- **name** (string) - Required - Display name for the first owner user.
- **password** (string) - Required - Password for the first owner user.
- **create_pat** (boolean) - Optional - Set to true to request a setup PAT. Ignored unless NB_SETUP_PAT_ENABLED=true.
- **pat_expire_in** (integer) - Optional - PAT lifetime in days. Applies only when create_pat is true. Defaults to 1; allowed range is 1 to 365.

### Request Example
{
  "email": "admin@example.com",
  "name": "Admin User",
  "password": "use-a-long-random-password",
  "create_pat": true,
  "pat_expire_in": 7
}

### Response
#### Success Response (200)
- **user_id** (string) - The unique identifier for the created user.
- **email** (string) - The email address of the created user.
- **personal_access_token** (string) - The generated personal access token (if requested).

### Response Example
{
  "user_id": "abc123def456",
  "email": "admin@example.com",
  "personal_access_token": "nbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

--------------------------------

### Install NetBird via PowerShell

Source: https://docs.netbird.io/manage/for-partners/acronis-integration

Requires Administrator privileges to execute. The script supports optional setup keys and management URL parameters for automated configuration.

```powershell
# NetBird MSI Installation Script
# Requires Administrator privileges

param(
    [string]$SetupKey = "",
    [string]$ManagementUrl = "",
    [switch]$UseLatestRelease = $true
)

# Check if running as Administrator
if (-NOT ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) {
    Write-Error "This script requires Administrator privileges. Please run as Administrator."
    exit 1
}

try {
    # Define variables
    $TempDir = $env:TEMP
    $NetBirdMSI = "$TempDir\netbird-installer.msi"
    
    if ($UseLatestRelease) {
        # Get the latest release from GitHub API
        Write-Host "Fetching latest NetBird release information..."
        $ReleaseInfo = Invoke-RestMethod -Uri "https://api.github.com/repos/netbirdio/netbird/releases/latest"
        
        # Find MSI installer
        $MSIAsset = $ReleaseInfo.assets | Where-Object { $_.name -like "*windows*" -and $_.name -like "*.msi" }
        
        if (-not $MSIAsset) {
            Write-Error "Could not find Windows MSI installer in latest release"
            exit 1
        }
        
        $DownloadUrl = $MSIAsset.browser_download_url
        Write-Host "Found MSI installer: $($MSIAsset.name)"
    } else {
        # Use the direct package repository URL
        $DownloadUrl = "https://pkgs.netbird.io/windows/msi/x64/netbird_installer_windows_amd64.msi"
        Write-Host "Using direct package repository URL"
    }
    
    # Download the MSI installer
    Write-Host "Downloading NetBird MSI installer from: $DownloadUrl"
    try {
        Invoke-WebRequest -Uri $DownloadUrl -OutFile $NetBirdMSI -UseBasicParsing
        Write-Host "Download completed successfully"
    } catch {
        Write-Error "Failed to download MSI installer: $($_.Exception.Message)"
        exit 1
    }
    
    # Verify MSI file was downloaded
    if (-not (Test-Path $NetBirdMSI)) {
        Write-Error "MSI installer file not found after download"
        exit 1
    }
    
    # Install NetBird using msiexec
    Write-Host "Installing NetBird via MSI..."
    $LogFile = "$TempDir\netbird-install.log"
    
    # Build MSI installation arguments
    $MsiArgs = @(
        "/i", $NetBirdMSI,
        "/qn",           # Quiet mode, no user interface
        "/norestart",    # Do not restart automatically
        "/L*v", $LogFile # Verbose logging
    )
    
    # Add setup key if provided
    if ($SetupKey) {
        $MsiArgs += "SETUP_KEY=$SetupKey"
    }
    
    # Add management URL if provided
    if ($ManagementUrl) {
        $MsiArgs += "MANAGEMENT_URL=$ManagementUrl"
    }
    
    Write-Host "Running: msiexec $($MsiArgs -join ' ')"
    $Process = Start-Process -FilePath "msiexec.exe" -ArgumentList $MsiArgs -Wait -PassThru -NoNewWindow
    
    # Check installation result
    if ($Process.ExitCode -eq 0) {
        Write-Host "NetBird MSI installation completed successfully" -ForegroundColor Green
        
        # Verify installation
        $NetBirdPath = "C:\Program Files\NetBird\netbird.exe"
        if (Test-Path $NetBirdPath) {
            Write-Host "NetBird installed successfully at: $NetBirdPath" -ForegroundColor Green
            
            # Start NetBird service
            $Service = Get-Service -Name "*NetBird*" -ErrorAction SilentlyContinue
            if ($Service) {
                Write-Host "Starting NetBird service..."
                Start-Service $Service.Name -ErrorAction SilentlyContinue
            }
            
            # Connect with setup key if provided and not already configured via MSI properties
            if ($SetupKey -and -not $MsiArgs.Contains("SETUP_KEY")) {
                Write-Host "Connecting NetBird with setup key..."
                $ConnectArgs = @("up", "--setup-key", $SetupKey)
                if ($ManagementUrl) {
                    $ConnectArgs += @("--management-url", $ManagementUrl)
                }
                & $NetBirdPath $ConnectArgs
            }
            
        } else {
            Write-Error "Installation verification failed. NetBird not found at expected location."
            if (Test-Path $LogFile) {
                Write-Host "Installation log content:"
                Get-Content $LogFile | Select-Object -Last 20
            }
            exit 1
        }
        
    } else {
        Write-Error "MSI installation failed with exit code: $($Process.ExitCode)"
        if (Test-Path $LogFile) {
            Write-Host "Installation log content:"
            Get-Content $LogFile | Select-Object -Last 20
        }
        exit 1
    }
    
} catch {
    Write-Error "Installation failed: $($_.Exception.Message)"
    exit 1
} finally {
    # Cleanup
    if (Test-Path $NetBirdMSI) {
        Remove-Item $NetBirdMSI -Force -ErrorAction SilentlyContinue
    }
}

Write-Host "NetBird MSI installation completed successfully!" -ForegroundColor Green
```

--------------------------------

### Build the installer package with pkgbuild

Source: https://docs.netbird.io/manage/peers/mdm-deployment/macos-cli-pkg-deployment

Assemble the signed binary and scripts into a .pkg file using a Developer ID Installer certificate.

```bash
pkgbuild \
  --root pkg-root \
  --scripts scripts \
  --identifier com.your-org.netbird-cli \
  --version "${VERSION}" \
  --install-location / \
  --sign "Developer ID Installer: Your Organization (TEAMID)" \
  netbird-cli-${VERSION}.pkg
```

--------------------------------

### Provision Edge Node with User Data Script

Source: https://docs.netbird.io/use-cases/cloud/distributed-multi-cloud-ai

Automates the installation of NetBird, MicroK8s, and GPU drivers on a new VM. Replace <SETUP-KEY> with a valid NetBird setup key before execution.

```bash
#!/bin/bash
sudo hostnamectl set-hostname telekom-germany-cluster

sudo apt update

sudo DEBIAN_FRONTEND=noninteractive apt install ca-certificates curl gnupg snapd vim ubuntu-drivers-common -y
sudo curl -L https://pkgs.netbird.io/debian/public.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/netbird.gpg
sudo echo 'deb https://pkgs.netbird.io/debian stable main' | sudo tee /etc/apt/sources.list.d/netbird.list

sudo apt update && apt install netbird -y
exec 1>/root/startup.log 2>&1

sudo netbird up --setup-key <SETUP-KEY> --management-url https://api.netbird.io --hostname telekom-germany-cluster --allow-server-ssh

sudo ufw disable || true

sudo snap install microk8s --classic --channel 1.32/stable
sudo microk8s status --wait-ready

sudo usermod -a -G microk8s ubuntu
sudo chown -f -R ubuntu ~/.kube

microk8s disable ha-cluster --force
sudo microk8s status --wait-ready

for addon in dns helm3 hostpath-storage; do
  microk8s enable $addon
done

microk8s enable gpu --gpu-operator-version v25.10.0 --gpu-operator-set toolkit.env[3].name=RUNTIME_CONFIG_SOURCE --gpu-operator-set toolkit.env[3].value='file=/var/snap/microk8s/current/args/containerd.toml'

microk8s status --wait-ready

echo "End of startup.sh"
```

--------------------------------

### Enable Postgres in setup.env

Source: https://docs.netbird.io/selfhosted/maintenance/postgres-store

Set the store engine to postgres in the setup.env file for older architectures.

```bash
NETBIRD_STORE_CONFIG_ENGINE=postgres
```

--------------------------------

### Silent MSI Installation

Source: https://docs.netbird.io/get-started/install/windows

Perform an unattended installation using the MSI installer with msiexec.

```bash
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet
```

--------------------------------

### Silent EXE Installation

Source: https://docs.netbird.io/get-started/install/windows

Perform an unattended installation using the EXE installer with the /S flag.

```bash
netbird_installer_<VERSION>_windows_amd64.exe /S
```

--------------------------------

### Obtain Migration Tool

Source: https://docs.netbird.io/selfhosted/migration/external-to-embedded-idp

Download or build the migration tool binary required for the transition.

```bash
# Replace VERSION with the release tag, and adjust the architecture as needed
curl -L -o netbird-idp-migrate.tar.gz \
  https://github.com/netbirdio/netbird/releases/download/v0.67.2/netbird-idp-migrate_0.67.2_linux_amd64.tar.gz
tar xzf netbird-idp-migrate.tar.gz
chmod +x netbird-idp-migrate
```

```bash
go build -o netbird-idp-migrate ./tools/idp-migrate/
```
Tokens:
Raw