lloadd.conf.5 20.9 KB
Newer Older
Ondřej Kuzník's avatar
Ondřej Kuzník committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
.TH LLOADD.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.\" $OpenLDAP$
.SH NAME
lloadd.conf \- configuration file for lloadd, the stand-alone LDAP daemon
.SH SYNOPSIS
ETCDIR/lloadd.conf
.SH DESCRIPTION
The file
.B ETCDIR/lloadd.conf
contains configuration information for the
.BR lloadd (8) daemon.
.LP
The
.B lloadd.conf
file consists of a series of global configuration options that apply to
.B 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.
.LP
The general format of
.B lloadd.conf
is as follows:
.LP
.nf
    # comment - these options apply to the server as a whole
    <global configuration options>
    # first backend definition & configuration options
    backend <backend 1 definition>
    <configuration options specific to backend 1>
    # subsequent backend definitions & configuration options
    ...
.fi
.LP
As many backend-specific sections as desired may be included.  Global
options can be overridden in a backend (for options that appear more
than once, the last appearance in the
.B lloadd.conf
file is used).
.LP
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.
.LP
Blank lines and comment lines beginning with
a `#' character are ignored.  Note: continuation lines are unwrapped
before comment processing is applied.
.LP
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.
.LP
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.

.SH GLOBAL CONFIGURATION OPTIONS
Options described in this section apply to all backends, unless specifically
overridden in a backend definition. Arguments that should be replaced by
actual text are shown in brackets <>.
.TP
.B argsfile <filename>
The (absolute) name of a file that will hold the
.B lloadd
server's command line (program name and options).
.TP
.B 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.
.\" .TP
.\" .B gentlehup { on | off }
.\" A SIGHUP signal will only cause a 'gentle' shutdown-attempt:
.\" .B Lloadd
.\" will stop listening for new connections, but will not close the
.\" connections to the current clients.  Future write operations return
.\" unwilling-to-perform, though.  Lloadd terminates when all clients
.\" have closed their connections (if they ever do), or - as before -
.\" if it receives a SIGTERM signal.  This can be useful if you wish to
.\" terminate the server and start a new
.\" .B lloadd
.\" server
.\" .B with another database,
.\" without disrupting the currently active clients.
.\" The default is off.  You may wish to use
.\" .B idletimeout
.\" along with this option.
.\" .TP
.\" .B idletimeout <integer>
.\" Specify the number of seconds to wait before forcibly closing
.\" an idle client connection.  A idletimeout of 0 disables this
.\" feature.  The default is 0. You may also want to set the
.\" .B iotimeout
.\" option.
.TP
.B feature <feature> [...]
Switch additional features supported by the LDAP Load Balancer on.
Supported features are:
.RS
.RS
.PD 0
.TP
.B proxyauthz
when proxying an operation, pass the client's authorized identity using
the proxy authorization control (RFC 4370).
.\" .TP
.\" .B vc
.\" when receiving a bind operation from a client, pass it onto a backend
.\" as a verify credentials external operation request. With this enabled,
.\" the
.\" .BR backend 's
.\" .B bindconns
.\" option has no effect as there is no need to maintain dedicated bind
.\" connections anymore.
.PD
.RE
.TP
.B include <filename>
Read additional configuration information from the given file before
continuing with the next line of the current file.
.TP
128
.B io-threads <integer>
Ondřej Kuzník's avatar
Ondřej Kuzník committed
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
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.
.TP
.B logfile <filename>
Specify a file for recording debug log messages. By default these messages
only go to stderr and are not recorded anywhere else. Specifying a logfile
copies messages to both stderr and the logfile.
.TP
.B loglevel <integer> [...]
Specify the level at which debugging statements and operation
statistics should be syslogged (currently logged to the
.BR 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:
.RS
.RS
.PD 0
.TP
.B 1
.B (0x1 trace)
trace function calls
.TP
.B 2
.B (0x2 packets)
debug packet handling
.TP
.B 4
.B (0x4 args)
heavy trace debugging (function args)
.TP
.B 8
.B (0x8 conns)
connection management
.TP
.B 16
.B (0x10 BER)
print out packets sent and received
.\" .TP
.\" .B 32
.\" .B (0x20 filter)
.\" search filter processing
.TP
.B 64
.B (0x40 config)
configuration file processing
.\" .TP
.\" .B 128
.\" .B (0x80 ACL)
.\" access control list processing
.TP
.B 256
.B (0x100 stats)
connections, LDAP operations, results (recommended)
.TP
.B 512
.B (0x200 stats2)
stats log entries sent
.\" .TP
.\" .B 1024
.\" .B (0x400 shell)
.\" print communication with shell backends
.\" .TP
.\" .B 2048
.\" .B (0x800 parse)
.\" entry parsing
\".TP
\".B 4096
\".B (0x1000 cache)
\"caching (unused)
\".TP
\".B 8192
\".B (0x2000 index)
\"data indexing (unused)
.\" .TP
.\" .B 16384
.\" .B (0x4000 sync)
.\" LDAPSync replication
.TP
.B 32768
.B (0x8000 none)
only messages that get logged whatever log level is set
.PD
.RE
The desired log level can be input as a single integer that combines
the (ORed) desired levels, both in decimal or in hexadecimal notation,
as a list of integers (that are ORed internally),
or as a list of the names that are shown between parentheses, such that
.LP
.nf
    loglevel 513
    loglevel 0x201
    loglevel 512 1
    loglevel 0x200 0x1
    loglevel stats trace
.fi
.LP
are equivalent.
The keyword
.B any
can be used as a shortcut to enable logging at all levels (equivalent to \-1).
The keyword
.BR none ,
or the equivalent integer representation, causes those messages
that are logged regardless of the configured loglevel to be logged.
In fact, if loglevel is set to 0, no logging occurs,
so at least the
.B none
level is required to have high priority messages logged.

The loglevel defaults to \fBstats\fP.
This level should usually also be included when using other loglevels, to
help analyze the logs.
.RE
.TP
.B pidfile <filename>
The (absolute) name of a file that will hold the
.B lloadd
server's process ID (see
.BR getpid (2)).
.TP
.B sockbuf_max_incoming <integer>
Specify the maximum incoming LDAP PDU size for anonymous sessions.
The default is 262143.
.TP
.B sockbuf_max_incoming_auth <integer>
Specify the maximum incoming LDAP PDU size for authenticated sessions.
The default is 4194303.
.TP
.B 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
.BR tcp (7)
for details.
Note that some OS-es implement automatic TCP buffer tuning.
.TP
.B threads <integer>
Specify the maximum size of the primary thread pool.
The default is 16; the minimum value is 2.
.TP
.B 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.

.SH TLS OPTIONS
If
.B lloadd
is built with support for Transport Layer Security, there are more options
you can specify.
.TP
.B 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:
.RS
.RS
.TP
.I OpenSSL:
TLSCipherSuite HIGH:MEDIUM:+SSLv2
.TP
.I GnuTLS:
TLSCiphersuite SECURE256:!AES-128-CBC
.RE

To check what ciphers a given spec selects in OpenSSL, use:

.nf
	openssl ciphers \-v <cipher-suite-spec>
.fi

With GnuTLS the available specs can be found in the manual page of
.BR gnutls\-cli (1)
(see the description of the
option
.BR \-\-priority ).

In older versions of GnuTLS, where gnutls\-cli does not support the option
\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling:

.nf
	gnutls\-cli \-l
.fi

When using Mozilla NSS, the OpenSSL cipher suite specifications are used and
translated into the format used internally by Mozilla NSS.  There isn't an easy
way to list the cipher suites from the command line.  The authoritative list
is in the source code for Mozilla NSS in the file sslinfo.c in the structure
.nf
        static const SSLCipherSuiteInfo suiteInfo[]
.fi
.RE
.TP
.B TLSCACertificateFile <filename>
Specifies the file that contains certificates for all of the Certificate
Authorities that
.B 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.
.TP
.B 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.
.TP
.B TLSCertificateFile <filename>
Specifies the file that contains the
.B 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:
.nf
	TLSCertificateFile Server-Cert
.fi
If using a token other than the internal built in token, specify the
token name first, followed by a colon:
.nf
	TLSCertificateFile my hardware device:Server-Cert
.fi
Use certutil \-L to list the certificates by name:
.nf
	certutil \-d /path/to/certdbdir \-L
.fi
.TP
.B TLSCertificateKeyFile <filename>
Specifies the file that contains the
.B lloadd
server private key that matches the certificate stored in the
.B 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
specifes /etc/openldap/certdb as the location of the cert/key database, use
modutil to change the password to the empty string:
.nf
	modutil \-dbdir /etc/openldap/certdb \-changepw 'NSS Certificate DB'
.fi
You must have the old password, if any.  Ignore the WARNING about the running
browser.  Press 'Enter' for the new password.
.TP
.B 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.
.TP
.B 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.
.TP
.B 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.,

.nf
	TLSProtocolMin 3.2
.fi

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.
.TP
.B 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.
.TP
.B TLSVerifyClient <level>
Specifies what checks to perform on client certificates in an
incoming TLS session, if any.
The
.B <level>
can be specified as one of the following keywords:
.RS
.TP
.B never
This is the default.
.B lloadd
will not ask the client for a certificate.
.TP
.B allow
The client certificate is requested.  If no certificate is provided,
the session proceeds normally.  If a bad certificate is provided,
it will be ignored and the session proceeds normally.
.TP
.B try
The client certificate is requested.  If no certificate is provided,
the session proceeds normally.  If a bad certificate is provided,
the session is immediately terminated.
.TP
.B demand | hard | true
These keywords are all equivalent, for compatibility reasons.
The client certificate is requested.  If no certificate is provided,
or a bad certificate is provided, the session is immediately terminated.
.TP
.B TLSCRLCheck <level>
Specifies if the Certificate Revocation List (CRL) of the CA should be
used to verify if the client certificates have not been revoked. This
requires
.B TLSCACertificatePath
parameter to be set. This directive is ignored with GnuTLS and Mozilla NSS.
.B <level>
can be specified as one of the following keywords:
.RS
.TP
.B none
No CRL checks are performed
.TP
.B peer
Check the CRL of the peer certificate
.TP
.B all
Check the CRL for a whole certificate chain
.RE
.TP
.B TLSCRLFile <filename>
Specifies a file containing a Certificate Revocation List to be used
for verifying that certificates have not been revoked. This directive is
only valid when using GnuTLS and Mozilla NSS.

.SH GENERAL BACKEND OPTIONS
Options in this section only apply to the configuration file section
for the specified backend.  They are supported by every
type of backend.
.TP
.B backend
.B uri=ldap[s]://<hostname>[:port]
.B [retry=<retry interval in ms>]
.B [network\-timeout=<seconds>]
.B [timeout=<seconds>]
.B [bindmethod=simple|sasl]
.B [binddn=<dn>]
.B [saslmech=<mech>]
.B [authcid=<identity>]
.B [authzid=<identity>]
.B [credentials=<passwd>]
.B [realm=<realm>]
.B [secprops=<properties>]
.B [keepalive=<idle>:<probes>:<interval>]
.B [starttls=yes|critical]
.B [tls_cert=<file>]
.B [tls_key=<file>]
.B [tls_cacert=<file>]
.B [tls_cacertdir=<path>]
.B [tls_reqcert=never|allow|try|demand]
.B [tls_cipher_suite=<ciphers>]
.B [tls_crlcheck=none|peer|all]
.B [tls_protocol_min=<major>[.<minor>]]
.B [numconns=<conns>]
.B [bindconns=<conns>]
.B [max-pending-ops=<ops>]
.B [conn-max-pending=<ops>]

Marks the beginning of a backend definition.

.B 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
.B numconns
active connections and
.\" unless the
.\" .B vc
.\" feature is enabled,
also
.B 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
.B retry
parameter.

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

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

The
.B network\-timeout
parameter sets how long the consumer will wait to establish a
network connection to the provider. Once a connection is
established, the
.B timeout
parameter determines how long the consumer will wait for the initial
Bind request to complete. The defaults for these parameters come
from
.BR ldap.conf (5).

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

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

The
.B starttls
parameter specifies use of the StartTLS extended operation
to establish a TLS session before Binding to the provider. If the
.B 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.

.\" .TP
.\" .B readonly on | off
.\" This option puts the backend into "read-only" mode.  Only read
.\" operations (i.e. bind, search, compare) will be directed towards this
.\" backend. By default, readonly is off.
.\" .TP
.\" .B restrict <oplist>
.\" Specify a whitespace separated list of operations that are restricted.
.\" If defined inside a database specification, restrictions apply only
.\" to that database, otherwise they are global.
.\" Operations can be any of
.\" .BR add ,
.\" .BR bind ,
.\" .BR compare ,
.\" .BR delete ,
.\" .BR extended[=<OID>] ,
.\" .BR modify ,
.\" .BR rename ,
.\" .BR search ,
.\" or the special pseudo-operations
.\" .B read
.\" and
.\" .BR write ,
.\" which respectively summarize read and write operations.
.\" The use of
.\" .I restrict write
.\" is equivalent to
.\" .I readonly on
.\" (see above).
.\" The
.\" .B extended
.\" keyword allows one to indicate the OID of the specific operation
.\" to be restricted.

.SH EXAMPLES
.LP
Here is a short example of a configuration file:
.LP
.RS
.nf
argsfile  LOCALSTATEDIR/run/lloadd.args
pidfile   LOCALSTATEDIR/run/lloadd.pid

backend
    uri=ldap://ldap1.example.com
    bindmethod=simple
    binddn=cn=test
    credentials=pass
    numconns=3
    bindconns=2
    retry=5000
    max-pending-ops=5
    conn-max-pending=3

backend
    uri=ldap://ldap2.example.com
    bindmethod=simple
    binddn=cn=test
    credentials=pass
    numconns=3
    bindconns=2
    retry=5000
    max-pending-ops=5
    conn-max-pending=3
.fi
.RE
.LP
"OpenLDAP Administrator's Guide" contains a longer annotated
example of a configuration file.
The original ETCDIR/lloadd.conf is another example.

.SH FILES
.TP
ETCDIR/lloadd.conf
default lloadd configuration file
.SH SEE ALSO
.BR ldap (3),
.BR gnutls\-cli (1),
.BR lloadd (8),
.BR slapd (8).
.LP
"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
.SH ACKNOWLEDGEMENTS
.so ../Project