Skip to content
NetDefense Docs

VPN Networks

NetDefense manages WireGuard-based networks that interconnect devices across sites. Each network defines an overlay IP range and a set of member devices that form encrypted tunnels between each other.

Network Concepts

Section titled “Network Concepts”
ConceptExplanation
CIDRThe overlay IP range for the network (e.g., 10.100.0.0/24). Each member device gets a unique IP from this range.
Listen PortThe UDP port used for WireGuard connections. Each network uses its own port.
HUBA central device with a public endpoint (a reachable IP/hostname). Hubs accept connections from spokes and route traffic between them. Typically deployed at headquarters or data centers.
SPOKEA device that connects to hubs but doesn’t need a public endpoint. Spokes can be behind NAT or dynamic IPs. Typically branch office or remote site firewalls.
Auto-Connect-HubsWhen enabled, NetDefense automatically creates connections between all hubs (hub-to-hub) and between each hub and every spoke (hub-to-spoke).
Auto-Firewall-RulesWhen enabled, NetDefense emits OPNsense pass rules on the wireguard interface group so peers can reach each other’s published subnets through the tunnel. Off by default — firewall policy is an explicit decision. See Automatic Firewall Rules.
Overlay IPThe IP address assigned to a member device within the network’s CIDR range.
EndpointThe public IP/hostname and port where a HUB device listens for WireGuard connections. Spokes don’t need endpoints because they initiate outbound connections.
PSK (Pre-Shared Key)An optional additional layer of encryption on a specific link. When enabled, both sides must have the same key for the tunnel to establish.
TransitAllows a spoke to route traffic through a specific hub to reach other networks. The hub publishes network prefixes so the spoke knows which traffic to send through the tunnel.
OverridesThe count of explicit link overrides — manually created or modified links that change the default connectivity behavior (e.g., adding a spoke-to-spoke link, disabling an automatic connection, or adding PSK to a specific link).

Full Mesh Networks

Section titled “Full Mesh Networks”

Mesh networks are topologies in which every member is directly interconnected with all other members. In this model, each device establishes a link with every other device in the network.

NetDefense can implement a full mesh by creating a network with the Auto-Connect-Hubs option enabled and assigning all devices the HUB role.

Section titled “Automatic vs Manual Links”

Network links (connections between devices) can be:

  • Automatic — created implicitly based on member roles. Hub-to-spoke links are always automatic. Hub-to-hub links are automatic when Auto-Connect-Hubs is enabled. These links don’t require manual configuration.
  • Manual — explicitly created to enable connections that aren’t automatic, like spoke-to-spoke links (which allow two branch offices to communicate directly without routing through a hub). You can also manually override an automatic link to add PSK or disable it entirely.

Automatic Firewall Rules

Section titled “Automatic Firewall Rules”

WireGuard only encrypts the tunnel — OPNsense still blocks traffic on the wireguard interface by default until you author pass rules. For site-to-site VPNs where every peer should just reach every other peer’s published subnets, authoring those rules by hand is repetitive and drifts as members come and go.

Enabling Auto-Firewall-Rules on a network makes NetDefense emit the rules for you on every sync:

  • One pass in on wireguard rule per (remote published prefix × local published prefix) pair, so each side’s LAN is reachable from every other member.
  • One overlay-ping rule scoped to the network’s overlay CIDR, so peers can ping each other’s tunnel IPs even before publishing any LAN prefixes.

The generated rules are tagged [nd-vpn:<network-name>] in their description so they’re easy to spot in the OPNsense firewall UI. NetDefense owns their lifecycle — turn the flag off (or delete a member / unpublish a prefix) and the next sync removes the corresponding rules. NetDefense never touches rules it didn’t create.

Terminal window
# Enable at creation time
ndcli network create site-to-site --cidr 10.100.0.0/24 --auto-firewall-rules


# Or toggle on an existing network
ndcli network update corporate-vpn --auto-firewall-rules


# Turn it off — rules disappear on the next sync
ndcli network update corporate-vpn --auto-firewall-rules=false

The flag is off by default. Leave it off when you need stricter policy than “anything from one published subnet to another” — in that case, author the rules through a RULE-type snippet on a template applied to the relevant devices.

List Networks

Section titled “List Networks”
Terminal window
ndcli network list
╭─────────────────┬───────────────┬───────────┬───────┬─────────┬───────────╮
│ NAME            │ CIDR          │ AUTO-HUBS │ PORT  │ MEMBERS │ OVERRIDES │
├─────────────────┼───────────────┼───────────┼───────┼─────────┼───────────┤
│ corporate-vpn   │ 10.100.0.0/24 │ Yes       │ 51820 │ 5       │ 1         │
│ management-mesh │ 10.102.0.0/24 │ Yes       │ 51822 │ 0       │ 0         │
│ site-to-site    │ 10.101.0.0/24 │ No        │ 51821 │ 0       │ 0         │
╰─────────────────┴───────────────┴───────────┴───────┴─────────┴───────────╯

