NAME

SYNOPSIS

DESCRIPTION

The lloadd.conf file consists of a series of global configuration options that apply to lloadd as a whole (including all backends), followed by zero or more backend definitions that contain information specific how a backend instance should be contacted. The configuration options are case-insensitive; their value, on a case by case basis, may be case-sensitive.

The general format of lloadd.conf is as follows:

    # comment - these options apply to the server as a whole
    <global configuration options>
    # first backend definition
    backend-server <backend 1 definition>
    # subsequent backend definitions
    ...

As many backend servers may be configured as desired.

If a line begins with white space, it is considered a continuation of the previous line. No physical line should be over 2000 bytes long.

Blank lines and comment lines beginning with a `#' character are ignored. Note: continuation lines are unwrapped before comment processing is applied.

Arguments on configuration lines are separated by white space. If an argument contains white space, the argument should be enclosed in double quotes. If an argument contains a double quote (`"') or a backslash character (`\'), the character should be preceded by a backslash character.

The specific configuration options available are discussed below in the Global Configuration Options and General Backend Options. Refer to the "OpenLDAP Administrator's Guide" for more details on the lloadd configuration file.

SLAPD INTEGRATION

An additional option is available when running as a slapd module:

listen <listen URIs>

The URIs the Load Balancer module should listen on. Must not overlap with the ones that slapd uses for its own listening sockets. The related cn=config attribute is olcBkLloadListen with each URI provided as a separate value. No changes to this attribute made after the server has started up will take effect until it is restarted.

GLOBAL CONFIGURATION OPTIONS

argsfile <filename>

The (absolute) name of a file that will hold the lloadd server's command line (program name and options).

concurrency <integer>

Specify a desired level of concurrency. Provided to the underlying thread system as a hint. The default is not to provide any hint.

feature <feature> [...]

Switch additional features supported by the LDAP Load Balancer on. Supported features are:

include <filename>

Read additional configuration information from the given file before continuing with the next line of the current file.

io-threads <integer>

Specify the number of threads to use for the connection manager. The default is 1 and this is typically adequate for up to 16 CPU cores. The value should be set to a power of 2.

If modified after server starts up, a change to this option will not take effect until the server has been restarted.

logfile <filename>

Specify a file for recording lloadd debug messages. By default these messages only go to stderr, are not recorded anywhere else, and are unrelated to messages exposed by the loglevel configuration parameter. Specifying a logfile copies messages to both stderr and the logfile.

loglevel <integer> [...]

Specify the level at which debugging statements and operation statistics should be syslogged (currently logged to the syslogd(8) LOG_LOCAL4 facility). They must be considered subsystems rather than increasingly verbose log levels. Some messages with higher priority are logged regardless of the configured loglevel as soon as any logging is configured. Log levels are additive, and available levels are:

    loglevel 513
    loglevel 0x201
    loglevel 512 1
    loglevel 0x200 0x1
    loglevel stats trace

pidfile <filename>

The (absolute) name of a file that will hold the lloadd server's process ID (see getpid(2)).

sockbuf_max_incoming_client <integer>

Specify the maximum LDAP PDU size accepted coming from clients. The default is 262143.

sockbuf_max_incoming_upstream <integer>

Specify the maximum LDAP PDU size accepted coming from upstream connections. The default is 4194303.

tcp-buffer [listener=<URL>] [{read|write}=]<size>

Specify the size of the TCP buffer. A global value for both read and write TCP buffers related to any listener is defined, unless the listener is explicitly specified, or either the read or write qualifiers are used. See tcp(7) for details. Note that some OS-es implement automatic TCP buffer tuning.

threads <integer>

Specify the maximum size of the primary thread pool. The default is 16; the minimum value is 2.

threadqueues <integer>

Specify the number of work queues to use for the primary thread pool. The default is 1 and this is typically adequate for up to 8 CPU cores. The value should not exceed the number of CPUs in the system.

max_pdus_per_cycle <integer>

If set to 0, PDUs are handled by the I/O threads directly, otherwise a task is queued to be picked up by the thread pool. This task will process PDUs from the connection until there is no more data to be read or this limit is reached when the I/O thread can pick it up again. Very high values have a potential to cause some connections to be starved in a very high-bandwidth environment. The default is 1000.

client_max_pending <integer>

Will cause the load balancer to limit the number unfinished operations for each client connection. The default is 0, unlimited.

iotimeout <integer>

Specify the number of milliseconds to wait before forcibly closing a connection with an outstanding write. This allows faster recovery from various network hang conditions. An iotimeout of 0 disables this feature. The default is 10000.

TLS OPTIONS

TLSShareSlapdCTX { on | off }

If set to no (the default), lloadd will use its own TLS context (needs to be configured via cn=config unless lloadd is run as a standalone daemon). If enabled, the options for slapd apply instead, since the slapd's TLS context is used then.

The following options are available only when compiled as a standalone daemon. When compiled as a slapd(8) module, the cn=config equivalents need to be used if a separate TLS context for the module is needed, otherwise use the TLSShareSlapdCTX option.

TLSCipherSuite <cipher-suite-spec>

Permits configuring what ciphers will be accepted and the preference order. <cipher-suite-spec> should be a cipher specification for the TLS library in use (OpenSSL, GnuTLS, or Mozilla NSS). Example:

	openssl ciphers -v <cipher-suite-spec>

	gnutls-cli -l

        static const SSLCipherSuiteInfo suiteInfo[]

TLSCACertificateFile <filename>

Specifies the file that contains certificates for all of the Certificate Authorities that lloadd will recognize. The certificate for the CA that signed the server certificate must be included among these certificates. If the signing CA was not a top-level (root) CA, certificates for the entire sequence of CA's from the signing CA to the top-level CA should be present. Multiple certificates are simply appended to the file; the order is not significant.

TLSCACertificatePath <path>

Specifies the path of a directory that contains Certificate Authority certificates in separate individual files. Usually only one of this or the TLSCACertificateFile is used. This directive is not supported when using GnuTLS.

When using Mozilla NSS, <path> may contain a Mozilla NSS cert/key database. If <path> contains a Mozilla NSS cert/key database and CA cert files, OpenLDAP will use the cert/key database and will ignore the CA cert files.

TLSCertificateFile <filename>

Specifies the file that contains the lloadd server certificate.

When using Mozilla NSS, if using a cert/key database (specified with TLSCACertificatePath), TLSCertificateFile specifies the name of the certificate to use:

	TLSCertificateFile Server-Cert
    

If using a token other than the internal built in token, specify the token name first, followed by a colon:

	TLSCertificateFile my hardware device:Server-Cert
    

Use certutil -L to list the certificates by name:

	certutil -d /path/to/certdbdir -L
    

TLSCertificateKeyFile <filename>

Specifies the file that contains the lloadd server private key that matches the certificate stored in the TLSCertificateFile file. Currently, the private key must not be protected with a password, so it is of critical importance that it is protected carefully.

When using Mozilla NSS, TLSCertificateKeyFile specifies the name of a file that contains the password for the key for the certificate specified with TLSCertificateFile. The modutil command can be used to turn off password protection for the cert/key database. For example, if TLSCACertificatePath specifies /etc/openldap/certdb as the location of the cert/key database, use modutil to change the password to the empty string:

	modutil -dbdir /etc/openldap/certdb -changepw 'NSS Certificate DB'
    

You must have the old password, if any. Ignore the WARNING about the running browser. Press 'Enter' for the new password.

TLSDHParamFile <filename>

This directive specifies the file that contains parameters for Diffie-Hellman ephemeral key exchange. This is required in order to use a DSA certificate on the server, or an RSA certificate missing the "key encipherment" key usage. Note that setting this option may also enable Anonymous Diffie-Hellman key exchanges in certain non-default cipher suites. Anonymous key exchanges should generally be avoided since they provide no actual client or server authentication and provide no protection against man-in-the-middle attacks. You should append "!ADH" to your cipher suites to ensure that these suites are not used. When using Mozilla NSS these parameters are always generated randomly so this directive is ignored.

TLSECName <name>

Specify the name of a curve to use for Elliptic curve Diffie-Hellman ephemeral key exchange. This is required to enable ECDHE algorithms in OpenSSL. This option is not used with GnuTLS; the curves may be chosen in the GnuTLS ciphersuite specification. This option is also ignored for Mozilla NSS.

TLSProtocolMin <major>[.<minor>]

Specifies minimum SSL/TLS protocol version that will be negotiated. If the server doesn't support at least that version, the SSL handshake will fail. To require TLS 1.x or higher, set this option to 3.(x+1), e.g.,

	TLSProtocolMin 3.2
    

would require TLS 1.1. Specifying a minimum that is higher than that supported by the OpenLDAP implementation will result in it requiring the highest level that it does support. This directive is ignored with GnuTLS.

TLSRandFile <filename>

Specifies the file to obtain random bits from when /dev/[u]random is not available. Generally set to the name of the EGD/PRNGD socket. The environment variable RANDFILE can also be used to specify the filename. This directive is ignored with GnuTLS and Mozilla NSS.

TLSVerifyClient <level>

Specifies what checks to perform on client certificates in an incoming TLS session, if any. The <level> can be specified as one of the following keywords:

BACKEND CONFIGURATION

