NAT traversal

Use static inbound mapping

shredstream.sh pushes raw UDP to the IP address and port registered for the destination. A receiver behind NAT needs a stable inbound mapping from that public pair to an internal IP and UDP port.

The receiver does not connect to a service endpoint and does not send an application registration datagram. NAT hole punching, STUN, TURN, and provider-operated relay traversal are not currently specified. Configure the mapping explicitly in the customer network.

Every service datagram originates from ${SOURCE_IP}. Restrict the public-side mapping or firewall to ${SOURCE_IP}/32 when the platform supports a source condition.

Define both pairs

Record the external pair and internal pair before opening the dashboard. For example:

public destination: 198.51.100.20:9000/udp
internal receiver: 10.0.4.25:9000/udp
allowed source: 64.130.40.90/32

198.51.100.20 is documentation-only example space. Replace it with the public address you control. The public and internal ports may differ when the NAT device supports port translation, but using the same port reduces configuration ambiguity.

Register the public pair in the dashboard. Bind the internal pair on the receiver. Do not register the private address unless it is actually routable from the service, which is not a documented deployment mode.

Configure the path

1. Reserve the public IP address.
2. Reserve the public UDP port.
3. Assign a stable internal IP to the receiver.
4. Bind the receiver to the internal UDP port.
5. Create the inbound UDP destination mapping.
6. Restrict the mapping source to ${SOURCE_IP} when supported.
7. Add the edge firewall allow rule.
8. Add the host firewall allow rule.
9. Register the public pair in the dashboard.
10. Request the verification challenge.

NAT syntax and object names vary by router, operating system, and cloud platform. A product-required NAT implementation is not currently specified. Use the device's supported static destination-NAT or port-forward control.

Verify at two observation points

Capture on the public-facing interface and the receiver. Replace interface names and port values with the actual configuration.

At the edge:

sudo tcpdump -n -i eth0 -c 1 'src host 64.130.40.90 and udp dst port 9000'

At the receiver:

sudo tcpdump -n -i any -c 1 'src host 64.130.40.90 and udp dst port 9000'

Request a challenge while both observation points are ready. A packet seen at the edge but not internally identifies the NAT or internal firewall path. A packet absent at the edge identifies the public pair, upstream route, provider-side state, or edge firewall as the area to inspect.

When the translated internal port differs, use that port in the receiver-side filter. Keep the source address ${SOURCE_IP} unless a customer-controlled device performs source NAT.

Avoid source NAT when possible

Destination NAT changes where a packet is delivered. Source NAT changes who the receiver appears to receive it from. If an internal proxy or gateway rewrites the source, the final receiver cannot enforce the original ${SOURCE_IP} check directly.

Preserve the source address across the internal path when the network design permits it. When source NAT is required, enforce ${SOURCE_IP}/32 at the public edge and document the translated internal source separately. Customer source-NAT behavior is outside the delivery contract.

Do not change the application to trust every internal sender without an edge control. The source allowlist is the documented authentication mechanism for delivery.

Keep the mapping stable

Use a reserved public address and a persistent UDP port-forward rule. A dynamically changing public address can redirect the registered pair away from the receiver. Dynamic DNS support and automatic destination updates are not currently specified.

UDP mapping idle timers apply primarily to dynamically created state. The delivery model should use an explicit inbound mapping that remains present without outbound receiver traffic. Required timer values and keepalive behavior are not currently specified.

Do not depend on an outbound packet from the receiver to open the path. No provider endpoint for that outbound packet is documented.

Account for multiple receivers

One paid destination addresses one public IP and UDP port. A NAT device can forward that pair to one internal target under the normal mapping described here. Provider-side fanout to several internal receivers is not part of the purchase.

If the customer builds an internal fanout process, keep the provider-facing socket bound at the mapped target and define local delivery behavior separately. Internal fanout guarantees, buffering, and source preservation are not currently specified by the product.

Do not configure two competing NAT rules for the same public pair. Rule priority and load-sharing behavior depend on the customer platform and can make verification reach a different receiver than the stream.

Change a mapped destination

Changing the public IP or public UDP port changes the registered destination and requires re-verification. Changing only the internal target leaves the registered pair unchanged, but can still lose packets during the customer-side transition.

Prepare the new internal mapping and receiver before removing the old one. Confirm packet capture and application counters after the change. Raw UDP has no retransmission for packets lost during the handoff.

Each destination permits three registered address changes per day. Whether a dashboard edit consumes a change is determined by the dashboard; internal-only NAT edits do not themselves call the dashboard.

Check MTU through tunnels

NAT alone normally rewrites headers without creating a lower path MTU, but VPNs, overlays, and encapsulation can add overhead. The documented UDP payload can reach 1,228 bytes. Validate the effective path MTU when the NAT path includes a tunnel.

Fragmentation policy, tunnel overhead, and supported encapsulations are not currently specified. Use packet capture to look for fragmentation and interface counters to identify drops.