VPN network management commands for NDCLI. These commands allow you to create and manage WireGuard-based overlay networks, add devices as members, configure links between members, and publish IP prefixes.
Command alias: net
List all VPN networks in the organization.
ndcli network list [flags]
Flag Type Default Description --pageint 1Page number --per-pageint 30Items per page
ndcli network list -f json
Show detailed information about a VPN network.
ndcli network describe [network]
Argument Required Description networkYes Network name
ndcli network describe my-network
ndcli network describe my-network -f json
Create a new VPN overlay network.
ndcli network create [name] [flags]
Argument Required Description nameYes Network name
Flag Type Default Description --cidrstring Overlay CIDR (required, e.g. 10.100.0.0/24) --listen-portint 51820Default WireGuard listen port --mtuint Default MTU (1280–9000) --keepaliveint Default keepalive interval (1–65535 seconds) --auto-connect-hubsbool falseAuto-create links between HUB members --auto-firewall-rulesbool falseAuto-generate OPNsense pass rules on the wireguard interface group so peers can reach each other’s published subnets (see Automatic firewall rules )
ndcli network create my-network --cidr 10.100.0.0/24
ndcli network create branch-vpn --cidr 10.200.0.0/24 --listen-port 51821 --keepalive 25
ndcli network create hub-network --cidr 10.0.0.0/24 --auto-connect-hubs
ndcli network create site-to-site --cidr 10.100.0.0/24 --auto-firewall-rules
Update an existing VPN network’s settings.
ndcli network update [network] [flags]
Argument Required Description networkYes Network name
Flag Type Default Description --namestring New network name --listen-portint Default WireGuard listen port --mtuint Default MTU (use 0 to clear) --keepaliveint Default keepalive interval (use 0 to clear) --auto-connect-hubsbool Auto-create links between HUB members --auto-firewall-rulesbool Toggle auto-generated pass rules on the wireguard interface group (see Automatic firewall rules ) -y, --yesbool falseSkip confirmation prompt
ndcli network update my-network --name new-name
ndcli network update my-network --keepalive 25
ndcli network update my-network --mtu 0
ndcli network update my-network --auto-firewall-rules=false
Delete a VPN network.
ndcli network delete [network] [flags]
Argument Required Description networkYes Network name
Flag Type Default Description -y, --yesbool falseSkip confirmation prompt
ndcli network delete my-network
ndcli network delete my-network --yes
This permanently deletes the network, all its members, links, and prefix configurations. Member devices are not removed from the organization.
List all members in a VPN network.
ndcli network member list [network] [flags]
Argument Required Description networkYes Network name
Flag Type Default Description --pageint 1Page number --per-pageint 30Items per page
ndcli network member list my-network
ndcli network member list my-network -f json
Show detailed information about a VPN network member.
ndcli network member describe [network] [device]
Argument Required Description networkYes Network name deviceYes Device name
ndcli network member describe my-network my-firewall
Add a device to a VPN network as a member.
ndcli network member add [network] [device] [flags]
Argument Required Description networkYes Network name deviceYes Device name
Flag Type Default Description --rolestring SPOKEMember role: HUB or SPOKE --overlay-ipstring Overlay IPv4 address (auto-allocated if empty) --endpoint-hoststring Public hostname or IP for incoming connections --endpoint-portint Public endpoint port --listen-portint WireGuard listen port override --mtuint MTU override --keepaliveint Keepalive interval override (seconds) --transit-via-hubstring Route through this HUB device name --enabledbool trueEnable the member
Role Description HUBActs as a relay; auto-connects to all SPOKE members and (if auto-connect-hubs is on) other HUBs SPOKEConnects to HUBs automatically; spoke-to-spoke requires a manual link
# Add a spoke member (auto-allocated overlay IP)
ndcli network member add my-network branch-firewall
# Add a hub member with a public endpoint
ndcli network member add my-network datacenter-fw \
--endpoint-host vpn.example.com \
# Add a spoke with a specific overlay IP
ndcli network member add my-network remote-fw --overlay-ip 10.100.0.5
Update a VPN network member’s settings.
ndcli network member update [network] [device] [flags]
Argument Required Description networkYes Network name deviceYes Device name
Flag Type Default Description --rolestring Member role: HUB or SPOKE --endpoint-hoststring Public hostname or IP (use none to clear) --endpoint-portint Public endpoint port (use 0 to clear) --listen-portint WireGuard listen port override (use 0 to clear) --mtuint MTU override (use 0 to clear) --keepaliveint Keepalive interval override (use 0 to clear) --transit-via-hubstring HUB device to route through (use none to clear) --enabledbool Enable or disable the member --regenerate-keysbool falseRegenerate the WireGuard keypair
ndcli network member update my-network branch-fw --endpoint-host new.ip.example.com
ndcli network member update my-network branch-fw --endpoint-host none
ndcli network member update my-network branch-fw --regenerate-keys
Remove a device from a VPN network.
ndcli network member remove [network] [device] [flags]
Argument Required Description networkYes Network name deviceYes Device name
Flag Type Default Description -y, --yesbool falseSkip confirmation prompt
ndcli network member remove my-network branch-fw
ndcli network member remove my-network branch-fw --yes
List all effective VPN connections in a network. By default, shows effective connections derived from member roles. Use --raw to see only explicit link overrides stored in the database.
ndcli network link list [network] [flags]
Argument Required Description networkYes Network name
Flag Type Default Description --devicestring Filter connections involving this device --rawbool falseShow raw link database rows instead of effective connections --pageint 1Page number (only with --raw) --per-pageint 30Items per page (only with --raw)
Pair Connected? HUB ↔ SPOKE Always (automatic) HUB ↔ HUB Automatic if auto-connect-hubs is enabled on the network SPOKE ↔ SPOKE Only via a manual link (network link create)
ndcli network link list my-network
ndcli network link list my-network --device branch-fw
ndcli network link list my-network --raw
Show details of a specific VPN connection between two members.
ndcli network link describe [network] [device-a] [device-b]
Argument Required Description networkYes Network name device-aYes First device name device-bYes Second device name
ndcli network link describe my-network spoke-a spoke-b
Create a manual VPN link between two network members. This is required for SPOKE-to-SPOKE connections.
ndcli network link create [network] [device-a] [device-b] [flags]
Argument Required Description networkYes Network name device-aYes First device name device-bYes Second device name
Flag Type Default Description --enabledbool trueEnable the link --generate-pskbool falseGenerate a WireGuard pre-shared key for additional security
ndcli network link create my-network spoke-a spoke-b
ndcli network link create my-network spoke-a spoke-b --generate-psk
Update a VPN link between two members.
ndcli network link update [network] [device-a] [device-b] [flags]
Argument Required Description networkYes Network name device-aYes First device name device-bYes Second device name
Flag Type Default Description --enabledbool trueEnable or disable the link --regenerate-pskbool falseRegenerate the pre-shared key
ndcli network link update my-network spoke-a spoke-b --enabled=false
ndcli network link update my-network spoke-a spoke-b --regenerate-psk
Delete a VPN link between two members.
ndcli network link delete [network] [device-a] [device-b] [flags]
Argument Required Description networkYes Network name device-aYes First device name device-bYes Second device name
Flag Type Default Description -y, --yesbool falseSkip confirmation prompt
ndcli network link delete my-network spoke-a spoke-b
List all IP prefixes published by a VPN network member.
ndcli network prefix list [network] [device] [flags]
Argument Required Description networkYes Network name deviceYes Device name
Flag Type Default Description --pageint 1Page number --per-pageint 30Items per page
ndcli network prefix list my-network branch-fw
Publish an IP prefix on a VPN network member. The prefix is defined by a variable (typically of type prefix) associated with that device.
ndcli network prefix add [network] [device] [variable] [flags]
Argument Required Description networkYes Network name deviceYes Device name variableYes Variable name that holds the prefix value
Flag Type Default Description --publishbool trueAdvertise the prefix to other VPN peers
ndcli network prefix add my-network branch-fw lan_prefix
ndcli network prefix add my-network branch-fw lan_prefix --publish=false
Update the settings of a published prefix on a VPN member.
ndcli network prefix update [network] [device] [variable] [flags]
Argument Required Description networkYes Network name deviceYes Device name variableYes Variable name
Flag Type Default Description --publishbool trueWhether to advertise the prefix to peers
ndcli network prefix update my-network branch-fw lan_prefix --publish=false
Remove a published prefix from a VPN network member.
ndcli network prefix remove [network] [device] [variable] [flags]
Argument Required Description networkYes Network name deviceYes Device name variableYes Variable name
Flag Type Default Description -y, --yesbool falseSkip confirmation prompt
ndcli network prefix remove my-network branch-fw lan_prefix
WireGuard only handles tunnel encryption — OPNsense still blocks peer traffic by default until you author pass rules. The --auto-firewall-rules flag on network create / network update asks NetDefense to emit those rules for you on every sync.
When the flag is on, every member device gets one pass rule per (remote published prefix, local published prefix) pair on the wireguard interface group, plus one overlay-ping rule allowing anything in the network’s overlay CIDR to reach the member’s own tunnel IP. Descriptions are tagged [nd-vpn:<network-name>] so you can spot them in the OPNsense firewall UI.
The flag is off by default — firewall policy is an explicit decision. Only enable it if you want NetDefense to manage these rules for you. Toggling it off removes the rules on the next sync; NetDefense never touches rules it didn’t create.
ndcli network create site-to-site --cidr 10.100.0.0/24 --auto-firewall-rules
ndcli network update site-to-site --auto-firewall-rules=false # stop managing them
If you need stricter policy than the cross-product rules NetDefense generates, leave the flag off and author the rules through a RULE-type snippet on a template instead.
