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:
- 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. - Server-side infrastructure inside the overlay — a STUN server implementation plus a
BootAddressManagerthat 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. - 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:
Source/com.p2pframework.stun/bnd.bnd—Bundle-SymbolicName: com.p2pframework.stun, version1.0.0,Bundle-RequiredExecutionEnvironment: JavaSE-17, exports all packages,Require-Bundle: rice.freepastry;bundle-version="1.0.0", com.common.utilities.settings.gradlelines 32 and 84 include the project and point it atSource/com.p2pframework.stun.Source/com.p2pframework/build.gradlekeepsimplementation project(':com.p2pframework.stun').
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:
Source/com.p2pframework/src/com/p2pframework/network/freepastry/PastryNetwork.javalines 569–626: the whole STUN block is commented out, includingstartLocalStunServer(InetAddress, RendezvousSocketPastryNodeFactory), theaddressManager/localStunServerfields, and the callfactory.addAdditionalValue(STUNPortNodeHandleItem.KEY_NAME, new STUNPortNodeHandleItem(stunServerPort)). A stale log line inInternetPastryNodeFactory.newNodeSelector()still says"… skipping connectivity check and starting Stun server", although no server is started.Source/com.p2pframework/src/com/p2pframework/network/freepastry/InternetPastryNodeFactory.javalines ~552–566:isNatted()based onstunClient.startNATDiscovery()exists only as a comment.Source/com.p2pframework/src/com/p2pframework/Configuration.javastill imports the bundle and keepsstunStartPort = STUNServer.DEFAULT_PORTandstunPortRange = 1000withgetSTUNStartPort()/getSTUNPortRange()— no production caller remains.- The only live consumers are in
Source/com.p2pframework.unittests/src/com/p2pframework/network/freepastry/nat/:CheckStunNatTypeDetection.java(twoSTUNServers plus one client,Assert.assertEquals(expectedNatType, client.getNATType())),StunAttributes.java(attribute round-trip),StunLifenessCheckerTest.java, and the@DeprecatedCheckStunPort.java. These are manual harnesses with hard-coded LAN addresses (192.168.1.102,192.168.178.41), selected by editing aRoleenum in the source — they are not automated CI tests.
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:
- STUN classifies only if a second reachable server on a different IP answers; the client raises
STUNServer2UnavailableException, and the server code carries aTODO: server2 NEEDS TO BE AVAILABLE— a peer-to-peer network cannot guarantee that. - Publishing a usable STUN port is a chicken-and-egg problem: a firewalled node cannot advertise one.
Commit
e0ae17603renamedsetStunPorttosetPotentialStunPortand introduced the-1sentinel. - Classification is not stable: the 2017 bug report lists "insufficient NAT, firewall and port-forwarding handling", with hosts that have both a public and a private address misclassified as weak, and a manual forwarding entry ("External Port 0") ignored in favour of a private address.
- Relaying is the only option that also survives symmetric NAT and hostile firewalls, which is exactly the case STUN cannot resolve by itself — so relaying had to be built anyway, and adding hole punching on top would have required a type-dependent strategy that was never written.
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.
Related publications
- Pastry: Scalable, decentralized object location and routing for large-scale peer-to-peer systems (2001) — the overlay whose transport assumptions (routable addresses, hosts behind at most one NAT) define the problem this component attacks.
- A Distributed Framework for Social Networks — Final Report (Project Group 2011) (2012) — state before NAT traversal existed: public IP addresses only.
- Seminararbeiten 2012: "A Peer-to-Peer Framework for Social Networks" (Sammelband, UPB Paderborn) (2012) — the NAT-traversal survey (NAT classes, port forwarding, relaying, hole punching, connection reversal, STUNT, NatTrav) behind the design matrix above.
- A Peer-to-Peer Framework for Social Networks — Dokumentation (Abschlussbericht der Projektgruppe 2012, UPB Paderborn) (2013) — first recommendation to support STUN/STUNT in the overlay.
- Seminararbeiten 2013: "A Peer-to-Peer Framework for Social Networks" (Sammelband, UPB Paderborn) (2013) — RFC 3489 → 5389 history, TURN, ICE candidate pairs, and the proposal to embed a STUN server in the framework.
- A Peer-to-Peer Framework for Social Networks — Final Report (Project Group 2013/14, LifeSocial) (2014) — the authoritative record of the decision: port forwarding plus relaying in use, "STUN (currently unused)", relaying bottleneck caveat, single-NAT limitation.
- A Peer-to-Peer Framework for Social Networks — Project Group 2013/2014 (2014) — closing presentation: NAT support through automatic external-IP detection and port forwarding, further NAT strategies listed as next steps.
- LibreSocial Report – Summary of known Bugs (maybe outdated) (2017) — the open NAT/firewall/port-forwarding defects (weak/strong classification, "External Port 0").
- Systematic Benchmarking of a fully Distributed Communication System (Folien zur Masterarbeit) (2018) — evaluation under realistic Internet conditions with NAT traversal delegated to PlanetLab.
- LibreSocial: A peer-to-peer framework for online social networks (2020) — the consolidated framework description, which mentions STUN/relay servers only as MyZone's (server-based) approach.