mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-20 17:36:36 +00:00
Final Doc Restructure (#497)
This commit is contained in:
Brandon Hopkins
@@ -1,75 +0,0 @@
|
||||
|
||||
# Use service users and tokens to access NetBird's public API
|
||||
|
||||
## Service Users
|
||||
|
||||
Service users are non-interactive accounts that are used to create tokens to access resources and perform actions within your organization's network using [NetBird's public API](/api).
|
||||
|
||||
Service users provide additional security by allowing you to limit the scope of access granted to the service user and void losing automated access to critical systems when employees leave the company.
|
||||
|
||||
### What can you use NetBird service users and access tokens for?
|
||||
|
||||
|
||||
Most network management operations administrators do in the [NetBird Dashboard](https://app.netbird.io) can also be done via NetBird API using service users' access tokens.
|
||||
|
||||
The most common usage scenarios:
|
||||
|
||||
- **Automated scripts**: if you need to run automated scripts or infrastructure as code tools like Ansible or Terraform that configure your NetBird network.
|
||||
- **Third-party integrations**: if you want to integrate NetBird with a third-party service, you can use a service user to provide access to your data without giving the third-party service access to your personal account.
|
||||
**Command-line tools**: if you use command-line tools like cUrl to interact with your NetBird network.
|
||||
|
||||
### Creating a service user
|
||||
|
||||
To create a service user, you'll need to log in to your organization's account at https://app.netbird.io and navigate to the "Team" -> "Service Users" section of your account.
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/service-user-overview.png" alt="service-user-overview" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
From there, you can create a new service user and specify a role that the user should have.
|
||||
User role allows read-only access, use the admin for write access.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/service-user-creation.png" alt="service-user-creation-popup" className="imagewrapper"/>
|
||||
</p>
|
||||
‚
|
||||
<Note>
|
||||
It's important to keep your service users secure, as they can provide access to sensitive data and actions within your organization. You should treat your service users like you would treat your own personal account and limit the scope of access granted to the service user.
|
||||
</Note>
|
||||
|
||||
### Creating an access token
|
||||
|
||||
To create an access token, you'll need to log in to your account and navigate to the "Team" section and look for your user or create a [service user](#service-users) to use for your API requests.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/personal-access-token-overview.png" alt="personal-access-token-overview" width="780" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
From there, you can create a new token and specify expiration for the token. You won't be able to modify your token.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/personal-access-token-creation.png" alt="personal-access-creation-popup" width="400" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
After the token was generated successfully you will see a plain version of your token to copy and store in a secure place.
|
||||
Be aware that once you close the popup it is impossible to see the plain version of the token again as NetBird only stores a hashed version of the token.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/personal-access-token-example.png" alt="personal-access-token-example" width="400" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
It's important to keep your personal access tokens secure, as they can provide access to sensitive data and actions within your account. You should treat your personal access tokens like you would treat your password and never share them with anyone else.
|
||||
</Note>
|
||||
|
||||
### Using access tokens
|
||||
|
||||
Once you have created an access token, you can use it to authenticate API requests to NetBird. See [NetBird API](/api/introduction) documentation for detailed usage.
|
||||
|
||||
For example, if you were using the API, you might include your personal access token like this:
|
||||
|
||||
```bash {{ title: 'Example request with personal access token' }}
|
||||
curl https://api.netbird.io/api/users \
|
||||
-H "Authorization: Token {token}"
|
||||
```
|
||||
|
||||
With this header included, the NetBird API would authenticate your request using your personal access token and grant you access to the resources that your user has been authorized to.
|
||||
@@ -1,636 +0,0 @@
|
||||
# Deploying NetBird with Acronis Cyber Protect Cloud
|
||||
|
||||
Acronis Cyber Protect Cloud serves as the centralized management hub for Managed Service Providers (MSPs) and enterprise IT departments, delivering comprehensive cybersecurity and data protection through a unified platform. Acronis' Remote Monitoring and Management (RMM) functionality enables IT professionals to efficiently oversee client networks, automate maintenance tasks, and remotely deploy software across Windows, macOS, and Linux machines at scale. This software deployment capability becomes particularly powerful when MSPs need to install security solutions, such as NetBird, across multiple client environments without requiring manual intervention on each endpoint.
|
||||
|
||||
NetBird offers a WireGuard-based overlay network with Zero Trust Network Access capabilities, integrating seamlessly with RMM deployment workflows. Once Acronis RMM handles the automated installation and initial configuration, NetBird delivers secure network connectivity through its peer-to-peer private network infrastructure with zero ongoing manual configuration requirements. This integration creates a streamlined operational approach where:
|
||||
|
||||
- **Acronis Cyber Protect Cloud** automates NetBird installation, manages updates, and maintains deployment compliance across client networks
|
||||
- **NetBird** establishes secure network pathways with granular access controls and direct encrypted connections
|
||||
- **Combined solution** delivers automated Zero Trust networking deployment with centralized management capabilities
|
||||
|
||||
This approach allows MSPs to deploy comprehensive Zero Trust security solutions efficiently while maintaining centralized control over both installation processes and ongoing network access policies.
|
||||
|
||||
In this hands-on tutorial, you'll learn how to use Acronis Cyber Protect Cloud software deployment capabilities to install and configure NetBird across Windows and macOS machines, creating secure, manageable network environments for distributed teams.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before beginning this tutorial, ensure you have the following prerequisites in place:
|
||||
|
||||
- A [NetBird account](https://app.netbird.io) with administrative permissions to create and manage access policies.
|
||||
- NetBird's Windows installer (`exe` or `.msi`) downloaded from the [NetBird installation documentation](https://docs.netbird.io/get-started/install/windows)
|
||||
- An active [Acronis Cyber Protect Cloud](https://www.acronis.com/en-us/products/cloud/cyber-protect/) subscription like [Cyber Protect Advanced](https://www.acronis.com/en-us/support/documentation/AcronisCyberProtect_15/index.html#editions-and-licensing.html).
|
||||
- Acronis Cyber Protect Cloud Agent [installed and registered on all target Windows and macOS machines](https://www.acronis.com/en-us/support/documentation/AcronisCyberProtect_15/index.html#installation-overview.html).
|
||||
- Administrative access to the Acronis Cyber Protect Cloud Console with [permissions to manage software deployment and device policies](https://www.acronis.com/en-us/support/documentation/AcronisCyberProtect_15/index.html#adding-administrators-acronis-account.html).
|
||||
- At least one Windows and one macOS device listed in the **All devices** screen in Acronis Protect Cloud.
|
||||
|
||||
## Setting Up NetBird Access Policies for Team-Specific Permissions
|
||||
|
||||
[NetBird's Access Control Policies](https://docs.netbird.io/manage/access-control/manage-network-access) let you implement a zero-trust security approach alongside Acronis Cyber Protect Cloud. They enable you to define precise permissions based on user groups and resource categories, ensuring that team members can only access what they need for their specific roles. This granular approach aligns with MSP requirements for managing multiple client environments with distinct access requirements.
|
||||
|
||||
These policies work in tandem with Acronis RMM's monitoring and management capabilities. While Acronis monitors system compliance and maintains device health, NetBird enforces network-level access restrictions based on predefined group memberships.
|
||||
|
||||
For example, let's create an access policy. While the steps are the same for macOS, this demonstration will use a Windows group for simplicity. Our goal is to enable the `IT Administrators` team to access the `Windows Workstations` group:
|
||||
|
||||
- Log in to your NetBird management dashboard with administrative credentials
|
||||
- Navigate to `Access Control > Policies` and click the `Add Policy` button in the upper right corner.
|
||||
- Set the source group to `IT Administrators` and the destination group to `Windows Workstations`
|
||||
- Configure the protocol and port settings based on required access patterns (e.g., TCP 22 for SSH access to servers, TCP 80 for web servers, etc.)
|
||||
|
||||
|
||||
|
||||
Provide a descriptive name for the policy, such as "IT to Windows machines" that indicates its purpose, and click `Save` to create and activate the policy.
|
||||
|
||||
|
||||
|
||||
This access policy will automatically apply to all devices managed by Acronis Cyber Protect Cloud that belong to users in the `IT Administrators` group, providing them secure access to designated resources while preventing lateral movement to unauthorized systems. The policy enforcement occurs at the network level, complementing Acronis Cyber Protect Cloud's device-level monitoring and management capabilities.
|
||||
|
||||
|
||||
|
||||
Moreover, users will only gain this network access when their devices are actively monitored and maintained through Acronis Cyber Protect Cloud, creating a comprehensive security approach where device health monitoring and network access controls work together. This combination ensures that only properly managed and compliant devices can establish secure network connections to protected resources.
|
||||
|
||||
> **Note**: For maximum security, create separate policies rather than overly broad policies for each distinct access requirement. This approach minimizes your attack surface by ensuring precise access controls aligned with job responsibilities and reducing complexity in multi-client MSP environments.
|
||||
|
||||
With these access policies configured, you can now proceed to use Acronis' software deployment capabilities to install NetBird across your managed Windows machines, ensuring that all team members have the required secure connectivity client automatically deployed and configured.
|
||||
|
||||
## Installing NetBird in Windows using Acronis Packages
|
||||
|
||||
This section demonstrates how to create a software package in Acronis Cyber Protect Cloud and deploy NetBird across your managed Windows machines using automated installation commands.
|
||||
|
||||
### Adding the NetBird Installer Package to Acronis
|
||||
|
||||
Log in to Acronis Cyber Protect Cloud, navigate to `SOFTWARE MANAGEMENT > My packages` and click the `Add package` button:
|
||||
|
||||
|
||||
|
||||
In the `General information` tab, provide a descriptive name for the package (e.g., "NetBird EXE Installer") and specify the vendor name. Optionally, add a package description and select the appropriate license type from the dropdown menu. Click `Next` to continue.
|
||||
|
||||
|
||||
|
||||
In the `Upload package` tab, enter the installer version (required field) and select the target architecture type. Click the `+ Upload` button in the top right corner to upload the NetBird installer package.
|
||||
|
||||
|
||||
|
||||
Select the NetBird installer file from your local system. Once the upload completes, click `Next` to proceed.
|
||||
|
||||
|
||||
|
||||
In the `Install / Uninstall commands` tab, configure the silent installation parameters by entering the following commands:
|
||||
|
||||
- **Installation options:** `"{{full_path}}" /S`
|
||||
- **Uninstallation options:** `{{uninstall_cmd}} /S`
|
||||
|
||||
The `/S` parameter ensures silent installation without user prompts for NetBird's EXE installer, while `{{full_path}}` and `{{uninstall_cmd}}` are Acronis variables that automatically resolve to the correct paths during deployment. Click `Next` when ready.
|
||||
|
||||
> **Note**: If you're using NetBird's MSI installer instead of the EXE installer, use `/qn` in the **Installation options** field instead of `"{{full_path}}" /S`. The **Uninstallation options** field remains the same (`{{uninstall_cmd}} /S`) for both installer types. The `/qn` parameter provides quiet installation with no user interface for MSI packages.
|
||||
|
||||
|
||||
|
||||
In the `Summary` tab, review all package configuration details for accuracy. Check the required boxes to confirm your settings and accept the End User License Agreement (EULA) terms. Click `Next` to proceed.
|
||||
|
||||
|
||||
|
||||
The `Digital signature check` tab provides security verification options for the uploaded package. Enable digital signature checking to ensure package integrity and authenticity—this represents a security best practice for enterprise deployments. Click `Add package` to complete the package creation process.
|
||||
|
||||
|
||||
|
||||
Acronis will perform the digital signature verification automatically. Once completed, you'll see a `Verified` status next to the NetBird package in your software library.
|
||||
|
||||
|
||||
|
||||
With the NetBird package successfully added to your Acronis software library, you can now proceed to deploy it across your managed Windows machines.
|
||||
|
||||
### Deploying the NetBird Package to Windows Endpoints
|
||||
|
||||
Acronis Cyber Protect Cloud provides multiple deployment methods for installing NetBird across your managed Windows machines, allowing you to choose the approach that best fits your operational workflow and scheduling requirements.
|
||||
|
||||
**Method 1: Direct Installation from Package Library**
|
||||
|
||||
To install NetBird from the available packages, navigate to `SOFTWARE MANAGEMENT > My packages` and click the three-dot menu next to the NetBird package. Select `Install` from the dropdown options.
|
||||
|
||||
|
||||
|
||||
In the `Deploy software` window, click `+ Add workloads` and select your target machines from the available endpoints.
|
||||
|
||||
|
||||
|
||||
For this example, we selected a single endpoint called `Windows-11`. Click the `Install now` button to begin the immediate deployment process.
|
||||
|
||||
|
||||
|
||||
Monitor the installation progress by navigating to `MONITORING > Activities`, where you can track the deployment status across all selected machines.
|
||||
|
||||
|
||||
|
||||
Verify successful installation by navigating to `SOFTWARE MANAGEMENT > Software inventory`, where NetBird should appear in the installed software list for each target machine.
|
||||
|
||||
|
||||
|
||||
**Method 2: Bulk Selection from Device Management**
|
||||
|
||||
Alternatively, navigate to `DEVICES > All devices` and select the checkboxes for all target endpoints you want to include in the deployment. Click on any selected device to open the right sidebar, then select `Deploy software`. This approach opens the same `Deploy software` interface with your pre-selected workloads ready for deployment.
|
||||
|
||||
|
||||
|
||||
**Method 3: Scheduled Deployment Plans**
|
||||
|
||||
For more advanced deployment control, use Acronis' deployment plans feature. Navigate to `MANAGEMENT > Software deployment plans` and click `+ Create plan` in the upper right corner.
|
||||
|
||||
|
||||
|
||||
In the `Create software deployment plan` window, click the pencil icon to customize the plan name, select either `Install` or `Uninstall` under Action, and click `Select software` to add the NetBird package. Configure your preferred deployment schedule by setting the specific date and time for automated execution.
|
||||
|
||||
|
||||
|
||||
After configuring the plan parameters, click `Create` to save the plan for future use, or click `+ Add workloads` to immediately select target endpoints and execute the deployment.
|
||||
|
||||
|
||||
|
||||
The advantage of deployment plans is that they enable scheduled, repeatable installations across multiple client environments, allowing MSPs to standardize NetBird deployments during designated maintenance windows while maintaining consistent configuration management across all managed endpoints.
|
||||
|
||||
## Installing NetBird in Windows using a PowerShell Script
|
||||
|
||||
In addition to packages, Acronis Cyber Protect Cloud allows you to install NetBird using PowerShell scripts. This method is handy to automate NetBird installation on Windows Servers, especially if you plan to use [setup keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys).
|
||||
|
||||
### Adding NetBird PowerShell Scripts to Acronis
|
||||
|
||||
To add a new PowerShell script, navigate to `MANAGEMENT > Script repository` and click the `Create script by using AI` button.
|
||||
|
||||
Paste the following script into the IDE:
|
||||
|
||||
```shell
|
||||
# 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
|
||||
```
|
||||
|
||||
The script automatically downloads the latest `.exe` installer from the official releases page and installs it using the silent flag.
|
||||
|
||||
Next, on the right sidebar:
|
||||
|
||||
- Enter a descriptive name for the script (e.g., NetBird EXE Script)
|
||||
- Ensure the `Language` is set to `PowerShell` and the `Operating system` is `Windows`.
|
||||
- If needed, Acronis lets you pass `Arguments` to the installer, such as setup keys and the management URL.
|
||||
- Once done, set the script's status to `Approved` and click `Save`.
|
||||
|
||||
|
||||
|
||||
Using a similar procedure, you can add the following script to use the MSI installer instead of the EXE installer:
|
||||
|
||||
```shell
|
||||
# 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
|
||||
```
|
||||
|
||||
The script downloads the official `.msi` installer and uses the silent flag to install NetBird on Windows machines, just as the `.exe` installer.
|
||||
|
||||
|
||||
|
||||
Likewise, you can add an **Uninstall NetBird** script:
|
||||
|
||||
```shell
|
||||
# NetBird Windows Uninstall Script
|
||||
# Requires Administrator privileges
|
||||
|
||||
param(
|
||||
[switch]$Silent = $true,
|
||||
[switch]$Force = $false
|
||||
)
|
||||
|
||||
# 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 {
|
||||
Write-Host "Starting NetBird uninstallation..." -ForegroundColor Yellow
|
||||
|
||||
# Define paths
|
||||
$NetBirdPath = "C:\Program Files\NetBird"
|
||||
$NetBirdUninstaller = "$NetBirdPath\netbird_uninstall.exe"
|
||||
$NetBirdExe = "$NetBirdPath\netbird.exe"
|
||||
|
||||
# Stop NetBird service first
|
||||
Write-Host "Stopping NetBird services..."
|
||||
try {
|
||||
$NetBirdServices = Get-Service -Name "*NetBird*" -ErrorAction SilentlyContinue
|
||||
foreach ($Service in $NetBirdServices) {
|
||||
if ($Service.Status -eq 'Running') {
|
||||
Write-Host "Stopping service: $($Service.Name)"
|
||||
Stop-Service $Service.Name -Force -ErrorAction SilentlyContinue
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
Write-Warning "Could not stop NetBird services: $($_.Exception.Message)"
|
||||
}
|
||||
|
||||
# Use NetBird CLI to uninstall service if available
|
||||
if (Test-Path $NetBirdExe) {
|
||||
try {
|
||||
Write-Host "Uninstalling NetBird service via CLI..."
|
||||
& $NetBirdExe service uninstall
|
||||
} catch {
|
||||
Write-Warning "CLI service uninstall failed: $($_.Exception.Message)"
|
||||
}
|
||||
}
|
||||
|
||||
# Stop all NetBird processes
|
||||
Write-Host "Stopping NetBird processes..."
|
||||
try {
|
||||
Get-Process | Where-Object { $_.Name -like "*netbird*" } | Stop-Process -Force -ErrorAction SilentlyContinue
|
||||
Start-Sleep -Seconds 2
|
||||
} catch {
|
||||
Write-Warning "Could not stop all NetBird processes: $($_.Exception.Message)"
|
||||
}
|
||||
|
||||
# Run the uninstaller
|
||||
if (Test-Path $NetBirdUninstaller) {
|
||||
Write-Host "Running NetBird uninstaller: $NetBirdUninstaller"
|
||||
|
||||
if ($Silent) {
|
||||
$UninstallArgs = "/S" # Silent uninstall flag
|
||||
$Process = Start-Process -FilePath $NetBirdUninstaller -ArgumentList $UninstallArgs -Wait -PassThru -NoNewWindow
|
||||
} else {
|
||||
$Process = Start-Process -FilePath $NetBirdUninstaller -Wait -PassThru
|
||||
}
|
||||
|
||||
if ($Process.ExitCode -eq 0) {
|
||||
Write-Host "NetBird uninstaller completed successfully" -ForegroundColor Green
|
||||
} else {
|
||||
Write-Warning "Uninstaller exit code: $($Process.ExitCode)"
|
||||
}
|
||||
|
||||
} else {
|
||||
Write-Warning "NetBird uninstaller not found at: $NetBirdUninstaller"
|
||||
|
||||
# Alternative: Try using Windows Uninstall via registry/WMI
|
||||
Write-Host "Attempting alternative uninstall method..."
|
||||
try {
|
||||
$UninstallEntry = Get-WmiObject -Class Win32_Product | Where-Object { $_.Name -like "*NetBird*" }
|
||||
if ($UninstallEntry) {
|
||||
Write-Host "Found NetBird in installed programs, removing..."
|
||||
$UninstallEntry.Uninstall()
|
||||
}
|
||||
} catch {
|
||||
Write-Warning "Alternative uninstall method failed: $($_.Exception.Message)"
|
||||
}
|
||||
}
|
||||
|
||||
# Verify uninstallation
|
||||
Start-Sleep -Seconds 3
|
||||
|
||||
if (Test-Path $NetBirdPath) {
|
||||
if ($Force) {
|
||||
Write-Host "Force removing remaining NetBird directory..."
|
||||
Remove-Item $NetBirdPath -Recurse -Force -ErrorAction SilentlyContinue
|
||||
} else {
|
||||
Write-Warning "NetBird directory still exists at: $NetBirdPath"
|
||||
Write-Host "Use -Force parameter to remove remaining files"
|
||||
}
|
||||
} else {
|
||||
Write-Host "NetBird directory removed successfully" -ForegroundColor Green
|
||||
}
|
||||
|
||||
# Check for remaining services
|
||||
$RemainingServices = Get-Service -Name "*NetBird*" -ErrorAction SilentlyContinue
|
||||
if ($RemainingServices) {
|
||||
Write-Warning "Some NetBird services may still be present:"
|
||||
$RemainingServices | ForEach-Object { Write-Host " - $($_.Name) ($($_.Status))" }
|
||||
} else {
|
||||
Write-Host "All NetBird services removed successfully" -ForegroundColor Green
|
||||
}
|
||||
|
||||
} catch {
|
||||
Write-Error "Uninstallation failed: $($_.Exception.Message)"
|
||||
exit 1
|
||||
}
|
||||
|
||||
Write-Host "NetBird uninstallation process completed!" -ForegroundColor Green
|
||||
```
|
||||
|
||||
The script executes `netbird_uninstall.exe` using the silent flag to remove NetBird from Windows endpoints.
|
||||
|
||||
|
||||
|
||||
If you need to edit or delete any script, you can do it by navigating to `MANAGEMENT > Script repository > My scripts`
|
||||
|
||||
### Deploying NetBird Scripts to Windows Endpoints
|
||||
|
||||
As with packages, you can use different methods to deploy NetBird scripts to Windows endpoints:
|
||||
|
||||
**Method 1: Quick Run from My scripts**
|
||||
|
||||
Navigate to `MANAGEMENT > Script repository > My scripts`, click the three-dot menu on the script you want to install, and select `Script quick run`:
|
||||
|
||||
|
||||
|
||||
Next, you can select the workloads where you want to run the script and click the `Run now` button.
|
||||
|
||||
|
||||
|
||||
As before, you can follow the installation progress by navigating to `MONITORING > Activities`.
|
||||
|
||||
**Method 2: Scheduled Scripting Plans**
|
||||
|
||||
Navigate to `MANAGEMENT > Scripting plans` and click on `Create plan`. Next:
|
||||
|
||||
- Click on the little “pencil” icon to provide a name to the plan.
|
||||
- Choose the script to run, the schedule to run it, and the maximum duration
|
||||
- Add the desired workloads
|
||||
- Once ready, click the `Create` button.
|
||||
|
||||
|
||||
|
||||
From `MANAGEMENT > Scripting plans`, you can click on the three-dot menu of any plan to view its details, edit it, or manually run it.
|
||||
|
||||
|
||||
|
||||
## Installing NetBird in macOS using a Bash Script
|
||||
|
||||
For large-scale deployments, you can automate the NetBird client installation on multiple macOS endpoints using a Bash script. This method downloads the official package directly from NetBird's GitHub releases and proceeds with the installation.
|
||||
|
||||
You can optionally use NetBird's [setup keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) to pre-authorize devices during provisioning. The key ensures that once a machine joins the network, it is automatically placed in the correct groups with all the right access permissions already applied.
|
||||
|
||||
### Adding NetBird Bash Scripts to Acronis
|
||||
|
||||
Download the most recent NetBird macOS installer script using the following command:
|
||||
|
||||
```shell
|
||||
curl -fsSL https://pkgs.netbird.io/install.sh > install.sh
|
||||
```
|
||||
|
||||
The script downloads the latest macOS package (`.pkg`) from the official NetBird releases page and perform a silent, unattended installation.
|
||||
|
||||
Next, from the Acronis console, go to `MANAGEMENT > Script repository` to create a new script for your macOS devices. Select the `Create script by using AI` option and paste the script code into the editor.
|
||||
|
||||
Configure the following properties in the right sidebar:
|
||||
|
||||
* **Name:** Enter a descriptive name for the script (e.g., `macOS Install Script`).
|
||||
* **Language settings:** Ensure the `Language` is set to `Bash` and the `Operating system` is `macOS`.
|
||||
* **Arguments:** If needed, you can pass parameters to the script through the `Arguments` field, such as setup keys for automated enrollment.
|
||||
* Once configured, set the script's status to `Approved` and click `Save`.
|
||||
|
||||
|
||||
|
||||
If you need to manage your scripts, you can do it by navigating to `MANAGEMENT > Script repository > My scripts`
|
||||
|
||||
### Deploying NetBird Scripts to macOS Endpoints
|
||||
|
||||
Once the script is saved, you can run it on-demand from `My scripts` or add it to a scripting plan to schedule its execution
|
||||
|
||||
**Method 1: Quick Run from My scripts**
|
||||
|
||||
* Navigate to `MANAGEMENT > Script repository > My scripts`.
|
||||
* Find the macOS script you created, click the three-dot menu icon next to it, and select `Script quick run`.
|
||||
* In the pop-up that opens, select the target macOS devices (workloads) for the installation.
|
||||
* Click `Run now` to deploy the script to the chosen devices.
|
||||
* To track the installation status, go to `MONITORING > Activities`.
|
||||
|
||||
|
||||
|
||||
**Method 2: Scheduled Scripting Plans**
|
||||
|
||||
This method allows you to automate the script's execution on a recurring basis.
|
||||
|
||||
First, navigate to `MANAGEMENT > Scripting plans` and click `Create plan`. In the configuration window, set up the following options:
|
||||
|
||||
* **Name the plan:** Click the pencil icon to enter a descriptive name.
|
||||
* **Choose what to run:** Select your macOS script from the list.
|
||||
* **Define the schedule:** Set the desired frequency, time, and maximum allowed runtime for the script.
|
||||
* **Select targets:** Add the macOS devices (workloads) that will be part of this plan.
|
||||
|
||||
Once all settings are configured, click `Create` to save and activate the plan.
|
||||
|
||||
|
||||
|
||||
Tip: You can manually trigger any plan outside its schedule. Go to `MANAGEMENT > Scripting plans`, find the plan you want to execute, click its three-dot menu, and run it.
|
||||
|
||||
## Confirming Endpoint Registration in NetBird
|
||||
|
||||
While Acronis Cyber Protect Cloud handles the automated deployment of NetBird clients to your Windows and macOS endpoints, client authentication operates independently through NetBird's identity provider integration system. NetBird [supports major Identity Providers (IdP)](https://docs.netbird.io/manage/team/add-users-to-your-network#identity-provider-id-p-sync), including Microsoft Entra ID, Google Workspace, Okta, and others, allowing organizations to maintain their existing authentication infrastructure.
|
||||
|
||||
For example, organizations using Microsoft 365 can use the [NetBird-Microsoft Entra ID integration](https://docs.netbird.io/manage/team/idp-sync/microsoft-entra-id-sync#get-started-with-net-bird-entra-id-integration) to automatically authenticate and synchronize users and groups from Entra ID to NetBird. This integration eliminates manual user provisioning by automatically syncing organizational structure, including group memberships and user access permissions. Once synchronized, users automatically inherit the corresponding Access Control Policies created in the initial configuration section (`IT Administrators` group has access to the `Windows Workstations` group), ensuring that network access permissions align with their organizational roles.
|
||||
|
||||
To confirm that your Acronis-deployed Windows (or macOS) endpoints successfully joined NetBird, navigate to the `Peers` menu in your NetBird dashboard. Successfully registered endpoints will appear in the peers list with their device names, connection status, and assigned IP addresses within your NetBird network.
|
||||
|
||||
This verification step ensures that your automated deployment process has completed successfully and that devices are ready to enforce the access control policies configured for your organization's security requirements.
|
||||
|
||||
|
||||
@@ -1,32 +0,0 @@
|
||||
import {Note} from "@/components/mdx";
|
||||
|
||||
# Delete your NetBird account
|
||||
To delete your NetBird organization account, you must be a user with the [owner role](/manage/team/add-users-to-your-network#manage-user-roles). You can ask the owner to delete the organization account if you are not the account owner.
|
||||
## Delete your account
|
||||
<Note>
|
||||
Before proceeding to delete your Netbird account, please be aware that this action is irreversible. Once your account is deleted, you will permanently lose access to all associated data, including your peers, users, groups, policies, and routes.
|
||||
</Note>
|
||||
|
||||
Go to the `Settings` tab, then click on `Danger Zone`. Review the message and click on the `Delete Account` button.
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/account-settings-danger-zone.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
To confirm, click on the `Delete` button.
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/account-settings-delete-account-confirm.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
After you delete your account, your session will end, and you will be redirected to the login page.
|
||||
<Note>
|
||||
If you log in again, a new account will be created.
|
||||
</Note>
|
||||
## Get started
|
||||
<p float="center" >
|
||||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
|
||||
</p>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
- Join our [Slack Channel](/slack-url)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,70 +0,0 @@
|
||||
import {Note} from "@/components/mdx";
|
||||
|
||||
# Enable post-quantum cryptography
|
||||
Post-quantum cryptography aims to mitigate risks associated with quantum computing's potential to undermine existing encryption methods.
|
||||
Current concerns include the possibility of bad actors collecting encrypted network traffic to decrypt it once quantum computers become available.
|
||||
This 'harvest and decrypt later' strategy threatens the confidentiality of presently secure communications.
|
||||
[Rosenpass](https://rosenpass.eu), a post-quantum secure protocol, addresses these concerns by offering advanced cryptographic measures to protect VPN connections against such future threats.
|
||||
|
||||
|
||||
## About Rosenpass
|
||||
[Rosenpass](https://rosenpass.eu) is a post-quantum secure key-exchange protocol that enhances [WireGuard](https://www.wireguard.com/) VPNs against quantum computer attacks.
|
||||
It employs advanced cryptographic methods [Classic McEliece](https://classic.mceliece.org) and [Kyber](https://pq-crystals.org/kyber/).
|
||||
The software is [open-source](https://github.com/rosenpass/rosenpass) and designed for easy integration with existing WireGuard installations.
|
||||
It ensures future-proof security against quantum threats by continuously generating and rotating WireGuard pre-shared keys every two minutes.
|
||||
Rosenpass can also be used as a generic key-exchange mechanism for other protocols.
|
||||
|
||||
Starting [v0.25.4](https://github.com/netbirdio/netbird/releases), the NetBird agent runs an embedded Rosenpass server
|
||||
that automatically rotates and applies WireGuard pre-shared keys to every point-to-point connection.
|
||||
<Note>
|
||||
NetBird uses a [Golang implementation](https://github.com/cunicu/go-rosenpass) of the Rosenpass protocol by the [cunīcu](https://cunicu.li) project.
|
||||
</Note>
|
||||
|
||||
## Enable Rosenpass in NetBird
|
||||
<Note>
|
||||
This is still an experimental feature, may contain bugs, and is not supported on mobile devices.
|
||||
</Note>
|
||||
Rosenpass can be enabled by setting a flag on client start-up.
|
||||
```bash
|
||||
netbird up --enable-rosenpass
|
||||
```
|
||||
Rosenpass respects a provided pre-shared key and uses it for its initial key generation. It is possible to define a manually generated pre-shared key.
|
||||
```bash
|
||||
netbird up --enable-rosenpass --preshared-key <preshared-key>
|
||||
```
|
||||
This configuration is persistent and preserved by the agent during restarts.
|
||||
|
||||
<Note>
|
||||
If the Rosenpass feature is enabled on a peer it will only be able to communicate with other peers that have Rosenpass enabled.
|
||||
</Note>
|
||||
|
||||
## Disable Rosenpass
|
||||
|
||||
To disable Rosenpass again use the following command.
|
||||
```bash
|
||||
netbird down
|
||||
netbird up --enable-rosenpass=false
|
||||
```
|
||||
|
||||
## Enable permissive mode
|
||||
|
||||
Enabling Rosenpass on one peer assumes that all peers have Rosenpass enabled. If one of the peers does not enable this feature
|
||||
or run an older version that lacks Rosenpass, the connection won't work.
|
||||
To allow non-Rosenpass enabled peers to connect to a Rosenpass peer, the permissive mode can be activated. In this case,
|
||||
the NetBird client will default to a standard WireGuard connection without pre-shared keys for those connections that
|
||||
don't support Rosenpass. It will continue negotiating PSKs with Rosenpass for the rest, ensuring enhanced security wherever possible:
|
||||
|
||||
```bash
|
||||
netbird up --enable-rosenpass --rosenpass-permissive
|
||||
```
|
||||
|
||||
|
||||
## Get started
|
||||
<p float="center" >
|
||||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
|
||||
</p>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
- Join our [Slack Channel](/slack-url)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,50 +0,0 @@
|
||||
|
||||
# Enforce periodic user authentication
|
||||
|
||||
To ensure a high level of security, NetBird offers a peer login expiration feature that requires users to periodically reauthenticate their devices.
|
||||
Every new network has this feature enabled, and the expiration period is set to 24 hours by default. You can disable this feature and configure the expiration period in the account settings in the web UI https://app.netbird.io/settings.
|
||||
|
||||
<Note>
|
||||
This feature is only applied to peers added with the [interactive SSO login feature](/get-started/install#running-net-bird-with-sso-login). Peers, added with a setup key, won't be affected.
|
||||
</Note>
|
||||
|
||||
Expired peers will appear in the peers' view with the status `Login required`.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/team/peer-needs-login.png" alt="peer-needs-login.png" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
## Configure and disable expiration
|
||||
The expiration period can be set to anything between one hour and 180 days.
|
||||
Go to the Web UI `Settings` tab and set the desired period in the Authentication section.
|
||||
You can also disable the expiration for the whole network in the same section.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/team/peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
|
||||
<Note>
|
||||
Enabling peer expiration or changing the expiration period will cause some peers added with the SSO login to disconnect,
|
||||
and re-authentication will be required.
|
||||
</Note>
|
||||
|
||||
## Disable expiration individually per peer
|
||||
Sometimes, you might want to disable peer expiration for some peers.
|
||||
With NetBird you can disable login expiration per peer without disabling expiration globally.
|
||||
In the Peers tab of the web UI click on the peer you want to disable expiration for and use the Login Expiration switch.
|
||||
Peers with `Expiration disabled` will be marked with a corresponding label in the Peers table.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/team/individual-peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
## Get started
|
||||
<p float="center" >
|
||||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
|
||||
</p>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
- Join our [Slack Channel](/slack-url)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,218 +0,0 @@
|
||||
# Deploying NetBird with Intune
|
||||
|
||||
Microsoft Intune is a cloud-based endpoint management solution that manages user access to organizational resources and simplifies app and device management across multiple platforms, including Android, iOS/iPadOS, Linux, macOS, and Windows client devices. Working alongside Microsoft Entra ID (formerly Azure Active Directory), Intune forms a powerful identity and access management framework that organizations rely on to secure digital assets.
|
||||
|
||||
When combined, Intune and Microsoft Entra ID ensure that only managed and compliant devices can access email, Microsoft 365 services, Software as a service (SaaS) apps, and on-premises applications. This integration combines multiple security signals, such as user identity, device health, and location, to enforce organizational policies using Conditional Access capabilities.
|
||||
|
||||
NetBird enhances this security ecosystem by providing a WireGuard-based overlay network with Zero Trust Network Access capabilities. While Intune focuses on device compliance and application management, NetBird provides secure network connectivity through its point-to-point private network infrastructure. This creates a complementary security approach where:
|
||||
|
||||
- **Intune** verifies device compliance and manages application policies
|
||||
- **Entra ID** provides identity verification and conditional access decisions
|
||||
- **NetBird** establishes secure network pathways with granular access controls
|
||||
|
||||
This division of security responsibilities creates a comprehensive zero-trust implementation in which devices are verified as compliant before they can establish network connections to protected resources.
|
||||
|
||||
In this hands-on tutorial, you'll learn how to deploy NetBird with Intune to grant tailored access permissions for different teams.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before beginning this tutorial, ensure you have the following prerequisites in place:
|
||||
|
||||
- Complete the tutorial [Provision Users and Groups From Microsoft Entra ID](https://docs.netbird.io/manage/team/idp-sync/microsoft-entra-id-sync) to ensure you can select Entra ID-managed users and groups within Intune.
|
||||
- A [NetBird account](https://app.netbird.io) with administrative permissions to create and manage access policies.
|
||||
- An active [Microsoft Intune license](https://learn.microsoft.com/en-us/intune/intune-service/fundamentals/licenses) (included with Microsoft 365 E3, E5, F1, F3, Enterprise Mobility + Security E3/E5, or Business Premium plans).
|
||||
- An Intune admin user with at least the [Policy and Profile Manager](https://learn.microsoft.com/en-us/intune/intune-service/fundamentals/role-based-access-control-reference#policy-and-profile-manager) built-in role (*Intune Administrator* role recommended for full control over advanced features)
|
||||
- At least one device (Windows, Mac, iPad, iPhone, Android, Linux) [enrolled in Intune](https://learn.microsoft.com/en-us/intune/intune-service/enrollment/quickstart-setup-auto-enrollment).
|
||||
|
||||
## Setting Up NetBird Access Policies for Team-Specific Permissions
|
||||
|
||||
[NetBird's Access Control Policies](https://docs.netbird.io/manage/access-control/manage-network-access) provide the foundation for implementing a zero-trust architecture with Intune. They enable you to define precise permissions based on user groups and resource categories. This ensures that team members can only access what they need for their specific roles.
|
||||
|
||||
These policies work in tandem with Intune's device compliance mechanisms, creating a powerful security layer where identity and device posture determine access rights to the network.
|
||||
|
||||
Let's create a policy that enables the `Development` team to access the `Servers` group.
|
||||
|
||||
- Log in to your NetBird management dashboard with administrative credentials
|
||||
- Navigate to `Access Control > Policies` and click the `Add Policy` button in the upper right corner.
|
||||
- Set the source group to `Development` (or the appropriate team group synchronized from Entra ID) and the destination group to `Servers`
|
||||
- Configure the protocol and port settings based on required access patterns (e.g., TCP 22 for SSH access to servers)
|
||||
|
||||
|
||||
|
||||
Provide a descriptive name for the policy, such as "Dev Team Server Access" that indicates its purpose, and click `Save` to create and activate the policy.
|
||||
|
||||
|
||||
|
||||
This access policy will automatically apply to all devices enrolled in Intune that belong to users in the `Development` group (as synchronized from **Entra ID**), providing them secure access to designated resources while preventing lateral movement to unauthorized systems.
|
||||
|
||||
Moreover, users will only gain this network access when using compliant devices that meet your organization's security standards, creating a true zero-trust environment where user identity and device security status are verified before granting resource access.
|
||||
|
||||
> **Note**: For maximum security, create separate policies rather than overly broad policies for each distinct access requirement. This approach minimizes your attack surface by ensuring precise access controls aligned with job responsibilities.
|
||||
|
||||
With these access policies in place, we can now proceed to configure the automated deployment of NetBird through Intune, ensuring that all team members have the required secure connectivity client installed on their devices.
|
||||
|
||||
## Deploying NetBird as a Win32 App
|
||||
|
||||
Opt for Win32 app deployment over the Line-of-Business (LOB) method (described in the next section) when requiring advanced features such as specific detection rules, prerequisites, dependencies, or update supersedence.
|
||||
|
||||
### Preparing the `.intunewin` File
|
||||
|
||||
Using the Win32 method requires you to convert either NetBird's `.exe` or `.msi` installer to the `.intunewin` format. Here's an overview of the procedure using the `.exe` installer:
|
||||
|
||||
- Download the Microsoft Win32 Content Prep Tool from [GitHub](https://github.com/Microsoft/Microsoft-Win32-Content-Prep-Tool)
|
||||
- Download your preferred NetBird Windows installer from the [NetBird installation documentation](https://docs.netbird.io/get-started/install/windows)
|
||||
- Run the Content Prep Tool and follow the instructions to convert the NetBird installer to `.intunewin` format. You'll be asked about the source folder (usually where you downloaded the installer), the NetBird setup file you will use, and the output folder (where you want the `.intunewin` file to be saved).
|
||||
- For detailed information on using the Win32 Content Prep Tool, refer to [Microsoft's documentation](https://learn.microsoft.com/en-us/intune/intune-service/apps/apps-win32-prepare).
|
||||
|
||||
### Adding NetBird Win32 App to Intune Catalog
|
||||
|
||||
- Sign in to the [Microsoft Intune admin center](https://intune.microsoft.com), navigate to `Apps`, and click the `Windows` button.
|
||||
|
||||
|
||||
|
||||
- Click the `+ Create` button to add a new Windows application
|
||||
|
||||
|
||||
|
||||
- In the `App type` dropdown, select `Windows app (Win32)` and click `Select`
|
||||
|
||||
|
||||
|
||||
- On the `Add App` screen, click `Select app package file` and browse to the location of the NetBird `.intunewin` file you created earlier
|
||||
|
||||
- Select the `.intunewin` file and click `OK`
|
||||
|
||||
|
||||
|
||||
- On the `App information` tab, configure NetBird with the following values:
|
||||
|
||||
- **Name**: Leave the default file name
|
||||
- **Description**: Leave the default file name
|
||||
- **Publisher**: NetBird
|
||||
- **App Version**: Enter the current app version (optional)
|
||||
- **Category**: Select any category that fits your needs (optional)
|
||||
- **Show this as a featured app in the Company Portal**: Yes
|
||||
- **Information URL**: https://docs.netbird.io/
|
||||
- **Developer**: NetBird (optional)
|
||||
|
||||
You can leave the rest of the fields empty.
|
||||
|
||||
|
||||
|
||||
- Click `Next` to advance to the `Program` tab. Use the following commands in the install and uninstall fields:
|
||||
|
||||
- **Install command:** `netbird_installer_0.43.0_windows_amd64.exe /S`
|
||||
- **Uninstall command:** `"%ProgramFiles%\Netbird\netbird_uninstall.exe" /S`
|
||||
|
||||
>**Note:** The commands above assume a standard installation using the `/S` flag to specify "silent mode". Change them accordingly if you require NetBird installed on a different path.
|
||||
|
||||
For this example, leave the rest of the configuration unchanged. Note that you can change the install behavior and users' ability to uninstall NetBird if required.
|
||||
|
||||
|
||||
|
||||
- Click `Next` to advance to the `Requirements` tab. Here you can specify the architecture and minimum OS version required for installing NetBird. For instance:
|
||||
|
||||
- **Operating system architecture:** 64-bit
|
||||
- **Minimum operating system:** Windows 10 22H2
|
||||
|
||||
|
||||
|
||||
- Click `Next` to advance to the `Detection rules` tab. Intune lets you choose between **using a custom detection script** or **manually configuring detection rules**. Select the latter and configure it as follows:
|
||||
|
||||
- **Rule type:** File
|
||||
- **Path:** `%ProgramFiles%\Netbird`
|
||||
- **File or folder:** `netbird.exe`
|
||||
- **Detection method:** File or folder exists
|
||||
- **Associated with a 32-bit app on 64-bit clients:** No
|
||||
|
||||
Click `OK` when ready.
|
||||
|
||||
|
||||
|
||||
For examples on registry-based detection rules, refer to [Intune documentation](https://learn.microsoft.com/en-us/intune/intune-service/apps/apps-win32-add#step-4-detection-rules)
|
||||
|
||||
- Click `Next` to continue to the `Dependencies` tab. In this tab, you can add any applications that must be installed before NetBird. For this demonstration, click `Next` to continue.
|
||||
|
||||
- Intune's `Supersedence` tab lets you choose between updating or entirely replacing any other specific application listed. Click `Next` without adding any apps to skip the supersedence configuration for this deployment.
|
||||
|
||||
- On the `Assignments` tab, under `Required`, click `+ Add group`
|
||||
|
||||
|
||||
|
||||
- Select the appropriate group that contains your users (like the `Development` group synchronized from Entra ID) and click `Select`
|
||||
|
||||
|
||||
|
||||
- To continue, click `Next`. Review your configuration in the `Review + create` tab, then click `Create` to add NetBird to your Intune app catalog.
|
||||
|
||||
|
||||
|
||||
- To verify that NetBird was added to Intune, navigate to `Apps > All Apps` to see your Windows applications:
|
||||
|
||||
|
||||
|
||||
## Deploying NetBird as a Line-of-business (LOB) App
|
||||
|
||||
As a simpler alternative to the Win32 method described previously, you can deploy the NetBird MSI installer directly as a Line-of-Business (LOB) app. This approach is ideal for basic deployment scenarios that don't necessitate the advanced management features offered by Win32.
|
||||
|
||||
### Adding NetBird MSI Installer to Intune
|
||||
|
||||
- Download the NetBird Windows MSI installer from the [NetBird installation documentation](https://docs.netbird.io/get-started/install/windows)
|
||||
- Sign in to the [Microsoft Intune admin center](https://intune.microsoft.com), navigate to `Apps`, and click the `Windows` button.
|
||||
|
||||
|
||||
|
||||
- Click the `+ Create` button to add a new Windows application
|
||||
|
||||
|
||||
|
||||
- In the `App type` dropdown, select `Line-of-business app` and click `Select`
|
||||
|
||||
|
||||
|
||||
- On the `Add App` screen, click `Select app package file` and browse to the location of the NetBird MSI file you downloaded earlier
|
||||
- Select the NetBird MSI installer and click `OK`
|
||||
|
||||
|
||||
|
||||
Click `Next` to configure NetBird with the following details:
|
||||
|
||||
- **Name**: NetBird
|
||||
- **Description**: NetBird
|
||||
- **Publisher**: NetBird
|
||||
- **App install context**: Device
|
||||
- **Ignore app version**: No (This ensures updates will be applied when available)
|
||||
- **Command-line arguments**: Leave empty
|
||||
- **Category**: Select any category that fits your needs (optional)
|
||||
- **Show this as a featured app in the Company Portal**: Yes
|
||||
- **Information URL**: https://docs.netbird.io/
|
||||
|
||||
You can leave the rest of the fields empty.
|
||||
|
||||
|
||||
|
||||
When ready, click `Next` to proceed to the `Assignments` tab. Under `Required`, click `+ Add group`
|
||||
|
||||
|
||||
|
||||
- Select the appropriate group that contains your users (like the `Development` group synchronized from Entra ID) and click `Select`
|
||||
|
||||
|
||||
|
||||
- To continue, click `Next`. Review your configuration in the `Review + create` tab, then click `Create` to add NetBird to your Intune app catalog.
|
||||
|
||||
|
||||
|
||||
After adding NetBird, you'll see an overview screen for the NetBird app, showing deployment status and management options.
|
||||
|
||||
|
||||
|
||||
To verify that NetBird was added to Intune, navigate to `Home > Apps | Windows` to see all your Windows applications:
|
||||
|
||||
|
||||
|
||||
### Deploying NetBird to Other Platforms
|
||||
|
||||
While each platform has slightly different configuration options, adding NetBird and assigning it to groups follows the same pattern across Intune. For more information, refer to [Intune app management](https://learn.microsoft.com/en-us/intune/intune-service/apps/app-management).
|
||||
|
||||
With NetBird successfully deployed through Intune, your organization has the foundation for implementing a comprehensive zero-trust access model that verifies user identity and device compliance before granting network access.
|
||||
@@ -1,150 +0,0 @@
|
||||
# Deploying NetBird's with Jamf Pro
|
||||
|
||||
Integrating NetBird with Jamf Pro's robust device management capabilities creates a scalable system for secure access management across your entire Apple ecosystem.
|
||||
|
||||
This comprehensive tutorial guides you through deploying NetBird on Apple devices using Jamf Pro, covering:
|
||||
|
||||
1. Setting up NetBird Access Policies for Team-Specific Permissions
|
||||
2. Creating a Jamf Pro Policy for Automated NetBird Deployment
|
||||
3. Verifying the Automated Provisioning Process
|
||||
|
||||
By following these steps, you'll establish an automated pipeline that:
|
||||
|
||||
* Streamlines network security management
|
||||
* Minimizes manual configuration errors
|
||||
* Ensures appropriate access levels for each team in your organization
|
||||
|
||||
This integration enhances your organization's security posture while simplifying remote access management for your Apple devices.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before beginning the integration process, make sure you have the following:
|
||||
|
||||
* A [NetBird account](https://app.netbird.io/) with administrative privileges.
|
||||
* A [Jamf Pro subscription](https://www.jamf.com/request-trial/) with administrative permissions.
|
||||
* A valid [Jamf Pro Push Certificate](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Push_Certificates.html).
|
||||
* At least one Apple device (Mac, iPhone, or iPad) enrolled in Jamf Pro.
|
||||
|
||||
These requirements are essential for successfully implementing NetBird-Jamf Pro integration and managing your Apple devices securely.
|
||||
|
||||
## Setting Up NetBird Access Policies for Team-Specific Permissions
|
||||
|
||||
NetBird's [Access Control Policies](https://docs.netbird.io/manage/access-control/manage-network-access) are essential to this integration, allowing you to define and enforce specific permissions for different user groups. This ensures that team members can only access the resources necessary for their roles.
|
||||
|
||||
For this tutorial, we'll create a policy that allows the `Support` team to access the `Servers` group:
|
||||
|
||||
* Log in to your NetBird dashboard.
|
||||
* Navigate to `Access Control > Policies` and click `Add Policy`.
|
||||
* Set the source group to `Support` and the destination group to `Servers`.
|
||||
* Configure the appropriate protocol and port settings (e.g., TCP 22 for SSH access).
|
||||
|
||||
|
||||
|
||||
Give the policy a descriptive name (e.g., "Support team remote access") and click `Save` to create the policy.
|
||||
|
||||
|
||||
|
||||
With this policy in place, any device assigned to the `Support` group will gain access to the `Servers` group as defined in the Access Control Policy.
|
||||
|
||||
Now that NetBird is configured, let's proceed to the next step: setting up Jamf Pro to deploy NetBird on support team devices.
|
||||
|
||||
## Creating Jamf Pro Policy for Automated NetBird Deployment
|
||||
|
||||
To deploy NetBird using Jamf Pro, you need to [upload the NetBird package](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Package_Deployment.html) to Jamf and then [configure a policy](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Policy_Management.html) that includes the package.
|
||||
|
||||
### Uploading NetBird Package
|
||||
|
||||
Navigate to `Settings > Computer management > Packages` and click `+ New`.
|
||||
|
||||
In the `General` tab:
|
||||
* Enter a descriptive **Display name** (e.g., NetBird_vX.XX_Support_Team, where X.XX is the current NetBird version).
|
||||
* Optionally, assign a **Category** (e.g., VPN).
|
||||
* Upload or drop the package file in the **Filename** field. This tutorial uses the Apple Silicon package you can download [here](https://pkgs.netbird.io/macos/arm64).
|
||||
* Optionally, add Info and Notes.
|
||||
|
||||
In the `Options` tab:
|
||||
* Set a **Priority** (default is 10).
|
||||
* The priority determines the order in which packages are installed when multiple packages are included in a policy. Lower numbers indicate higher priority (e.g., 1 is a higher priority than 10). Use this to ensure critical packages are installed before NetBird if needed.
|
||||
|
||||
Click `Save` to finish. If you see the message "Availability pending", click `Refresh` to update the package status.
|
||||
|
||||
|
||||
|
||||
### Creating a Policy for NetBird
|
||||
|
||||
Go to `Computers > Computer management > Policies` and click `+ New` to create a new policy for the NetBird app.
|
||||
|
||||
In the `General` section of the `Options` tab:
|
||||
* Provide a descriptive name in the **Display Name** field (e.g., NetBird Apple Silicon)
|
||||
|
||||
In the **Trigger** options, check the following boxes:
|
||||
* Startup: Installs NetBird when the computer starts up.
|
||||
* Enrollment Complete: Ensures NetBird is installed immediately after the device is enrolled in Jamf Pro.
|
||||
* Recurring Check-in: Allows periodic checks to ensure NetBird is installed and up-to-date.
|
||||
|
||||
These trigger selections ensure NetBird is installed promptly and remains current on all managed devices. Leave the remaining options as default.
|
||||
|
||||
|
||||
|
||||
In the `Packages` section, click `Configure` and add the corresponding NetBird package:
|
||||
|
||||
|
||||
|
||||
Accept the default values for **Distribution Point** and **Action**
|
||||
|
||||
|
||||
|
||||
In the `Scope` tab, specify the target computers (all computers, specific computers or groups, etc.). For simplicity in this example, use `All Computers`.
|
||||
|
||||
|
||||
|
||||
Optionally, in the `User Interaction` tab:
|
||||
* Enter messages to display before and after the policy runs.
|
||||
* This can help inform users about the installation process.
|
||||
|
||||
|
||||
|
||||
Click `Save` to finish.
|
||||
|
||||
|
||||
|
||||
This configuration ensures NetBird is installed as soon as any machine enrolls, maintaining security across your device fleet.
|
||||
|
||||
It's worth mentioning that for first-time devices when NetBird is launched after installation, it automatically triggers the Single Sign-On (SSO) login flow. This seamless process combines connection setup and authentication, establishing both network connectivity and user verification in one streamlined step.
|
||||
|
||||
The SSO flow works as follows:
|
||||
|
||||
1. When users open NetBird for the first time, they will be prompted to authenticate.
|
||||
2. The user will be redirected to your organization's identity provider (IdP) login page.
|
||||
3. After successful authentication, the user is automatically connected to the NetBird network.
|
||||
4. NetBird then configures itself with the appropriate permissions based on the user's identity and group memberships.
|
||||
|
||||
This approach ensures secure and efficient user authentication by integrating with your organization's identity management system. It eliminates the need for separate VPN credentials, simplifying the user experience while maintaining robust security.
|
||||
|
||||
Throughout the process, NetBird logs its actions, which can be useful for troubleshooting purposes. Upon successful completion of the SSO flow and network connection, NetBird is fully operational, marking the end of a smooth, automated deployment and configuration process.
|
||||
|
||||
## Verifying the Automated Provisioning Process
|
||||
|
||||
After setting up NetBird deployment policy in Jamf Pro, it's crucial to verify that the automated provisioning process is working correctly. Follow these steps to confirm the successful installation of NetBird:
|
||||
|
||||
* In Jamf Pro, navigate to `Computers > Search Inventory`.
|
||||
* Click `Search` to display all enrolled machines.
|
||||
* Select a newly enrolled machine from the list.
|
||||
* In the device details, go to the `Management` tab and locate the `Policies` section.
|
||||
* Look for the NetBird policy in the list of applied policies.
|
||||
|
||||
|
||||
|
||||
If you see the NetBird policy listed, that would indicate that NetBird has been successfully installed on the device.
|
||||
|
||||
To further verify the integration, check that the machine has been added to your NetBird network:
|
||||
|
||||
* Log into a NetBird account with administrative privileges.
|
||||
* Go to the `Peers` section.
|
||||
* Look for the newly enrolled machine in the list of peers.
|
||||
|
||||
If you can see the new machine listed as a peer in NetBird, this confirms that the automated provisioning process is working correctly and the device has been successfully added to your NetBird network.
|
||||
|
||||
By following these verification steps, you can ensure that your Jamf Pro policy is effectively deploying NetBird to your managed devices and integrating them into your secure network infrastructure.
|
||||
|
||||
This tutorial taught you how to seamlessly integrate NetBird's VPN solution with Jamf Pro for Apple devices. By configuring NetBird Access Policies, creating a Jamf Pro policy for automated deployment, and verifying the provisioning process, you've established a solid system for managing secure network access across your organization.
|
||||
@@ -1,192 +0,0 @@
|
||||
# Deploying NetBird with Kandji MDM
|
||||
|
||||
Combining NetBird's with [Kandji's orchestration capabilities](https://www.kandji.io) creates a powerful solution for securing and managing access across your entire Apple ecosystem, from mobile devices to desktops.
|
||||
|
||||
In this hands-on guide, you'll learn how to deploy NetBird on Apple devices using Kandji MDM to grant tailored access permissions for different teams by:
|
||||
|
||||
1. Configuring NetBird Access Policies for Team-Specific Permissions
|
||||
2. Creating Kandji MDM Blueprints for Automated NetBird Deployment
|
||||
3. Testing and Verifying the Automated Provisioning Pipeline
|
||||
|
||||
Following these steps, you'll set up an automated pipeline that simplifies network security management, reduces manual configuration errors, and ensures appropriate access levels for each team.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To successfully integrate NetBird with Kandji MDM, ensure you have the following prerequisites in place:
|
||||
|
||||
* [Active NetBird account](https://app.netbird.io/) with administrative access.
|
||||
* [Kandji MDM subscription](https://signup.kandji.io) with administrative privileges.
|
||||
* At least one Apple device (Mac, iPhone, iPad) [enrolled in Kandji MDM](https://support.kandji.io/support/solutions/articles/72000560543-configuring-device-enrollment).
|
||||
|
||||
## Configuring NetBird Access Policies for Team-Specific Permissions
|
||||
|
||||
NetBird plays a crucial role in this integration by providing granular access control through its [Access Control Policies](https://docs.netbird.io/manage/access-control/manage-network-access). These features allow you to define and enforce specific permissions for different user groups, ensuring that team members can only access the resources necessary for their roles.
|
||||
|
||||
For instance, let's suppose you want to create a policy that allows the `Support` team to access the `Servers` group:
|
||||
|
||||
* In NetBird, navigate to `Access Control > Policies` and click `Add Policy`.
|
||||
* Set the source group to `Support` and the destination group to `Servers`.
|
||||
* Choose the appropriate protocol and port settings (e.g., TCP 22).
|
||||
|
||||
|
||||
|
||||
Give the policy a descriptive name (e.g., Support team remote access) and click `Save` to create the policy.
|
||||
|
||||
|
||||
|
||||
Now that you've configured NetBird, let's shift the focus to Kandji MDM integration and set up the automated deployment of NetBird on support team devices.
|
||||
|
||||
## Integrating NetBird with Kandji Custom Apps
|
||||
|
||||
Navigate to `Library` and click `Add new`. Then, find and select `Custom Apps` and click `Add & Configure` to deploy a new [Custom App](https://www.support.kandji.io/support/solutions/articles/72000559807-deploying-custom-apps).
|
||||
|
||||
|
||||
|
||||
Give the Custom App a descriptive name (e.g., NetBird_vX.XX_Support_Team, where X.XX is the current version of NetBird being deployed). Scroll down to **Install Details**, where you'll see different options.
|
||||
|
||||
Select `Installer Package` to install NetBird using the official macOS package. Using a package ensures you're installing the exact same version on all devices. This example uses the Apple Silicon package that you can download [here](https://pkgs.netbird.io/macos/arm64). Drag the file to the `Installer Package` field box to upload it to Kandji MDM.
|
||||
|
||||
|
||||
|
||||
Next, click on `Add Preinstall Script` and paste the following code:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
|
||||
set -x
|
||||
|
||||
LOG_FILE=/var/log/netbird/client_pre_install.log
|
||||
AGENT=/usr/local/bin/netbird
|
||||
|
||||
mkdir -p /var/log/netbird/
|
||||
|
||||
{
|
||||
# check if it was installed with brew
|
||||
brew list --formula | grep netbird
|
||||
if [ $? -eq 0 ]
|
||||
then
|
||||
echo "NetBird has been installed with Brew. Please use Brew to update the package."
|
||||
exit 1
|
||||
fi
|
||||
osascript -e 'quit app "Netbird"' || true
|
||||
$AGENT service stop || true
|
||||
|
||||
echo "Preinstall complete"
|
||||
exit 0 # all good
|
||||
} &> $LOG_FILE
|
||||
```
|
||||
|
||||
<Note>
|
||||
This preinstall script prepares the system for a smooth NetBird installation by setting up logging, checking for previous Homebrew installations, and stopping any running NetBird instances. It ensures a clean slate, preventing conflicts and maintaining consistency across deployments, ultimately reducing potential errors during installation.
|
||||
</Note>
|
||||
|
||||
Now, click on `Add Postinstall Script` and paste the following code:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
The post-install script completes the NetBird installation through a series of steps:
|
||||
|
||||
* It begins by verifying the app's presence in the Applications folder, creating necessary symlinks, initiating the NetBird service, and configuring NetBird with the provided hostname.
|
||||
* For first-time devices, when the script executes the `netbird up` command, it automatically triggers the Single Sign-On (SSO) login flow. This seamless process combines connection setup and authentication, establishing both network connectivity and user verification in one streamlined step.
|
||||
* This approach ensures secure and efficient user authentication by integrating with your organization's identity management system.
|
||||
* Throughout the process, the script logs its actions for troubleshooting purposes.
|
||||
* Upon successful completion, NetBird is launched, marking the end of a smooth, automated deployment process.
|
||||
|
||||
|
||||
Keep in mind that you can use these scripts as customizable templates, which can be tailored to meet the specific requirements of your organization's NetBird deployment process.
|
||||
|
||||
## Creating Kandji Blueprints for Automated NetBird Deployment
|
||||
|
||||
Creating a Blueprint ([Assignment Map](https://www.support.kandji.io/support/solutions/articles/72000627627-getting-started-with-assignment-maps)) for NetBird deployment ensures consistent and automated installation across designated devices. Moreover, Kandji Blueprints allow you to define specific configurations and apps that should be installed on devices based on certain criteria, which is ideal for targeting particular teams or device groups with your NetBird deployment.
|
||||
|
||||
For instance, you can [create tags](https://www.support.kandji.io/support/solutions/articles/72000630421-tags-for-devices) for different teams (e.g., support, finance, marketing) in Kandji's device management interface. These tags can then be used in the Blueprint logic to assign the appropriate NetBird configuration to the right user groups, ensuring each team receives the correct access permissions.
|
||||
|
||||
To create a tag in Kandji MDM, go to `DEVICES`, click on the hamburger menu at the top right, and select `Manage tags`:
|
||||
|
||||
|
||||
|
||||
A new pop-up window will appear; click `+ Add tag`, enter a name for the tag (e.g., `Support`), and click `Save`.
|
||||
|
||||
|
||||
|
||||
Navigate to the `BLUEPRINTS` section in Kandji and click the `New Blueprint` dropdown. Select `New Assignment Map` from the options. In the new window, you'll be presented with preconfigured templates or the option to start a new Blueprint from scratch. For this custom NetBird deployment, choose to start a new Blueprint from scratch.
|
||||
|
||||
|
||||
|
||||
Give the Blueprint a descriptive name (e.g., NetBird_Apple_Silicon) and click `Create Blueprint`. This action will open Kandji's visual Blueprint builder, where you'll configure the deployment logic for NetBird.
|
||||
|
||||
Click `Edit assignments` to start editing the Blueprint.
|
||||
|
||||
|
||||
|
||||
You'll see a list of apps from the library on the left, including the recently created NetBird custom app. To implement the deployment logic, hover over the `+` sign and click it to add a new conditional block. This block will determine which devices receive the NetBird installation based on specific criteria.
|
||||
|
||||
|
||||
|
||||
Next, click the pencil icon to edit the rules.
|
||||
|
||||
|
||||
|
||||
In the **Assignment Rules** window, configure the conditions for NetBird installation. Use the `Support` tag to trigger the deployment, ensuring NetBird is installed only on devices assigned to the support team. Press `Confirm` to continue.
|
||||
|
||||
|
||||
|
||||
Back to the visual Blueprint builder, locate the NetBird custom app and drag it into the newly created conditional block. This action associates the NetBird installation with the specified deployment criteria for the support team.
|
||||
|
||||
|
||||
|
||||
Click `Save` to update the Blueprint with the new logic. This action also assigns the Blueprint to the NetBird custom app, finalizing the deployment pipeline configuration.
|
||||
|
||||
|
||||
|
||||
## Testing and Verifying the Automated Provisioning Pipeline
|
||||
|
||||
Kandji checks devices every 15 minutes by default, so any device tagged with `Support` will automatically trigger the NetBird installation based on this Blueprint.
|
||||
|
||||
To verify the deployment pipeline, navigate to `DEVICES` in Kandji, select an enrolled device, and click `Edit device details` > `Edit tags`. Assign the `Support` tag to trigger the NetBird installation.
|
||||
|
||||
|
||||
|
||||
You can also confirm the process in NetBird. Log in to a NetBird account with administrative privileges, navigate to the `Peers` section, and look for the new device.
|
||||
|
||||
|
||||
|
||||
In this tutorial, you've learned how to integrate NetBird's VPN solution with Kandji MDM for Apple devices. By configuring NetBird Access Policies, creating Kandji MDM Blueprints, and setting up an automated deployment pipeline, you've established a robust system for managing network access across your organization.
|
||||
@@ -1,419 +0,0 @@
|
||||
# Access Private Kubernetes Clusters with NetBird Kubernetes Operator
|
||||
|
||||
Accessing private Kubernetes clusters can be challenging, especially when connecting from remote locations or
|
||||
having multiple clusters to manage. NetBird Kubernetes operator simplifies this process by enabling secure access
|
||||
to your Kubernetes clusters using custom resource configurations and annotations to expose your cluster and services in your NetBird network.
|
||||
|
||||
The NetBird Kubernetes operator automatically creates [Networks and Resources](/manage/networks) in your NetBird account, allowing you to
|
||||
seamlessly access your Kubernetes services and control plane from your NetBird network.
|
||||
|
||||
## Deployment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- (Recommended) helm version 3+
|
||||
- kubectl version v1.11.3+.
|
||||
- Access to a Kubernetes v1.11.3+ cluster.
|
||||
- (Recommended) Cert Manager.
|
||||
|
||||
#### Using Helm
|
||||
1. Add helm repository.
|
||||
```shell
|
||||
helm repo add netbirdio https://netbirdio.github.io/helms
|
||||
```
|
||||
2. (Recommended) Install [cert-manager](https://cert-manager.io/docs/installation/#default-static-install) for k8s API to communicate with the NetBird operator.
|
||||
```shell
|
||||
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml
|
||||
```
|
||||
3. Add NetBird API token. You can create a PAT by following the steps [here](/how-to/access-netbird-public-api#creating-a-service-user).
|
||||
```shell
|
||||
kubectl create namespace netbird
|
||||
kubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=$(cat ~/nb-pat.secret)
|
||||
```
|
||||
<Note>
|
||||
Replace `~/nb-pat.secret` with your NetBird API key.
|
||||
</Note>
|
||||
|
||||
4. (Recommended) Create a [`values.yaml`](https://github.com/netbirdio/kubernetes-operator/blob/main/examples/ingress/values-kubernetes-operator.yaml) file, check `helm show values netbirdio/kubernetes-operator` for more info.
|
||||
```yaml
|
||||
# by default the managementURL points to the NetBird cloud service: https://api.netbird.io:443
|
||||
# managementURL: "https://netbird.example.io:443"
|
||||
ingress:
|
||||
enabled: true
|
||||
|
||||
netbirdAPI:
|
||||
keyFromSecret:
|
||||
name: "netbird-mgmt-api-key"
|
||||
key: "NB_API_KEY"
|
||||
```
|
||||
5. Install using helm install:
|
||||
```shell
|
||||
helm install --create-namespace -f values.yaml -n netbird netbird-operator netbirdio/kubernetes-operator
|
||||
```
|
||||
6. Check installation
|
||||
```shell
|
||||
kubectl -n netbird get pods
|
||||
```
|
||||
Output should be similar to:
|
||||
```
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
netbird-operator-kubernetes-operator-67769f77db-tmnfn 1/1 Running 0 42m
|
||||
```
|
||||
```shell
|
||||
kubectl -n netbird get services
|
||||
```
|
||||
Output should be similar to:
|
||||
```shell
|
||||
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
netbird-operator-kubernetes-operator-metrics ClusterIP 192.168.194.165 <none> 8080/TCP 47m
|
||||
netbird-operator-kubernetes-operator-webhook-service ClusterIP 192.168.194.222 <none> 443/TCP 47m
|
||||
```
|
||||
7.(Optional) Install Routing Peer and Policies, create a [`values.yaml`](https://github.com/netbirdio/kubernetes-operator/blob/main/examples/ingress/values-netbird-operator-config.yaml) file, check `helm show values netbirdio/netbird-operator-config` for more info.
|
||||
```yaml
|
||||
router:
|
||||
enabled: true
|
||||
policies:
|
||||
default:
|
||||
name: Kubernetes Default Policy
|
||||
sourceGroups:
|
||||
- All
|
||||
```
|
||||
8. Install using helm install:
|
||||
```shell
|
||||
helm install -f values.yaml -n netbird netbird-operator-config netbirdio/netbird-operator-config
|
||||
```
|
||||
|
||||
### Updating or Modifying the Operator Configuration
|
||||
The configuration or version update of the operator can be done with `helm upgrade`:
|
||||
|
||||
#### Operator version updates
|
||||
```shell
|
||||
helm upgrade -f values.yaml -n netbird netbird-operator netbirdio/kubernetes-operator
|
||||
```
|
||||
|
||||
#### Configuration Update
|
||||
```shell
|
||||
helm upgrade -f values.yaml -n netbird netbird-operator-config netbirdio/netbird-operator-config
|
||||
```
|
||||
|
||||
## Expose Kubernetes Control Plane to your NetBird Network
|
||||
To access your Kubernetes control plane from a NetBird network, you can expose your Kubernetes control plane as a
|
||||
[NetBird resource](/how-to/networks#resources) by enabling the following option in the netbird-operator-config values:
|
||||
|
||||
```yaml
|
||||
kubernetesAPI:
|
||||
enabled: true
|
||||
```
|
||||
The operator will create a NetBird network resource similar to the example below:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/kubernetes/kubernetes-api.png" alt="API" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
## Expose Kubernetes Services to NetBird Network
|
||||
|
||||
Kubernetes services is a common way to route traffic to your application pods. With the NetBird operator `ingress` you can expose services to your
|
||||
NetBird network as resources by using annotations in your services. The operator will create networks, resources,
|
||||
and add routing peers to your NetBird configuration.
|
||||
|
||||
By default, the ingress configuration is disabled. You can enable it with the following values using the `netbird-operator-config` helm chart:
|
||||
```yaml
|
||||
router:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
You can expose services using the annotations `netbird.io/expose: "true"` and `netbird.io/groups: "resource-group"`; see the example below:
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: app
|
||||
annotations:
|
||||
netbird.io/expose: "true"
|
||||
netbird.io/groups: "app-access"
|
||||
spec:
|
||||
selector:
|
||||
app: app
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 8080
|
||||
targetPort: 80
|
||||
type: ClusterIP
|
||||
```
|
||||
|
||||
This will create a Network and a resource similar to the example below:
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/kubernetes/resources-1.png" alt="resources" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Ingress DNS Resolution requires enabled `DNS Wildcard Routing` and at least one DNS Nameserver configured for clients.
|
||||
Learn more about Networks settings [here](/manage/networks#enable-dns-wildcard-routing).
|
||||
</Note>
|
||||
|
||||
Other annotations can be used to further configure the resources created by the operator:
|
||||
|
||||
|Annotation|Description|Default|Valid Values|
|
||||
|:---:|:---:|:---:|:---:|
|
||||
|`netbird.io/expose`| Expose service using NetBird Network Resource ||(`null`, `true`)|
|
||||
|`netbird.io/groups`| Comma-separated list of group names to assign to Network Resource. If non-existing, the operator will create them for you. |`{ClusterName}-{Namespace}-{Service}`|Any comma-separated list of strings.|
|
||||
|`netbird.io/resource-name`| Network Resource name |`{Namespace}-{Service}`|Any valid network resource name, make sure they're unique!|
|
||||
|`netbird.io/policy`| Name(s) of NBPolicy to propagate service ports as destination. ||Comma-separated list of names of any NBPolicy resource|
|
||||
|`netbird.io/policy-ports`| Narrow down exposed ports in a policy. Leave empty for all ports. ||Comma-separated integer list, integers must be between 0-65535|
|
||||
|`netbird.io/policy-protocol`| Narrow down protocol for use in a policy. Leave empty for all protocols. ||(`tcp`,`udp`)|
|
||||
|
||||
## Control Access to Your Kubernetes Resources with Access Control Policies
|
||||
By default, resources created by the operator will not have any access control policies assigned to them.
|
||||
To allow the operator to manage your access control policies, configure policy bases in your `values.yaml` file.
|
||||
In this file, you can define source groups, name suffixes, and other settings related to access control policies.
|
||||
Afterward, you can tag the policies in your service annotations using the annotation `netbird.io/policy: "policy-base"`.
|
||||
See the examples `values.yaml` for `netbird-operator-config` below:
|
||||
|
||||
```yaml
|
||||
router:
|
||||
enabled: true
|
||||
policies:
|
||||
app-users:
|
||||
name: App users # Required, name of policy in NetBird console
|
||||
description: Policy for app users access # Optional
|
||||
sourceGroups: # Required, name of groups to assign as source in Policy.
|
||||
- app-users
|
||||
protocols: # Optional, restricts protocols allowed to resources, defaults to ['tcp', 'udp'].
|
||||
- tcp
|
||||
bidirectional: false
|
||||
k8s-admins:
|
||||
name: App admins
|
||||
sourceGroups:
|
||||
- app-admins
|
||||
```
|
||||
After adding the policy base and [applying the configuration](#updating-or-modifying-the-operator-configuration),
|
||||
you can use the `app-users` and `k8s-admins` bases for your services and Kubernetes API configurations.
|
||||
|
||||
### Linking Policy Bases to the Kubernetes API Service
|
||||
To link a policy base to the Kubernetes API, we need to update the operator configuration by adding the policy and groups to the `kubernetesAPI` key in `netbird-operator-config` as follows:
|
||||
```yaml
|
||||
kubernetesAPI:
|
||||
enabled: false
|
||||
groups:
|
||||
- k8s-access
|
||||
policies:
|
||||
- k8s-admins
|
||||
```
|
||||
After updating and [applying the configuration](#updating-or-modifying-the-operator-configuration), you should see a policy similar to the one below:
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/kubernetes/kubernetes-api-policy.png" alt="resources policy" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
### Linking Policy Bases to Kubernetes Services
|
||||
You can link policy bases with the annotation `netbird.io/policy:` where you can simply add one or more bases to the service,
|
||||
see the example below where we link the base `"app-users"` to our app service:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: app
|
||||
annotations:
|
||||
netbird.io/expose: "true"
|
||||
netbird.io/groups: "app-access"
|
||||
netbird.io/policy: "app-users"
|
||||
spec:
|
||||
selector:
|
||||
app: app
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 8080
|
||||
targetPort: 80
|
||||
type: ClusterIP
|
||||
```
|
||||
|
||||
The operator will create a policy in your management account similar to the one below:
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/kubernetes/resources-policy.png" alt="resources policy" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
You can reference multiple policy bases using a comma separated list of policy bases: `netbird.io/policy: "app-users,app-admins"`
|
||||
|
||||
### Policy auto-creation
|
||||
|
||||
1. Ensure `ingress.allowAutomaticPolicyCreation` is set to true in the Helm chart and apply.
|
||||
2. Annotate a service with `netbird.io/policy` with the name of the policy as a kubernetes object, for example `netbird.io/policy: default`. This will create an NBPolicy with the name `default-<Service Namespace>-<Service Name>`.
|
||||
3. Annotate the same service with `netbird.io/policy-source-groups` with a comma-separated list of group names to allow as a source, for example `netbird.io/policy-source-groups: dev`.
|
||||
4. (Optional) Annotate the service with `netbird.io/policy-name` for a human-friendly name, for example `netbird.io/policy-name: "default:Default policy for kubernetes cluster"`.
|
||||
Example:
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: app
|
||||
annotations:
|
||||
netbird.io/expose: "true"
|
||||
netbird.io/groups: "app-access"
|
||||
netbird.io/policy: "app-users"
|
||||
netbird.io/policy-source-groups: "dev"
|
||||
netbird.io/policy-name: "dev:Developers to app"
|
||||
spec:
|
||||
selector:
|
||||
app: app
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 8080
|
||||
targetPort: 80
|
||||
type: ClusterIP
|
||||
```
|
||||
|
||||
<Note>
|
||||
If a policy already exists with the name specified in `netbird.io/policy`, the other settings will be ignored in favor of the existing policy.
|
||||
</Note>
|
||||
|
||||
## Accessing Remote Services Using Sidecars
|
||||
To access services running in different locations from your Kubernetes clusters, you can deploy NetBird sidecars—additional
|
||||
containers that run alongside your Kubernetes service containers within the same pod.
|
||||
|
||||
A NetBird sidecar joins your network as a regular peer and becomes a subject to access control, routing,
|
||||
and DNS configurations as any other peer in your NetBird network. This allows your Kubernetes application traffic to be securely routed
|
||||
through the NetBird network, enabling egress-like access to remote services from your Kubernetes services across various locations or cloud providers.
|
||||
|
||||
To enable sidecar functionality in your deployments, you first need to generate a setup key, either via the UI (see image below)
|
||||
or by following [this guide](/manage/peers/register-machines-using-setup-keys) for more details.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key.png" alt="Setup Keys" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Next, you'll create a secret in Kubernetes and add a new resource called `NBSetupKey`. The `NBSetupKey` name can then be
|
||||
referenced in your deployments or daemon sets to specify which setup key should be used when injecting a sidecar into
|
||||
your application pods. Below is an example of a secret and an `NBSetupKey` resource:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
stringData:
|
||||
setupkey: EEEEEEEE-EEEE-EEEE-EEEE-EEEEEEEEEEEE
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: app-setup-key
|
||||
```
|
||||
NBSetupKey:
|
||||
```yaml
|
||||
apiVersion: netbird.io/v1
|
||||
kind: NBSetupKey
|
||||
metadata:
|
||||
name: app-setup-key
|
||||
spec:
|
||||
# Optional, overrides management URL for this setupkey only
|
||||
# defaults to https://api.netbird.io
|
||||
# managementURL: https://netbird.example.com
|
||||
secretKeyRef:
|
||||
name: app-setup-key # Required
|
||||
key: setupkey # Required
|
||||
```
|
||||
|
||||
After adding the resource, you can reference the `NBSetupKey` in your deployments or daemon-sets as shown below:
|
||||
|
||||
```yaml
|
||||
kind: Deployment
|
||||
...
|
||||
spec:
|
||||
...
|
||||
template:
|
||||
metadata:
|
||||
annotations:
|
||||
netbird.io/setup-key: app-setup-key # Must match the name of an NBSetupKey object in the same namespace
|
||||
...
|
||||
spec:
|
||||
containers:
|
||||
...
|
||||
```
|
||||
|
||||
### Using Extra Labels to Access Multiple Pods Using the Same Name
|
||||
Starting with `v0.27.0`, NetBird supports extra DNS labels, allowing you to define extended DNS names for peers. This enables grouping peers under a shared DNS name and distributing traffic using DNS round-robin load balancing.
|
||||
|
||||
To use this feature, create a setup key with the “Allow Extra DNS Labels” option enabled. See the example below for reference:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key-with-extra-labels.png" alt="Setup keys with extra labels" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
And add the annotation `netbird.io/extra-dns-labels` to your pod; see the example below:
|
||||
|
||||
```yaml
|
||||
kind: Deployment
|
||||
...
|
||||
spec:
|
||||
...
|
||||
template:
|
||||
metadata:
|
||||
annotations:
|
||||
netbird.io/setup-key: app-setup-key # Must match the name of an NBSetupKey object in the same namespace
|
||||
netbird.io/extra-dns-labels: "app"
|
||||
...
|
||||
spec:
|
||||
containers:
|
||||
...
|
||||
```
|
||||
With this setup, other peers in your NetBird network can reach these pods using the domain `app.<NETBIRD_DOMAIN>`
|
||||
(e.g., for NetBird cloud, app.netbird.cloud). The access will be made using a DNS round-robin fashion for multiple pods.
|
||||
|
||||
## Uninstallation
|
||||
|
||||
### v0.2.0+
|
||||
|
||||
To uninstall the NetBird Kubernetes Operator and its associated resources, you can use the following Helm commands:
|
||||
```shell
|
||||
helm uninstall -n netbird netbird-operator-config
|
||||
helm uninstall -n netbird kubernetes-operator
|
||||
```
|
||||
|
||||
<Note>
|
||||
Order of uninstallation is important; make sure to uninstall `netbird-operator-config` first to avoid orphaned resources. If you have any routing peers or policies in the cluster, uninstalling `kubernetes-operator` first may lead to issues.
|
||||
</Note>
|
||||
|
||||
### < v0.2.0
|
||||
To uninstall the NetBird Kubernetes Operator and its associated resources, you'll need to manually delete all NBRoutingPeers and NBPolicies created by the operator before uninstalling the Helm chart. You can do this using the following commands:
|
||||
```shell
|
||||
kubectl -A delete nbroutingpeers --all
|
||||
kubectl delete nbpolicies --all
|
||||
helm uninstall -n netbird kubernetes-operator-operator
|
||||
```
|
||||
|
||||
<Note>
|
||||
NBRoutingPeer deletion will be blocked if there are any Services with the annotation `netbird.io/expose: "true"` present in the cluster. Make sure to remove the annotation from those Services or delete the Services themselves before proceeding with the deletion of NBRoutingPeers.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Make sure to delete all NBRoutingPeers and NBPolicies before uninstalling the Helm chart to avoid orphaned resources.
|
||||
</Note>
|
||||
|
||||
## Upgrade Notes
|
||||
|
||||
### Upgrading from Helm Chart v0.1.0 to v0.2.0 and above
|
||||
Starting from version v0.2.0, the NetBird Kubernetes Operator Helm chart has been split into two separate charts:
|
||||
- `kubernetes-operator`: This chart contains the core operator functionality.
|
||||
- `netbird-operator-config`: This chart is responsible for configuring the NetBird operator, including routing peers and policies.
|
||||
|
||||
The configuration files responsible for creating NBRoutingPeers and NBPolicies have been moved to the `netbird-operator-config` chart, allowing for easier uninstallation of the operator without affecting existing routing peers and policies, as well as uninstalling configuration with a proper cleanup.
|
||||
|
||||
During Helm versions v0.2.x, `kubernetes-operator` chart will still install NBRoutingPeers and NBPolicies if they are defined in the `values.yaml` file. However, this behavior will be deprecated in future releases. It is recommended to migrate your configuration to the `netbird-operator-config` chart to ensure compatibility with future updates.
|
||||
|
||||
You can migrate to the new chart by following these steps:
|
||||
1. Create a new `values.yaml` file for the `netbird-operator-config`
|
||||
2. Move the routing peer and policy configurations from your existing `values.yaml` file to the new file.
|
||||
3. Install or upgrade the `netbird-operator-config` chart using Helm with the new `values.yaml` file using the `--take-ownership` flag.
|
||||
```shell
|
||||
helm install -f values.yaml -n netbird netbird-operator-config netbirdio/netbird-operator-config --take-ownership
|
||||
```
|
||||
4. Remove routing peer and policy configurations from the `kubernetes-operator` `values.yaml` file to avoid duplication.
|
||||
5. Upgrade the `kubernetes-operator` chart using Helm with the updated `values.yaml` file.
|
||||
```shell
|
||||
helm upgrade -f values.yaml -n netbird netbird-operator netbirdio/kubernetes-operator
|
||||
```
|
||||
|
||||
## Get started
|
||||
<p float="center" >
|
||||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
|
||||
</p>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
- Join our [Slack Channel](/slack-url)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,154 +0,0 @@
|
||||
# NetBird MSP Portal for Managed Service Providers
|
||||
|
||||
NetBird Cloud offers a multi-tenant MSP Portal for Managed Service Providers (MSPs) and Managed Security Service Providers (MSSPs)
|
||||
to manage customers (tenants) from a single place. As an MSP, you can manage multiple NetBird accounts under your organization,
|
||||
configure network settings, billing, and control network access for each tenant just like you would for your own NetBird account.
|
||||
|
||||
An MSP account is a standard NetBird account with the added 'Tenants' section, allowing for the management of customer networks.
|
||||
With an MSP account, you can also manage your own internal network, just like with a regular NetBird account.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/tenants.png" alt="tenants" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
The MSP Portal is designed to help you efficiently manage multiple tenant networks, providing a seamless experience for
|
||||
switching between tenants and your MSP account. You can do so without the need to log in and out of different accounts
|
||||
or inconvenient customer-specific URLs.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/tenant-switch.png" alt="tenant-switch" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
## How to Apply for an MSP Account?
|
||||
To apply for an MSP account, follow these steps:
|
||||
|
||||
* Ensure you have an active NetBird subscription ([Team plan](https://netbird.io/pricing) or higher).
|
||||
* Visit our MSP application form at [https://netbird.io/msp](https://netbird.io/demo?form=msp&utm_source=docs&utm_medium=docs&utm_content=msp-portal).
|
||||
* Complete the application form with your details and company information.
|
||||
|
||||
Submit the form for review by our team. Our team will evaluate your application and, if approved, grant you MSP status
|
||||
and access to the MSP Portal.
|
||||
|
||||
## Access the MSP Portal
|
||||
Once approved as an MSP, you will see the 'Tenants' section in your NetBird dashboard.
|
||||
You can now add new tenant accounts under your organization.
|
||||
|
||||
## Add New Tenants
|
||||
|
||||
In the 'Tenants' section of your dashboard, click on the 'Add Tenant' button to add a new tenant account.
|
||||
|
||||
1. Provide the tenant's name and domain:
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/add-new-tenant-name-domain.png" alt="add-new-tenant-name-domain" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
2. Define who can access the tenant account by selecting the user groups of your account and the applicable [user role](/manage/team/add-users-to-your-network#manage-user-roles) when they switch to the tenant. Only users from the selected groups will
|
||||
be able to switch to and manage the tenant account.
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/add-new-tenant-permissions.png" alt="add-new-tenant-permissions" className="imagewrapper"/>
|
||||
</p>
|
||||
<Note>
|
||||
If a user belongs to multiple groups with different roles, the highest permission role will be applicable.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Please see [Existing Account](#existing-account) if a Netbird account already exists in our system for the supplied tenant domain.
|
||||
</Note>
|
||||
|
||||
3. To ensure that you have rights to manage the tenant, you need to verify the ownership of the tenant domain by adding
|
||||
a TXT DNS record to the tenant's domain:
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/add-new-tenant-verify-domain.png" alt="add-new-tenant-verify-domain" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
4. Once the domain is verified, select a plan for the tenant.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/add-new-tenant-plan.png" alt="add-new-tenant-plan" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Existing Account
|
||||
|
||||
If an account already exists in our system for the specified tenant domain, you’ll need to explicitly request access
|
||||
to manage this account.
|
||||
The current account owner will be prompted to grant this access the next time they log in.
|
||||
|
||||
1. Press the "Request Access" button if the account already exists:
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/tenant-already-exists.png" alt="tenant-already-exists" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
2. Ask the account owner to log in to the dashboard and press "Grant Access"
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/tenant-grant-or-deny.png" alt="tenant-grant-or-deny" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
When granted, the existing account owner role will change to admin and their subscription will be converted to a 3-days trial.
|
||||
</Note>
|
||||
|
||||
## Manage Tenant Networks
|
||||
|
||||
Every user in your MSP account that has permissions to manage tenants can switch between the MSP account and tenant
|
||||
accounts using the tenant switcher in the top right corner.
|
||||
|
||||
Choose the tenant you want to manage from the dropdown list to switch to the tenant account and the system will redirect
|
||||
you to the tenant's network.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/tenant-switch.png" alt="tenant-switch" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
If no tenants appear in the dropdown list, it may be because your user lacks the necessary permissions to manage tenants.
|
||||
Please verify that your user is assigned to the appropriate groups listed under the 'Permission Groups' column in the 'Tenants'
|
||||
table.
|
||||
</Note>
|
||||
|
||||
Once you switch to a tenant account, you can manage the tenant's network settings, enable integrations, control network access, and more.
|
||||
Your user will have the 'Admin' role within the tenant account, granting you full administrative access.
|
||||
|
||||
Note that your user will not appear in the 'Team' -> 'Users' section of the tenant account, as user management is handled
|
||||
through the MSP account. However, your user will be visible in the Audit Log, labeled as 'External.'
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/tenant-audit-log.png" alt="audit-log" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
## Tenant Usage, Billing and Subscription Management
|
||||
|
||||
For your convenience, NetBird provides a daily usage overview.
|
||||
Please note that the usage displayed in the MSP portal may differ from what you see when switching to a tenant account.
|
||||
This is because the MSP portal shows billable usage — meaning only active users and machines are counted
|
||||
(see [NetBird plans](/how-to/plans-and-billing#net-bird-plans) for more details).
|
||||
|
||||
The usage data is refreshed once per day and reflects the number of users and peers that will be included in your billing at the end of the cycle.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/msp-portal/tenant-usage.png" alt="tenant-usage" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
Each tenant you add is treated as an individual Stripe subscription under your MSP account. When you go to Manage Plan
|
||||
in the 'Plans & Billing' section, you'll see a list of subscriptions — one for each tenant.
|
||||
|
||||
However, you’ll only be charged once, with the total consolidated amount across all tenant subscriptions.
|
||||
A single consolidated invoice is generated for your convenience, which you can download from the 'Tenants' overview page.
|
||||
|
||||
<Note>
|
||||
All tenant billing cycles are automatically aligned with your MSP account's billing cycle.
|
||||
For example, if your MSP subscription starts on March 2nd and you add a new tenant on March 15th,
|
||||
the tenant’s billing cycle will still be set to March 2nd. As a result, the first full-month charge will occur on April 2nd.
|
||||
</Note>
|
||||
|
||||
## Free Trial for Tenant Accounts
|
||||
|
||||
To make things easier for you, all new tenant accounts come with a 14-day free trial. This gives you the perfect opportunity
|
||||
to showcase NetBird to your customers before committing to a paid plan. Simply select 'Continue with Free Trial' when
|
||||
setting up a new tenant plan. After the 14-day trial ends, the MSP account will no longer be able to make changes to the Tenant account. The interface will display a popup message indicating this restriction. However, all existing configurations within the Tenant account will remain intact, and network connections will continue to operate normally. Tenant administrators will no longer be able to make changes to the account as well and will see a notification instructing them to contact their MSP to proceed.
|
||||
|
||||
## Delayed Tenant Domain Verification
|
||||
|
||||
Just like with the free trial, you have the flexibility to verify your tenant's domain at a later time, making it easier
|
||||
to demo NetBird to companies that aren't yet your customers. However, if someone logs in using the same domain, NetBird will
|
||||
create a separate account to avoid any security risks. We hope that the ease of use and advanced security features of NetBird will help drive
|
||||
your business growth and attract new customers.
|
||||
@@ -1,64 +0,0 @@
|
||||
# Multi-Factor Authentication (MFA)
|
||||
|
||||
NetBird supports Multi-Factor Authentication (MFA) to enhance the security of your account by requiring a second form of verification during login.
|
||||
This works automatically if you have enabled MFA in your SSO Provider (Google, Microsoft etc.) and use the **interactive SSO login** feature in NetBird.
|
||||
|
||||
NetBird MFA is primarily for users with **email / password login**. It is available for all users and can be enabled from the Dashboard on the Settings page [https://app.netbird.io/settings](https://app.netbird.io/settings).
|
||||
|
||||
<Note>
|
||||
You may not need NetBird MFA. Your SSO Provider (Google, Microsoft etc.) may already have MFA enabled. Enabling this setting could result in duplicated MFA checks.
|
||||
</Note>
|
||||
<Note>
|
||||
This feature is only available in the cloud version of NetBird. <br />Self-Hosted users can use their own Identity Provider for MFA.
|
||||
</Note>
|
||||
|
||||
## Enabling and Disabling MFA
|
||||
Navigate to the Dashboard's `Settings` page and the `Authentication` tab and enable or disable MFA. <br />
|
||||
After enabling, you can `Logout` and log back in to see the MFA prompt.
|
||||
|
||||
- When disabling MFA, the current active MFA devices of all users will not be removed and will be reused when MFA is enabled again. To remove MFA devices from users, check the [Reset MFA](#reset-mfa) section below.
|
||||
- If a user is not part of the account and MFA is enabled, the first-time `Sign Up` will not require MFA. <br /> Only subsequent logins will require MFA.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/mfa/mfa-settings.png" alt="MFA Settings" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
|
||||
### Remember Browser for MFA
|
||||
When you enable MFA, you can choose to remember your browser for 30 days. This means you will only need to enter the MFA code once every 30 days.
|
||||
When disabled, you will need to enter the MFA code every time you log in.<br />
|
||||
Once enabled you will see a checkbox to remember your browser for 30 days while entering the MFA code during login.
|
||||
|
||||
|
||||
## Checking User MFA Status
|
||||
You can check individual user MFA status by going to the `Users` page of the Dashboard.<br />
|
||||
Click on a specific user to see their MFA status.
|
||||
- `Active` - MFA is enabled and user **has completed** the MFA setup.
|
||||
- `Not enrolled` - MFA is enabled but user **has not completed** the MFA setup yet.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/mfa/mfa-not-enrolled.png" alt="MFA Status" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
## Reset MFA
|
||||
To reset MFA for a specific user, click on the user in the `Users` tab and click on the `Reset MFA` button.<br />
|
||||
This will reset MFA for the user, and they will need to set it up again during the next login.
|
||||
|
||||
<Note>
|
||||
Currently NetBird does not provide recovery codes for MFA. Make sure to have multiple administrators configured to prevent lockout situations.
|
||||
If all `Owners` or `Admins` lose access to the Dashboard, you should contact [support@netbird.io](mailto:support@netbird.io) for assistance.
|
||||
</Note>
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/mfa/mfa-reset-mfa.png" alt="MFA Reset" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
## Get started
|
||||
<p float="center" >
|
||||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
|
||||
</p>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
- Join our [Slack Channel](/slack-url)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,213 +0,0 @@
|
||||
# Introduction
|
||||
|
||||
NetBird’s **Traffic Events** feature provides a high-level view of traffic flows between network peers and resources.
|
||||
It captures connection events on the client (peer) side – for example, when `Peer A` connects to `Peer B` –
|
||||
allowing administrators to observe how devices communicate across the NetBird network.
|
||||
The primary purpose of traffic events is to help network admins monitor network activity,
|
||||
detect unusual or unauthorized connections, and troubleshoot connectivity issues in their NetBird mesh VPN.
|
||||
Unlike packet capture, **Traffic Events** record metadata about the traffic (addresses, ports, timestamps, etc.) rather than the contents,
|
||||
preserving privacy while still giving useful insight.
|
||||
|
||||
By focusing on client-side events, NetBird’s **Traffic Events** show what each peer is doing on the network.
|
||||
This includes which peers or services it is contacting, over which protocols, and when.
|
||||
Traffic Events are especially useful for verifying that access control policies are working as expected (e.g. confirming that a peer could reach an allowed resource,
|
||||
or that blocked traffic wasn’t forwarded).
|
||||
In essence, they provide an audit trail of network connections in your NetBird environment,
|
||||
helping administrators ensure the network is being used according to policy and to quickly identify
|
||||
any anomalies or needed configuration changes.
|
||||
|
||||
# Data Collected on Peers
|
||||
|
||||
When enabled, a NetBird peer will record metadata for each network flow that it participates in. The data collected typically includes:
|
||||
|
||||
* **Timestamp**: When the flow started and ended.
|
||||
* **Source and Destination IP Addresses**: The IP of the peer (source) and the IP of the remote endpoint (destination). For peer-to-peer traffic, these will be the NetBird network IPs (e.g. 100.x.x.x addresses of each peer). For traffic to an external resource (like a private server or subnet), the destination might be an IP in that remote network.
|
||||
* **Source and Destination Ports**: The network ports used by the connection (for TCP/UDP flows). ICMP flows will be identified by ICMP type rather than ports.
|
||||
* **Protocol**: The protocol of the traffic, such as TCP, UDP, or ICMP.
|
||||
* **Direction**: Whether the flow was incoming or outgoing.
|
||||
* **Volume of Data**: The amount of data transferred, measured in number of packets and bytes sent/received for the duration of the flow.
|
||||
|
||||
# Kernel Mode vs Userspace Mode
|
||||
|
||||
NetBird leverages WireGuard for its tunneling, and it can operate in two modes on client devices: kernel mode or userspace mode.
|
||||
In kernel mode, NetBird utilizes the operating system’s WireGuard kernel module (when available) for handling encryption and routing.
|
||||
This offers very efficient performance with low overhead, as the heavy lifting is done inside the OS kernel.
|
||||
NetBird is designed to take advantage of kernel-mode WireGuard whenever possible for direct peer-to-peer connections.
|
||||
If the kernel module isn’t available or if the platform doesn’t support it (for example, Windows, or certain BSD-based systems),
|
||||
NetBird falls back to a userspace implementation of WireGuard (running in the NetBird agent process).
|
||||
Userspace mode may introduce slightly higher CPU usage or latency since packets are handled in the application layer rather than the kernel,
|
||||
but it ensures compatibility across all environments.
|
||||
|
||||
# Log Retention
|
||||
|
||||
NetBird does not store Traffic Events indefinitely; instead, we follow a retention policy to
|
||||
balance storage use and privacy. By default, traffic event data is retained for 24 hours on the management system,
|
||||
after which older records are automatically deleted.
|
||||
|
||||
However, while in experimental mode, logs are retained for **48 hours**.
|
||||
Additionally, please note that the current API returns a maximum of **50,000 events**.
|
||||
We are actively working on expanding this limit in the coming days to support larger datasets and increased usage.
|
||||
|
||||
# Log Shipping
|
||||
|
||||
To enhance monitoring and centralized analysis, we support shipping Traffic Events to external logging solutions.
|
||||
This integration allows you to seamlessly forward Traffic Events from NetBird to DataDog, Amazon S3 or Amazon DataFirehose,
|
||||
where you can leverage advanced dashboards, alerting, and analytics to gain deeper insights into your network activity.
|
||||
|
||||
# Use Cases
|
||||
|
||||
This section outlines common scenarios in which Traffic Events are useful, explaining what administrators can glean in each case.
|
||||
We’ll also illustrate some scenarios with examples and screenshots of log data where applicable.
|
||||
|
||||
## 1. Peer-to-Peer Connections
|
||||
|
||||
When two NetBird peers communicate directly, a traffic event is generated on the peer that initiated the connection.
|
||||
This covers basic peer-to-peer traffic such as one workstation pinging another, an SSH session from one server to another,
|
||||
or any application data exchanged between two peers over NetBird.
|
||||
The log will show the source peer’s NetBird IP and the destination peer’s NetBird IP, along with the protocol and ports used.
|
||||
|
||||
#### **1.1. Example of a traffic event for a TCP connection between two peers.**
|
||||
|
||||
In the above example, a peer named `Nevada Windows` opened a TCP connection from source port `52480` to another peer named `acltest` on destination port `80`.
|
||||
Each peer would log the event from its perspective – typically, the initiator peer `Peer A` logs it as an outgoing connection and
|
||||
the responder peer `acltest` logs it as an incoming connection.
|
||||
|
||||
|
||||
#### **1.2. Example of a traffic event for an UDP connection between two peers.**
|
||||
|
||||
|
||||
In the case of UDP traffic between peers, the event will similarly record the source/dest IPs and ports and label the protocol as UDP.
|
||||
|
||||
#### 1.3. Example of a traffic event for an ICMP connection between two peers.
|
||||
|
||||
|
||||
ICMP flows (like a ping) will appear with protocol ICMP in the logs. For a ping, you’d see the two peers’ IPs and the fact it was ICMP;
|
||||
if packet/byte counting is on, you might see a couple of packets (an echo request and reply) recorded.
|
||||
|
||||
## 2. Peer-to-Resource Connections
|
||||
|
||||
#### 2.1. Peer-To-Host Connection
|
||||
|
||||
|
||||
|
||||
This scenario involves a NetBird peer accessing a specific host resource on an internal network, via a routing peer.
|
||||
In NetBird, you can define resources (in Access Control) that are single hosts (single IP addresses) which a peer should be allowed to reach.
|
||||
For example, you might have an on-premises service at IP `192.168.0.201` that is not itself running NetBird,
|
||||
but one of your NetBird peers `Routing Peer A` is in that network and can route traffic to it.
|
||||
Another peer `Peer A` somewhere else is granted access to that host through NetBird.
|
||||
When `Peer A` tries to connect (e.g. HTTPS on port 443) to the host resource `192.168.0.201` the traffic will go through `Routing Peer A`
|
||||
(which acts as a routing peer for that resource).
|
||||
|
||||
Traffic Events are extremely useful here to understand each step:
|
||||
|
||||
* On `Peer A`’s log, you would see an outgoing event with destination `192.168.0.201`:443 (for example) over TCP.
|
||||
The source would be `Peer A`’s NetBird IP and source port, destination the host’s IP and port 443.
|
||||
This confirms that Peer A attempted to reach the server.
|
||||
* On `Routing Peer A`’s log, you will see the related event: coming from `Peer A`
|
||||
(`Peer A`’s NB IP to `192.168.0.201` on port 443). Routing `Peer A` essentially bridges the two networks,
|
||||
so it sees an incoming event and forwards the traffic internally.
|
||||
|
||||
**Another Example**: Imagine DNS is disabled on a printer, and a user’s laptop `Peer A` tries to ping the printer’s IP
|
||||
via a NetBird routing peer. The logs on `Peer A` would show an ICMP flow to the printer’s IP;
|
||||
the routing peer’s logs would show the traffic coming from the laptop and going to the printer.
|
||||
If the ping fails, you could see whether the flow reached the printer or not.
|
||||
All of this without capturing packets – the flow records give a concise summary of what happened.
|
||||
In summary, for peer-to-host resource events, look at the initiating peer’s log for an outbound flow to the host’s IP,
|
||||
and the routing peer’s log for the corresponding transit.
|
||||
These flows confirm that NetBird is correctly carrying traffic to specific network resources in your network.
|
||||
|
||||
#### 2.2. Peer-To-Subnet Connection
|
||||
|
||||
Similar to the above, this scenario deals with a peer accessing an entire subnet (range of IPs) via a routing peer.
|
||||
NetBird allows administrators to define network routes (or the newer “Networks” feature) where a peer acts as a gateway to a subnet (for example, an office `LAN 10.0.5.0/24`).
|
||||
A common use case is site-to-site connectivity or allowing remote peers to access a whole VLAN or VPC through one NetBird node.
|
||||
|
||||
In a peer-to-subnet case, the Traffic Events will show when a peer communicates with any IP in the target subnet:
|
||||
|
||||
* On the client (peer) side, an outgoing traffic event will appear whenever it sends traffic to an IP within the allowed subnet. For instance,
|
||||
if `Peer A` (remote laptop) connects to `10.0.5.100` (an internal server in the subnet),
|
||||
`Peer A`’s logs will list a flow with destination `10.0.5.100` (and whatever port/protocol).
|
||||
* On the routing peer’s side (the peer that has access to that subnet),
|
||||
you’ll again see the flow coming from `Peer A`’s NetBird IP out to the `10.0.5.x` address.
|
||||
|
||||
One thing to note is that when a subnet is allowed, a peer might generate many traffic events if it scans
|
||||
or communicates with multiple hosts in that subnet. Each distinct connection (to each IP and port)
|
||||
is a separate traffic event. The logs can thus help you map out which internal hosts a remote peer is talking to.
|
||||
For example, you might see peer-a accessing `10.0.5.25 (file server)` on `TCP 445`, and also `10.0.5.100` on `TCP 3389 (RDP)`.
|
||||
This tells you which services are being used.
|
||||
|
||||
Traffic Events in this scenario can highlight if any unexpected access is happening.
|
||||
Perhaps a peer is only supposed to use a database, but you see events to a domain controller’s IP – that could be a red flag to investigate.
|
||||
Conversely, if a user complains they can’t access anything in the subnet, you could check the traffic events
|
||||
if absolutely no traffic events to that subnet appear in their peer log, maybe their client isn’t attempting the connection.
|
||||
|
||||
#### 2.3. Peer-To-Domain Connection
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
NetBird also supports defining resources by domain name – for example,
|
||||
an access policy might allow a peer to reach example.com or *.corp.internal.
|
||||
In these cases, the NetBird client will handle domain name resolution (often through NetBird’s DNS features)
|
||||
and then allow traffic to the resulting IP addresses if they match the domain policy.
|
||||
Traffic Events will capture the actual IP connections made, but it’s important to understand how domain-based rules reflect in the logs.
|
||||
|
||||
When a peer initiates a connection to an allowed domain (say, intranet.corp.internal), the following happens:
|
||||
|
||||
The peer resolves the domain to an IP using the routing peer's embedded resolver.
|
||||
The connection proceeds to that IP over the tunnel. The event on the peer will show a connection to that IP address (since that’s what ultimately happens on the network layer).
|
||||
|
||||
As a result, an administrator analyzing the logs may see a connection to an IP address, such as 10.8.0.5 on TCP 443,
|
||||
with an explicit reference to the domain it was resolved from.
|
||||
|
||||
The event for peer-to-domain scenarios will look just like any other peer-to-host event:
|
||||
peer’s NB IP -> some destination IP, protocol, port, bytes.
|
||||
The difference is that the allowed destination IP might not be static – it could change
|
||||
if the DNS name resolves differently. NetBird, however, will log whatever actual addresses were contacted.
|
||||
For example, consider a rule allowing access to pool.ntp.org (which resolves to various IPs).
|
||||
If a peer (Peer A) uses that, on Peer A’s log over time you might see events to multiple different IP addresses
|
||||
on UDP port 123 (NTP). Each of those events corresponds to the domain resource.
|
||||
|
||||
## 3. Site-to-Site Connections
|
||||
|
||||
In a site-to-site setup, NetBird connects two or more networks (sites) each with a routing peer.
|
||||
For example, an AWS VPC network and an on-prem network could be linked via their respective NetBird peers,
|
||||
so that machines in each site can talk to each other through the NetBird tunnel
|
||||
(often without each machine running NetBird – the routing peers relay traffic).
|
||||
Traffic Events become a powerful tool to monitor and troubleshoot this inter-site traffic.
|
||||
|
||||
Consider two sites: Site A (with subnet 10.1.0.0/16, routing peer = Peer-A) and Site B (with subnet 192.168.1.0/24, routing peer = Peer-B).
|
||||
NetBird is configured so that each site’s subnet is accessible to the other via the respective routing peers.
|
||||
Now suppose a host in Site A (10.1.0.50) is trying to reach a host in Site B (192.168.1.75) on some service.
|
||||
|
||||
Here’s how the Traffic Events play out:
|
||||
|
||||
* Peer-A’s logs (routing peer at Site A): Peer-A will log an incoming event from 10.1.0.50 (a host on its LAN)
|
||||
going to 192.168.1.75 via the NetBird tunnel.
|
||||
* Peer-B’s logs (routing peer at Site B): Correspondingly, Peer-B will log an incoming event from Peer-A (over NetBird)
|
||||
destined to 192.168.1.75 on its local network.
|
||||
|
||||
Using these logs, you can trace end-to-end connectivity between sites.
|
||||
If Site A can’t talk to Site B, check Peer-A’s logs: do we see events attempting to go out?
|
||||
If not, the issue might be that the Site A host isn’t routing to Peer-A.
|
||||
If yes, then check Peer-B’s logs: did it receive anything?
|
||||
If Peer-B’s log is empty for that traffic, then maybe the tunnel is down or ACL is missing.
|
||||
If Peer-B got it and forwarded to 192.168.1.75, but no reply came, then the problem is likely on the Site B host or network.
|
||||
Essentially, the Traffic Events allow you to break the problem into segments (A -> tunnel, tunnel -> B, B -> host, etc.).
|
||||
|
||||
Even in normal operation, site-to-site Traffic Events give visibility into the volume and types of traffic flowing between locations.
|
||||
This can be useful for capacity planning or security monitoring.
|
||||
For example, if one site suddenly starts sending a lot of data to another at odd hours, the logs on the routing peers will reflect that in bytes and packets counts.
|
||||
Administrators might set up external log analysis to alert on unusual site-to-site flow patterns (e.g., a spike in ICMP traffic or large data transfers).
|
||||
|
||||
# Privacy and Security Considerations
|
||||
**[CHECK] Add this section if needed**
|
||||
|
||||
# Conclusion
|
||||
|
||||
Traffic Events in NetBird provide network administrators with valuable visibility into the traffic within their secure network, all while operating at a high level that avoids delving into packet contents.
|
||||
In this documentation, we covered what Traffic Events are and how they function on NetBird clients:
|
||||
they record who is talking to whom, over what, and when, giving you an overview of network activity that is essential for both troubleshooting and security auditing.
|
||||
We outlined the data points collected (IPs, ports, timestamps, etc.) and noted that by default NetBird is careful not to log sensitive payload or DNS information, aligning the feature with privacy best practices.
|
||||
|
||||
@@ -1,101 +0,0 @@
|
||||
# Plans and billing
|
||||
|
||||
## NetBird Plans
|
||||
|
||||
NetBird offers diverse plans to accommodate various networking needs, ensuring scalable and secure connectivity.
|
||||
|
||||
- **Free Plan:** The Free plan provides secure connectivity for up to 5 users and 100 machines suitable for individuals or small teams.
|
||||
It features peer-to-peer connections and encryption, access control, routing, and private DNS. This plan includes Single Sign-On (SSO) integration with identity providers like Google Workspace, Azure, and Okta.
|
||||
|
||||
- **Team Plan:** Priced at **$5 per user per month**, the Team Plan offers unlimited admin and regular users, multi-factor authentication (MFA), access and connection logging, user and group provisioning and sync from your identity provider (IdP), and custom SSO login options, making it ideal for larger teams seeking scalable and secure connectivity.
|
||||
|
||||
- **Business Plan:** At **$12 per user per month**, the Business Plan offers enhanced network security with a Zero Trust approach. It supports unlimited users and includes features like device approvals and integrations (MDM and EDR) for comprehensive control, device posture checks and activity events streaming, making it an excellent choice for organizations seeking advanced security solutions.
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/pricing-overview.png" alt="pricing-overview" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
Details can be found on our [pricing page](https://netbird.io/pricing).
|
||||
|
||||
## Usage-based Billing
|
||||
|
||||
NetBird uses a pay-as-you-go model, charging only for active users or machines.
|
||||
We bill you at the end of each monthly cycle based on actual usage:
|
||||
* A user or machine counts as "active" only if it connects or logs in (including the admin dashboard) at least once during the billing period.
|
||||
* If you integrate NetBird with your [Identity Provider (IdP)](/manage/team/idp-sync),
|
||||
we automatically sync your users and machines. Inactive synced user accounts that never connect or log in won't incur charges.
|
||||
|
||||
Example:
|
||||
You sync 300 users from Entra ID, but only 100 connect during the month. You're billed for 100 users, not 300.
|
||||
If the next month only 70 connect, you pay for 70 users.
|
||||
|
||||
Refer to our pricing calculator on the [pricing page](https://netbird.io/pricing#calculator) to estimate your monthly costs based on your expected usage.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/plans-and-billing/calculator.png" alt="pricing-calculator" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
## Machine-based Usage
|
||||
|
||||
NetBird offers scalable plans for networks with a machine-based usage model. This approach is relevant, among other scenarios,
|
||||
for IoT use cases where there is a large number of machines on the network but comparatively fewer users.
|
||||
This option is available under both Team and Business plans. Simply subscribe to the Team or Business plan, and we'll
|
||||
automatically adjust the machine costs as detailed in the following sections.
|
||||
|
||||
|
||||
### Inclusive Machine Allowance
|
||||
- **Team and Business plans**: Start with 100 free machines and an extra 10 machines for each paid user.
|
||||
- **Example**: a Team plan with 10 users provides:
|
||||
- `(10 users × 10 machines/user) + 100 base machines = 200 machines`
|
||||
|
||||
### Additional Machine Billing
|
||||
- Extra machines are billed at a set rate per machine.
|
||||
- **Example**: Adding 20 extra machines to a Team plan with 10 users:
|
||||
- Base plan cost: `(10 users × €5/user) = €50`
|
||||
- Extra machines cost: `(20 extra machines × €0.5/machine) = €10`
|
||||
- **Total monthly cost**: `€50 + €10 = €60`
|
||||
|
||||
## Starting a Subscription
|
||||
|
||||
To start or change your current plan, navigate to `Settings` > `Plans & Billing` and choose the plan you wish to upgrade or downgrade to.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/plans-and-billing/chose-plan.png" alt="chose-plan" width="780" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
**Payment Information**
|
||||
|
||||
Next, you'll be directed to enter your payment information. Available payment options currently include credit cards, Google Pay, and Link.
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/payment-information.png" alt="payment-information" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
**Confirmation and Billing Cycle**
|
||||
|
||||
After successfully submitting your payment information, the updated version of your plan will be reflected in your account.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/plans-and-billing/plans-billing-overview.png" alt="plans-billing-overview" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
|
||||
<Note>
|
||||
Please note that changes to the number of peers and user counts are updated in our system daily at 2 AM UTC. So, it might take up to 24 hours for these changes to show in your account.
|
||||
</Note>
|
||||
|
||||
|
||||
## Changing a Subscription
|
||||
|
||||
Based on your current plan, you have the flexibility to upgrade or downgrade at any time as your needs change.
|
||||
|
||||
<Note>
|
||||
Your subscription cycle starts on the first day of your original subscription. If you adjust your plan during the billing cycle, and since billing occurs at the end of the subscription month, you will be charged for the plan you are on at the end of the billing cycle.
|
||||
</Note>
|
||||
|
||||
|
||||
## Deleting an Account
|
||||
|
||||
If you [delete your account](https://docs.netbird.io/how-to/delete-account), the final charge for your usage will be processed during the next daily statistics update cycle at 2 AM UTC.
|
||||
@@ -1,238 +0,0 @@
|
||||
# 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.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/profiles/profiles.png" alt="profiles" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Watch a short demo GIF demonstrating how profile switching works [here](/docs-static/img/how-to-guides/profiles/profiles.gif).
|
||||
|
||||
## NetBird 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
|
||||
|
||||
* **Add** a new profile with a friendly name input.
|
||||
* **Delete** any inactive profile (trash icon).
|
||||
* **Active and default** profiles cannot be removed.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/profiles/manage-profiles.png" alt="profiles" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
## 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?
|
||||
|
||||
- **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
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
sudo netbird service install --disable-profiles
|
||||
```
|
||||
|
||||
Alternatively, you can set the `NB_DISABLE_PROFILES` environment variable:
|
||||
|
||||
```shell
|
||||
export NB_DISABLE_PROFILES=true
|
||||
sudo netbird service install
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Profile CLI Commands
|
||||
|
||||
With the CLI, you can manage profiles easily. The main command is:
|
||||
|
||||
```bash
|
||||
netbird profile <add|list|select|remove> [name]
|
||||
````
|
||||
|
||||
### Add a New Profile
|
||||
|
||||
To create a new profile, use the command:
|
||||
|
||||
```bash
|
||||
netbird profile add <PROFILE_NAME>
|
||||
```
|
||||
|
||||
For example, the command below creates a new profile named `work`:
|
||||
|
||||
```bash
|
||||
netbird profile add work
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
The command below lists all available profiles along with their status:
|
||||
|
||||
```bash
|
||||
netbird profile list
|
||||
```
|
||||
|
||||
For example, running this command might output:
|
||||
|
||||
```text
|
||||
Found 3 profiles:
|
||||
✓ work
|
||||
✗ default
|
||||
✗ home
|
||||
```
|
||||
|
||||
* **✓** = active
|
||||
* **✗** = inactive
|
||||
|
||||
### Select (Switch) a Profile
|
||||
|
||||
To switch to a specific profile, use:
|
||||
|
||||
```bash
|
||||
netbird profile select <PROFILE_NAME>
|
||||
```
|
||||
|
||||
For example, to switch to the `home` profile:
|
||||
|
||||
```bash
|
||||
netbird profile select home
|
||||
```
|
||||
|
||||
The successful command will output:
|
||||
|
||||
```text
|
||||
Profile switched successfully to: home
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```text
|
||||
Error: profile home does not exist
|
||||
```
|
||||
|
||||
### Remove a Profile
|
||||
|
||||
To remove a profile, use:
|
||||
|
||||
```bash
|
||||
netbird profile remove <PROFILE_NAME>
|
||||
```
|
||||
|
||||
For example, to remove the `home` profile:
|
||||
|
||||
```bash
|
||||
netbird profile remove home
|
||||
```
|
||||
|
||||
If successful, you'll see:
|
||||
|
||||
```text
|
||||
Profile removed successfully: home
|
||||
```
|
||||
|
||||
You can't remove an active profile. If the profile your are trying to remove is active, you'll see an error:
|
||||
|
||||
```text
|
||||
Cannot remove active profile: home
|
||||
```
|
||||
|
||||
If the profile does not exist, you'll see an error message:
|
||||
|
||||
```text
|
||||
Error: profile home does not exist
|
||||
```
|
||||
|
||||
The command does the following in the background:
|
||||
|
||||
* Removes `home.json` and `home.state.json` files from your config folder.
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
|
||||
```bash
|
||||
netbird up --profile work
|
||||
netbird login --profile home
|
||||
```
|
||||
|
||||
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,67 +0,0 @@
|
||||
# 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](#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](/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](/slack-url).
|
||||
|
||||
## 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](/how-to/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.
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user