Skip to main content
Mole configuring UDP

UDP Configuration

Tunnel UDP traffic through the mesh. Enable this on exit nodes to support applications like DNS queries, VoIP, and games that need UDP.

Quick setup:

udp:
  enabled: true
  max_associations: 1000
  idle_timeout: 5m

Configuration​

udp:
  enabled: true
  max_associations: 1000
  idle_timeout: 5m
  max_datagram_size: 1472

Options​

OptionTypeDefaultDescription
enabledbooltrueEnable UDP relay
max_associationsint1000Maximum concurrent UDP associations
idle_timeoutduration5mAssociation timeout after inactivity
max_datagram_sizeint1472Maximum UDP payload size in bytes

Association Limits​

Control resource usage with association limits:

udp:
  max_associations: 1000    # Per exit node
  idle_timeout: 5m          # Close inactive associations

max_associations​

Maximum number of concurrent UDP associations. When the limit is reached, new UDP ASSOCIATE requests are rejected with an error.

Set to 0 for unlimited associations (not recommended for production).

idle_timeout​

Time after which inactive associations are closed. The timer resets on each datagram sent or received.

Datagram Size​

udp:
  max_datagram_size: 1472

Maximum UDP payload size in bytes. The default (1472) is calculated as:

MTU (1500) - IP header (20) - UDP header (8) = 1472 bytes

Datagrams exceeding this size are rejected.

Examples​

Basic UDP Relay​

Enable UDP relay with default settings:

udp:
  enabled: true

Custom Timeouts​

Adjust timeouts for your environment:

udp:
  enabled: true
  idle_timeout: 2m

High-Capacity Exit​

For exit nodes handling many clients:

udp:
  enabled: true
  max_associations: 10000
  idle_timeout: 10m
  max_datagram_size: 1472

Disabled​

To disable UDP relay:

udp:
  enabled: false

Complete Exit Configuration​

UDP relay works alongside TCP exit routing:

exit:
  enabled: true
  routes:
    - "0.0.0.0/0"
  dns:
    servers:
      - "8.8.8.8:53"
    timeout: 5s

udp:
  enabled: true
  max_associations: 1000
  idle_timeout: 5m

Troubleshooting​

UDP ASSOCIATE Rejected​

Check that:

  1. udp.enabled is true
  2. Exit node is connected to mesh
  3. Route exists from ingress to exit

Too Many Associations​

If new associations are rejected:

Error: UDP association limit reached

Increase max_associations or reduce idle_timeout to free resources faster.

Datagram Rejected​

If datagrams are rejected for size:

Error: datagram too large

The payload exceeds max_datagram_size. Either:

  • Reduce payload size in the application
  • Increase max_datagram_size (not recommended above MTU)

Security​

  1. Limit associations: Set reasonable max_associations
  2. Short timeouts: Use shorter idle_timeout for high-traffic nodes
  3. Monitor usage: Track UDP relay metrics for abuse