It is assumed all backend servers serve the same data. On startup, the configured connections are set up and those not dedicated to handle bind requests are authenticated with the backend using the information in the bindconf option. The authentication configuration is shared between them.

bindconf

[bindmethod=simple|sasl] [binddn=<dn>] [saslmech=<mech>] [authcid=<identity>] [authzid=<identity>] [credentials=<passwd>] [realm=<realm>] [secprops=<properties>] [timeout=<seconds>] [network-timeout=<seconds>] [tcp-user-timeout=<milliseconds>]

Specifies the bind credentials lloadd uses when setting up its regular connections to all backends.

A bindmethod of simple requires the options binddn and credentials and should only be used when adequate security services (e.g. TLS or IPSEC) are in place. REMEMBER: simple bind credentials must be in cleartext! A bindmethod of sasl requires the option saslmech. Depending on the mechanism, an authentication identity and/or credentials can be specified using authcid and credentials. The authzid parameter may be used to specify an authorization identity. Specific security properties (as with the sasl-secprops keyword above) for a SASL bind can be set with the secprops option. A non default SASL realm can be set with the realm option.

The timeout parameter indicates how long an operation can be pending a response (result, search entry, ...) from the server in seconds. Due to how timeouts are detected, the timeout might not be detected and handled up to timeout seconds after it happens.

The network-timeout parameter sets how long the consumer will wait to establish a network connection to the provider. Once a connection is established, the timeout parameter determines how long the consumer will wait for the initial Bind request to complete.

Timeout set to 0 means no timeout is in effect and by default, no timeouts are in effect.

The tcp-user-timeout parameter, if non-zero, corresponds to the TCP_USER_TIMEOUT set on the upstream connections, overriding the operating system setting. Only some systems support the customization of this parameter, it is ignored otherwise and system-wide settings are used.

BACKEND OPTIONS

backend-server

uri=ldap[s]://<hostname>[:port] [retry=<retry interval in ms>] [keepalive=<idle>:<probes>:<interval>] [starttls=yes|critical] [tls_cert=<file>] [tls_key=<file>] [tls_cacert=<file>] [tls_cacertdir=<path>] [tls_reqcert=never|allow|try|demand] [tls_cipher_suite=<ciphers>] [tls_crlcheck=none|peer|all] [tls_protocol_min=<major>[.<minor>]] [numconns=<conns>] [bindconns=<conns>] [max-pending-ops=<ops>] [conn-max-pending=<ops>]

Marks the beginning of a backend definition.

uri specifies the backend as an LDAP URI. If <port> is not given, the standard LDAP port number (389 or 636) is used.

Lloadd will attempt to maintain numconns active connections and also bindconns active connections dedicated to handling client bind requests.

If an error occurs on a working connection, a new connection attempt is made immediately, if one happens on establishing a new connection to this backend, lloadd will wait before a new reconnect attempt is made according to the retry parameter (default is 5 seconds).

Operations will be distributed across the backend's connections (upstreams).

The parameter conn-max-pending unless set to 0 (the default), will limit the number unfinished operations per upstream connection. Similarly, max-pending-ops will limit the total number or unfinished operations across all backend's connections, 0, the default, means no limit will be imposed for this backend.

The keepalive parameter sets the values of idle, probes, and interval used to check whether a socket is alive; idle is the number of seconds a connection needs to remain idle before TCP starts sending keepalive probes; probes is the maximum number of keepalive probes TCP should send before dropping the connection; interval is interval in seconds between individual keepalive probes. Only some systems support the customization of these values; the keepalive parameter is ignored otherwise, and system-wide settings are used.

The starttls parameter specifies use of the StartTLS extended operation to establish a TLS session before Binding to the provider. If the critical argument is supplied, the session will be aborted if the StartTLS request fails. Otherwise the syncrepl session continues without TLS. The tls_reqcert setting defaults to "demand" and the other TLS settings default to the same as the main slapd TLS settings.

EXAMPLES

argsfile  /var/db/run/lloadd.args
pidfile   /var/db/run/lloadd.pid
bindconf
    bindmethod=simple
    binddn=cn=test
    credentials=pass
backend-server
    uri=ldap://ldap1.example.com
    numconns=3
    bindconns=2
    retry=5000
    max-pending-ops=5
    conn-max-pending=3
backend-server
    uri=ldap://ldap2.example.com
    numconns=3
    bindconns=2
    retry=5000
    max-pending-ops=5
    conn-max-pending=3

"OpenLDAP Administrator's Guide" contains a longer annotated example of a configuration file. The original /usr/local/etc/openldap/lloadd.conf is another example.

LIMITATIONS

FILES

/usr/local/etc/openldap/lloadd.conf

default lloadd configuration file

SEE ALSO

"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)

ACKNOWLEDGEMENTS