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

Concept	Explanation
CIDR	The overlay IP range for the network (e.g., 10.100.0.0/24). Each member device gets a unique IP from this range.
Listen Port	The UDP port used for WireGuard connections. Each network uses its own port.
HUB	A 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.
SPOKE	A 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-Hubs	When enabled, NetDefense automatically creates connections between all hubs (hub-to-hub) and between each hub and every spoke (hub-to-spoke).
Auto-Firewall-Rules	When 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 IP	The IP address assigned to a member device within the network’s CIDR range.
Endpoint	The 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.
Transit	Allows 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.
Overrides	The 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

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.

Note

While full mesh is technically straightforward to configure, it is rarely the best design choice in practice. Local inbound traffic restrictions, segmentation requirements, and monitoring needs often make hub-and-spoke or hybrid topologies more appropriate.

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.

Publishing Prefixes

A member only advertises its overlay address until you publish a prefix for it. Publishing tells the other peers which LAN subnets to route through the tunnel.

A published prefix is a device-scoped variable holding the CIDR blocks to advertise, and a device-scoped variable can only exist as an override of an organization-scope variable of the same name. So the organization-scope variable has to exist first, then the device override, then the prefix itself:

ndcli variable org create office-lan 10.20.0.0/24
ndcli variable device create fw01 office-lan 10.20.0.0/24
ndcli network prefix add hq fw01 office-lan

Or do all three in one command with --value:

ndcli network prefix add hq fw01 office-lan --value 10.20.0.0/24

Publish several subnets by separating them with commas, or by repeating the flag:

ndcli network prefix add hq fw01 office-lan --value 10.20.0.0/24,10.21.0.0/24

If either variable already exists holding exactly this value, that step is treated as done and the command continues. If one exists holding a different value, the command refuses rather than overwriting it — changing a published prefix changes a live tunnel’s routing, so use ndcli variable org set or ndcli variable device set deliberately. If a run fails partway, re-run the same command: the steps that succeeded are skipped.

A network with no published prefixes carries no traffic

Publishing is not optional if you want the tunnel to be useful. With no published prefixes, each peer advertises only its own overlay address, so the handshake succeeds, the tunnel comes up, and no LAN routes exist across it — traffic to the remote subnet never enters the tunnel.

Nothing reports this as an error, because an overlay-only network is a legitimate configuration. If a tunnel is up but nothing behind it is reachable, check ndcli network prefix list <network> <device> on both ends first.

Publishing an empty value has the same effect as not publishing at all, so the CLI rejects empty and malformed values before writing anything.

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.
• One listener rule per network — a floating pass in for UDP on the network’s listen port, destined for the device itself, so peers’ handshakes can arrive.

The listener rule’s source

The listener rule is narrowed to the endpoint addresses of the peers this device is linked to: a single address inline, or an alias when there are several. It falls back to allowing any source, and that fallback is all-or-nothing across the device’s peers — one peer that cannot be narrowed safely leaves the whole rule open. That happens when a linked peer:

• has no configured endpoint — a spoke that dials out, or anything behind NAT, has no address to allow in. Narrowing here would block exactly the handshakes the rule exists for.
• has a hostname endpoint — a name is usually configured because the address changes, so an address resolved when the rule was written would go stale.
• has an IPv6 endpoint — the generated rule is IPv4.

So a hub whose spokes all have fixed IP endpoints gets a tightly-scoped rule; a hub serving any roaming or dynamic-DNS peer keeps an any-source rule for the listen port. If you need a tighter policy than that, leave Auto-Firewall-Rules off and author the listener rule yourself.

On a WAN that blocks inbound by default

The generated rule is a floating rule, not one bound to the WAN interface — NetDefense does not know your device’s interface names, so it cannot write an interface-bound rule for you.

If handshakes still do not arrive on a device whose WAN denies inbound traffic by default, add a rule on the WAN interface allowing UDP to the listen port yourself. Check Firewall > Log Files > Live View on the device for blocked UDP to that port to confirm before adding it.

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 edits or removes rules it didn’t create; it may only raise their sequence numbers, keeping their order, so its PREPEND rules, these generated ones included, come before your own rules in their section. See The device’s own rules can be renumbered.

# 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

View in NDWeb

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

View in NDWeb

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

View in NDWeb

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.

List Links

View in NDWeb

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.