Quickstart

Set the destination values

This procedure uses UDP port 9000 as a runnable example. Keep that value when it is free, or replace every occurrence with one port you control. Register the server's public IP address, not a private address, unless a public NAT address forwards the same UDP port to the receiver.

Every verification and stream datagram originates from ${SOURCE_IP}. Permit inbound UDP from that exact address. This rule is required even when a cloud firewall, host firewall, or network ACL already permits other traffic. Forgetting this source rule is the most common activation failure.

Open the host firewall

Use this ufw command when ufw manages the host firewall:

sudo ufw allow proto udp from 64.130.40.90 to any port 9000
sudo ufw status numbered

Use the matching command from Firewall configuration when the host uses iptables or nftables. Add the same source CIDR, ${SOURCE_IP}/32, to the cloud firewall or security group when the server runs behind one. Do not replace the narrow source with 0.0.0.0/0.

Start a receiver

Run this command in a terminal on the destination server. It binds all local IPv4 interfaces on UDP port 9000, prints the verification payload as text, and reports aggregate stream counters once per second.

python3 - <<'PY'
import socket
import time

HOST = "0.0.0.0"
PORT = 9000
SOURCE_IP = "64.130.40.90"

sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, 8 * 1024 * 1024)
sock.bind((HOST, PORT))
print(f"listening on udp://{HOST}:{PORT}", flush=True)

stream_packets = 0
stream_bytes = 0
last_report = time.monotonic()

while True:
    data, peer = sock.recvfrom(65535)
    if not peer[0] == SOURCE_IP:
        print(f"ignored source={peer[0]}:{peer[1]} bytes={len(data)}", flush=True)
        continue
    if data.startswith(b"SHRED-FANOUT-VERIFY/1"):
        print(data.decode("utf-8", errors="replace"), flush=True)
        continue
    stream_packets += 1
    stream_bytes += len(data)
    now = time.monotonic()
    if now - last_report >= 1.0:
        print(
            f"source={peer[0]} stream_packets={stream_packets} "
            f"stream_bytes={stream_bytes}",
            flush=True,
        )
        stream_packets = 0
        stream_bytes = 0
        last_report = now
PY

Leave this terminal running. The receive buffer setting asks the kernel for 8 MiB. The kernel may cap the effective buffer according to host policy. Changing that cap is an operating-system task and is not required to read the one verification datagram.

Register and verify the destination

1. Open the paid destination in the dashboard.
2. Enter the server's public IP address.
3. Enter UDP port 9000.
4. Save the destination.
5. Request the verification challenge.
6. Read the line beginning with ${CHALLENGE_PREFIX} in the receiver terminal.
7. Copy the token from that datagram.
8. Paste the token into the dashboard.
9. Submit the token before ${CHALLENGE_TTL_SECONDS} seconds elapse.
10. Keep the receiver running.

The datagram begins with the literal prefix ${CHALLENGE_PREFIX}, followed by the destination ID and token. The delimiter and exact field encoding after the prefix are not currently specified. Read the complete printable payload instead of using a parser that assumes spaces, colons, JSON, or line breaks.

The service sends one challenge datagram per request. UDP does not retransmit it. Request a resend in the dashboard when the receiver does not print the challenge or when the ${CHALLENGE_TTL_SECONDS} second window expires. Do not submit a token from an earlier request.

Confirm the stream

After the dashboard accepts the token, watch the existing receiver terminal. Stream datagrams from ${SOURCE_IP} should replace the single verification message. The exact activation delay is not currently specified.

Open a second terminal and observe counters without decoding payloads:

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

The command exits after 20 matching datagrams. A healthy feed is measured at ${FEED.mbps} Mbps and ${FEED.packetsPerSecond.toLocaleString("en-US")} packets per second, with a ${FEED.meanPacketBytes} byte mean packet size. These are measured feed characteristics, not an ordering or delivery promise. Individual service datagrams can be as large as ${WIRE.maxPacketBytes} bytes.

Confirm that the Python stream counter reports ${SOURCE_IP} for accepted traffic. The UDP source port is not currently specified, so do not filter it. Filter the source IP, protocol, and your destination port.

Preserve the working configuration

The example ufw rule is managed by ufw. Persistence for iptables and nftables depends on the Linux distribution and is not currently specified by the product. Store the chosen rule through the host's normal firewall configuration after confirming delivery.

Keep the public IP and port stable. Changing either field counts as a destination address change and requires a new verification challenge. A destination permits three address changes per day.

Monitor receive errors, kernel UDP drops, process restarts, and firewall changes. Raw UDP supplies no retransmission, ordering, or backpressure. A slow or stopped receiver cannot ask the sender to replay missed packets. Plan sustained capacity for the published ${FEED.mbps} Mbps and ${FEED.packetsPerSecond.toLocaleString("en-US")} packets per second, plus environment-specific headroom. A required headroom percentage is not currently specified.

If no packet arrives

Run the tcpdump command while requesting a new challenge. If tcpdump sees nothing, check the public IP, cloud rule, host rule, NAT mapping, and dashboard port. If tcpdump sees the challenge but Python does not, another process may own the port or the receiver may be bound to a different interface. Use sudo ss -ulnp | grep ':9000 ' to inspect the binding.

Do not debug the shred decoder until the network path works. First prove that one datagram from ${SOURCE_IP} reaches the configured UDP socket. Then complete verification. Then count stream datagrams. Decode payloads only after those three checks pass.