NAT traversal

Use static inbound mapping

shredstream.sh pushes raw UDP toward the pair registered for a destination. When NAT separates that public pair from the receiver, a stable inbound mapping must connect it 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/udpinternal receiver: 10.0.4.25:9000/udpallowed source: 203.23.178.228/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 across routers, operating systems, and cloud platforms. The product mandates no particular implementation. Configure a static destination-NAT or port-forward object supported by the device.

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 203.23.178.228 and udp dst port 9000'

At the receiver:

sudo tcpdump -n -i any -c 1 'src host 203.23.178.228 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 source address across the internal path when its design permits. If source NAT is required, enforce ${SOURCE_IP}/32 at the external boundary, then document the translated internal origin separately. Customer source-NAT behavior lies 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. No required timer or keepalive behavior is published.

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 a single public network pair. NAT can forward that pair to one internal target under the 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 separately. The product makes no commitment about internal fanout guarantees, buffering, or source preservation.

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.

No fragmentation policy, tunnel overhead, or supported encapsulation list is published. Look for fragmentation with packet capture and identify drops through interface counters.