Describe a Network

Section titled “Describe a Network”
Terminal window
ndcli network describe corporate-vpn -f detailed
╭─ VPN Network ───────────────────────────────────────╮
│  corporate-vpn                                      │
│  CIDR: 10.100.0.0/24                                │
╰─────────────────────────────────────────────────────╯


  Auto-Hubs      Yes       Listen Port    51820
  Auto-FW Rules  No
  MTU            -         Keepalive      -
  Organization   example-org


┌─ Statistics ────────────────────────────────────────┐
│    Members: 5                                       │
│    Overrides: 1                                     │
└─────────────────────────────────────────────────────┘


  Created        2026-02-20 19:19:21
  Updated        2026-02-20 19:19:21

List Members

Section titled “List Members”
Terminal window
ndcli network member list corporate-vpn
╭───────────────────┬───────┬─────────┬────────────┬────────────────────────────┬─────────╮
│ DEVICE            │ ROLE  │ ENABLED │ OVERLAY IP │ ENDPOINT                   │ TRANSIT │
├───────────────────┼───────┼─────────┼────────────┼────────────────────────────┼─────────┤
│ fw-hq-primary     │ HUB   │ Yes     │ 10.100.0.1 │ vpn.example-org.com:51820  │ -       │
│ fw-hq-secondary   │ HUB   │ Yes     │ 10.100.0.2 │ vpn2.example-org.com:51820 │ -       │
│ fw-branch-chicago │ SPOKE │ Yes     │ 10.100.0.3 │ -                          │ -       │
│ fw-branch-denver  │ SPOKE │ Yes     │ 10.100.0.4 │ -                          │ -       │
│ fw-branch-austin  │ SPOKE │ Yes     │ 10.100.0.5 │ -                          │ -       │
╰───────────────────┴───────┴─────────┴────────────┴────────────────────────────┴─────────╯

Notice that HUBs have public endpoints (vpn.example-org.com, vpn2.example-org.com) while SPOKEs show - because they initiate outbound connections to the hubs.

Section titled “List Links”
Terminal window
ndcli network link list corporate-vpn
╭───────────────────┬───────────────────┬─────────────┬────────┬─────┬─────────────╮
│ DEVICE A          │ DEVICE B          │ PAIR        │ ACTIVE │ PSK │ NOTES       │
├───────────────────┼───────────────────┼─────────────┼────────┼─────┼─────────────┤
│ fw-hq-primary     │ fw-hq-secondary   │ hub↔hub     │ Yes    │ No  │ automatic   │
│ fw-hq-primary     │ fw-branch-austin  │ hub↔spoke   │ Yes    │ No  │ automatic   │
│ fw-hq-primary     │ fw-branch-chicago │ hub↔spoke   │ Yes    │ No  │ automatic   │
│ fw-hq-primary     │ fw-branch-denver  │ hub↔spoke   │ Yes    │ No  │ automatic   │
│ fw-hq-secondary   │ fw-branch-austin  │ hub↔spoke   │ Yes    │ No  │ automatic   │
│ fw-hq-secondary   │ fw-branch-chicago │ hub↔spoke   │ Yes    │ No  │ automatic   │
│ fw-hq-secondary   │ fw-branch-denver  │ hub↔spoke   │ Yes    │ No  │ automatic   │
│ fw-branch-chicago │ fw-branch-denver  │ spoke↔spoke │ Yes    │ Yes │ manual link │
╰───────────────────┴───────────────────┴─────────────┴────────┴─────┴─────────────╯


8 connections (7 automatic, 1 manual link)

The corporate-vpn network uses a hub-and-spoke topology:

  • 2 HUBs (fw-hq-primary, fw-hq-secondary) with public endpoints — providing redundancy at headquarters.
  • 3 SPOKEs (fw-branch-chicago, fw-branch-denver, fw-branch-austin) — each spoke automatically connects to both hubs, so if one hub goes down, the other maintains connectivity.
  • 7 automatic links — all hub-to-hub and hub-to-spoke connections were created automatically because Auto-Connect-Hubs is enabled.
  • 1 manual spoke-to-spoke link — an explicit override between Chicago and Denver with PSK enabled, allowing those two branch offices to communicate directly without routing through a hub.