LibreSocial · Documentation

NAT traversal

Purpose

Most peers of a residential social network sit behind a home gateway: they have a private address, they cannot be contacted from the outside, and their UDP mappings expire. The com.p2pframework.stun bundle provides the pieces needed to cope with that on three levels:

  1. Diagnosis — a STUN client (RFC 3489 semantics, RFC 5389 wire format) that discovers the peer's external ("mapped") address and port and classifies the NAT/firewall into one of eight classes (NAT.UDP_BLOCKED, OPEN_INTERNET, FULL_CONE_NAT, RESTRICTED_CONE_NAT, RESTRICTED_PORT_NAT, SYMMETRIC_NAT, SYMMETRIC_FIREWALL, NOT_KNOWN). The class is what a NAT-type-dependent traversal strategy (hole punching, port forwarding, relaying) would be chosen from.
  2. Server-side infrastructure inside the overlay — a STUN server implementation plus a BootAddressManager that keeps the list of reachable Pastry bootstraps and of STUN servers currently running in the network in files, refreshed from live routing-table/leafset changes, so a joining node never needs a hard-coded public STUN infrastructure. Nodes advertise their STUN port through their Pastry node handle.
  3. Liveness/caching support — reachability probes for STUN servers and for Pastry bootstraps, and pluggable caching of the last used address, so that discovery does not hammer the network.

The bundle is self-contained: it contains no FreePastry routing code, only the STUN protocol, the address book, and a RendezvousSocketNodeHandle value item for port propagation.

Current implementation (as of 2026)

Build status

The bundle is still part of the build and still ships:

But nothing in the production path calls it. As of 2026 the STUN code is dead weight that is compiled, exported and unit-tested, not wired into a running node:

Key classes

