listen

The listen attribute is used to configure the network interfaces and ports on which the RADIUS server will accept requests. This is used to define specific IP addresses and ports for handling RADIUS traffic.

Example configuration of a listen clause:

listen {
    # Transport protocol
    protocol udp;

    # Transport protocol port to listen to
    port 1813;

    # IPv4 address to listen to
    ip 127.0.0.1;

    # Default idle timeout for TCP/TLS connections (optional)
    # Used when client has no timeout configured
    timeout 30s;

    # TCP keepalive settings (optional, TCP/TLS only)
    keepalive {
        idle 60s;      # Time before first probe
        interval 10s;  # Time between probes
        count 3;       # Max probes before connection is dead
    }
}

timeout

The timeout option sets the default idle timeout for TCP and TLS connections on this listener. If no data is received within this period, the connection is closed.

Timeout priority:

• If the client has a timeout configured, the client's value is used (including 0 to explicitly disable)
• If the client has no timeout configured, the listener's timeout is used
• If neither has a timeout, defaults to 10 seconds

keepalive

The keepalive block configures TCP keepalive probes for connections on this listener. Keepalive probes detect stale or dead connections at the TCP layer, even when no application data is being exchanged.

When to use keepalive: If you set a large timeout value (or disable it entirely), consider enabling keepalive to detect and close stale connections that may have been disconnected without proper termination (e.g., due to network failures, NAT timeouts, or client crashes).

Options:

• idle: Time a connection must be idle before the first keepalive probe is sent.
• interval: Time between subsequent keepalive probes.
• count: Number of unanswered probes before the connection is considered dead and closed.

Example: RadSec with long timeout and keepalive

For RadSec (RADIUS over TLS) connections that should remain open for extended periods, use a long timeout combined with keepalive to detect stale connections:

listen {
    protocol tls;
    port 2083;
    ip 0.0.0.0;
    ip ::;

    # Allow connections to remain idle for up to 1 hour
    timeout 1h;

    # But probe every minute to detect dead connections
    keepalive {
        idle 1m;       # Start probing after 1 minute of idle
        interval 10s;  # Send probes every 10 seconds
        count 3;       # Close after 3 failed probes (30s max)
    }

    tls {
      ...
    }
}

This configuration keeps connections open for long-lived RadSec sessions while ensuring dead connections are detected within ~90 seconds (1 minute idle + 3 x 10 second probes).

TLS Connection Logging

When a TLS connection is accepted, a log message at log level debug is generated with details about the connection. The log message includes the following fields:

• client_name: Name of the matched client configuration
• client_addr: Client IP address and port
• tls_version: Negotiated TLS version (e.g., TLSv1_3)
• cipher_suite: Negotiated cipher suite (e.g., TLS13_AES_256_GCM_SHA384)
• alpn: ALPN protocol if negotiated (e.g., radius/1.0)
• cert_subject: Subject of the client certificate
• cert_issuer: Issuer of the client certificate

Example log output:

{
  "message": "Accepting Radius TLS client connection",
  "fields": {
    "client_name": "RADSEC_CLIENT",
    "client_addr": "192.168.1.100:54321",
    "tls_version": "TLSv1_3",
    "cipher_suite": "TLS13_AES_256_GCM_SHA384",
    "alpn": "radius/1.0",
    "cert_subject": "cn=client.example.com",
    "cert_issuer": "cn=Example CA"
  }
}