server

This clause defines an LDAP server to connect to. A single backend can have multiple servers configured for high availability and load balancing. Each server is identified by a unique name.

Example configuration of a server:

server "ldap.example.com" {
    url "ldap://ldap.example.com:389/";
    timeout 3s;
    connections {
        max 10;
        idle-timeout 60s;
        min 2;
        min-timeout 1s;
        min-retry 250ms;
        exclusive 10;
    }
    authentication {
        dn "cn=admin,dc=example,dc=com";
        password "secret";
    }
}

Example configuration with TLS:

server "ldaps.example.com" {
    url "ldaps://ldaps.example.com:636/";
    timeout 3s;
    authentication {
        dn "cn=manager,dc=example,dc=com";
        password "<manager_password>";
    }

    tls {
        # LDAP server's certificate's root CA
        server_ca_certificate "ldap.server.ca";
    }
}

Server Options

url

Specifies the URL of the LDAP server. This parameter is required.

The URL scheme determines the connection method:

• ldap:// -- plain LDAP (default port 389). Use with a tls block for STARTTLS.
• ldaps:// -- LDAP over TLS (default port 636). Requires a tls block with at least server_ca_certificate defined.

timeout

Specifies the maximum time Radiator waits for an LDAP operation (search, bind, or connection establishment) to complete. If the operation does not complete within this time, it fails and the request may be retried on another server if server-selection is configured.

Accepts duration units such as 3s, 500ms, 1m.

Default: 3s

connections

Use the connections { ... } block to configure both LDAP connection pools.

connections {
    max 25;           # Maximum shared pool size.
    idle-timeout 60s; # Idle connection timeout.
    min 2;            # Keep two shared connections ready.
    min-timeout 1s;   # Shared warm-pool maintenance probe timeout.
    min-retry 250ms;  # Delay between shared warm-pool maintenance retries.
    exclusive 10;     # Maximum exclusive bind pool size.
}

Parameters:

• max: Maximum shared pool size. Default: 10.
• idle-timeout: Idle connection timeout. Accepts duration units such as 30s, 5m, and 1h. Default: none.
• min: Shared warm-pool floor. Default: 0.
• min-timeout: Shared warm-pool maintenance probe timeout. Default: 1s.
• min-retry: Delay between shared warm-pool maintenance retries. Default: 250ms.
• exclusive: Maximum exclusive pool size for bind operations. Default: 10.

max, min, min-timeout, and min-retry apply only to the shared pool. Shared connections stay permanently bound with the credentials configured in the authentication block and are used for search operations that run under the server identity.

When idle-timeout is set, Radiator closes LDAP connections that have been idle longer than this duration. This frees resources on both Radiator and LDAP server sides. If idle-timeout is not set, connections remain open indefinitely until the LDAP server closes them.

Radiator verifies shared connections are healthy on each pool checkout.

Setting min to a value greater than 0 keeps a warm-pool floor of established shared connections and starts background maintenance probes.

Set max to match the number of concurrent search operations you expect. A value equal to the number of worker threads is a good starting point.

The exclusive parameter in the connections block sets the maximum number of connections reserved for exclusive per-operation use. These connections are used by bind operations that authenticate individual users. Each active bind checks out one connection, binds it with the user's credentials, then returns it to the pool.

Because exclusive connections are always rebound with new credentials before use, Radiator only verifies that the underlying TCP connection is still open when recycling them.

priority

Controls server selection order when multiple servers are configured. Lower values indicate higher priority (0 = highest priority). Servers with equal priority are tried in alphabetical order by name.

Default: 0 Range: 0-255

See Backend Load Balancing for details and examples.

authentication

Configures how Radiator authenticates (binds) to the LDAP server. If omitted, Radiator connects anonymously.

See authentication for details on the supported modes: simple bind and SASL External.

service-level-objective

Configures automatic health monitoring for the server. When the failure rate is exceeded, the server is marked as degraded and temporarily skipped during server selection. See the Service Level Objective documentation for details.

service-level-objective {
    failure-rate 3/5;
    initial-backoff-period 3s;
    max-backoff-period 30s;
    recovery-probe-count 2;
}

When server-selection is configured on the parent ldap block, these defaults are applied automatically to any server without an explicit service-level-objective block.

statistics

Enables metrics collection for this specific LDAP server. See statistics for configuring counters, histograms, sample windows, and collection intervals.