Skip to main content
Mole configuring listeners

Listener Configuration

Listeners accept incoming peer connections. Each listener binds to an address and transport protocol.

Configuration​

listeners:
  - transport: quic             # quic, h2, ws
    address: "0.0.0.0:4433"     # Bind address
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"
      client_ca: "./certs/ca.crt"  # Optional: require client certs

Transport Types​

QUIC Listener​

Best performance, UDP-based:

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

HTTP/2 Listener​

TCP-based, firewall-friendly:

listeners:
  - transport: h2
    address: "0.0.0.0:8443"
    path: "/mesh"              # Optional URL path
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

WebSocket Listener​

Maximum compatibility:

listeners:
  - transport: ws
    address: "0.0.0.0:443"
    path: "/mesh"              # Required for WebSocket
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

Multiple Listeners​

An agent can listen on multiple transports simultaneously:

listeners:
  # Primary: QUIC for direct connections
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

  # Fallback: HTTP/2 for firewall traversal
  - transport: h2
    address: "0.0.0.0:8443"
    path: "/mesh"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

  # Alternative: WebSocket for maximum compatibility
  - transport: ws
    address: "0.0.0.0:443"
    path: "/mesh"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

TLS Configuration​

File-Based Certificates​

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

Inline PEM Certificates​

For containerized deployments:

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert_pem: |
        -----BEGIN CERTIFICATE-----
        MIIBkTCB+wIJAKi...
        -----END CERTIFICATE-----
      key_pem: |
        -----BEGIN PRIVATE KEY-----
        MIIEvQIBADANBg...
        -----END PRIVATE KEY-----

Inline PEM takes precedence over file paths.

Mutual TLS (mTLS)​

Require clients to present valid certificates:

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"
      client_ca: "./certs/ca.crt"   # Require client certs signed by this CA

With mTLS:

  • Only peers with valid certificates can connect
  • Provides mutual authentication
  • Recommended for production

See TLS Configuration for details.

Bind Address​

All Interfaces​

Accept connections from anywhere:

listeners:
  - transport: quic
    address: "0.0.0.0:4433"    # All IPv4 interfaces

Specific Interface​

Bind to specific IP:

listeners:
  - transport: quic
    address: "192.168.1.10:4433"   # Specific interface

IPv6​

listeners:
  - transport: quic
    address: "[::]:4433"           # All IPv6 interfaces

Localhost Only​

For testing or local-only access:

listeners:
  - transport: quic
    address: "127.0.0.1:4433"      # Localhost only

Port Selection​

TransportDefault PortAlternative Ports
QUIC4433Any UDP port
HTTP/28443, 443Any TCP port
WebSocket443, 80Any TCP port

Firewall Considerations​

# For restrictive firewalls, use HTTPS port
listeners:
  - transport: h2
    address: "0.0.0.0:443"
    tls: ...

# Or WebSocket on standard HTTPS
listeners:
  - transport: ws
    address: "0.0.0.0:443"
    path: "/mesh"
    tls: ...

URL Path​

HTTP/2 and WebSocket support URL paths:

listeners:
  - transport: h2
    address: "0.0.0.0:443"
    path: "/mesh/v1"
    tls: ...

Peers must use matching path:

peers:
  - transport: h2
    address: "server.example.com:443"
    path: "/mesh/v1"

Examples​

Development​

listeners:
  - transport: quic
    address: "127.0.0.1:4433"
    tls:
      cert: "./certs/agent.crt"
      key: "./certs/agent.key"

Production (Multi-Transport)​

listeners:
  # QUIC for performance
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert: "/etc/muti-metroo/certs/agent.crt"
      key: "/etc/muti-metroo/certs/agent.key"
      client_ca: "/etc/muti-metroo/certs/ca.crt"

  # HTTP/2 for TCP fallback
  - transport: h2
    address: "0.0.0.0:443"
    path: "/mesh"
    tls:
      cert: "/etc/muti-metroo/certs/agent.crt"
      key: "/etc/muti-metroo/certs/agent.key"
      client_ca: "/etc/muti-metroo/certs/ca.crt"

Docker/Kubernetes​

listeners:
  - transport: quic
    address: "0.0.0.0:4433"
    tls:
      cert_pem: "${TLS_CERT}"
      key_pem: "${TLS_KEY}"
      ca_pem: "${TLS_CA}"

Troubleshooting​

Port Already in Use​

# Find what's using the port
lsof -i :4433
netstat -tlnp | grep 4433

# Kill the process or choose different port

Permission Denied​

Ports below 1024 require root on Linux:

# Option 1: Use port > 1024
address: "0.0.0.0:4433"

# Option 2: Run as root (not recommended)
sudo muti-metroo run -c config.yaml

# Option 3: Use capabilities
sudo setcap 'cap_net_bind_service=+ep' muti-metroo

Certificate Errors​

# Verify certificate
muti-metroo cert info ./certs/agent.crt

# Check key matches certificate
openssl x509 -noout -modulus -in agent.crt | openssl md5
openssl rsa -noout -modulus -in agent.key | openssl md5
# (should match)