6.3.2.4 UDP Port Publishing

UDP port publishing requires explicitly specifying the /udp protocol suffix when mapping a port, necessary for applications using UDP-based protocols — DNS servers, certain VoIP or streaming protocols — which would otherwise be incorrectly mapped if treated as TCP by default.

Publishing a UDP Port

The /udp suffix on the container port portion of a mapping specifies that this particular port mapping should use UDP rather than the default TCP.

docker run -d -p 53:53/udp myapp-dns:1.0

Without this explicit suffix, the mapping would default to TCP, which would not work correctly for a DNS server's UDP-based query handling.

Publishing Both TCP and UDP for the Same Port Number

Some applications use the same port number for both TCP and UDP traffic, serving different purposes on each — both can be published together when necessary.

docker run -d -p 53:53/tcp -p 53:53/udp myapp-dns:1.0

Why Mismatched Protocols Cause Silent Failures

Publishing a port using the wrong protocol doesn't produce an obvious error — the mapping succeeds, but traffic using the actual protocol the application expects simply never reaches it, resulting in a connection that appears to silently fail or time out.

docker run -d -p 53:53 myapp-dns:1.0

Without the /udp suffix, this mapping defaults to TCP, and DNS queries sent over UDP (as is typical) won't actually reach the application, despite the container appearing to run correctly.

Verifying a UDP Port Mapping Works

Testing a UDP-based service requires a client tool that actually communicates over UDP, since a default TCP-based test wouldn't accurately verify the mapping.

dig @localhost -p 53 example.com

Why UDP Port Publishing Matters

Correctly identifying when an application genuinely requires UDP, and explicitly specifying the /udp protocol suffix accordingly, avoids a specific, easily overlooked class of networking mistake where a port mapping appears correctly configured but simply doesn't work for the actual protocol in use.