diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/guide/admin/loadbalancer.sdf | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/doc/guide/admin/loadbalancer.sdf b/doc/guide/admin/loadbalancer.sdf new file mode 100644 index 0000000..c14916d --- /dev/null +++ b/doc/guide/admin/loadbalancer.sdf @@ -0,0 +1,169 @@ +# $OpenLDAP$ +# Copyright 2021-2022 The OpenLDAP Foundation, All Rights Reserved. +# COPYING RESTRICTIONS APPLY, see COPYRIGHT. +H1: Load Balancing with lloadd + +As covered in the {{SECT:Replication}} chapter, replication is a fundamental +requirement for delivering a resilient enterprise deployment. As such +there's a need for an LDAPv3 capable load balancer to spread the load between the +various directory instances. + +{{lloadd}}(8) provides the capability to distribute LDAP v3 requests between a +set of running {{slapd}} instances. It can run as a standalone daemon +{{lloadd}}, or as an embedded module running inside of {{slapd}}. + +H2: Overview + +{{lloadd}}(8) was designed to handle LDAP loads. +It is protocol-aware and can balance LDAP loads on a per-operation basis rather +than on a per-connection basis. + +{{lloadd}}(8) distributes the load across a set of slapd instances. The client +connects to the load balancer instance which forwards the request to one +of the servers and returns the response back to the client. + +H2: When to use the OpenLDAP load balancer + +In general, the OpenLDAP load balancer spreads the load across configured backend servers. It does not perform +so-called intelligent routing. It does not understand semantics behind the operations being performed by the clients. + +More considerations: + + - Servers are indistinguishable with respect to data contents. The exact same copy of data resides on every server. + - Clients do not require 'sticky' sessions. + - The sequence of operations isn't important. For example, read after update isn't required by the client. + - If your client can handle both connection pooling and load distribution then it's preferable to lloadd. + - Clients that require a consistent session (e.g. do writes), the best practice is to let them set up a direct session to one of the providers. The read-only clients are still free to use lloadd. + - 2.6 release of lloadd will include sticky sessions (coherency). + +H2: Runtime configurations + +It deploys in one of two ways: + +^ Standalone daemon: {{ lloadd }} ++ Loaded into the slapd daemon as a module: {{ lloadd.la }} + +It is recommended to run with the balancer module embedded in slapd because dynamic configuration (cn=config) and the monitor backend are then available. + +{{B: Sample load balancer scenario:}} + +!import "load-balancer-scenario.png"; align="center"; title="Load Balancer Scenario" +FT[align="Center"] Figure: Load balancer sample scenario + +^ The LDAP client submits an LDAP operation to +the load balancer daemon. + ++ The load balancer forwards the request to one of the backend instances in its pool of servers. + ++ The backend slapd server processes the request and returns the response to +the load balancer instance. + ++ The load balancer returns the response to the client. The client's unaware that it's connecting to a load balancer instead of slapd. + +H2: Build Notes + +To build the load balancer from source, follow the instructions in the +{{SECT: A Quick-Start Guide}} substituting the following commands: + +^ To configure as standalone daemon: + +..{{EX:./configure --enable-balancer=yes}} + ++ To configure as embedded module to slapd: + +..{{EX:./configure --enable-modules --enable-balancer=mod}} + +H2: Sample Runtime + +^ To run embedded as {{ lloadd }} module: + +..{{EX: slapd [-h URLs] [-f lloadd-config-file] [-u user] [-g group]}} + + - the startup is the same as starting the {{ slapd }} daemon. + - URLs is for slapd management. The load balancer's listener URLs set in the configuration file or node. (more later) + ++ To run as standalone daemon: + +..{{EX: lloadd [-h URLs] [-f lloadd-config-file] [-u user] [-g group]}} + + - Other than a different daemon name, running standalone has the same options as starting {{ slapd }}. + - -h URLs specify the lloadd's interface directly, there is no management interface. + +For a complete list of options, checkout the man page {{ lloadd.8 }} + +H2: Configuring load balancer + +H3: Common configuration options + +Many of the same configuration options as slapd. For complete list, check +the {{lloadd}}(5) man page. + +.{{S: }} +{{B:Edit the slapd.conf or cn=config configuration file}}. + +To configure your working {{lloadd}}(8) you need to make the following changes to your configuration file: + ^ include {{ core.schema }} (embedded only) + + {{ TLSShareSlapdCTX { on | off } }} + + Other common TLS slapd options + + Setup argsfile/pidfile + + Setup moduleload path (embedded mode only) + + {{ moduleload lloadd.la }} + + loglevel, threads, ACL's + + {{ backend lload }} begin lloadd specific backend configurations + + {{ listen ldap://:PORT }} Specify listen port for load balancer + + {{ feature proxyauthz }} Use the proxy authZ control to forward client's identity + + {{ io-threads INT }} 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 + +H3: Sample backend config + +Sample setup config for load balancer running in front of four slapd instances. + +>backend lload +> +># The Load Balancer manages its own sockets, so they have to be separate +># from the ones slapd manages (as specified with the -h "URLS" option at +># startup). +>listen ldap://:1389 +> +># Enable authorization tracking +>feature proxyauthz +> +># 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: +>io-threads 2 +> +># If TLS is configured above, use the same context for the Load Balancer +># If using cn=config, this can be set to false and different settings +># can be used for the Load Balancer +>TLSShareSlapdCTX true +> +># Authentication and other options (timeouts) shared between backends. +>bindconf bindmethod=simple +> binddn=dc=example,dc=com credentials=secret +> network-timeout=5 +> tls_cacert="/usr/local/etc/openldap/ca.crt" +> tls_cert="/usr/local/etc/openldap/host.crt" +> tls_key="/usr/local/etc/openldap/host.pem" +> +> +># List the backends we should relay operations to, they all have to be +># practically indistinguishable. Only TLS settings can be specified on +># a per-backend basis. +> +>backend-server uri=ldap://ldaphost01 starttls=critical retry=5000 +> max-pending-ops=50 conn-max-pending=10 +> numconns=10 bindconns=5 +>backend-server uri=ldap://ldaphost02 starttls=critical retry=5000 +> max-pending-ops=50 conn-max-pending=10 +> numconns=10 bindconns=5 +>backend-server uri=ldap://ldaphost03 starttls=critical retry=5000 +> max-pending-ops=50 conn-max-pending=10 +> numconns=10 bindconns=5 +>backend-server uri=ldap://ldaphost04 starttls=critical retry=5000 +> max-pending-ops=50 conn-max-pending=10 +> numconns=10 bindconns=5 +> +>####################################################################### +># Monitor database +>####################################################################### +>database monitor |