Enable native QUIC transfers
Expose separate UDP listeners and pin the deployment's native-transfer identity.
On this page
Forward UDP to the VOTPort server
Native transfers require UDP connectivity to the server. Forward the native ports through your router or firewall and allow them on the host. An HTTPS site that works in a browser does not establish that QUIC is reachable.
QUIC is the native transport that keeps transfers moving over long-distance and lossy connections. Browser transfers and native authorization requests use HTTPS; the native file bytes use separate UDP listeners. A normal HTTP reverse proxy does not carry that UDP traffic.
If your server is behind NAT, create UDP port-forwarding rules from the public address to the VOTPort host. Also allow the ports in the host firewall and any cloud security group. Container port publishing alone does not configure an upstream router or firewall.
Configure both directions
This Compose fragment enables native sending into VOTPort on UDP 8322 and native delivery from VOTPort on UDP 8323:
ports:
- "127.0.0.1:8321:8080"
- "8322:8322/udp"
- "8323:8323/udp"
environment:
VOTPORT_PUSH_BIND: "0.0.0.0:8322"
VOTPORT_PUSH_ADVERTISE: "203.0.113.10:8322"
VOTPORT_SERVE_BIND: "0.0.0.0:8323"
VOTPORT_SERVE_ADVERTISE: "203.0.113.10:8323"
Replace the example public address with the address your clients can actually reach. These are example ports, not mandatory port numbers. If NAT changes the external port, advertise that external port and forward it to the corresponding internal listener.
| Traffic | Example public entry | Forward to | Purpose |
|---|---|---|---|
| HTTPS | TCP 443 | Your HTTPS reverse proxy, then VOTPort HTTP | Browser access, sign-in, metadata, and native preflight |
| Native push | UDP 8322 | VOTPort host UDP 8322, then container UDP 8322 | Files sent to request links |
| Native delivery | UDP 8323 | VOTPort host UDP 8323, then container UDP 8323 | Files received from delivery links |
Native push is disabled when VOTPORT_PUSH_BIND is unset. Native delivery is disabled when VOTPORT_SERVE_BIND is unset. Enabling one does not enable the other.
Use a public IPv4 address or bracketed IPv6 address when supporting clients that require a numeric socket address. Do not advertise a private LAN address to internet clients. If an upstream NAT is outside your control, arrange a reachable UDP endpoint with your network operator.
Verify from outside the facility
- Check the server logs for both enabled UDP listeners and their advertised addresses.
- Test a small send from a native client on an external connection, then a small delivery receive.
- Confirm the client reports the native transport for each direction. A successful HTTP fallback does not validate UDP forwarding.
- Confirm the finished files verify, then test an interrupted transfer and recovery within the link’s allowed lifetime.
The client network must permit outgoing UDP to the advertised endpoints and the return traffic. Clients normally initiate the connection; they do not need their own inbound port-forwarding rule. Test beyond the facility LAN because a local connection can bypass the public NAT path entirely.
An HTTP health check, a TCP port check, or a generic UDP scan cannot prove that an authenticated native transfer works. Use the VOTPort client for the final check.
Certificates and identity
When both VOTPORT_PUSH_CERT and VOTPORT_PUSH_KEY are unset, VOTPort creates a persistent self-signed certificate pair under /data. GET /api/push-identity exposes its digest. Verify and pin that digest in the sender.
To use external PEM files, set both variables together and protect those files separately. VOTPort does not obtain an ACME certificate for this UDP listener. Back up the generated certificate pair and /data/push-issuer.key; externally configured certificates need their own backup.
Certificate rotation changes the digest. Coordinate the new pin with clients before expecting transfers to succeed.
Native delivery
VOTPORT_SERVE_BIND enables the separate native delivery listener. Configure VOTPORT_SERVE_ADVERTISE, expose its UDP port, and apply the same firewall checks. It shares the push certificate and capability issuer, so the same verified digest pins both directions.
A delivery page shows native-client instructions when supported. HTTPS preflight checks the grant and mints a capability tied to the recipient's public key. The capability lasts up to an hour, bounded by grant expiry. Each mint reserves a delivery slot until completion or expiry; revocation, exhaustion, and expiry are enforced.
The first native delivery preflight prepares a package by reading the selected files. Allow time for that operation with large deliveries. Later sessions can reuse the prepared package.
Limits and storage
Native push shares tenant and link quotas, upload sessions, receipts, retention, and upload history with browser receiving. A native package is published only after the entire package verifies; failure or cancellation does not expose partial destination files.
On Linux, the native listeners request a 16 MiB receive socket buffer and an 8 MiB send buffer. If high-throughput native transfers suffer packet loss, inspect the kernel limits and VOTPort's socket-buffer warning before tuning the Docker host. Those limits are host-wide and do not affect the HTTP transfer path.