mirror of
https://github.com/netbirdio/docs.git
synced 2026-05-05 00:36:37 +00:00
Reorganize Get Started Documentation Structure (#490)
This commit is contained in:
Brandon Hopkins
122
src/pages/get-started/install/opnsense.mdx
Normal file
122
src/pages/get-started/install/opnsense.mdx
Normal 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
|
||||
Reference in New Issue
Block a user