Listeners

Listeners define how nvelox accepts incoming connections. Each listener binds to an address with a specific protocol.

TCP Listeners

Raw TCP stream proxying. Connections are forwarded byte-for-byte to the backend pool. Supports send_proxy_v2 to inject PROXY protocol headers, preserving the client IP through upstream proxies.

UDP Listeners

Datagram forwarding for DNS, syslog, QUIC, and custom UDP-based protocols.

TCP listener

listeners:
  - name: tcp_api
    protocol: tcp
    bind: ":3306"
    timeouts:
      connect: 5s
      read: 30s

UDP listener

listeners:
  - name: dns_udp
    protocol: udp
    bind: ":5353"

HTTP / HTTPS Listeners

HTTP listeners handle Layer 7 traffic with full request inspection. HTTPS listeners terminate TLS before routing. Both support HTTP/2 via ALPN negotiation and WebSocket upgrades.

HTTP and HTTPS listeners

listeners:
  - name: http_public
    protocol: http
    bind: ":8080"

  - name: https_public
    protocol: https
    bind: ":8443"
    tls:
      cert: /etc/nvelox/tls/server.crt
      key: /etc/nvelox/tls/server.key

HTTP/3 (QUIC)

HTTP/3 uses QUIC as its transport layer, built on UDP. Enable with http3: true on an HTTPS listener. Requires TLS certificates (QUIC mandates encryption).

HTTP/3 listener

listeners:
  - name: h3_public
    protocol: https
    bind: ":443"
    http3: true
    tls:
      cert: /etc/nvelox/tls/server.crt
      key: /etc/nvelox/tls/server.key

TLS Configuration

TLS is configured per listener with certificate and key file paths. For development, set auto_cert: true to generate a self-signed certificate on startup.

TLS Options

cert — Path to the TLS certificate file (PEM)
key — Path to the TLS private key file (PEM)
auto_cert — Generate self-signed cert on startup (dev only)
min_version — Minimum TLS version (default: 1.2)
client_auth — Client certificate mode (request, require, etc.)
client_ca — CA bundle for verifying client certificates
ocsp_stapling — Enable OCSP stapling
cipher_suites — Allowed cipher suites

Warning: Auto-generated certificates are self-signed and should only be used for development and testing.

TLS with provided certs

listeners:
  - name: https_prod
    protocol: https
    bind: ":443"
    tls:
      cert: /etc/nvelox/tls/example.com.crt
      key: /etc/nvelox/tls/example.com.key
      min_version: "1.3"
      ocsp_stapling: true

Auto TLS (dev)

listeners:
  - name: https_dev
    protocol: https
    bind: ":8443"
    tls:
      auto_cert: true

Mutual TLS (mTLS)

listeners:
  - name: mtls_api
    protocol: https
    bind: ":8443"
    tls:
      cert: /etc/nvelox/tls/server.crt
      key: /etc/nvelox/tls/server.key
      client_auth: require
      client_ca: /etc/nvelox/ca/client-ca.crt