Warn on kernel socket buffer clamping at UDP startup

Log a warning when the kernel clamps SO_RCVBUF or SO_SNDBUF below
the requested size, directing the operator to increase rmem_max or
wmem_max. Document buffer size defaults and sysctl requirements in
the Docker config template.

examples/docker-network/configs/node.template.yaml

@@ -19,6 +19,12 @@ transports:
   udp:
     bind_addr: "0.0.0.0:4000"
     mtu: 1472
+    # recv_buf_size: 2097152   # 2 MB (default)
+    # send_buf_size: 2097152   # 2 MB (default)
+    # Note: The kernel clamps socket buffers to net.core.rmem_max / wmem_max.
+    # Ensure these sysctls are >= the configured buffer sizes:
+    #   sysctl -w net.core.rmem_max=2097152
+    #   sysctl -w net.core.wmem_max=2097152
 
 peers:
 {{PEERS}}

src/transport/udp.rs

@@ -112,6 +112,21 @@ impl UdpTransport {
         let actual_send = sock2.send_buffer_size()
             .map_err(|e| TransportError::StartFailed(format!("get send buffer: {}", e)))?;
 
+        if actual_recv < recv_buf {
+            warn!(
+                requested = recv_buf,
+                actual = actual_recv,
+                "UDP recv buffer clamped by kernel (increase net.core.rmem_max)"
+            );
+        }
+        if actual_send < send_buf {
+            warn!(
+                requested = send_buf,
+                actual = actual_send,
+                "UDP send buffer clamped by kernel (increase net.core.wmem_max)"
+            );
+        }
+
         // Convert to tokio UdpSocket
         let std_socket: std::net::UdpSocket = sock2.into();
         let socket = UdpSocket::from_std(std_socket)