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 10;
    exclusive-connections 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

idle-timeout

Controls how long idle LDAP connections remain in the pool before Radiator closes them. When set, connections that have been idle longer than this duration are closed automatically, freeing resources on both the Radiator and LDAP server sides.

If not set, connections remain open indefinitely until the LDAP server closes them.

Accepts duration units such as 30s, 5m, 1h.

Default: No default. Connections are kept open indefinitely.

connections

Sets the maximum number of shared connections in the pool for server-authenticated operations. 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.

Radiator verifies shared connections are healthy on each pool checkout.

The keyword shared-connections is accepted as an alias for connections.

Default: 10

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

exclusive-connections

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.

Size this pool to match the maximum number of simultaneous user authentications (bind operations) the server handles.

Default: 10

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.