Reorganize Get Started Documentation Structure (#490)

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

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

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

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

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

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>

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 NetBirds 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 isnt 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

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 NetBirds 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

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 youre 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 youll 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 youll 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 youd 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**, youll 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)

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