Commit 296dde8f authored by Ondřej Kuzník's avatar Ondřej Kuzník Committed by Quanah Gibson-Mount
Browse files

ITS#9780 Document lloadd features new in 2.6

parent fb736b01
Pipeline #4156 failed with stage
in 32 minutes and 55 seconds
......@@ -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 reqests 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 appropritate 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
......
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment