Skip to main content

UDP and TCP Ingress

Traditional DNS ingress over UDP, TCP, and optional TLS on TCP (DoT).

udp_server​

Purpose​

Listens for DNS over UDP and forwards requests to entry.

Example Configuration​

- tag: udp_in
  type: udp_server
  args:
    # Entry executor for this listener
    entry: "seq_main"
    # Can be written as ip:port, [ipv6]:port, or :port
    listen: ":53"

Configuration Details​

entry​

  • Type: string; Required: yes; Default: none
  • Purpose: Selects the executor that handles every request arriving on this listener.
  • Example: entry: "seq_main"
  • Requirements:
    • Must reference an existing executor plugin.
    • In practice this is usually a sequence tag.
  • Runtime impact:
    • All requests entering this udp_server continue through that executor.
    • Initialization fails if the reference is missing or of the wrong type.

listen​

  • Type: string; Required: yes; Default: none
  • Purpose: Defines the UDP bind address.
  • Examples:
    • listen: "0.0.0.0:53"
    • listen: ":5353"
  • Supported forms:
    • ip:port
    • [ipv6]:port
    • :port
  • Runtime impact:
    • Determines the bound address and port.
    • :port means dual-stack [::]:port; use 0.0.0.0:port for IPv4-only.
    • Invalid addresses, port conflicts, or bind failures prevent startup.

Behavior​

  • Receives requests through a UDP socket.
  • Response encoding respects the client's advertised EDNS UDP payload size.
  • Oversized responses are truncated according to DNS semantics rather than by blindly cutting raw bytes.

Good Fits​

  • Standard low-overhead DNS ingress with high concurrency.
  • The main listener for local networks.
  • Multi-protocol setups alongside tcp_server or http_server.
Notes
  • UDP and QUIC both consume UDP ports. Avoid conflicts.
  • Prefer a shared sequence entry instead of duplicating policy logic in multiple server instances.

tcp_server​

Purpose​

Listens for DNS over TCP. If cert and key are both configured, it can also serve as a DoT listener.

Example Configuration​

- tag: tcp_in
  type: tcp_server
  args:
    # TCP requests enter the main policy chain
    entry: "seq_main"
    # Listen on the standard TCP DNS port
    listen: ":53"
    # Idle connection lifetime in seconds
    idle_timeout: 10

- tag: dot_in
  type: tcp_server
  args:
    # Reuse the same policy chain for DoT
    entry: "seq_main"
    # Typical DoT port
    listen: ":853"
    # PEM certificate chain
    cert: "/etc/oxidns/server.crt"
    # PEM private key
    key: "/etc/oxidns/server.key"
    # Keep DoT connections alive a bit longer for reuse
    idle_timeout: 30

Configuration Details​

entry​

  • Type: string; Required: yes; Default: none
  • Purpose: Selects the executor used by TCP or DoT requests.
  • Example: entry: "seq_main"
  • Requirements:
    • Must reference an existing executor plugin.
  • Runtime impact:
    • Every DNS message on accepted connections is processed by that executor.

listen​

  • Type: string; Required: yes; Default: none
  • Purpose: Defines the TCP bind address.
  • Examples:
    • listen: ":53"
    • listen: "127.0.0.1:853"
  • Supported forms:
    • ip:port
    • [ipv6]:port
    • :port
  • Runtime impact:
    • Controls the bind address for plaintext TCP or DoT.
    • :port means dual-stack [::]:port; use 0.0.0.0:port for IPv4-only.

cert​

  • Type: string; Required: no; Default: none
  • Purpose: Path to the TLS certificate file.
  • Example: cert: "/etc/oxidns/server.crt"
  • Usage:
    • Enables TLS when paired with key.
  • Runtime impact:
    • Allows the same plugin type to act as a DoT listener.

key​

  • Type: string; Required: no; Default: none
  • Purpose: Path to the TLS private key file.
  • Example: key: "/etc/oxidns/server.key"
  • Usage:
    • Enables TLS when paired with cert.
  • Runtime impact:
    • TLS mode cannot start if the key is missing or invalid.

idle_timeout​

  • Type: integer; Required: no; Default: 10
  • Unit: seconds
  • Purpose: Controls idle connection lifetime.
  • Example: idle_timeout: 30
  • Runtime impact:
    • Affects keepalive behavior and long-lived connection reuse.

Behavior​

  • Without TLS it serves DNS over TCP.
  • With both cert and key it serves DNS over TLS.
  • The TLS ALPN is set to dot.
  • A single connection can carry multiple DNS messages.

Good Fits​

  • TCP fallback ingress.
  • DoT deployments.
  • Clients that benefit from long-lived connections.
Notes
  • cert and key must be configured together.
  • Define two separate plugin instances when both plaintext TCP and DoT are required.