From 8d85912ab9f2cb350db0931d5a572a9d6b72a09c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Kuzn=C3=ADk?= Date: Thu, 25 May 2017 15:24:58 +0100 Subject: [PATCH] lloadd documentation --- doc/man/man5/lloadd.conf.5 | 715 +++++++++++++++++++++++++++++++++++++ doc/man/man8/lloadd.8 | 249 +++++++++++++ 2 files changed, 964 insertions(+) create mode 100644 doc/man/man5/lloadd.conf.5 create mode 100644 doc/man/man8/lloadd.8 diff --git a/doc/man/man5/lloadd.conf.5 b/doc/man/man5/lloadd.conf.5 new file mode 100644 index 0000000000..e26d7319f9 --- /dev/null +++ b/doc/man/man5/lloadd.conf.5 @@ -0,0 +1,715 @@ +.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 + + # first backend definition & configuration options + backend + + # 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 +The (absolute) name of a file that will hold the +.B lloadd +server's command line (program name and options). +.TP +.B concurrency +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 +.\" 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 [...] +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 +Read additional configuration information from the given file before +continuing with the next line of the current file. +.TP +.B listener-threads +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 +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 [...] +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 +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 +Specify the maximum incoming LDAP PDU size for anonymous sessions. +The default is 262143. +.TP +.B sockbuf_max_incoming_auth +Specify the maximum incoming LDAP PDU size for authenticated sessions. +The default is 4194303. +.TP +.B tcp-buffer [listener=] [{read|write}=] +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 +Specify the maximum size of the primary thread pool. +The default is 16; the minimum value is 2. +.TP +.B threadqueues +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 +Permits configuring what ciphers will be accepted and the preference order. + 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 +.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 +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 +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, may contain a Mozilla NSS cert/key +database. If 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 +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 +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 +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 +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 [.] +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 +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 +Specifies what checks to perform on client certificates in an +incoming TLS session, if any. +The +.B +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 +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 +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 +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]://[:port] +.B [retry=] +.B [network\-timeout=] +.B [timeout=] +.B [bindmethod=simple|sasl] +.B [binddn=] +.B [saslmech=] +.B [authcid=] +.B [authzid=] +.B [credentials=] +.B [realm=] +.B [secprops=] +.B [keepalive=::] +.B [starttls=yes|critical] +.B [tls_cert=] +.B [tls_key=] +.B [tls_cacert=] +.B [tls_cacertdir=] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_cipher_suite=] +.B [tls_crlcheck=none|peer|all] +.B [tls_protocol_min=[.]] +.B [numconns=] +.B [bindconns=] +.B [max-pending-ops=] +.B [conn-max-pending=] + +Marks the beginning of a backend definition. + +.B uri +specifies the backend as an LDAP URI. If 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 +.\" 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[=] , +.\" .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 diff --git a/doc/man/man8/lloadd.8 b/doc/man/man8/lloadd.8 new file mode 100644 index 0000000000..dd635cbeb1 --- /dev/null +++ b/doc/man/man8/lloadd.8 @@ -0,0 +1,249 @@ +.TH LLOADD 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2017-2020 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +lloadd \- LDAP Load Balancer Daemon +.SH SYNOPSIS +.B LIBEXECDIR/lloadd +[\c +.BR \-4 | \-6 ] +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ lloadd-config-file\fR] +[\c +.BI \-h \ URLs\fR] +[\c +.BI \-n \ service-name\fR] +[\c +.BI \-s \ syslog-level\fR] +[\c +.BI \-l \ syslog-local-user\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BI \-r \ directory\fR] +[\c +.BI \-u \ user\fR] +[\c +.BI \-g \ group\fR] +.SH DESCRIPTION +.LP +.B Lloadd +is the stand-alone LDAP daemon. It listens for LDAP connections on +any number of ports (default \fB389\fP), forwarding the LDAP operations +it receives over these connections to be handled by the configured +backends. +.B lloadd +is typically invoked at boot time, usually out of +.BR /etc/rc.local . +Upon startup, +.B lloadd +normally forks and disassociates itself from the invoking tty. +If configured in the config file, the +.B lloadd +process will print its process ID (see +.BR getpid (2)) +to a +.B .pid +file, as well as the command line options during invocation to an +.B .args +file (see +.BR lloadd.conf (5)). +If the +.B \-d +flag is given, even with a zero argument, +.B lloadd +will not fork and disassociate from the invoking tty. +.LP +See the "OpenLDAP Administrator's Guide" for more details on +.BR lloadd . +.SH OPTIONS +.TP +.B \-4 +Listen on IPv4 addresses only. +.TP +.B \-6 +Listen on IPv6 addresses only. +.TP +.BI \-d \ debug-level +Turn on debugging as defined by +.IR debug-level . +If this option is specified, even with a zero argument, +.B lloadd +will not fork or disassociate from the invoking terminal. Some general +operation and status messages are printed for any value of \fIdebug-level\fP. +\fIdebug-level\fP is taken as a bit string, with each bit corresponding to a +different kind of debugging information. See for details. +Comma-separated arrays of friendly names can be specified to select +debugging output of the corresponding debugging information. +All the names recognized by the \fIloglevel\fP directive +described in \fBlloadd.conf\fP(5) are supported. +If \fIdebug-level\fP is \fB?\fP, a list of installed debug-levels is printed, +and lloadd exits. + +Remember that if you turn on packet logging, packets containing bind passwords +will be output, so if you redirect the log to a logfile, that file should +be read-protected. +.TP +.BI \-s \ syslog-level +This option tells +.B lloadd +at what debug-level debugging statements should be logged to the +.BR syslog (8) +facility. +The value \fIsyslog-level\fP can be set to any value or combination +allowed by the \fB\-d\fP switch. +Lloadd logs all messages selected by \fIsyslog-level\fP +at the +.BR syslog (3) +severity debug-level \fBDEBUG\fP, +on the unit specified with \fB\-l\fP. +.TP +.BI \-n \ service-name +Specifies the service name for logging and other purposes. Defaults +to basename of argv[0], i.e.: "lloadd". +.TP +.BI \-l \ syslog-local-user +Selects the local user of the +.BR syslog (8) +facility. Value can be +.BR LOCAL0 , +through +.BR LOCAL7 , +as well as +.B USER +and +.BR DAEMON . +The default is +.BR LOCAL4 . +However, this option is only permitted on systems that support +local users with the +.BR syslog (8) +facility. +Logging to syslog(8) occurs at the "DEBUG" severity debug-level. +.TP +.BI \-f \ lloadd-config-file +Specifies the lloadd configuration file. The default is +.BR ETCDIR/lloadd.conf . +.TP +.BI \-h \ URLlist +.B lloadd +will by default serve +.B ldap:/// +(LDAP over TCP on all interfaces on default LDAP port). That is, +it will bind using INADDR_ANY and port \fB389\fP. +The +.B \-h +option may be used to specify LDAP (and other scheme) URLs to serve. +For example, if lloadd is given +.BR "\-h \(dqldap://127.0.0.1:9009/ ldaps:/// ldapi:///\(dq" , +it will listen on 127.0.0.1:9009 for LDAP, 0.0.0.0:636 for LDAP over TLS, +and LDAP over IPC (Unix domain sockets). Host 0.0.0.0 represents +INADDR_ANY (any interface). +A space separated list of URLs is expected. The URLs should be of +the LDAP, LDAPS, or LDAPI schemes, and generally +without a DN or other optional parameters (excepting as discussed below). +Support for the latter two schemes depends on selected configuration +options. Hosts may be specified by name or IPv4 and IPv6 address formats. +Ports, if specified, must be numeric. The default ldap:// port is \fB389\fP +and the default ldaps:// port is \fB636\fP. + +For LDAP over IPC, +.B name +is the name of the socket, and no +.B port +is required, nor allowed; note that directory separators must be +URL-encoded, like any other characters that are special to URLs; +so the socket + + /usr/local/var/ldapi + +must be specified as + + ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi + +The default location for the IPC socket is LOCALSTATEDIR/run/ldapi +.TP +.BI \-r \ directory +Specifies a directory to become the root directory. lloadd will +change the current working directory to this directory and +then +.BR chroot (2) +to this directory. This is done after opening listeners but before +reading any configuration file or initializing any backend. When +used as a security mechanism, it should be used in conjunction with +.B \-u +and +.B \-g +options. +.TP +.BI \-u \ user +.B lloadd +will run lloadd with the specified user name or id, and that user's +supplementary group access list as set with initgroups(3). The group ID +is also changed to this user's gid, unless the \fB\-g\fP option is used to +override. Note when used with +.BR \-r , +lloadd will use the user database in the change root environment. +.TP +.BI \-g \ group +.B lloadd +will run with the specified group name or id. Note when used with +.BR \-r , +lloadd will use the group database in the change root environment. +.TP +.BI \-o \ option\fR[ = value\fR] +This option provides a generic means to specify options without the need to reserve +a separate letter for them. + +It supports the following options: +.RS +.TP +.BR slp= { on \||\| off \||\| \fIslp-attrs\fP } +When SLP support is compiled into lloadd, disable it (\fBoff\fP), + enable it by registering at SLP DAs without specific SLP attributes (\fBon\fP), +or with specific SLP attributes +.I slp-attrs +that must be an SLP attribute list definition according to the SLP standard. + +For example, \fB"slp=(tree=production),(server-type=OpenLDAP),(server\-version=2.4.15)"\fP +registers at SLP DAs with the three SLP attributes tree, server-type and server-version +that have the values given above. +This allows one to specifically query the SLP DAs for LDAP servers holding the +.I production +tree in case multiple trees are available. +.RE +.SH EXAMPLES +To start +.I lloadd +and have it fork and detach from the terminal and start load-balancing +the LDAP servers defined in the default config file, just type: +.LP +.nf +.ft tt + LIBEXECDIR/lloadd +.ft +.fi +.LP +To start +.B lloadd +with an alternate configuration file, and turn +on voluminous debugging which will be printed on standard error, type: +.LP +.nf +.ft tt + LIBEXECDIR/lloadd \-f /var/tmp/lloadd.conf \-d 255 +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR lloadd.conf (5), +.BR slapd (8). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH BUGS +See http://www.openldap.org/its/ +.SH ACKNOWLEDGEMENTS +.so ../Project