NAT-PMP & UPnP

For clients to connect directly to your server, the WireGuard UDP port needs to be reachable from the internet. atreoAGENT can open that port automatically using PCP, NAT-PMP, or UPnP. Port mapping only opens the port; your public IP is determined separately by atreoLINK from the agent’s authenticated connection (see Endpoint discovery). If your router doesn’t support any of these, or you switch them off, set up a manual port forward instead.

Mapping order

When port mapping is enabled, the agent tries multiple methods in order:

1. PCP. Port Control Protocol (RFC 6887). Tried first, on the same UDP port 5351 as NAT-PMP, which it supersedes.
2. NAT-PMP. Sends a UDP packet directly to the router on port 5351. IPv4 only — the protocol has no IPv6 mechanism, so it stays as an IPv4 fallback behind PCP.
3. UPnP (standard). Tries WANIPConnection2, then WANIPConnection1, then WANPPPConnection1.
4. Raw multicast discovery. Manual discovery on each network interface as a last resort.

IPv6 has no NAT, so there’s nothing to map. Instead the agent opens an inbound firewall pinhole for the WireGuard port on the gateway — via PCP first, then UPnP IGDv2 (WANIPv6FirewallControl / AddPinhole) — so the published AAAA endpoint is reachable. Controlled by ipv6_pinhole_enabled / WG_IPV6_PINHOLE_ENABLED.

If none succeed, the agent logs an actionable “forward UDP <port>” message every maintenance cycle and keeps running. The tunnel still works as soon as the port is reachable via a manual port forward (or, for IPv6, an inbound firewall rule), with no endpoint_ip needed.

NAT-PMP

NAT-PMP (Network Address Translation Port Mapping Protocol) is the preferred method. It’s supported by many modern routers.

• The agent detects the default gateway by assuming .1 on the local subnet.
• Sends a UDP mapping request on port 5351.
• Lease time: 1800 seconds (30 minutes).
• Renewal: every 5 minutes in the maintenance loop.

UPnP

If NAT-PMP isn’t available, the agent falls back to UPnP (Universal Plug and Play). This is supported by most consumer routers.

The agent tries three UPnP service types in order:

1. WANIPConnection2 (IPv6-aware).
2. WANIPConnection1 (standard).
3. WANPPPConnection1 (PPP connections like DSL).

Port change detection

Sometimes routers assign a different external port than requested. The agent handles this:

• On each renewal, the agent checks if the returned port matches the expected port.

• If there’s a mismatch, it logs an error and continues retrying the original port.

• After 35 minutes of persistent mismatch, the agent sends a push notification to all paired phones:

  Port mapping lost Your router assigned port X instead of Y. All tunnel connections are broken.

• If the correct port is restored, a recovery notification is sent.

Caution

A port change breaks all existing WireGuard connections. Clients reconnect automatically once the correct port is restored (or you pin it with a manual port forward).

The agent never auto-updates its endpoint silently in this case. Changing the endpoint mid-session would break every active peer; the agent waits for human intervention.

Manual port forwarding

If your router doesn’t support NAT-PMP or UPnP, or you’ve turned port mapping off, forward the WireGuard UDP port yourself in the router admin UI. That’s all that’s required: atreoLINK still learns your public IP from the agent’s connection, so you do not need to set endpoint_ip. Optionally stop the agent attempting to auto-map:

config.yaml

wireguard:
  upnp_enabled: false

WG_UPNP_ENABLED=false   # or pass --no-upnp

endpoint_ip / endpoint_port remain available as an explicit IP override for CGNAT or proxied control paths only. See Manual port forwarding for the full walkthrough.

Cleanup

When the agent shuts down gracefully, it removes the NAT-PMP/UPnP port mapping from the router. This prevents stale mappings from accumulating.