From 5aa1f2c7a8e7877200ab52f542cbe7b4f37bc27f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ond=C5=99ej=20Kuzn=C3=ADk?= Date: Tue, 1 Feb 2022 18:20:31 +0000 Subject: [PATCH] ITS#9780 Document lloadd features new in 2.6 --- doc/guide/admin/loadbalancer.sdf | 162 ++++++++++++++++++++++++++++++- doc/guide/preamble.sdf | 1 + 2 files changed, 160 insertions(+), 3 deletions(-) diff --git a/doc/guide/admin/loadbalancer.sdf b/doc/guide/admin/loadbalancer.sdf index c14916dfee..9bbd4b4ef5 100644 --- a/doc/guide/admin/loadbalancer.sdf +++ b/doc/guide/admin/loadbalancer.sdf @@ -30,11 +30,166 @@ so-called intelligent routing. It does not understand semantics behind the opera 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). + - Clients with different requirements (e.g. a coherent session vs. simple but high traffic clients) are directed to separate lloadd configurations. + +H2: Directing operations to backends + + +H3: Default behaviour + +In the simplest configuration several backends would be configured within a single roundrobin tier: + +> feature proxyauthz +> +> bindconf bindmethod=simple +> binddn="cn=Manager,dc=example,dc=com" +> credentials=secret +> +> tier roundrobin +> backend-server uri=ldap://server1.example.com +> numconns=5 bindconns=5 +> max-pending-ops=10 conn-max-pending=3 +> retry=5000 +> backend-server uri=ldap://server2.example.com +> numconns=5 bindconns=5 +> max-pending-ops=10 conn-max-pending=3 +> retry=5000 + +After startup {{lloadd}} will open 10 connections to each +{{B:ldap://server1.example.com}} and {{B:ldap://server2.example.com}}, +5 for regular requests, where it will bind as {{B:cn=Manager,dc=example,dc=com}}, +and 5 dedicated to serving client Bind requests. If connection set up fails, it +will wait 5000ms (5 seconds) before making another attempt to that server. + +When a new Bind request comes from a client, it will be allocated to one of the +available {{bind connections}}, each of which can only carry one request at a +time. For other requests that need to be passed on to the backends, backends are +considered in order: +* if the number of pending/in-flight for that backend is at or above 10, it is +skipped +* the first appropriate upstream connection is chosen: +** an idle {{bind connection}} for Bind requests +** a {{regular connection}} with less than 3 pending operations for other +types of requests +* if no such connection is available, the next backend in order is checked +* if we go through the whole list without choosing an upstream connection, +we return a failure to the client, either an {{B:LDAP_UNAVAILABLE}} if no +connections of the appropriate type have been established at all or +{{B:LDAP_BUSY}} otherwise + +When a connection is chosen, the operation is forwarded and response(s) +returned to the client. Should that connection go away before the final +response is received, the client is notified with a {{B:LDAP_OTHER}} failure +code. + +So long as {{feature proxyauthz}} is configured, every operation forwarded over +a {{regular connection}} has the {{B:PROXYAUTHZ}} control ({{REF:RFC4370}}) +prepended indicating the client's bound identity, unless that identity matches +the {{binddn}} configured in {{bindconf}}. + +If another tier is configured: + +> tier roundrobin +> backend-server uri=ldap://fallback.example.com +> numconns=5 bindconns=5 +> max-pending-ops=10 conn-max-pending=3 +> retry=5000 + +Backends in this tier will only be considered when {{lloadd}} would have +returned {{B:LDAP_UNAVAILABLE}} in the above case. + + +H3: Alternate selection strategies + +For various reasons, the {{roundrobin}} tier is appropriate in the majority of +use cases as it is both very scalable in terms of its implementation and how +its self-limiting interacts with backends when multiple {{lloadd}} instances +are being used at the same time. + +Two alternative selection strategies have been implemented: + +- {{tier weighted}} applies predefined weights to how often a backend is + considered first +- {{tier bestof}} measures the time to first response from each backend, when a + new operation needs to be forwarded, two backends are selected at random and + the backend with better response time is considered first. If connections on + neither backend can be used, selection falls back to the regular strategy + used by the roundrobin backend + +The {{weighted}} tier might be appropriate when servers have differing load +capacity. Due to its reinforced self-limiting feedback, the {{bestof}} tier +might be appropriate in large scale environments where each backend's +capacity/latency fluctuates widely and rapidly. + + +H3: Coherence + +H4: Write coherence + +In default configurations, every operation submitted by the client is either +processed internally (e.g. StartTLS, Abandon, Unbind, ...) or is forwarded to a +connection of lloadd's choosing, independent of any other other operation +submitted by the same client. + +There are certain traffic patterns where such such freedom is undesirable and +some kind of coherency is required. This applies to write traffic, controls +like Paged Results or many extended operations. + +Client's operations can be pinned to the same backend as the last write +operation: + +> write_coherence 5 + +In this case, client's requests will be passed over to the same backend (not +necessarily over the same upstream connection) from the moment a write request +is passed on till at least 5 seconds have elapsed since last write operation +has finished. + +> write_coherence -1 + +Here, there is no timeout and the moment a write request is passed on to a +backend, the client's operations will forever be passed on to this backend. + +In both cases above, this limitation is lifted the moment a Bind request is +received from the client connection. + +H4: Extended operations/controls + +Many controls and Extended operations establish shared state on the session. +While {{lloadd}} implements some of these (StartTLS being one example), it +supports the administrator in defining how to deal with those it does not +implement special handling for. + +> restrict_exop 1.1 reject +> # TXN Exop +> restrict_exop 1.3.6.1.1.21.1 connection +> # Password Modify Exop +> restrict_exop 1.3.6.1.4.1.4203.1.11.1 write +> +> # Paged Results Control +> restrict_control 1.2.840.113556.1.4.319 connection +> # Syncrepl +> restrict_control 1.3.6.1.4.1.4203.1.9.1 reject + +The above configuration uses the special invalid OID of {{1.1}} to instruct +{{lloadd}} to reject any Extended operation it does not recognize, except for +Password Modify operation which is treated according to {{write_coherence}} +above and the LDAP transactions, where it forwards all subsequent requests over +to the same upstream connection. Similarly, once a Paged results control is +seen on an operation, subsequent request will stick to the same upstream +connection while LDAP Syncrepl requests will be rejected outright. + +With both {{restrict_exop}} and {{restrict_control}}, any such limitation is +lifted when a new Bind request comes in as any client state is assumed to be +reset. + +When configuring these to anything else than {{reject}}, keep in mind that many +extensions have not been designed or implemented with a multiplexing proxy like +{{lloadd}} in mind and might open considerable operational and/or security +concerns when allowed. + H2: Runtime configurations @@ -150,6 +305,7 @@ Sample setup config for load balancer running in front of four slapd instances. ># practically indistinguishable. Only TLS settings can be specified on ># a per-backend basis. > +>tier roundrobin >backend-server uri=ldap://ldaphost01 starttls=critical retry=5000 > max-pending-ops=50 conn-max-pending=10 > numconns=10 bindconns=5 diff --git a/doc/guide/preamble.sdf b/doc/guide/preamble.sdf index c5850b801e..d5d94d2f35 100644 --- a/doc/guide/preamble.sdf +++ b/doc/guide/preamble.sdf @@ -295,6 +295,7 @@ RFC3384|I|Lightweight Directory Access Protocol (version 3) Replication Requirem RFC3494|I|Lightweight Directory Access Protocol version 2 (LDAPv2) to Historic Status|https://www.rfc-editor.org/rfc/rfc3494.txt RFC4013|PS|SASLprep: Stringprep Profile for User Names and Passwords|https://www.rfc-editor.org/rfc/rfc4013.txt RFC4346|PS|The Transport Layer Security (TLS) Protocol, Version 1.1|https://www.rfc-editor.org/rfc/rfc4346.txt +RFC4370|PS|Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control|https://www.rfc-editor.org/rfc/rfc4370.txt RFC4422|PS|Simple Authentication and Security Layer (SASL)|https://www.rfc-editor.org/rfc/rfc4422.txt RFC4510|PS|Lightweight Directory Access Protocol (LDAP): Technical Specification Roadmap|https://www.rfc-editor.org/rfc/rfc4510.txt RFC4511|PS|Lightweight Directory Access Protocol (LDAP): The Protocol|https://www.rfc-editor.org/rfc/rfc4511.txt -- 2.47.3