1# $OpenLDAP$
2# Copyright 2021 The OpenLDAP Foundation, All Rights Reserved.
3# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4H1: Load Balancing with lloadd
5
6As covered in the {{SECT:Replication}} chapter, replication is a fundamental
7requirement for delivering a resilient enterprise deployment.  As such
8there's a need for an LDAPv3 capable load balancer to spread the load between the
9various directory instances.
10
11{{lloadd}}(8) provides the capability to distribute LDAP v3 requests between a
12set of running {{slapd}} instances.  It can run as a standalone daemon
13{{lloadd}}, or as an embedded module running inside of {{slapd}}.
14
15H2: Overview
16
17{{lloadd}}(8) was designed to handle LDAP loads.
18It is protocol-aware and can balance LDAP loads on a per-operation basis rather
19than on a per-connection basis.
20
21{{lloadd}}(8) distributes the load across a set of slapd instances. The client
22connects to the load balancer instance which forwards the request to one
23of the servers and returns the response back to the client.
24
25H2: When to use the OpenLDAP load balancer
26
27In general, the OpenLDAP load balancer spreads the load across configured backend servers.  It does not perform
28so-called intelligent routing. It does not understand semantics behind the operations being performed by the clients.
29
30More considerations:
31
32 - Servers are indistinguishable with respect to data contents.  The exact same copy of data resides on every server.
33 - Clients do not require 'sticky' sessions.
34 - The sequence of operations isn't important.  For example, read after update isn't required by the client.
35 - If your client can handle both connection pooling and load distribution then it's preferable to lloadd.
36 - 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.
37 - 2.6 release of lloadd will include sticky sessions (coherency).
38
39H2: Runtime configurations
40
41It deploys in one of two ways:
42
43^ Standalone daemon: {{ lloadd }}
44+ Loaded into the slapd daemon as a module: {{ lloadd.la }}
45
46It is recommended to run with the balancer module embedded in slapd because dynamic configuration (cn=config) and the monitor backend are then available.
47
48{{B: Sample load balancer scenario:}}
49
50!import "load-balancer-scenario.png"; align="center"; title="Load Balancer Scenario"
51FT[align="Center"] Figure: Load balancer sample scenario
52
53^ The LDAP client submits an LDAP operation to
54the load balancer daemon.
55
56+ The load balancer forwards the request to one of the backend instances in its pool of servers.
57
58+ The backend slapd server processes the request and returns the response to
59the load balancer instance.
60
61+ The load balancer returns the response to the client.  The client's unaware that it's connecting to a load balancer instead of slapd.
62
63H2: Build Notes
64
65To build the load balancer from source, follow the instructions in the
66{{SECT: A Quick-Start Guide}} substituting the following commands:
67
68^ To configure as standalone daemon:
69
70..{{EX:./configure --enable-balancer=yes}}
71
72+ To configure as embedded module to slapd:
73
74..{{EX:./configure --enable-modules --enable-balancer=mod}}
75
76H2: Sample Runtime
77
78^ To run embedded as {{ lloadd }} module:
79
80..{{EX: slapd [-h URLs]  [-f lloadd-config-file] [-u user] [-g group]}}
81
82 - the startup is the same as starting the {{ slapd }} daemon.
83 - URLs is for slapd management. The load balancer's listener URLs set in the configuration file or node. (more later)
84
85+ To run as standalone daemon:
86
87..{{EX: lloadd [-h URLs]  [-f lloadd-config-file] [-u user] [-g group]}}
88
89 - Other than a different daemon name, running standalone has the same options as starting {{ slapd }}.
90 - -h URLs specify the lloadd's interface directly, there is no management interface.
91
92For a complete list of options, checkout the man page {{ lloadd.8 }}
93
94H2: Configuring load balancer
95
96H3: Common configuration options
97
98Many of the same configuration options as slapd. For complete list, check
99the {{lloadd}}(5) man page.
100
101.{{S: }}
102{{B:Edit the slapd.conf or cn=config configuration file}}.
103
104To configure your working {{lloadd}}(8) you need to make the following changes to your configuration file:
105  ^ include {{ core.schema }} (embedded only)
106  + {{ TLSShareSlapdCTX { on | off } }}
107  + Other common TLS slapd options
108  + Setup argsfile/pidfile
109  + Setup moduleload path (embedded mode only)
110  + {{ moduleload      lloadd.la }}
111  + loglevel, threads, ACL's
112  + {{ backend lload }} begin lloadd specific backend configurations
113  + {{ listen ldap://:PORT }} Specify listen port for load balancer
114  + {{ feature proxyauthz }} Use the proxy authZ control to forward client's identity
115  + {{ 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
116
117H3: Sample backend config
118
119Sample setup config for load balancer running in front of four slapd instances.
120
121>backend lload
122>
123># The Load Balancer manages its own sockets, so they have to be separate
124># from the ones slapd manages (as specified with the -h "URLS" option at
125># startup).
126>listen ldap://:1389
127>
128># Enable authorization tracking
129>feature proxyauthz
130>
131># 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.
132># The value should be set to a power of 2:
133>io-threads  2
134>
135># If TLS is configured above, use the same context for the Load Balancer
136># If using cn=config, this can be set to false and different settings
137># can be used for the Load Balancer
138>TLSShareSlapdCTX true
139>
140># Authentication and other options (timeouts) shared between backends.
141>bindconf bindmethod=simple
142>         binddn=dc=example,dc=com credentials=secret
143>         network-timeout=5
144>         tls_cacert="/usr/local/etc/openldap/ca.crt"
145>         tls_cert="/usr/local/etc/openldap/host.crt"
146>         tls_key="/usr/local/etc/openldap/host.pem"
147>
148>
149># List the backends we should relay operations to, they all have to be
150># practically indistinguishable. Only TLS settings can be specified on
151># a per-backend basis.
152>
153>backend-server uri=ldap://ldaphost01 starttls=critical retry=5000
154>               max-pending-ops=50 conn-max-pending=10
155>               numconns=10 bindconns=5
156>backend-server uri=ldap://ldaphost02 starttls=critical retry=5000
157>               max-pending-ops=50 conn-max-pending=10
158>               numconns=10 bindconns=5
159>backend-server uri=ldap://ldaphost03 starttls=critical retry=5000
160>               max-pending-ops=50 conn-max-pending=10
161>               numconns=10 bindconns=5
162>backend-server uri=ldap://ldaphost04 starttls=critical retry=5000
163>               max-pending-ops=50 conn-max-pending=10
164>               numconns=10 bindconns=5
165>
166>#######################################################################
167># Monitor database
168>#######################################################################
169>database        monitor
170