sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-19 17:06:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reorganize Get Started Documentation Structure (#490)

Browse Source
This commit is contained in:
Brandon Hopkins
2025-11-21 17:17:10 -08:00
committed by GitHub
parent 0878851d41
commit 227e5cbb89
79 changed files with 182 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

700
src/pages/get-started/cli.mdx Normal file
View File

@@ -0,0 +1,700 @@
# NetBird Agent command line interface (CLI)
The NetBird client installation adds a binary called `netbird` to your system. This binary runs as a daemon service to connect
your computer or server to the NetBirt network as a peer. But it can also be used as a client to control the daemon service.
This section will explore the commands available in `netbird`.
## Syntax
Use the following syntax to run `netbird` commands from your terminal window:
```shell
netbird [command] [subcommand] [flags]
```
* `command`: Specifies the operation that you want to perform or a top-level command: `up`, `login`, `down`, `status`, `ssh`, `version`, and `service`
* `subcommand`: Specifies the operation to be executed for a top-level command like `service`: `install`, `uninstall`, `start`, and `stop`
* `flags`: Specifies optional flags. For example, you can use the `--setup-key` flag to specify the setup key to be used in the commands `login` and `up`
<Note>
To see detailed command information, use the flag `--help` after each command
</Note>
## Configuration precedence
This is the CLI configuration precedence (highest to lowest priority):
1. environment variables (eg: `NB_WIREGUARD_PORT`)
2. command line flags (eg: `--wireguard-port`)
3. configuration file entries `<profile>.json` (formerly: `config.json`), eg: `WgPort` key
We are preserving the unusual priority of environment variables for backwards compatibility with existing deployments.
## Global flags
`netbird` has a set of global flags that are available in every command. They specify settings that are core or shared between two or more commands, e.g. `--setup-key` is used by `login` and `up` to authenticate the client against a management service.
Below is the list of global flags:
```shell
--admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io")
-A, --anonymize anonymize IP addresses and non-netbird.io domains in logs and status output
--daemon-addr string Daemon service address to serve CLI requests [unix|tcp]://[path|host:port] (default "unix:///var/run/netbird.sock")
--log-file string sets NetBird log path. If console is specified the the log will be output to stdout (default "/var/log/netbird/client.log")
-l, --log-level string sets NetBird log level (default "info")
-m, --management-url string Management Service URL [http|https]://[host]:[port] (default "https://api.wiretrustee.com:443")
-p, --preshared-key string Sets Wireguard PreSharedKey property. If set, then only peers that have the same key can communicate.
-k, --setup-key string Setup key obtained from the Management Service Dashboard (used to register peer)
```
### Environment Variables
Every flag of a `netbird` command can be passed as an environment variable. We are using the following rule for the environment variables composition:
* `PREFIX_FLAGNAME` and for flags with multiple parts: `PREFIX_FLAGNAMEPART1_FLAGNAMEPART2`
* The prefix is always **NB**
* The flag parts are separated by a dash ("-") when passing as flags and with an underscore ("_") when passing as an environment variable
For example, let's check how we can pass `--config` and `--management-url` as environment variables:
```shell
export NB_CONFIG="/opt/netbird/config.json"
export NB_MANAGEMENT_URL="https://api.self-hosted.com:33073"
netbird up
```
The `up` command would process the variables, read the configuration file on `/opt/netbird/config.json` and attempt to connect to the management service running at `https://api.self-hosted.com:33073`.
Here are some additional examples of environment variables:
```shell
# Disable profiles feature
export NB_DISABLE_PROFILES=true
# Disable update settings functionality
export NB_DISABLE_UPDATE_SETTINGS=true
# Set custom log level
export NB_LOG_LEVEL=debug
# Set custom daemon address
export NB_DAEMON_ADDR="tcp://localhost:8080"
```
## Commands
### up
Single command to log in and start the NetBird client. It can send a signal to the daemon service or run in the foreground with the flag `--foreground-mode`.
The command will check if the peer is logged in and connect to the management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
#### Flags
```shell
--allow-server-ssh Allow SSH server on peer. If enabled, the SSH server will be permitted
--disable-auto-connect Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.
--disable-ssh-auth Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication
--dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best ip and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address ""
--ssh-jwt-cache-ttl int SSH JWT token cache TTL in seconds. Set to 0 to disable caching (default). E.g. --ssh-jwt-cache-ttl 3600 for 1-hour cache
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
--enable-ssh-local-port-forwarding Enable local port forwarding on SSH server. Requires --allow-server-ssh
--enable-ssh-remote-port-forwarding Enable remote port forwarding on SSH server. Requires --allow-server-ssh
--enable-ssh-root Enable root user login on SSH server. Requires --allow-server-ssh
--enable-ssh-sftp Enable SFTP subsystem on SSH server. Requires --allow-server-ssh
--external-ip-map strings Sets external IPs maps between local addresses and interfaces.You can specify a comma-separated list with a single IP and IP/IP or IP/Interface Name. An empty string "" clears the previous configuration. E.g. --external-ip-map 12.34.56.78/10.0.0.1 or --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1 or --external-ip-map ""
--extra-dns-labels strings Sets DNS labels. You can specify a comma-separated list of up to 32 labels. An empty string "" clears the previous configuration. E.g. --extra-dns-labels vpc1 or --extra-dns-labels vpc1,mgmt1 or --extra-dns-labels ""
-F, --foreground-mode start service in foreground
-h, --help help for up
--interface-name string Wireguard interface name (default "utun100")
--rosenpass-permissive [Experimental] Enable Rosenpass in permissive mode to allow this peer to accept WireGuard connections without requiring Rosenpass functionality from peers that do not have Rosenpass enabled.
--wireguard-port uint16 Wireguard interface listening port (default 51820)
```
#### Usage
The minimal form of running the command is:
```shell
netbird up
```
If you are running on a self-hosted environment, you can pass your management url by running the following:
```shell
netbird up --management-url https://api.self-hosted.com:33073
```
if you want to run in the foreground, you can use "console" as the value for `--log-file` and run the command with sudo:
```shell
sudo netbird up --log-file console
```
<Note>
On Windows, you may need to run the command from an elevated terminal session.
</Note>
In case you need to use a setup key, use the `--setup-key` flag :
```shell
netbird up --setup-key AAAA-BBB-CCC-DDDDDD
```
You can set extra DNS labels with the `--extra-dns-labels` flag:
```shell
netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels vpc1,mgmt1
```
<Note>
This feature requires a setup-key with permissions to add peers with the extra labels.
</Note>
Multiple peers with the same extra labels will generate grouped DNS labels on the client side, and this feature can be used for DNS round-robing load balancing.
### login
Command to authenticate the NetBird client to a management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
#### Usage
The minimal form of running the command is:
```shell
netbird login
```
If you are running on a self-hosted environment, you can pass your management url by running the following:
```shell
netbird login --management-url https://api.self-hosted.com:33073
```
In case you need to use a setup key, use the `--setup-key` flag:
```shell
netbird login --setup-key AAAA-BBB-CCC-DDDDDD
```
Passing a management url and a setup key:
```shell
netbird login --setup-key AAAA-BBB-CCC-DDDDDD --management-url https://api.self-hosted.com:33073
```
### down
Command to stop a connection with the management service and other peers in a NetBird network. After running this command, the daemon service will enter an `Idle` state.
#### Usage
The minimal form of running the command is:
```shell
netbird down
```
### status
Retrieves the peer status from the daemon service.
#### Flags
```shell
-d, --detail display detailed status information in human-readable format
--filter-by-ips strings filters the detailed output by a list of one or more IPs, e.g., --filter-by-ips 100.64.0.100,100.64.0.200
--filter-by-names strings filters the detailed output by a list of one or more peer FQDN or hostnames, e.g., --filter-by-names peer-a,peer-b.netbird.cloud
--filter-by-status string filters the detailed output by connection status(connected|disconnected), e.g., --filter-by-status connected
-A, --anonymize anonymize IP addresses and non-netbird.io domains in the status output
-h, --help help for status
--ipv4 display only NetBird IPv4 of this peer, e.g., --ipv4 will output 100.64.0.33
--json display detailed status information in json format
--yaml display detailed status information in yaml format
```
#### Usage
The minimal form of running the command is:
```shell
netbird status
```
This will output:
```shell
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 1/1 Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
If you want to see more details about the peer connections, you can use the `--detail` or `-d` flag:
```shell
netbird status -d
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.85.4
Public key: 2lI3F+fDUWh58g5oRN+y7lPHpNcEVWhiDv/wr1/jiF8=
Status: Disconnected
-- detail --
Connection type: -
Direct: false
ICE candidate (Local/Remote): -/-
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 26 seconds ago
Last Wireguard handshake: -
Transfer status (received/sent) 0 B/0 B
Quantum resistance: false
Routes: -
Latency: 10.74ms
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 26 seconds ago
Last Wireguard handshake: 25 seconds ago
Transfer status (received/sent) 2.0 KiB/355 B
Quantum resistance: false
Routes: 10.0.0.0/24
Latency: 20.14ms
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 26 seconds ago
Last Wireguard handshake: 24 seconds ago
Transfer status (received/sent) 2.4 MiB/532 KiB
Quantum resistance: false
Routes: -
Latency: 16.24ms
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
Relays:
[stun:stun.netbird.io:5555] is Available
[turns:turn.netbird.io:443?transport=tcp] is Available
Nameservers:
[8.8.8.8:53, 8.8.4.4:53] for [.] is Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
To filter the peers' output by connection status, you can use the `--filter-by-status` flag with either "connected" or "disconnected" as value:
```shell
netbird status -d --filter-by-status connected
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 28 seconds ago
Last Wireguard handshake: 27 seconds ago
Transfer status (received/sent) 2.0 KiB/355 B
Quantum resistance: false
Routes: 10.0.0.0/24
Latency: 20.14ms
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 28 seconds ago
Last Wireguard handshake: 26 seconds ago
Transfer status (received/sent) 2.4 MiB/532 KiB
Quantum resistance: false
Routes: -
Latency: 16.24ms
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
Relays:
[stun:stun.netbird.io:5555] is Available
[turns:turn.netbird.io:443?transport=tcp] is Available
Nameservers:
[8.8.8.8:53, 8.8.4.4:53] for [.] is Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
To filter the peers' output by peer IP addresses, you can use the `--filter-by-ips` flag with one or more IPs separated by a comma as a value:
```shell
netbird status -d --filter-by-ips 100.119.201.225
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 32 seconds ago
Last Wireguard handshake: 30 seconds ago
Transfer status (received/sent) 2.0 KiB/355 B
Quantum resistance: false
Routes: 10.0.0.0/24
Latency: 20.14ms
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
Relays:
[stun:stun.netbird.io:5555] is Available
[turns:turn.netbird.io:443?transport=tcp] is Available
Nameservers:
[8.8.8.8:53, 8.8.4.4:53] for [.] is Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
You can combine both filters and get the peers that are both connected and with specific IPs:
```shell
netbird status -d --filter-by-status connected --filter-by-ips 100.119.85.4,100.119.230.104
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 35 seconds ago
Last Wireguard handshake: 33 seconds ago
Transfer status (received/sent) 2.4 MiB/532 KiB
Quantum resistance: false
Routes: -
Latency: 16.24ms
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
Relays:
[stun:stun.netbird.io:5555] is Available
[turns:turn.netbird.io:443?transport=tcp] is Available
Nameservers:
[8.8.8.8:53, 8.8.4.4:53] for [.] is Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
<Note>
The peer with IP `100.119.85.4` wasn't returned because it was not connected
</Note>
### ssh
Command to connect via SSH to a remote peer in your NetBird network. The `ssh` command has several subcommands for different operations.
<Note>
Before using this command, make sure that SSH Access is enabled both on the target peer and in the NetBird Dashboard. Learn more about [enabling SSH access](/how-to/ssh).
</Note>
#### ssh (connect)
Connect to a remote peer via SSH with an interactive shell or execute a command.
**Flags:**
```shell
-L, --local-forward string Local port forwarding (e.g., 8080:localhost:80)
-R, --remote-forward string Remote port forwarding (e.g., 8080:localhost:3000)
-p, --port int Remote SSH port (default: 22)
```
**Arguments:**
* `user@host`: The remote user and NetBird peer IP address
* `[command]`: Optional command to execute on the remote peer
**Usage:**
Interactive shell:
```shell
netbird ssh user@100.119.230.104
```
Execute a single command:
```shell
netbird ssh user@100.119.230.104 "uptime"
```
Local port forwarding (forward local port 8080 to remote port 80):
```shell
netbird ssh -L 8080:localhost:80 user@100.119.230.104
```
Remote port forwarding (forward remote port 8080 to local port 3000):
```shell
netbird ssh -R 8080:localhost:3000 user@100.119.230.104
```
<Note>
Port forwarding must be enabled on the SSH server using `--enable-ssh-local-port-forwarding` and/or `--enable-ssh-remote-port-forwarding` flags.
</Note>
<Note>
For SFTP and SCP, use native clients (`sftp` and `scp` commands) which work with NetBird SSH automatically.
</Note>
#### Troubleshooting
**Connection fails:**
- Ensure SSH is enabled on the target peer:
```shell
netbird up --allow-server-ssh
```
- Verify SSH Access is enabled in the dashboard (Peers > your_peer > SSH Access)
- Check that an ACL policy allows TCP port 22022
**Authentication fails:**
- Complete the OIDC flow when prompted (browser window will open)
- Verify your IdP is properly configured
- To disable JWT authentication: `netbird up --allow-server-ssh --disable-ssh-auth`
**Port forwarding not working:**
- Ensure the server has the appropriate flags:
```shell
netbird up --allow-server-ssh \
--enable-ssh-local-port-forwarding \
--enable-ssh-remote-port-forwarding
```
<p>
<img src="/docs-static/img/ssh/ssh-dashboard.png" alt="netbird ssh dashboard" className="imagewrapper-big" />
</p>
### version
Outputs the `netbird` command version.
#### Usage
The minimal form of running the command is:
```shell
netbird version
```
This will output:
```shell
0.8.2
```
### service
The service command is a top-level command with subcommands to perform operations related to the daemon service.
You should run the service command with elevated permissions.
### service install
The install installs the daemon service on the system.
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service install
```
You can use the global flags to configure the daemon service. For instance, you can set a debug log level with the flag `--log-level`
```shell
sudo netbird service install --log-level debug
```
You can set a custom configuration path with the flag `--config`
```shell
sudo netbird service install --config /opt/netbird/config.json
```
#### Service-specific flags
```shell
--disable-profiles Disables profiles feature. If enabled, the client will not be able to change or edit any profile. To persist this setting, use: netbird service install --disable-profiles
--disable-update-settings Disables update settings feature. If enabled, the client will not be able to change or edit any settings. To persist this setting, use: netbird service install --disable-update-settings
```
<Note>
The `--disable-profiles` flag can also be set using the `NB_DISABLE_PROFILES` environment variable. Set it to any value (e.g., `true`, `1`, `yes`) to enable this feature.
The `--disable-update-settings` flag can also be set using the `NB_DISABLE_UPDATE_SETTINGS` environment variable. Set it to any value (e.g., `true`, `1`, `yes`) to enable this feature.
</Note>
### service uninstall
The uninstall uninstalls the daemon service from the system.
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service uninstall
```
### service start
Starts the daemon service
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service start
```
<Note>
If you installed the service with `--disable-profiles` or `--disable-update-settings`, these settings will persist and the respective features will remain disabled when the service starts.
</Note>
### service stop
Stops the daemon service
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service stop
```
### service restart
Restarts the daemon service
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service restart
```
### service status
Shows the status of the daemon service
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service status
```
### service reconfigure
Reconfigures the daemon service with current settings
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service reconfigure
```
<Note>
If you installed the service with `--disable-profiles` or `--disable-update-settings`, these settings will persist and the respective features will remain disabled after reconfiguration.
</Note>
### debug
The `debug` command provides tools for diagnosing and understanding the internal operations of the NetBird daemon.
#### Usage
To access debugging options:
```shell
netbird debug [command]
```
#### Subcommands
- `bundle`: Create a debug bundle that includes logs and system information for troubleshooting.
- `for`: Run the daemon with trace logging for a specified duration and create a debug bundle.
- `log`: Manage logging levels for the NetBird daemon.
#### Flags
```shell
-h, --help help for debug
```
### debug bundle
Generates a compressed archive containing diagnostic information, which can be used for troubleshooting.
The file will be generated in the a temporary directory and the path will be printed to the console.
The file is only accessible as root/Administrator.
#### Usage
To create a debug bundle:
```shell
netbird debug bundle [-A] [-S]
```
#### Examples
Create a debug bundle:
```shell
netbird debug bundle
```
This will output:
```
/tmp/netbird.debug.676945815.zip
```
#### Flags
```shell
-h, --help help for bundle
-A, --anonymize anonymize IP addresses and non-netbird.io domains in the debug output
-S, --system-info Adds system information to the debug bundle
```
### debug for
Sets the logging level to trace, runs for the specified duration, and then generates a debug bundle.
This is useful for capturing detailed logs over a period where issues are occurring.
#### Usage
To run debugging for a specific time period:
```shell
netbird debug for <time> [-A] [-S]
```
#### Examples
Run debugging for 5 minutes and generate an anonymized debug bundle:
```shell
netbird debug for 5m
```
This will output something similar to:
```
Netbird up
Log level set to trace.
Netbird down
Netbird up
Remaining time: 00:00:01
Duration completed
Creating debug bundle...
Netbird down
Log level restored to INFO
/tmp/netbird.debug.3162242909.zip
```
#### Flags
```shell
-h, --help help for for
-A, --anonymize anonymize IP addresses and non-netbird.io domains in the debug output
-S, --system-info Adds system information to the debug bundle
```
### debug log
This subcommand manages the logging level for the NetBird daemon during the current session.
The change in logging level is temporary and will revert back to the configured default upon daemon restart.
#### Usage
Adjust the logging level of the NetBird daemon:
```shell
netbird debug log level <level>
```
#### Available Levels
- `panic`: for panic level, the highest level of severity.
- `fatal`: for fatal level errors that cause the program to exit.
- `error`: for error conditions.
- `warn`: for warning conditions.
- `info`: for informational messages.
- `debug`: for debug-level messages.
- `trace`: for trace-level messages, which include more fine-grained information than debug.
#### Examples
Set the logging level to debug:
```shell
netbird debug log level debug
```
This will output:
```
Log level set successfully to debug
```

196
src/pages/get-started/index.mdx Normal file
View File

@@ -0,0 +1,196 @@
import {Note} from "@/components/mdx";
export const title = 'Getting Started'
## Quickstart Guide
Welcome to NetBird! This guide will walk you through our new onboarding process to create your account, connect your first devices,
and build a secure peer-to-peer overlay network in less than ten minutes.
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/dr0u-u9uD84" allow="fullscreen;"></iframe>
</div>
## Create Your Account
First, let's create your NetBird account.
![NetBird IdP SSO and MFA](/docs-static/img/get-started/onboarding/01_netbird-sso.jpeg)
1. Navigate to [netbird.io](https://netbird.io/) and click Get Started in the top-right corner. Or simply click [here](https://app.netbird.io/).
2. You’ll be redirected to the sign-in page, where NetBird uses your identity provider (IdP) for secure authentication.
It supports any OIDC-compliant provider, including social logins like Gmail and GitHub for personal use.
3. Follow the authentication steps for your chosen provider. If you have multi-factor authentication (MFA) enabled on your IdP account,
it will work automatically.
Upon your first login, you'll be greeted by a short onboarding survey. This helps us tailor your experience.
## Peer-to-Peer Network
One way of using NetBird is to create a peer-to-peer network, where you run the NetBird client on your devices to connect them directly.
![Onboarding Method Selection](/docs-static/img/get-started/onboarding/02_p2p-network.jpeg)
The onboarding process will now guide you to connect your first device, also known as a peer.
For this guide, we'll select Peer-to-Peer Network. If you’re selecting the Remote Network Access option, you can see that process [here](#remote-network-access).
### Install Your First Peer
![Download NetBird](/docs-static/img/get-started/onboarding/03_download-netbird.jpeg)
1. On the "Let's get your first device online" screen, click the Install NetBird button.
2. An [installation modal](https://app.netbird.io/install) will appear. Select your operating system (e.g., macOS, Windows, Linux). For this example, we're installing it on a macOS machine.
3. Download the installer and run it. Follow the on-screen prompts to complete the installation.
### Connect Your First Peer
With the client installed, you now need to connect it to your network.
![Connect NetBird Client](/docs-static/img/get-started/onboarding/04_connect-client.jpeg)
1. After installation, find the NetBird icon in your system tray or menu bar.
2. Click the icon and select **Connect**.
3. This will open a new browser tab, prompting you to authorize the new device. Authenticate using the same IdP you used to sign up.
4. Once authorized, you will see a "Login successful" message. The onboarding UI will update to show that your first peer is connected, displaying its name and assigned NetBird IP address.
### Add a Second Peer (Headless Linux Server)
Next, let's add a second, headless peer, like a Linux server or a Raspberry Pi. For devices without a graphical interface, we use a [Setup Key](https://docs.netbird.io/how-to/register-machines-using-setup-keys).
![Install NetBird Headless](/docs-static/img/get-started/onboarding/05_headless-installed.jpeg)
1. In the web UI, the onboarding flow will now prompt you to "bring in your second device." Click the link that says Install with a setup key.
2. A pop-up will explain that a one-off setup key will be created, which you can also learn more about here. Click Continue..
3. The onboarding UI will now provide two commands to run on your Linux server:
* **Install NetBird**: A curl command to download and run the installation script.
* **Run NetBird**: A [netbird up command](https://docs.netbird.io/get-started/cli) that includes your unique setup key.
4. SSH into your Linux server and run the commands:
First, copy the curl command, paste it into your server's terminal, and press **Enter**. You may be prompted for your sudo password.
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
Next, copy the netbird up --setup-key ... command and paste it into the terminal.
```bash
netbird up --setup-key <YOUR_SETUP_KEY>
```
After running the second command, the terminal will confirm Connected. Your headless device is now part of your NetBird network.
![Headless install connected](/docs-static/img/get-started/onboarding/06_headless-install-connected.jpeg)
### Verify the Connection
The onboarding UI will now display both of your connected peers. The onboarding wizard provides a simple way to test that they can communicate directly.
![Testing ping on NetBird](/docs-static/img/get-started/onboarding/07_ping-test.jpeg)
1. Copy the provided ping command from the onboarding UI. This command uses the NetBird IP address of your second peer (the Ubuntu server).
2. Open a terminal on your first peer and paste the command. Replace the example below with the NetBird IP for your machine.
```bash
ping 100.74.76.17
```
3. You should see successful ping replies, confirming that the two devices are connected over the NetBird network. Click It works! - Continue in the onboarding UI.
### Understanding Access Control
The final onboarding step introduces NetBird's powerful Access Control policies.
![NetBird policy disabled](/docs-static/img/get-started/onboarding/08_policy-disabled-example.jpeg)
1. By default, a policy is active that allows connections between all your devices. This is why the ping command in the previous step worked.
2. The wizard demonstrates this by allowing you to toggle the policy. If you disable the "Default Policy," the ping between your devices will immediately fail with a "Request timeout" error.
3. Re-enabling the policy instantly restores the connection. This gives you a basic understanding of how you can control traffic within your network. You can learn much more about policies [here](/manage/access-control/manage-network-access).
4. Click Continue to finish.
![Policy Example](/docs-static/img/get-started/onboarding/09_policy-example.jpeg)
In the policy example above, we allowed _IT Admins_ port specific access to peers under the _AWS Servers_ group. Policies are a key building block to access in NetBird. You can learn more about the power of policies [here](https://docs.netbird.io/manage/access-control/manage-network-access).
<Note>
If you manage users and groups with your identity provider, you can provision and sync them with NetBird. Learn more [here](https://docs.netbird.io/how-to/idp-sync) including the supported platforms.
</Note>
## Remote Network Access
The second way to use NetBird is for remote network access by running NetBird on a single machine within your private network.
This machine acts as a routing peer, routing traffic to internal resources that don't have the NetBird client installed.
The onboarding process will now guide you to build our first network resource.
For this guide, we'll select Remote Network Access.
![NetBird Onboarding](/docs-static/img/get-started/onboarding/10_remote-access-onboarding.jpeg)
### Define Your Network Resource
Next, you'll define the private network you want your users to be able to access.
1. The onboarding UI will prompt you to "Add your first resource." There are a few options here, but the easiest way to get started is with full access to an entire Network. Select the Entire Subnet option.
2. Enter the CIDR range of your private network. For example, `10.0.0.0/32`.
3. Click Create Resource. A "Network" will be created in your dashboard to contain this resource and its access rules.
![NetBird Subnet Setup](/docs-static/img/get-started/onboarding/11_entire-subnet.jpeg)
### Add and Configure a Routing Peer
A [routing peer](https://docs.netbird.io/how-to/routing-traffic-to-private-networks) is a NetBird peer that lives inside your private network and acts as a gateway, forwarding traffic between your remote users and the internal resources.
![Adding a routing peer](/docs-static/img/get-started/onboarding/12_add-routing-peer.jpeg)
1. The dashboard will now prompt you to "Add a routing peer." First, click Generate Setup Key. This creates a one-time key used to enroll the gateway machine into your NetBird account.
2. Next, click Install Routing Peer. Select the operating system of your gateway machine (the video uses Linux).
3. The installation modal will provide two commands: a curl script to install the NetBird agent and a netbird up command that includes your setup key.
4. SSH into your gateway machine (which must be inside the 10.0.0.0/24 subnet) and run the commands:
5. SSH into your Linux server and run the commands:
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
Next, copy the netbird up --setup-key ... command and paste it into the terminal.
```bash
netbird up --setup-key <YOUR_SETUP_KEY>
```
After running the second command, the terminal will confirm Connected. Your headless device is now part of your NetBird network.
### Connect a Client Device
Now, set up the device you will use to connect to your private network.
1. Back in the web UI, the wizard will prompt you to "Time to add your client device." Click Install NetBird.
2. Download and run the installer for your client machine's OS (e.g., macOS).
3. Once installed, find the NetBird icon in your system tray or menu bar, click it, and select Connect.
4. Authorize this new device in the browser tab that opens.
### Test the Connection
With both the routing peer and your client device online, you can now test your connection to the private network. To properly test connectivity you should move the client device to a different network, for example, connecting the device using your phone's hotspot.
![Switching Network](/docs-static/img/get-started/onboarding/13_switching-network.jpeg)
1. Open a terminal on your client device and run the test command (e.g., `ping 10.0.0.100`). Due note, the IP you ping needs to be a device on the same network that the routing peer is installed on.
2. You should see successful replies, confirming that your client device can reach internal resources through the routing peer.
3. Click It works! - Continue in the UI.
### Understanding Your Access Policy
The final step of the onboarding wizard explains the access rule that was automatically created for you.
![Testing Worked](/docs-static/img/get-started/onboarding/14_it-worked.jpeg)
1. A policy, named "Users to My Subnet," is enabled by default. This policy allows all authenticated users to access the resources within the subnet you define.
2. To demonstrate this, you can toggle this policy off. When disabled, the ping from your client device will begin to fail with a "Request timeout" error, showing that the connection is now blocked.
3. Re-enabling the policy will immediately restore access.
4. Click Continue to complete the setup.
![Understanding Your Access Policy](/docs-static/img/get-started/onboarding/16_onboarding-policies.jpeg)
Click Go to Dashboard to access the main NetBird admin panel. From here, you can:
* [Control Center](https://docs.netbird.io/how-to/control-center): Visualize your network topology and access relationships with an interactive graph.
* [Peers](https://docs.netbird.io/how-to/add-machines-to-your-network): View and manage all connected devices and their properties.
* [Setup Keys](https://docs.netbird.io/how-to/register-machines-using-setup-keys): Create and manage keys for adding new headless or ephemeral devices.
* [Access Control](https://docs.netbird.io/manage/access-control/manage-network-access): Define granular firewall rules to control which peers can access what.
* [Team](https://docs.netbird.io/how-to/add-users-to-your-network): Manage users and create groups for easier policy management.
You are now ready to explore the full capabilities of NetBird.
## Support Us
- Star us on [GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird release page on GitHub: [releases](https://github.com/netbirdio/netbird/releases/latest)

82
src/pages/get-started/install/docker.mdx Normal file
View File

@@ -0,0 +1,82 @@
import {Note} from "@/components/mdx";
# Docker Installation
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
## Docker Run Command
Set the ```NB_SETUP_KEY``` environment variable and run the command.
<Note>
You can pass other settings as environment variables. See [Environment variables](/get-started/cli#environment-variables) for details.
</Note>
NetBird makes use of eBPF and raw sockets, therefore to guarantee the client software functionality, we recommend adding the flags `--cap-add=SYS_ADMIN` and `--cap-add=SYS_RESOURCE` for docker clients.
The experience may vary depending on the docker daemon, operating system, or kernel version.
```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/var/lib/netbird netbirdio/netbird:latest
```
See [Docker example](/how-to/examples#net-bird-client-in-docker) for details.
### Troubleshooting
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
which is ```https://api.wiretrustee.com:33073```.
2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting)
to override it you can do the following:
```bash
netbird down
netbird up --management-url https://<CORRECT HOST:PORT>/
```
To override it see the solution #1 above.
## Docker Compose
If you prefer to run NetBird as a Docker compose stack below is an example. Configure to your specific needs.
```yaml
services:
netbird:
container_name: netbird
hostname: <HOSTNAME>
cap_add:
- NET_ADMIN
- SYS_ADMIN
- SYS_RESOURCE
network_mode: host
environment:
- NB_SETUP_KEY=<SETUP KEY>
volumes:
- netbird-client:/var/lib/netbird
image: netbirdio/netbird:latest
volumes:
netbird-client:
name: netbird-client
```
## Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/how-to/register-machines-using-setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/how-to/register-machines-using-setup-keys)).
```bash
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/var/lib/netbird netbirdio/netbird:<TAG>
```
> TAG > 0.6.0 version
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
````bash
sudo ifconfig utun100
````

87
src/pages/get-started/install/index.mdx Normal file
View File

@@ -0,0 +1,87 @@
import {Note} from "@/components/mdx";
# Install NetBird
If you're a new user you should visit the [Quickstart Guide](https://docs.netbird.io/get-started). This will help you setup your management dashboard and connect your first client. For quick install instructions, including desktop applications, visit the [install prompt](https://app.netbird.io/install) through the management dashboard. To view all the client installation methods we've set up a variety of platform specific pages.
<Button href="https://app.netbird.io/install" arrow="right" children="Download NetBird" />
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
## Install and Update Instructions
* [Install on Linux](/get-started/install/linux)
* [Install on macOS](/get-started/install/macos)
* [Install on Windows](/get-started/install/windows)
* [Install on Synology](/get-started/install/synology)
* [Install on Android](/get-started/install/mobile)
* [Install on iOS](/get-started/install/mobile)
## Running NetBird with SSO Login
### Desktop UI Application
If you installed the Desktop UI client, you can launch it and click on Connect.
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### CLI
Alternatively, you could use command line. Simply run
```bash
netbird up
```
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/docs-static/img/get-started/netbird-sso-login-cmd.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Check connection status:
```bash
netbird status
```
## Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/how-to/register-machines-using-setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/how-to/register-machines-using-setup-keys)).
For all systems:
```bash
netbird up --setup-key <SETUP KEY>
```
For **Docker**, you can run with the following command:
```bash
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/var/lib/netbird netbirdio/netbird:<TAG>
```
> TAG > 0.6.0 version
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
On **macOS** :
````bash
sudo ifconfig utun100
````
On **Linux**:
```bash
ip addr show wt0
```
On **Windows**:
```bash
netsh interface ip show config name="wt0"
```

278
src/pages/get-started/install/linux.mdx Normal file
View File

@@ -0,0 +1,278 @@
import {Note} from "@/components/mdx";
# Linux Installation
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
## Linux Install Script
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
### Ubuntu/Debian (APT)
1. Add the repository:
```bash
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg -y
curl -sSL https://pkgs.netbird.io/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/netbird-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netbird-archive-keyring.gpg] https://pkgs.netbird.io/debian stable main' | sudo tee /etc/apt/sources.list.d/netbird.list
```
2. Update APT's cache
```bash
sudo apt-get update
```
3. Install the package
```bash
# for CLI only
sudo apt-get install netbird
# for GUI package
sudo apt-get install netbird-ui
```
### RHEL/Amazon Linux 2 (RPM)
1. Add the repository:
```bash
sudo tee /etc/yum.repos.d/netbird.repo <<EOF
[netbird]
name=netbird
baseurl=https://pkgs.netbird.io/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.netbird.io/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
2. Install the package
```bash
# for CLI only
sudo yum install netbird
# for GUI package
sudo yum install libappindicator-gtk3 libappindicator netbird-ui
```
### Fedora/Amazon Linux 2023 (DNF)
1. Create the repository file:
```bash
sudo tee /etc/yum.repos.d/netbird.repo <<EOF
[netbird]
name=netbird
baseurl=https://pkgs.netbird.io/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.netbird.io/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
2. Import the file
```bash
#Fedora 40 or earlier/Amazon Linux 2023** (DNF 4)
sudo dnf config-manager --add-repo /etc/yum.repos.d/netbird.repo
#Fedora 41 or later (DNF 5)
sudo dnf config-manager addrepo --from-repofile=/etc/yum.repos.d/netbird.repo
```
3. Install the package
```bash
# for CLI only
sudo dnf install netbird
# for GUI package
sudo dnf install libappindicator-gtk3 libappindicator netbird-ui
```
On some recent releases, the default behaviour for `libappindicator` was changed, so we need to install `gnome-shell-extension-appindicator` and enable it:
```
sudo dnf install gnome-shell-extension-appindicator
sudo gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com
```
Under X11, you may need to restart GNOME Shell (Alt+F2, r, ⏎) after that. Under Wayland you need to logout and login again.
### Universal Blue (Native package)
1. Create the repository file:
```bash
sudo tee /etc/yum.repos.d/netbird.repo <<EOF
[netbird]
name=netbird
baseurl=https://pkgs.netbird.io/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.netbird.io/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
```
3. Install the package
```bash
# for CLI only
rpm-ostree install netbird
# for GUI package
rpm-ostree install netbird-ui
# Don't forget to reboot to apply
```
4. Start the service
```bash
systemctl enable --now netbird
```
### Fedora Universal Blue / SteamOS (DistroBox)
1. Create a distrobox container
```bash
distrobox create netbird --init --image debian:12 -a "--cap-add=NET_ADMIN" --additional-packages systemd --root
```
2. Install inside the container
```bash
distrobox enter --root netbird
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
3. Export the distrobird binary to the host
```bash
#from inside the container
distrobox-export -b /usr/bin/netbird
```
### openSUSE (zypper)
1. Add the repository:
```
sudo zypper addrepo https://pkgs.netbird.io/yum/ netbird
```
2. Install the package / GPG key
* Key Fingerprint: `AA9C 09AA 9DEA 2F58 112B 40DF DFFE AB2F D267 A61F`
* Key ID: `DFFEAB2FD267A61F`
* Email: `dev@netbird.io`
```
# MicroOS (immutable OS with selinux)
transactional-update pkg in netbird
reboot
# Tumbleweed / Leap
zypper in netbird
```
### NixOS 22.11+/unstable
1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)
```nix
{ config, pkgs, ... }:
{
services.netbird.enable = true; # for netbird service & CLI
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
}
```
2. Build and apply new configuration
```bash
sudo nixos-rebuild switch
```
### Binary Install
**Installation from binary (CLI only)**
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest release:
```bash
curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
```
<Note>
You need to replace some variables from the URL above:
- Replace **VERSION** with the latest released version.
- Replace **OS** with "linux", "darwin" for MacOS or "windows"
- Replace **Arch** with your target system CPU architecture
</Note>
3. Decompress
```bash
tar xzf ./netbird_<VERSION>.tar.gz
sudo mv netbird /usr/bin/netbird
sudo chown root:root /usr/bin/netbird
sudo chmod +x /usr/bin/netbird
```
After that you may need to add /usr/bin in your PATH environment variable:
````bash
export PATH=$PATH:/usr/bin
````
4. Install and run the service
```bash
sudo netbird service install
sudo netbird service start
```
## Updating
If your NetBird client was installed through a package manager, use that to update.
If you used the one-command script to install, you can follow this to update:
```bash
netbird down
curl -fsSLO https://pkgs.netbird.io/install.sh
chmod +x install.sh
./install.sh --update
netbird up
```
## Running NetBird with SSO Login
### Desktop UI Application
If you installed the Desktop UI client, you can launch it and click on Connect.
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### CLI
Alternatively, you could use command line. Simply run
```bash
netbird up
```
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/docs-static/img/get-started/netbird-sso-login-cmd.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Check connection status:
```bash
netbird status
```
## Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/how-to/register-machines-using-setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/how-to/register-machines-using-setup-keys)).
```bash
netbird up --setup-key <SETUP KEY>
```
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
```bash
ip addr show wt0
```

136
src/pages/get-started/install/macos.mdx Normal file
View File

@@ -0,0 +1,136 @@
import {Note} from "@/components/mdx";
# MacOS Installation
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
## Install with one command
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
### Package install
1. Download the latest MacOS release installer for your [processor](https://support.apple.com/en-us/HT211814 ):
- Intel: <Button href="https://pkgs.netbird.io/macos/amd64" variant="text" arrow="right">Download NetBird for Intel</Button>
- M1 & M2: <Button href="https://pkgs.netbird.io/macos/arm64" variant="text" arrow="right">Download NetBird for Apple Silicon</Button><br />
_If you require an older version checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)_
2. Proceed with the installation steps
3. This will install the NetBird app into /Applications and add the daemon service
4. After installing, you can follow the steps from [Running NetBird with SSO Login](#Running-NetBird-with-SSO-Login) steps.
> To uninstall the client remove the app from /Applications
### Homebrew install
1. Download and install homebrew at https://brew.sh/
2. If netbird was previously installed with homebrew, you will need to run:
```bash
# Stop and uninstall daemon service:
sudo netbird service stop
sudo netbird service uninstall
# unlink the app
brew unlink netbird
```
> netbird will copy any existing configuration from the netbird's default configuration paths to the new NetBird's default location
3. Install the client
```bash
# for CLI only
brew install netbirdio/tap/netbird
# for GUI package
brew install --cask netbirdio/tap/netbird-ui
```
4. If you installed CLI only, you need to install and start the client daemon service:
```bash
sudo netbird service install
sudo netbird service start
```
### Binary Install
**Installation from binary (CLI only)**
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest release:
```bash
curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
```
<Note>
You need to replace some variables from the URL above:
- Replace **VERSION** with the latest released version.
- Replace **OS** with "linux", "darwin" for MacOS or "windows"
- Replace **Arch** with your target system CPU architecture
</Note>
3. Decompress
```bash
tar xzf ./netbird_<VERSION>.tar.gz
sudo mv netbird /usr/bin/netbird
sudo chown root:root /usr/bin/netbird
sudo chmod +x /usr/bin/netbird
```
After that you may need to add /usr/bin in your PATH environment variable:
````bash
export PATH=$PATH:/usr/bin
````
4. Install and run the service
```bash
sudo netbird service install
sudo netbird service start
```
## Running NetBird with SSO Login
### Desktop UI Application
If you installed the Desktop UI client, you can launch it and click on Connect.
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### CLI
Alternatively, you could use command line. Simply run
```bash
netbird up
```
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/docs-static/img/get-started/netbird-sso-login-cmd.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Check connection status:
```bash
netbird status
```
### Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/how-to/register-machines-using-setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/how-to/register-machines-using-setup-keys)).
```bash
netbird up --setup-key <SETUP KEY>
```
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
````bash
sudo ifconfig utun100
````

26
src/pages/get-started/install/mobile.mdx Normal file
View File

@@ -0,0 +1,26 @@
import {Note} from "@/components/mdx";
# Mobile Applications
## Android
NetBird has an official Android application that you can download at Google Play Store:
<p>
<a href="https://play.google.com/store/apps/details?id=io.netbird.client" target="_blank">
<img src="/docs-static/img/how-to-guides/google-play-badge.png" alt="playstore" className="imagewrapper"/>
</a>
</p>
APK releases are also available to install directly on your Android device via the [NetBird Android GitHub repository](https://github.com/netbirdio/android-client/releases).
## iOS
NetBird has an official iOS application that you can download from the App Store:
<p>
<a href="https://apps.apple.com/de/app/netbird-p2p-vpn/id6469329339?l=en-GB" target="_blank">
<img src="/docs-static/img/how-to-guides/app-store-badge.svg" alt="appstore" className="imagewrapper" style={{ padding: '30px' }}/>
</a>
</p>

122
src/pages/get-started/install/opnsense.mdx Normal file
View File

@@ -0,0 +1,122 @@
# OPNsense Installation
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available,
there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/AK0Ct-ULFKg?start=669" allow="fullscreen;"></iframe>
</div>
<Note>
The NetBird package is officially included starting from OPNsense `25.7.3`.
</Note>
## Prerequisites
- Shell or Web UI access to your OPNsense system
- A [setup key](/how-to/register-machines-using-setup-keys#types-of-setup-keys) to authenticate and register the OPNsense device
## Installation
1. **Log in to your OPNsense system**
You can use the Web UI or SSH.
2. **Install the NetBird package**
In the OPNsense Web UI, navigate to `System` > `Firmware` > `Plugins`, and search for the `os-netbird` package. Click the install button next to it.
3. **Verify the installation**
Once installed, the NetBird configuration interface will be available under `VPN` > `NetBird` in the OPNsense menu
## Configuration
### Enable the service
Navigate to `VPN` > `NetBird` > `Settings` and ensure the toggle `Enable` is turned on in the `General` section.
This will enable us to continue with the next steps.
### Authenticate the machine
Fill out the authentication form with the following values and click `Save`:
- **Management URL**: Default is `https://api.netbird.io:443`. If self-hosting, enter your custom management server URL.
- **Setup Key**: Paste the setup key from your NetBird account.
<p>
<img src="/docs-static/img/get-started/opnsense/authentication.png" alt="authentication" className="imagewrapper-big"/>
</p>
### Verify Connection Status
The Status page shows detailed information about connected peers and control services, helping you monitor your deployment.
Access it via `VPN` > `NetBird` > `Status` in the OPNsense menu.
Use this section for diagnostics and troubleshooting common connection or setup issues.
<p>
<img src="/docs-static/img/get-started/opnsense/status.png" alt="connection status" className="imagewrapper-big"/>
</p>
### Assign NetBird interface
After installation, a new interface named `wt0` will be available but unassigned. To assign it go to `Interfaces` >
`Assignments`. Under `Assign a new interface`, set the following values:
- **Device**: `wt0`
- **Description**: `NetBird`
<p>
<img src="/docs-static/img/get-started/opnsense/interface_assignment.png" alt="interfaceAssignment" className="imagewrapper-big"/>
</p>
Click `Add` to assign the interface.
<p>
<img src="/docs-static/img/get-started/opnsense/new_interface.png" alt="interfaceAssignment" className="imagewrapper-big"/>
</p>
### Enable the NetBird interface
Now that the NetBird interface has been added, you need to enable it. Go to `Interfaces` > `[NetBird]`, then configure
the following options and click `Save`, then `Apply changes` to activate the interface:
- **Enable**: `✓ Enable Interface`
- **Lock**: `✓ Prevent interface removal`
<p> <img src="/docs-static/img/get-started/opnsense/enable_interface.png" alt="enableInterface" className="imagewrapper-big"/> </p>
<Note>
OPNsense includes native WireGuard support, however do not configure or manage the NetBird interface (wt0) via the OPNsense WireGuard UI.
NetBird fully manages the WireGuard interface and keys.
</Note>
### Configure Firewall Rules for the NetBird interface
To allow NetBird to handle all access control, permit all traffic on the NetBird interface in OPNsense.
This ensures traffic flows freely, while NetBird’s own policies (ACLs) govern the access restrictions.
1. Navigate to `Firewall` > `Rules` > `NetBird`.
2. Click `+ Add` to create a new rule.
3. Configure the rule:
- **Action**: `Pass`
- **Interface**: `NetBird`
- **Direction**: `in`
- **TCP/IP Version**: `IPv4`
- **Protocol**: `any`
- **Source**: `any`
- **Destination**: `any`
- **Description**: `Allow all on NetBird (managed by NetBird)`
4. Click `Save`, then `Apply changes`.
5. Ensure this rule is at the top of the `NetBird` rules list so it isn’t shadowed by other rules.
<p>
<img src="/docs-static/img/get-started/opnsense/firewall_rules.png" alt="firewallRules" 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

133
src/pages/get-started/install/pfsense.mdx Normal file
View File

@@ -0,0 +1,133 @@
# pfSense Installation
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available,
there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
<Note>
This installation is intended for early adopters while the pfSense package is under review and not yet available in the pfSense package manager.
</Note>
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/Kgrcquyeohc" allow="fullscreen;"></iframe>
</div>
## Prerequisites
- Shell/SSH access to pfSense (via Web UI shell or remote SSH)
- A [setup key](/how-to/register-machines-using-setup-keys#types-of-setup-keys) to authenticate and register the pfSense device
- The latest NetBird `.pkg` binary from the [GitHub Releases](https://github.com/netbirdio/pfsense-netbird/releases)
## Installation
1. **SSH into your pfSense system**
```sh
ssh admin@<pfsense-ip>
```
If remote SSH is enabled or use the built-in shell via the pfSense Web UI (`Diagnostics` > `Command Prompt`).
3. **Download the NetBird client(agent)**
From a shell on your pfSense system, run:
```sh
fetch https://github.com/netbirdio/pfsense-netbird/releases/download/v0.1.2/netbird-0.55.1.pkg
```
3. **Download the NetBird pfSense package**
From a shell on your pfSense system, run:
```sh
fetch https://github.com/netbirdio/pfsense-netbird/releases/download/v0.1.2/pfSense-pkg-NetBird-0.1.0.pkg
```
4. **Install the packages**
```sh
pkg add -f netbird-0.55.1.pkg
pkg add -f pfSense-pkg-NetBird-0.1.0.pkg
```
5. **Verify the installation**
The NetBird GUI should now appear under `VPN` > `NetBird` in the pfSense menu.
## Configuration
### Authenticate the machine
Fill out the authentication form with the following values and click `Save`:
- **Management URL**: Default is `https://app.netbird.io:443`. If self-hosting, enter your custom management server URL.
- **Setup Key**: Paste the setup key from your NetBird account. .
<p>
<img src="/docs-static/img/get-started/pfSense/authentication.png" alt="authentication" className="imagewrapper-big"/>
</p>
### Verify Connection Status
The Status page shows detailed information about connected peers and control services, helping you monitor your deployment.
Access it via `Status` > `NetBird` in the pfSense menu.
Use this section for diagnostics and troubleshooting common connection or setup issues.
<p>
<img src="/docs-static/img/get-started/pfSense/status.png" alt="connection status" className="imagewrapper-big"/>
</p>
### Assign NetBird interface
After authentication, a new interface named `wt0(wt0)` will be available but unassigned. To assign it go to
`Interfaces` > `Assignments`. Under `Available network ports`, select the NetBird interface `wt0(wt0)` and click `Add`.
<p>
<img src="/docs-static/img/get-started/pfSense/new_interface.png" alt="NewInterface" className="imagewrapper-big"/>
</p>
### Enable the NetBird interface
Now that the NetBird interface has been added, you need to enable it. Go to `Interfaces` > `OPT1`, then configure
the following options and click `Save`, then `Apply changes` to activate the interface:
- **Enable**: `✓ Enable Interface`
- **Description**: `NetBird`
<p> <img src="/docs-static/img/get-started/pfSense/enable_interface.png" alt="enableInterface" className="imagewrapper-big"/> </p>
### Configure Firewall Rules for the NetBird interface
To allow NetBird to handle all access control, permit all traffic on the NetBird interface in pfSense. This ensures traffic
flows freely, while NetBird’s own policies (ACLs) govern the access restrictions.
Create rules to control traffic coming from your NetBird network into pfSense and your local networks:
1. Go to `Firewall` > `Rules` and select the `NetBird` (interface) tab and click `Add` to create rules
2. Configure the rule:
- **Action**: `Pass`
- **Interface**: `NETBIRD`
- **Address Family**: `in`
- **Protocol**: `Any`
- **Source**: `Any`
- **Destination**: `Any`
- **Description**: `Allow all on NetBird (managed by NetBird)`
3. Click `Save`, then `Apply Changes`
<p><img src="/docs-static/img/get-started/pfSense/firewall_rules.png" alt="firewallRules" className="imagewrapper-big"/></p>
## Uninstallation
From a shell on your pfSense system, run:
<p>
```sh
pkg delete netbird-0.55.1 pfSense-pkg-NetBird-0.1.0
```
</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

132
src/pages/get-started/install/synology.mdx Normal file
View File

@@ -0,0 +1,132 @@
import {Note} from "@/components/mdx";
# Synology Installation
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
## Installation
Installing a NetBird Peer on Synology will require a few additional steps compared to a typical Linux install despite using the same single line command to get everything going.
1. Ensure your user has administrative privileges. _Control Panel > User & Group > User > Click User and Edit > User Groups > Ensure “administrators” is checked._
2. Enable SSH Connectivity. _Control Panel > Terminal & SNMP > Terminal > Check the box next to “Enable SSH Service” > Click Apply_
3. Login to your user using SSH. If you’re unsure if your Synology IP address it can be found under _Control Panel > Info Center > Network > DNS_ or using the [Synology Find Tool](https://finds.synology.com/). Open a terminal and run the command to connecting replacing the user and IP address with your own.
```bash
ssh user@192.168.0.53
```
4. Install with one command.
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
5. Add your Synology NAS as a Peer using the steps from [Add peers to your NetBird network](https://docs.netbird.io/how-to/add-machines-to-your-network) in the documentation.
## Reboot Script
In some cases on Synology, the NetBird service will not have the correct modules loaded on a reboot. In this case you’ll need to run a script every time you reboot your NAS. To automate this process, you can create a scheduled task in the Synology DSM.
1. _Control Panel > Task Scheduler > Create > Triggered Task > User defined script_.
2. Now you’ll have a _Create Task_ dialog box. Give a task name such as “Netbird Reboot”. Set the _User > Root_ and the _Event > Boot-up_. Make sure the Enable Box is checked.
3. Next, click on _Task Settings_ and copy/paste the script in the text field under _Run command > User-defined script_.
```sh
#!/bin/sh
# Create the necessary file structure for /dev/net/tun
if [ ! -c /dev/net/tun ]; then
if [ ! -d /dev/net ]; then
mkdir -m 755 /dev/net
fi
mknod /dev/net/tun c 10 200
chmod 0755 /dev/net/tun
fi
# Load the tun module if not already loaded
if !(lsmod | grep -q "^tun\s"); then
insmod /lib/modules/tun.ko
fi
```
4. If you’d like to see the logs for this task, select the task you create and click on Settings. Check the box that says Save output results, select a save location, and click OK. Now, if you select the task and **Action > View Result**, you’ll see any error logs and status.
## Running with a Setup Key
In case you are activating a server peer, you can use a [setup key](/how-to/register-machines-using-setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/how-to/register-machines-using-setup-keys)).
```bash
netbird up --setup-key <SETUP KEY>
```
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
```bash
ip addr show wt0
```
## Updating
If you used the one-command script to install, you can follow this to update:
```bash
netbird down
curl -fsSLO https://pkgs.netbird.io/install.sh
chmod +x install.sh
./install.sh --update
netbird up
```
## Uninstallation
The most straightforward method is to use NetBird's built-in uninstall command. You'll need to connect to your Synology NAS via SSH to execute these commands.
1. SSH into your Synology NAS: If you haven't already, enable SSH in your Synology's Control Panel under Terminal & SNMP. Then, use an SSH client to connect to your NAS. Switch to the root user:
```bash
sudo -i
```
2. Run the uninstall command: Once connected, execute the following command:
```bash
netbird service uninstall
```
3. Remove NetBird binary and configuration files.
/usr/local/bin/netbird: The installation script placed the NetBird binary here.
/var/lib/netbird: This directory contains the NetBird configuration files.
You can use the rm command to delete these files and directories:
```bash
rm /usr/local/bin/netbird
rm -rf /var/lib/netbird
```
**Important:** Be very careful when using the `rm -rf` command, as it will permanently delete the specified files and directories. Double-check the paths before executing the command.
4. Remove the Peer from the NetBird UI.
For a complete cleanup, you should also remove the Synology NAS as a peer from your NetBird account. Log in to the NetBird web UI. Navigate to the Peers section. Find the peer corresponding to your Synology NAS and delete it.
## Video Walkthrough
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/9VKOAe_T038" allow="fullscreen;"></iframe>
</div>
## Support Us
- Star us on [GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird release page on GitHub: [releases](https://github.com/netbirdio/netbird/releases/latest)

69
src/pages/get-started/install/windows.mdx Normal file
View File

@@ -0,0 +1,69 @@
import {Note} from "@/components/mdx";
# Windows Installation
The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
1. Download the latest Windows release:
- <Button href="https://pkgs.netbird.io/windows/x64" variant="text">EXE Installer</Button><br />
- <Button href="https://pkgs.netbird.io/windows/msi/x64" variant="text">MSI Installer</Button><br />
2. Execute the installer and proceed with the installation steps
3. This will install the UI client in the `C:\Program Files\NetBird` and add the daemon service
4. After installing, you can follow the steps from [Running NetBird with SSO Login](#running-net-bird-with-sso-login).
<Note>
To uninstall the client and service, you can use Add/Remove programs
</Note>
## Running NetBird with SSO Login
### Desktop UI Application
If you installed the Desktop UI client, you can launch it and click on Connect.
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### CLI
Alternatively, you could use command line. Simply run
```bash
netbird up
```
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
<p>
<img src="/docs-static/img/get-started/netbird-sso-login-cmd.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Check connection status:
```bash
netbird status
```
## Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/how-to/register-machines-using-setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/how-to/register-machines-using-setup-keys)).
For all systems:
```bash
netbird up --setup-key <SETUP KEY>
```
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
```
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
2. Check connection status:
```bash
netbird status
```
3. Check your IP:
```bash
netsh interface ip show config name="wt0"
```