Path (under Source/com.p2pframework.stun/src/com/p2pframework/stun/) Role
STUNClient.java (696 lines) Binding Request/Success exchange, startNATDiscovery(), discoverNAT(), checkFirewall(), checkFullConeNAT(), checkRestrictedNAT(), checkRestrictedConeNAT(), testI/testII/testIII()
NAT.java enum NOT_KNOWN, UDP_BLOCKED, OPEN_INTERNET, FULL_CONE_NAT, RESTRICTED_CONE_NAT, RESTRICTED_PORT_NAT, SYMMETRIC_NAT, SYMMETRIC_FIREWALL
STUNServer.java (325 lines) in-network STUN server, DEFAULT_PORT = 3478, second socket for changed address/port, CHANGE-REQUEST forwarding
Main.java interactive CLI harness (asks "Run as server?", prompts for server1/server2) — not part of the OSGi activator set
STUNPortNodeHandleItem.java INodeHandleValue, KEY_NAME = "STUN_PORT", serialises the port into RendezvousSocketNodeHandle additional values
messages/Message.java header codec: message type, length, 96-bit transaction id, MAGIC_COOKIE = 0x2112A442, SHORT_MAGIC_COOKIE = 0x2112
messages/attributes/* AttributeXorMappedAddress (IPv4/IPv6, X-Port XORed with the short cookie), AttributeChangeRequest, AttributeChangedAddress, AttributeSourceAddress, AttributeResponseAddress, AttributeError, AttributeUnknownAttributes, AttributeUsername, AttributeMessageIntegrity
bootstrap/BootAddressManager.java (477 lines) implements IfBootAddressProvider, NodeSetListener; maintains bootstraps.txt and stunServers.txt
bootstrap/IfBootAddressProvider.java getRandomStunServerAddress(InetAddress), getRandomPastryBootstrapAddress(InetSocketAddress)
bootstrap/lifeness/{IFLifenessChecker,StunLifenessChecker,PastryLifenessChecker}.java STUN: ICMP isReachable(3000) + dummy STUNClient.testI() with setMaxRetries(3); Pastry: FreePastry ConnectivityVerifier
bootstrap/caching/{IFCacheManager,PassiveChachingStrategy}.java single-entry cache of the last returned InetSocketAddress (class name misspelled in the source)
exceptions/ STUNException, STUNMessageReceiveException, STUNServer2UnavailableException, STUNSymmetricNATException, STUNUDPBlockedException

The traversal path that actually runs

NAT handling in a 2026 node is done by the FreePastry fork plus the factory in com.p2pframework, without any STUN packet on the wire:

Mechanism Where Notes / parameters
External-address discovery Source/com.p2pframework/src/com/p2pframework/ring/lifeness/PastryRingLifenessChecker.java → getExternalMostAddress(...) → ConnectivityVerifier.findExternalAddress(local, remote, ringId, continuation) probe-based, ring-scoped; 5 s timer, must not run on the Pastry selector thread
Static port forwarding Source/com.p2pframework/src/com/p2pframework/network/freepastry/PastryNetwork.java lines 436–473 ring setting isUsePortForwarding() + getPortForwardingIPAddress()/getPortForwardingPort(); result published as env param external_address
UPnP port opening PastryNetwork lines 448–469 via getDefaultPortForwardingNatHandler(bindAddress) nat_handler_class selects a NATHandler implementation, otherwise StubNATHandler (no UPnP); findAvailableFireWallPort(bindport, forwardingPort, 5, "LibreSocial"), openFireWallPort(...); failures are caught and logged ("Unable to open port using upnp.")
Firewalled vs. public classification InternetPastryNodeFactory.newNodeSelector() / isReachableFromExternalNode() internet_test_firewall (set to true by PastryNetwork line 353); internet_is_firewalled used when the check is disabled; 10 s timer; both udpSuccess and tcpSuccess required; first node in a ring boots from itself and skips the check
Relaying / pilots Source/rice.freepastry/src/rice/pastry/socket/nat/rendezvous/ (RendezvousSocketPastryNodeFactory, RendezvousApp, RendezvousJoinProtocol, LeafSetPilotStrategy, RendezvousRouterStrategy) factory chain in use: MonitoredSocketPastryNodeFactory ← InternetPastryNodeFactory ← RendezvousSocketPastryNodeFactory ← SocketPastryNodeFactory
Firewall/NAT device handling Source/rice.freepastry/src/rice/pastry/socket/nat/{NATHandler,StubNATHandler,TraversalStrategy,sbbi/} and org/mpisws/p2p/transport/nat/FirewallTLImpl.java UPnP IGD discovery via the SBBI stack; CantFindFirewallException

Design options and decision

The 2012 seminar volume of the Paderborn project group contains the survey that framed the decision (Mousavi Jazayeri, "NAT Traversal Issues and Solutions for P2P Networks"), and the 2013 seminar volume adds Peng's study of RFC 3489 → RFC 5389, STUNT, TURN and ICE. The options considered:

Option Mechanism Assessment in the project documents Outcome
Public IP only require a routable address what the 2011 group shipped: the CEBIT-2012 prototype ran with "no NAT support and therefore only public IP addresses" superseded
Port forwarding (manual or UPnP/IGD) open a fixed external port on the gateway works independently of the NAT type; the survey notes it is not sufficient on its own (the peer must still learn its external address, and non-cooperative gateways refuse it) in use (external_address, UPnP attempt in PastryNetwork)
Relaying / rendezvous (pilot nodes) public peers forward traffic for firewalled peers NAT-type independent, works with symmetric NATs and hostile firewalls; cost stated verbatim: "The relaying strategy is functional, but it requires that for one firewalled/NATed node, at least one public node is in the leafset to relay the traffic. This may imply bottlenecks." Random pilot selection was used to spread the load in use (rendezvous/pilot transport)
Connection reversal / UDP hole punching both peers send simultaneously so the NAT opens a symmetric mapping cheapest data path; but it fails against symmetric NAT and symmetric firewalls, and it needs the mapped address plus the NAT class — i.e. it presupposes STUN-like discovery not implemented; named as future work
STUN (RFC 3489/5389) query two servers on two addresses and two ports to classify the NAT gives the classification that type-dependent strategies need; needs reachable servers, four round trips, and a peer that can actually receive UDP on the tested socket implemented, not used
STUNT TCP three-way-handshake manipulation (low-TTL SYN, spoofed SYN/ACK) recommended in the 2012 group's closing report as the protocol the overlay should support, because STUN servers would then be needed anyway not implemented
TURN relay server allocated by the client a strong server dependency, at odds with a "no essential servers" design; also the design that the 2020 framework paper criticises in MyZone, whose architecture "includes … the relay server … and a STUN … server" not implemented
ICE / candidate pairs enumerate address candidates and test in priority order robust and standard, but a large state machine; only touched in the seminar literature not implemented
NatTrav / connection brokers TCP hole punching with broker roles survey item only not implemented

The recorded decision. The 2013/14 group chose the two NAT-independent mechanisms and kept STUN as a dormant capability: "We have implemented two possible ways to overcome NAT problem. They are Port Forwarding and Relaying. Our approaches are not NAT dependent, both of these techniques are independent of the type of NAT. Though we have also implemented STUN to support further NAT strategies. Though we have not used STUN in the current version of LifeSocial…" The same report lists the module as "STUN (currently unused): Checks, whether a node is NATed and determines the type of NAT", and states the reason plainly: "we currently don't use it, since we have no NAT-type dependant traversal strategy". The remaining known weakness is documented in the same place: relaying needs a public node in the leafset and may imply bottlenecks, and "Pastry currently only supports hosts behind a single NAT".

Reconstructed rationale (not stated as such in the reports, inferred from the code history and the cited surveys): the STUN client was connected to node creation, then disconnected again (commit 6a8ed8bdc, "Removed STUN to prevent some errors"). The engineering reasons visible in the code are:

Technical details

Wire format

messages/Message.java: 20-byte header — 2-byte type (BINDING_REQUEST 0x0001, BINDING_SUCCESS_RESPONSE 0x0101, BINDING_ERROR_RESPONSE 0x0111, BINDING_INDICATION 0x0011), 2-byte message length, MAGIC_COOKIE = 0x2112A442, then a 96-bit transaction id (byte[12], read from header bytes 8–20). genrateTransactionId() (sic) builds 8 bytes from System.currentTimeMillis() plus 4 random bytes. Attributes start at offset 20 and are truncated by the length field; a mismatch logs "Message length does not fit value in Message Length field". AttributeXorMappedAddress XORs the port with SHORT_MAGIC_COOKIE = 0x2112 and supports IPv4 and IPv6 families. Migration from RFC 3489 to RFC 5389 is complete for the fields the client uses; USERNAME, PASSWORD, REALM, NONCE, MESSAGE-INTEGRITY, SOFTWARE, ALTERNATE-SERVER, REFLECTED-FROM and FINGERPRINT are parsed or modelled but not exercised (the server has a TODO for the message-integrity check and for the 420 Unknown-Attributes path).

Classification flow

startNATDiscovery() skips the whole procedure if the last run is younger than NAT_DETERMINATION_TIME = 600000 ms. It opens a DatagramSocket on an ephemeral port (optionally bound to a given interface address), then runs the RFC 3489 test tree: testI() (same address, same port) → compare XOR-MAPPED-ADDRESS with all local addresses (NetworkHelper.existEqualLocalAddress) or with the bound one → if equal, checkFirewall(); if different, NAT detected, checkFullConeNAT(); testII() (different server address, different port, via CHANGED-ADDRESS and CHANGE-REQUEST) and testIII() (same address, changed port) discriminate cone/restricted/symmetric behaviour. A timeout with no answer at all yields NAT.UDP_BLOCKED; the code comments that it cannot distinguish blocked UDP from a dead server. A symmetric NAT or symmetric firewall makes getExternalAddress() throw STUNSymmetricNATException.

Client timing

initialTimeout = 500 ms (RFC 5389), MAX_RETRANSMISSIONS = 7 (overridable with setMaxRetries(int)), MAX_TIMEOUT = 30000 ms. Retransmission back-off deliberately deviates from the RFC's doubling: currentTimeout = currentTimeout + 100, with the in-code justification that once a UDP packet needs tens of seconds there is no point in waiting even longer.

Server side

STUNServer binds DEFAULT_PORT = 3478 (configurable), runs one receive loop on a thread named "STUN Server Thread" with setSoTimeout(1000), and uses NetworkHelper.getLocalAddr(...) to pick the local interface that can actually reach a known bootstrap — relevant on multi-homed hosts. A request with CHANGE-REQUEST changeIP=true is forwarded to a random other server obtained from IfBootAddressProvider.getRandomStunServerAddress(...), with a RESPONSE-ADDRESS attribute attached so that the second server replies to the client instead of the forwarder; changeIP is cleared before forwarding to avoid a loop. Responses always carry CHANGED-ADDRESS so the client learns server2.

Server and bootstrap bookkeeping

BootAddressManager reads and writes bootstraps.txt and stunServers.txt (one ip,port per line) in DEFALUT_DIRECTOY_BOOTSTRAP_LIST = "/tmp" (sic). The inner thread ListUpdater ("BootstrapStunListUpdater", DEFAULT_BOOTLISTS_UPDATE_INTERVALL = 30000 ms) rewrites a file only when the list's hashCode() changed, cloning the list first to keep the critical section short. As a NodeSetListener it only accepts RendezvousSocketNodeHandles where canContactDirect() is true, reads the peer's port from STUNPortNodeHandleItem.KEY_NAME = "STUN_PORT" (missing item → port -1), and sets isListUpToDate = false on the first routing update so the list can be rebuilt from live state. Random selection uses ThreadLocalRandom; results pass through PassiveChachingStrategy, a single-entry cache with DEFAULT_BOOTMANAGER_CACHE_EXPIRY = 30000 ms. Dead entries are removed by StunLifenessChecker (ICMP ping with 3 s timeout, then a dummy STUNClient subclass calling testI with 3 retries) and PastryLifenessChecker (FreePastry ConnectivityVerifier).

Gaps that remain open

The list of STUN servers was not pruned when the corresponding Pastry node went offline (commits de42b27e0, a1177d0bc, 2013-10-24/25); a null STUN port caused an NPE fixed in 259343730; the client cannot tell "UDP blocked" from "server gone"; and there is no authentication of STUN responses, so any host answering on 3478 could influence the classification.

Evolution and supersession

Date Change
2012 Project group 2011 delivers the CeBIT prototype with "no NAT support and therefore only public IP addresses"
2012/13 Seminar survey of NAT traversal; the 2012 closing report recommends supporting STUN/STUNT in the overlay because STUN servers would be needed anyway
2013-08-28 → 2013-09-17 NAT-aware node factory (efc9f3667), STUN code moved into its own plug-in project (8d5aecbe7); dynamic bootstrap/STUN lists with fallback to the user-supplied bootstrap (68c0abcef, 2013-09-30)
2013-10-03 34f83a61d: the FreePastry connectivity verifier becomes the primary means of detecting a firewalled node; STUN is kept for NAT type detection; a node that creates a new ring becomes a STUN server
2013-10-09 3998913ce: BootAddressManager redesigned with Strategy pattern for liveness checkers and caching strategies
2013-10-14/24 STUN port propagated through RendezvousSocketNodeHandle (924d362c1, 7ad956c40, 14d48d846); setStunPort → setPotentialStunPort, -1 for nodes that cannot serve (e0ae17603)
2013-12-09 6a8ed8bdc "Removed STUN to prevent some errors" — the wiring in PastryNetwork/InternetPastryNodeFactory is commented out and never re-enabled
2013-12-18/19 RFC 5389 rewrite of the still-present protocol code: magic cookie, XOR-MAPPED-ADDRESS, 96-bit transaction id, unknown-attribute handling (5892e4c9f, dcc9169a0, 98dc00856, length fix 044b56a6c)
2014 Video-chat feature ships against "a free Google STUN server" instead of the bundled one; the report notes that full independence would need an own server, ideally "started at every public node in the network" — exactly what the bundle implements but does not use
2017 Bug summary still lists NAT/firewall/port-forwarding handling as insufficient (weak/strong misclassification, ignored manual forwarding)
2018 Benchmarking work moves realistic-Internet evaluation to PlanetLab with NAT traversal rather than fixing traversal in the framework
2020 Framework paper describes STUN/relay/rendezvous servers only as MyZone's architecture and criticises it for relying on servers for essential services; the shipped traversal story is the relay/port-forwarding one
2025/26 Revival and setup documentation never mention STUN; the bundle is modernised for the build only — Gradle module (a07624e41, 2026-04-23), bnd.bnd/bndrun (c66b9436b, 2026-05-18), JavaSE-1.7 → JavaSE-17 (78b564d8b, 2026-06-09)

Status today: superseded, not deleted. The bundle compiles under Java 17/bnd and keeps its manual tests, so re-enabling it is a wiring task: restore startLocalStunServer() in PastryNetwork, create a BootAddressManager with the two liveness checkers, pass it to STUNClient/STUNServer, re-publish STUNPortNodeHandleItem, and then write the missing piece — a strategy that maps a NAT value to a traversal method. Until such a consumer exists, hole punching and connection reversal remain unimplemented, and relaying through public leafset members stays the only traversal path.