From 5ea77a75dd2d2158401331879f3c8f47940a732c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 18:35:32 +0200 Subject: Adding upstream version 2.5.13+dfsg. Signed-off-by: Daniel Baumann --- doc/man/man5/Makefile.in | 16 + doc/man/man5/ldap.conf.5 | 529 +++++++++ doc/man/man5/ldif.5 | 277 +++++ doc/man/man5/lloadd.conf.5 | 848 ++++++++++++++ doc/man/man5/slapd-asyncmeta.5 | 532 +++++++++ doc/man/man5/slapd-config.5 | 2274 ++++++++++++++++++++++++++++++++++++++ doc/man/man5/slapd-dnssrv.5 | 49 + doc/man/man5/slapd-ldap.5 | 700 ++++++++++++ doc/man/man5/slapd-ldif.5 | 54 + doc/man/man5/slapd-mdb.5 | 241 ++++ doc/man/man5/slapd-meta.5 | 1378 +++++++++++++++++++++++ doc/man/man5/slapd-monitor.5 | 126 +++ doc/man/man5/slapd-ndb.5 | 127 +++ doc/man/man5/slapd-null.5 | 72 ++ doc/man/man5/slapd-passwd.5 | 56 + doc/man/man5/slapd-perl.5 | 199 ++++ doc/man/man5/slapd-relay.5 | 207 ++++ doc/man/man5/slapd-sock.5 | 329 ++++++ doc/man/man5/slapd-sock.5.links | 1 + doc/man/man5/slapd-sql.5 | 699 ++++++++++++ doc/man/man5/slapd-wt.5 | 97 ++ doc/man/man5/slapd.access.5 | 1205 ++++++++++++++++++++ doc/man/man5/slapd.backends.5 | 140 +++ doc/man/man5/slapd.conf.5 | 2140 +++++++++++++++++++++++++++++++++++ doc/man/man5/slapd.overlays.5 | 204 ++++ doc/man/man5/slapd.plugin.5 | 124 +++ doc/man/man5/slapo-accesslog.5 | 514 +++++++++ doc/man/man5/slapo-auditlog.5 | 98 ++ doc/man/man5/slapo-autoca.5 | 120 ++ doc/man/man5/slapo-chain.5 | 152 +++ doc/man/man5/slapo-collect.5 | 52 + doc/man/man5/slapo-constraint.5 | 155 +++ doc/man/man5/slapo-dds.5 | 271 +++++ doc/man/man5/slapo-deref.5 | 80 ++ doc/man/man5/slapo-dyngroup.5 | 58 + doc/man/man5/slapo-dynlist.5 | 275 +++++ doc/man/man5/slapo-homedir.5 | 130 +++ doc/man/man5/slapo-memberof.5 | 145 +++ doc/man/man5/slapo-otp.5 | 138 +++ doc/man/man5/slapo-pbind.5 | 61 + doc/man/man5/slapo-pcache.5 | 327 ++++++ doc/man/man5/slapo-ppolicy.5 | 1060 ++++++++++++++++++ doc/man/man5/slapo-refint.5 | 78 ++ doc/man/man5/slapo-remoteauth.5 | 160 +++ doc/man/man5/slapo-retcode.5 | 257 +++++ doc/man/man5/slapo-rwm.5 | 669 +++++++++++ doc/man/man5/slapo-sssvlv.5 | 57 + doc/man/man5/slapo-syncprov.5 | 81 ++ doc/man/man5/slapo-translucent.5 | 133 +++ doc/man/man5/slapo-unique.5 | 187 ++++ doc/man/man5/slapo-valsort.5 | 97 ++ doc/man/man5/slappw-argon2.5 | 131 +++ 52 files changed, 18110 insertions(+) create mode 100644 doc/man/man5/Makefile.in create mode 100644 doc/man/man5/ldap.conf.5 create mode 100644 doc/man/man5/ldif.5 create mode 100644 doc/man/man5/lloadd.conf.5 create mode 100644 doc/man/man5/slapd-asyncmeta.5 create mode 100644 doc/man/man5/slapd-config.5 create mode 100644 doc/man/man5/slapd-dnssrv.5 create mode 100644 doc/man/man5/slapd-ldap.5 create mode 100644 doc/man/man5/slapd-ldif.5 create mode 100644 doc/man/man5/slapd-mdb.5 create mode 100644 doc/man/man5/slapd-meta.5 create mode 100644 doc/man/man5/slapd-monitor.5 create mode 100644 doc/man/man5/slapd-ndb.5 create mode 100644 doc/man/man5/slapd-null.5 create mode 100644 doc/man/man5/slapd-passwd.5 create mode 100644 doc/man/man5/slapd-perl.5 create mode 100644 doc/man/man5/slapd-relay.5 create mode 100644 doc/man/man5/slapd-sock.5 create mode 100644 doc/man/man5/slapd-sock.5.links create mode 100644 doc/man/man5/slapd-sql.5 create mode 100644 doc/man/man5/slapd-wt.5 create mode 100644 doc/man/man5/slapd.access.5 create mode 100644 doc/man/man5/slapd.backends.5 create mode 100644 doc/man/man5/slapd.conf.5 create mode 100644 doc/man/man5/slapd.overlays.5 create mode 100644 doc/man/man5/slapd.plugin.5 create mode 100644 doc/man/man5/slapo-accesslog.5 create mode 100644 doc/man/man5/slapo-auditlog.5 create mode 100644 doc/man/man5/slapo-autoca.5 create mode 100644 doc/man/man5/slapo-chain.5 create mode 100644 doc/man/man5/slapo-collect.5 create mode 100644 doc/man/man5/slapo-constraint.5 create mode 100644 doc/man/man5/slapo-dds.5 create mode 100644 doc/man/man5/slapo-deref.5 create mode 100644 doc/man/man5/slapo-dyngroup.5 create mode 100644 doc/man/man5/slapo-dynlist.5 create mode 100644 doc/man/man5/slapo-homedir.5 create mode 100644 doc/man/man5/slapo-memberof.5 create mode 100644 doc/man/man5/slapo-otp.5 create mode 100644 doc/man/man5/slapo-pbind.5 create mode 100644 doc/man/man5/slapo-pcache.5 create mode 100644 doc/man/man5/slapo-ppolicy.5 create mode 100644 doc/man/man5/slapo-refint.5 create mode 100644 doc/man/man5/slapo-remoteauth.5 create mode 100644 doc/man/man5/slapo-retcode.5 create mode 100644 doc/man/man5/slapo-rwm.5 create mode 100644 doc/man/man5/slapo-sssvlv.5 create mode 100644 doc/man/man5/slapo-syncprov.5 create mode 100644 doc/man/man5/slapo-translucent.5 create mode 100644 doc/man/man5/slapo-unique.5 create mode 100644 doc/man/man5/slapo-valsort.5 create mode 100644 doc/man/man5/slappw-argon2.5 (limited to 'doc/man/man5') diff --git a/doc/man/man5/Makefile.in b/doc/man/man5/Makefile.in new file mode 100644 index 0000000..edfb106 --- /dev/null +++ b/doc/man/man5/Makefile.in @@ -0,0 +1,16 @@ +# man5 Makefile.in for OpenLDAP +# $OpenLDAP$ +## This work is part of OpenLDAP Software . +## +## Copyright 1998-2022 The OpenLDAP Foundation. +## All rights reserved. +## +## Redistribution and use in source and binary forms, with or without +## modification, are permitted only as authorized by the OpenLDAP +## Public License. +## +## A copy of this license is available in the file LICENSE in the +## top-level directory of the distribution or, alternatively, at +## . + +MANSECT=5 diff --git a/doc/man/man5/ldap.conf.5 b/doc/man/man5/ldap.conf.5 new file mode 100644 index 0000000..df357ab --- /dev/null +++ b/doc/man/man5/ldap.conf.5 @@ -0,0 +1,529 @@ +.TH LDAP.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap.conf, .ldaprc \- LDAP configuration file/environment variables +.SH SYNOPSIS +ETCDIR/ldap.conf, ldaprc, .ldaprc, $LDAP +.SH DESCRIPTION +If the environment variable \fBLDAPNOINIT\fP is defined, all +defaulting is disabled. +.LP +The +.I ldap.conf +configuration file is used to set system-wide defaults to be applied when +running +.I ldap +clients. +.LP +Users may create an optional configuration file, +.I ldaprc +or +.IR .ldaprc , +in their home directory which will be used to override the system-wide +defaults file. +The file +.I ldaprc +in the current working directory is also used. +.LP +.LP +Additional configuration files can be specified using +the \fBLDAPCONF\fP and \fBLDAPRC\fP environment variables. +\fBLDAPCONF\fP may be set to the path of a configuration file. This +path can be absolute or relative to the current working directory. +The \fBLDAPRC\fP, if defined, should be the basename of a file +in the current working directory or in the user's home directory. +.LP +Environmental variables may also be used to augment the file based defaults. +The name of the variable is the option name with an added prefix of \fBLDAP\fP. +For example, to define \fBBASE\fP via the environment, set the variable +\fBLDAPBASE\fP to the desired value. +.LP +Some options are user-only. Such options are ignored if present +in the +.I ldap.conf +(or file specified by +.BR LDAPCONF ). +.LP +Thus the following files and variables are read, in order: +.nf + variable $LDAPNOINIT, and if that is not set: + system file ETCDIR/ldap.conf, + user files $HOME/ldaprc, $HOME/.ldaprc, ./ldaprc, + system file $LDAPCONF, + user files $HOME/$LDAPRC, $HOME/.$LDAPRC, ./$LDAPRC, + variables $LDAP. +.fi +Settings late in the list override earlier ones. +.SH SYNTAX +The configuration options are case-insensitive; +their value, on a case by case basis, may be case-sensitive. +.LP +Blank lines are ignored. +.br +Lines beginning with a hash mark (`#') are comments, and ignored. +.LP +Valid lines are made of an option's name (a sequence of non-blanks, +conventionally written in uppercase, although not required), +followed by a value. +The value starts with the first non-blank character after +the option's name, and terminates at the end of the line, +or at the last sequence of blanks before the end of the line. +The tokenization of the value, if any, is delegated to the handler(s) +for that option, if any. Quoting values that contain blanks +may be incorrect, as the quotes would become part of the value. +For example, + +.nf + # Wrong - erroneous quotes: + URI "ldap:// ldaps://" + + # Right - space-separated list of URIs, without quotes: + URI ldap:// ldaps:// + + # Right - DN syntax needs quoting for Example, Inc: + BASE ou=IT staff,o="Example, Inc",c=US + # or: + BASE ou=IT staff,o=Example\\2C Inc,c=US + + # Wrong - comment on same line as option: + DEREF never # Never follow aliases +.fi +.LP +A line cannot be longer than LINE_MAX, which should be more than 2000 bytes +on all platforms. +There is no mechanism to split a long line on multiple lines, either for +beautification or to overcome the above limit. +.SH OPTIONS +The different configuration options are: +.TP +.B URI +Specifies the URI(s) of an LDAP server(s) to which the +.I LDAP +library should connect. The URI scheme may be any of +.BR ldap , +.B ldaps +or +.BR ldapi , +which refer to LDAP over TCP, LDAP over SSL (TLS) and LDAP +over IPC (UNIX domain sockets), respectively. +Each server's name can be specified as a +domain-style name or an IP address literal. Optionally, the +server's name can followed by a ':' and the port number the LDAP +server is listening on. If no port number is provided, the default +port for the scheme is used (389 for ldap://, 636 for ldaps://). +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 + +A space separated list of URIs may be provided. +.TP +.B BASE +Specifies the default base DN to use when performing ldap operations. +The base must be specified as a Distinguished Name in LDAP format. +.TP +.B BINDDN +Specifies the default bind DN to use when performing ldap operations. +The bind DN must be specified as a Distinguished Name in LDAP format. +.B This is a user-only option. +.TP +.B DEREF +Specifies how alias dereferencing is done when performing a search. The +.B +can be specified as one of the following keywords: +.RS +.TP +.B never +Aliases are never dereferenced. This is the default. +.TP +.B searching +Aliases are dereferenced in subordinates of the base object, but +not in locating the base object of the search. +.TP +.B finding +Aliases are only dereferenced when locating the base object of the search. +.TP +.B always +Aliases are dereferenced both in searching and in locating the base object +of the search. +.RE +.TP +.TP +.B HOST +Specifies the name(s) of an LDAP server(s) to which the +.I LDAP +library should connect. Each server's name can be specified as a +domain-style name or an IP address and optionally followed by a ':' and +the port number the ldap server is listening on. A space separated +list of hosts may be provided. +.B HOST +is deprecated in favor of +.BR URI . +.TP +.B KEEPALIVE_IDLE +Sets/gets the number of seconds a connection needs to remain idle +before TCP starts sending keepalive probes. Linux only. +.TP +.B KEEPALIVE_PROBES +Sets/gets the maximum number of keepalive probes TCP should send +before dropping the connection. Linux only. +.TP +.B KEEPALIVE_INTERVAL +Sets/gets the interval in seconds between individual keepalive probes. +Linux only. +.TP +.B NETWORK_TIMEOUT +Specifies the timeout (in seconds) after which the poll(2)/select(2) +following a connect(2) returns in case of no activity. +.TP +.B PORT +Specifies the default port used when connecting to LDAP servers(s). +The port may be specified as a number. +.B PORT +is deprecated in favor of +.BR URI. +.TP +.B REFERRALS +Specifies if the client should automatically follow referrals returned +by LDAP servers. +The default is on. +Note that the command line tools +.BR ldapsearch (1) +&co always override this option. +.\" This should only be allowed via ldap_set_option(3) +.\".TP +.\".B RESTART +.\"Determines whether the library should implicitly restart connections (FIXME). +.TP +.B SIZELIMIT +Specifies a size limit (number of entries) to use when performing searches. +The number should be a non-negative integer. \fISIZELIMIT\fP of zero (0) +specifies a request for unlimited search size. Please note that the server +may still apply any server-side limit on the amount of entries that can be +returned by a search operation. +.TP +.B SOCKET_BIND_ADDRESSES +Specifies the source bind IP to be used for connecting to target LDAP server. +Multiple IP addresses must be space separated. Only one valid IPv4 +address and/or one valid IPv6 address are allowed in the list. +.TP +.B TIMELIMIT +Specifies a time limit (in seconds) to use when performing searches. +The number should be a non-negative integer. \fITIMELIMIT\fP of zero (0) +specifies unlimited search time to be used. Please note that the server +may still apply any server-side limit on the duration of a search operation. +.TP +.B VERSION {2|3} +Specifies what version of the LDAP protocol should be used. +.TP +.B TIMEOUT +Specifies a timeout (in seconds) after which calls to synchronous LDAP +APIs will abort if no response is received. Also used for any +.BR ldap_result (3) +calls where a NULL timeout parameter is supplied. +.SH SASL OPTIONS +If OpenLDAP is built with Simple Authentication and Security Layer support, +there are more options you can specify. +.TP +.B SASL_MECH +Specifies the SASL mechanism to use. +.TP +.B SASL_REALM +Specifies the SASL realm. +.TP +.B SASL_AUTHCID +Specifies the authentication identity. +.B This is a user-only option. +.TP +.B SASL_AUTHZID +Specifies the proxy authorization identity. +.B This is a user-only option. +.TP +.B SASL_SECPROPS +Specifies Cyrus SASL security properties. The +.B +can be specified as a comma-separated list of the following: +.RS +.TP +.B none +(without any other properties) causes the properties +defaults ("noanonymous,noplain") to be cleared. +.TP +.B noplain +disables mechanisms susceptible to simple passive attacks. +.TP +.B noactive +disables mechanisms susceptible to active attacks. +.TP +.B nodict +disables mechanisms susceptible to passive dictionary attacks. +.TP +.B noanonymous +disables mechanisms which support anonymous login. +.TP +.B forwardsec +requires forward secrecy between sessions. +.TP +.B passcred +requires mechanisms which pass client credentials (and allows +mechanisms which can pass credentials to do so). +.TP +.B minssf= +specifies the minimum acceptable +.I security strength factor +as an integer approximate to effective key length used for +encryption. 0 (zero) implies no protection, 1 implies integrity +protection only, 128 allows RC4, Blowfish and other similar ciphers, +256 will require modern ciphers. The default is 0. +.TP +.B maxssf= +specifies the maximum acceptable +.I security strength factor +as an integer (see +.B minssf +description). The default is +.BR INT_MAX . +.TP +.B maxbufsize= +specifies the maximum security layer receive buffer +size allowed. 0 disables security layers. The default is 65536. +.RE +.TP +.B SASL_NOCANON +Do not perform reverse DNS lookups to canonicalize SASL host names. The default is off. +.TP +.B SASL_CBINDING +The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING. The default is none. +.SH GSSAPI OPTIONS +If OpenLDAP is built with Generic Security Services Application Programming Interface support, +there are more options you can specify. +.TP +.B GSSAPI_SIGN +Specifies if GSSAPI signing (GSS_C_INTEG_FLAG) should be used. +The default is off. +.TP +.B GSSAPI_ENCRYPT +Specifies if GSSAPI encryption (GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG) +should be used. The default is off. +.TP +.B GSSAPI_ALLOW_REMOTE_PRINCIPAL +Specifies if GSSAPI based authentication should try to form the +target principal name out of the ldapServiceName or dnsHostName +attribute of the targets RootDSE entry. The default is off. +.SH TLS OPTIONS +If OpenLDAP is built with Transport Layer Security support, there +are more options you can specify. These options are used when an +.B ldaps:// URI +is selected (by default or otherwise) or when the application +negotiates TLS by issuing the LDAP StartTLS operation. +.TP +.B TLS_CACERT +Specifies the file that contains certificates for all of the Certificate +Authorities the client will recognize. +.TP +.B TLS_CACERTDIR +Specifies the path of a directory that contains Certificate Authority +certificates in separate individual files. The +.B TLS_CACERT +is always used before +.B TLS_CACERTDIR. +.TP +.B TLS_CERT +Specifies the file that contains the client certificate. +.B This is a user-only option. +.TP +.B TLS_ECNAME +Specify the name of the curve(s) to use for Elliptic curve Diffie-Hellman +ephemeral key exchange. This option is only used for OpenSSL. +This option is not used with GnuTLS; the curves may be +chosen in the GnuTLS ciphersuite specification. +.TP +.B TLS_KEY +Specifies the file that contains the private key that matches the certificate +stored in the +.B TLS_CERT +file. Currently, the private key must not be protected with a password, so +it is of critical importance that the key file is protected carefully. +.B This is a user-only option. +.TP +.B TLS_CIPHER_SUITE +Specifies acceptable cipher suite and preference order. + should be a cipher specification for +the TLS library in use (OpenSSL or GnuTLS). +Example: +.RS +.RS +.TP +.I OpenSSL: +TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv2 +.TP +.I GnuTLS: +TLS_CIPHER_SUITE 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 +.RE +.TP +.B TLS_PROTOCOL_MIN [.] +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 + TLS_PROTOCOL_MIN 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 parameter is ignored with GnuTLS. +.TP +.B TLS_RANDFILE +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 parameter is ignored with GnuTLS. +.TP +.B TLS_REQCERT +Specifies what checks to perform on server certificates in a TLS session. +The +.B +can be specified as one of the following keywords: +.RS +.TP +.B never +The client will not request or check any server certificate. +.TP +.B allow +The server certificate is requested. If a bad certificate is provided, it will +be ignored and the session proceeds normally. +.TP +.B try +The server certificate is requested. If a bad certificate is provided, +the session is immediately terminated. +.TP +.B demand | hard +These keywords are equivalent and the same as +.BR try . +This is the default setting. +.RE +.TP +.B TLS_REQSAN +Specifies what checks to perform on the subjectAlternativeName +(SAN) extensions in a server certificate when validating the certificate +name against the specified hostname of the server. The +.B +can be specified as one of the following keywords: +.RS +.TP +.B never +The client will not check any SAN in the certificate. +.TP +.B allow +The SAN is checked against the specified hostname. If a SAN is +present but none match the specified hostname, the SANs are ignored +and the usual check against the certificate DN is used. +This is the default setting. +.TP +.B try +The SAN is checked against the specified hostname. If no SAN is present +in the server certificate, the usual check against the certificate DN +is used. If a SAN is present but doesn't match the specified hostname, +the session is immediately terminated. This setting may be preferred +when a mix of certs with and without SANs are in use. +.TP +.B demand | hard +These keywords are equivalent. The SAN is checked against the specified +hostname. If no SAN is present in the server certificate, or no SANs +match, the session is immediately terminated. This setting should be +used when only certificates with SANs are in use. +.RE +.TP +.B TLS_CRLCHECK +Specifies if the Certificate Revocation List (CRL) of the CA should be +used to verify if the server certificates have not been revoked. This +requires +.B TLS_CACERTDIR +parameter to be set. This parameter is ignored with GnuTLS. +.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 TLS_CRLFILE +Specifies the file containing a Certificate Revocation List to be used +to verify if the server certificates have not been revoked. This +parameter is only supported with GnuTLS. +.SH "ENVIRONMENT VARIABLES" +.TP +LDAPNOINIT +disable all defaulting +.TP +LDAPCONF +path of a configuration file +.TP +LDAPRC +basename of ldaprc file in $HOME or $CWD +.TP +LDAP +Set as from ldap.conf +.SH FILES +.TP +.I ETCDIR/ldap.conf +system-wide ldap configuration file +.TP +.I $HOME/ldaprc, $HOME/.ldaprc +user ldap configuration file +.TP +.I $CWD/ldaprc +local ldap configuration file +.SH "SEE ALSO" +.BR ldap (3), +.BR ldap_set_option (3), +.BR ldap_result (3), +.BR openssl (1), +.BR sasl (3) +.SH AUTHOR +Kurt Zeilenga, The OpenLDAP Project +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/ldif.5 b/doc/man/man5/ldif.5 new file mode 100644 index 0000000..d3fa232 --- /dev/null +++ b/doc/man/man5/ldif.5 @@ -0,0 +1,277 @@ +.TH LDIF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldif \- LDAP Data Interchange Format +.SH DESCRIPTION +The LDAP Data Interchange Format (LDIF) is used to represent LDAP +entries and change records in text form. LDAP tools, such as +.BR ldapadd (1) +and +.BR ldapsearch (1), +read and write LDIF entry +records. +.BR ldapmodify (1) +reads LDIF change records. +.LP +This manual page provides a basic description of LDIF. A +formal specification of LDIF is published in RFC 2849. +.SH ENTRY RECORDS +.LP +LDIF entry records are used to represent directory entries. The basic +form of an entry record is: +.LP +.nf +.ft tt + dn: + : + : + :: + :< + ... +.ft +.fi +.LP +The value may be specified as UTF-8 text or as base64 encoded data, +or a URI may be provided to the location of the attribute value. +.LP +A line may be continued by starting the next line with a single space +or tab, e.g., +.LP +.nf +.ft tt + dn: cn=Barbara J Jensen,dc=exam + ple,dc=com +.ft +.fi +.LP +Lines beginning with a sharp sign ('#') are ignored. +.LP +Multiple attribute values are specified on separate lines, e.g., +.LP +.nf +.ft tt + cn: Barbara J Jensen + cn: Babs Jensen +.ft +.fi +.LP +If an value contains a non-printing character, or begins +with a space or a colon ':', the is followed by a +double colon and the value is encoded in base 64 notation. e.g., +the value " begins with a space" would be encoded like this: +.LP +.nf +.ft tt + cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U= +.ft +.fi +.LP +If the attribute value is located in a file, the is +followed by a ':<' and a file: URI. e.g., the value contained +in the file /tmp/value would be listed like this: +.LP +.nf +.ft tt + cn:< file:///tmp/value +.ft +.fi +Other URI schemes (ftp,http) may be supported as well. +.LP +Multiple entries within the same LDIF file are separated by blank +lines. +.SH ENTRY RECORD EXAMPLE +Here is an example of an LDIF file containing three entries. +.LP +.nf +.ft tt + dn: cn=Barbara J Jensen,dc=example,dc=com + cn: Barbara J Jensen + cn: Babs Jensen + objectclass: person + description:< file:///tmp/babs + sn: Jensen + + dn: cn=Bjorn J Jensen,dc=example,dc=com + cn: Bjorn J Jensen + cn: Bjorn Jensen + objectclass: person + sn: Jensen + + dn: cn=Jennifer J Jensen,dc=example,dc=com + cn: Jennifer J Jensen + cn: Jennifer Jensen + objectclass: person + sn: Jensen + jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD + A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ + ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG + ... +.ft +.fi +.LP +Note that the description in Barbara Jensen's entry is +read from file:///tmp/babs and the jpegPhoto in Jennifer +Jensen's entry is encoded using base 64. +.SH CHANGE RECORDS +LDIF change records are used to represent directory change requests. +Each change record starts with line indicating the distinguished +name of the entry being changed: +.LP +.nf + dn: +.fi +.LP +.nf + changetype: <[modify|add|delete|modrdn]> +.fi +.LP +Finally, the change information itself is given, the format of which +depends on what kind of change was specified above. For a \fIchangetype\fP +of \fImodify\fP, the format is one or more of the following: +.LP +.nf + add: + : + : + ... + \- +.fi +.LP +Or, for a replace modification: +.LP +.nf + replace: + : + : + ... + \- +.fi +.LP +If no \fIattributetype\fP lines are given to replace, +the entire attribute is to be deleted (if present). +.LP +Or, for a delete modification: +.LP +.nf + delete: + : + : + ... + \- +.fi +.LP +If no \fIattributetype\fP lines are given to delete, +the entire attribute is to be deleted. +.LP +For a \fIchangetype\fP of \fIadd\fP, the format is: +.LP +.nf + : + : + ... + : + : +.fi +.LP +For a \fIchangetype\fP of \fImodrdn\fP or \fImoddn\fP, +the format is: +.LP +.nf + newrdn: + deleteoldrdn: 0 | 1 + newsuperior: +.fi +.LP +where a value of 1 for deleteoldrdn means to delete the values +forming the old rdn from the entry, and a value of 0 means to +leave the values as non-distinguished attributes in the entry. +The newsuperior line is optional and, if present, specifies the +new superior to move the entry to. +.LP +For a \fIchangetype\fP of \fIdelete\fP, no additional information +is needed in the record. +.LP +Note that attribute values may be presented using base64 or in +files as described for entry records. Lines in change records +may be continued in the manner described for entry records as +well. +.SH CHANGE RECORD EXAMPLE +The following sample LDIF file contains a change record +of each type of change. +.LP +.nf + dn: cn=Babs Jensen,dc=example,dc=com + changetype: add + objectclass: person + objectclass: extensibleObject + cn: babs + cn: babs jensen + sn: jensen + + dn: cn=Babs Jensen,dc=example,dc=com + changetype: modify + add: givenName + givenName: Barbara + givenName: babs + \- + replace: description + description: the fabulous babs + \- + delete: sn + sn: jensen + \- + + dn: cn=Babs Jensen,dc=example,dc=com + changetype: modrdn + newrdn: cn=Barbara J Jensen + deleteoldrdn: 0 + newsuperior: ou=People,dc=example,dc=com + + dn: cn=Barbara J Jensen,ou=People,dc=example,dc=com + changetype: delete +.fi + +.SH INCLUDE STATEMENT +The LDIF parser has been extended to support an +.B include +statement for referencing other LDIF files. The +.B include +statement must be separated from other records by a blank line. +The referenced file is specified using a file: URI and all of its +contents are incorporated as if they were part of the original +LDIF file. As above, other URI schemes may be supported. For example: +.LP +.nf + dn: dc=example,dc=com + objectclass: domain + dc: example + + include: file:///tmp/example.com.ldif + + dn: dc=example,dc=org + objectclass: domain + dc: example +.fi +This feature is not part of the LDIF specification in RFC 2849 but +is expected to appear in a future revision of this spec. It is supported +by the +.BR ldapadd (1), +.BR ldapmodify (1), +and +.BR slapadd (8) +commands. + +.SH SEE ALSO +.BR ldap (3), +.BR ldapsearch (1), +.BR ldapadd (1), +.BR ldapmodify (1), +.BR slapadd (8), +.BR slapcat (8), +.BR slapd\-ldif (5). +.LP +"LDAP Data Interchange Format," Good, G., RFC 2849. +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/lloadd.conf.5 b/doc/man/man5/lloadd.conf.5 new file mode 100644 index 0000000..53f50ba --- /dev/null +++ b/doc/man/man5/lloadd.conf.5 @@ -0,0 +1,848 @@ +.TH LLOADD.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 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 + backend-server + # subsequent backend definitions + ... +.fi +.LP +As many backend servers may be configured as desired. +.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 SLAPD INTEGRATION +Note that when +.B lloadd +is configured as a +.B slapd +module, any option that shares the same name as an option in +.BR slapd.conf (5), +the +.B slapd +interpretation wins and the +.B lloadd +option mentioned is unavailable through +.BR slapd.conf (5) +directly, instead, it would have to be configured via a dedicated attribute in +cn=config. In particular, unless the +.B TLSShareSlapdCTX +option is set, +.B lloadd +keeps its own TLS context which cannot be configured except +through the dynamic configuration. + +An additional option is available when running as a +.B slapd +module: +.TP +.B listen "" +The URIs the Load Balancer module should listen on. Must not overlap with the +ones that +.B slapd +uses for its own listening sockets. The related +.B cn=config +attribute is +.B olcBkLloadListen +with each URI provided as a separate value. No changes to this attribute made +after the server has started up will take effect until it is restarted. + +.SH GLOBAL CONFIGURATION OPTIONS +Options described in this section apply to all backends. 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). No control is added to the +operation if initiated by a client whose bound identity matches the identity +configured in +.B bindconf +(no normalisation of the DN is attempted). + +If SASL binds are issued by clients and this feature is enabled, backend +servers need to support LDAP Who Am I? extended operation for the Load Balancer +to detect the correct authorization identity. +.\" .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 +.RE +.TP +.B include +Read additional configuration information from the given file before +continuing with the next line of the current file. +.TP +.B io-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. + +If modified after server starts up, a change to this option will not take +effect until the server has been restarted. +.TP +.B logfile +Specify a file for recording lloadd debug messages. By default these messages +only go to stderr, are not recorded anywhere else, and are unrelated to +messages exposed by the +.B loglevel +configuration parameter. 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_client +Specify the maximum LDAP PDU size accepted coming from clients. +The default is 262143. +.TP +.B sockbuf_max_incoming_upstream +Specify the maximum LDAP PDU size accepted coming from upstream +connections. +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. +.TP +.B max_pdus_per_cycle +If set to 0, PDUs are handled by the I/O threads directly, otherwise +a task is queued to be picked up by the thread pool. This task will +process PDUs from the connection until there is no more data to be +read or this limit is reached when the I/O thread can pick it up again. +Very high values have a potential to cause some connections to be +starved in a very high-bandwidth environment. The default is 1000. +.TP +.B client_max_pending +Will cause the load balancer to limit the number unfinished operations for each +client connection. The default is 0, unlimited. +.TP +.B iotimeout +Specify the number of milliseconds to wait before forcibly closing +a connection with an outstanding write. This allows faster recovery from +various network hang conditions. An iotimeout of 0 disables this feature. +The default is 10000. + +.SH TLS OPTIONS +If +.B lloadd +is built with support for Transport Layer Security, there are more options +you can specify. + +.TP +.B TLSShareSlapdCTX { on | off } +If set to no (the default), +.B lloadd +will use its own TLS context (needs to be configured via +.B cn=config +unless +.B lloadd +is run as a standalone daemon). If enabled, the options for +.B slapd +apply instead, since the +.BR slapd 's +TLS context is used then. + +.LP + +The following options are available only when compiled as a standalone daemon. +When compiled as a +.BR slapd (8) +module, the cn=config equivalents need to be used if a separate TLS context for +the module is needed, otherwise use the +.B TLSShareSlapdCTX +option. + +.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 +specifies /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 BACKEND CONFIGURATION +Options in this section describe how the +.B lloadd +connects and authenticates to the backend servers. + +It is assumed all backend servers serve the same data. On startup, the +configured connections are set up and those not dedicated to handle bind +requests are authenticated with the backend using the information in the +.B bindconf +option. The authentication configuration is shared between them. +.TP +.B bindconf +.B [bindmethod=simple|sasl] +.B [binddn=] +.B [saslmech=] +.B [authcid=] +.B [authzid=] +.B [credentials=] +.B [realm=] +.B [secprops=] +.B [timeout=] +.B [network\-timeout=] +.B [tcp\-user\-timeout=] + +Specifies the bind credentials +.B lloadd +uses when setting up its regular connections to all backends. + +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 timeout +parameter indicates how long an operation can be pending a response (result, +search entry, ...) from the server in seconds. Due to how timeouts are +detected, the timeout might not be detected and handled up to +.B timeout +seconds after it happens. + +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. + +Timeout set to 0 means no timeout is in effect and by default, no timeouts are +in effect. + +The +.B tcp\-user\-timeout +parameter, if non-zero, corresponds to the +.B TCP_USER_TIMEOUT +set on the upstream connections, overriding the operating system setting. +Only some systems support the customization of this parameter, it is +ignored otherwise and system-wide settings are used. + +.SH BACKEND OPTIONS + +.TP +.B backend-server +.B uri=ldap[s]://[:port] +.B [retry=] +.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 (default is 5 seconds). + +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 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 + +bindconf + bindmethod=simple + binddn=cn=test + credentials=pass + +backend-server + uri=ldap://ldap1.example.com + numconns=3 + bindconns=2 + retry=5000 + max-pending-ops=5 + conn-max-pending=3 + +backend-server + uri=ldap://ldap2.example.com + 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 LIMITATIONS +Support for proxying SASL Binds is limited to the +.B EXTERNAL +mechanism (and only to extract the DN of a client TLS cerificate if used during +the last renegotiation) and mechanisms that rely neither on connection metadata +(as Kerberos does) nor establish a SASL integrity/confidentialiy layer (again, +some Kerberos mechanisms, +.B DIGEST-MD5 +can negotiate this). + +.SH FILES +.TP +ETCDIR/lloadd.conf +default lloadd configuration file +.SH SEE ALSO +.BR ldap (3), +.BR gnutls\-cli (1), +.BR slapd.conf (5), +.BR tcp (7), +.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/man5/slapd-asyncmeta.5 b/doc/man/man5/slapd-asyncmeta.5 new file mode 100644 index 0000000..743d3ef --- /dev/null +++ b/doc/man/man5/slapd-asyncmeta.5 @@ -0,0 +1,532 @@ +.TH SLAPD-ASYNCMETA 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2016-2022 The OpenLDAP Foundation. +.\" Portions Copyright 2016 Symas Corporation. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.\" + +.SH NAME +slapd\-asyncmeta \- asynchronous metadirectory backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B asyncmeta +backend to +.BR slapd (8) +performs basic LDAP proxying with respect to a set of remote LDAP +servers, called "targets". +The information contained in these servers can be presented as +belonging to a single Directory Information Tree (DIT). + +.LP +A good knowledge of the functionality of the +.BR slapd\-meta(5) +backend is recommended. This backend has been designed as +an asynchronous version of the +.B meta +backend. Unlike +.B meta +, the operation handling threads are no longer pending +on the response from the remote server, thus decreasing the +number of threads necessary to handle the same load. While +.B asyncmeta +maintains the functionality of +.B meta +and has a largely similar codebase, +some changes in operation and some new configuration directives have been +added. Some configuration options, such as +.B conn\-pool\-max , +.B conn\-ttl , +.B single\-conn , +and +.B use\-temporary\-conn +have been removed, as they are no longer relevant. +.LP +.B New connection handling: +.LP + +Unlike +.B meta, +which caches bound connections, the +.B asyncmeta +works with a configured maximum number of connections per target. +For each request redirected to a target, a different connection is selected. +Each connection has a queue, to which the request is added before it is sent to the +remote server, and is removed after the last response for that request is received. + For each new request, the connection with the smallest number of pending requests +is selected, or using round\-robin if the numbers are equal. +.LP +.B Overlays: +.LP +Due to implementation specifics, there is no guarantee that any of the existing OpenLDAP overlays will work with +.B asyncmeta +backend. + +.SH EXAMPLES +Refer to +.B slapd\-meta(5) +for configuration examples. + +.SH CONFIGURATION +These +.B slapd.conf +options apply to the ASYNCMETA backend database. +That is, they must follow a "database asyncmeta" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. + +.SH SPECIAL CONFIGURATION DIRECTIVES +Target configuration starts with the "uri" directive. +All the configuration directives that are not specific to targets +should be defined first for clarity, including those that are common +to all backends. +They are: + +.TP +.B default\-target none +This directive forces the backend to reject all those operations +that must resolve to a single target in case none or multiple +targets are selected. +They include: add, delete, modify, modrdn; compare is not included, as +well as bind since, as they don't alter entries, in case of multiple +matches an attempt is made to perform the operation on any candidate +target, with the constraint that at most one must succeed. +This directive can also be used when processing targets to mark a +specific target as default. + +.TP +.B dncache\-ttl {DISABLED|forever|} +This directive sets the time-to-live of the DN cache. +This caches the target that holds a given DN to speed up target +selection in case multiple targets would result from an uncached +search; forever means cache never expires; disabled means no DN +caching; otherwise a valid ( > 0 ) ttl is required, in the format +illustrated for the +.B idle\-timeout +directive. + +.TP +.B onerr {CONTINUE|report|stop} +This directive allows one to select the behavior in case an error is returned +by one target during a search. +The default, \fBcontinue\fP, consists in continuing the operation, +trying to return as much data as possible. +If the value is set to \fBstop\fP, the search is terminated as soon +as an error is returned by one target, and the error is immediately +propagated to the client. +If the value is set to \fBreport\fP, the search is continued to the end +but, in case at least one target returned an error code, the first +non-success error code is returned. + +.TP +.B max\-timeout\-ops +Specify the number of consecutive timed out requests, +after which the connection will be considered faulty and dropped. + +.TP +.B max\-pending\-ops +The maximum number of pending requests stored in a connection's queue. +The default is 128. When this number is exceeded, +.B LDAP_BUSY +will be returned to the client. + +.TP +.B max\-target\-conns +The maximum number of connections per target. Unlike +.B slapd\-meta(5), +no new connections will be created +once this number is reached. The default value is 255. + +.TP +.B norefs +If +.BR yes , +do not return search reference responses. +By default, they are returned unless request is LDAPv2. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B noundeffilter +If +.BR yes , +return success instead of searching if a filter is undefined or contains +undefined portions. +By default, the search is propagated after replacing undefined portions +with +.BR (!(objectClass=*)) , +which corresponds to the empty result set. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B protocol\-version {0,2,3} +This directive indicates what protocol version must be used to contact +the remote server. +If set to 0 (the default), the proxy uses the same protocol version +used by the client, otherwise the requested protocol is used. +The proxy returns \fIunwillingToPerform\fP if an operation that is +incompatible with the requested protocol is attempted. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B pseudoroot\-bind\-defer {YES|no} +This directive, when set to +.BR yes , +causes the authentication to the remote servers with the pseudo-root +identity (the identity defined in each +.B idassert-bind +directive) to be deferred until actually needed by subsequent operations. +Otherwise, all binds as the rootdn are propagated to the targets. + +.TP +.B quarantine ,[;,[...]] +Turns on quarantine of URIs that returned +.IR LDAP_UNAVAILABLE , +so that an attempt to reconnect only occurs at given intervals instead +of any time a client requests an operation. +The pattern is: retry only after at least +.I interval +seconds elapsed since last attempt, for exactly +.I num +times; then use the next pattern. +If +.I num +for the last pattern is "\fB+\fP", it retries forever; otherwise, +no more retries occur. +This directive must appear before any target specification; +it affects all targets with the same pattern. + +.TP +.B rebind\-as\-user {NO|yes} +If this option is given, the client's bind credentials are remembered +for rebinds, when trying to re-establish a broken connection, +or when chasing a referral, if +.B chase\-referrals +is set to +.IR yes . + +.TP +.B session\-tracking\-request {NO|yes} +Adds session tracking control for all requests. +The client's IP and hostname, and the identity associated to each request, +if known, are sent to the remote server for informational purposes. +This directive is incompatible with setting \fIprotocol\-version\fP to 2. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.SH TARGET SPECIFICATION +Target specification starts with a "uri" directive: + +.TP +.B uri ://[]/ [...] +Identical to +.B meta. +See +.B slapd\-meta(5) +for details. + +.TP +.B acl\-authcDN "" +DN which is used to query the target server for acl checking, +as in the LDAP backend; it is supposed to have read access +on the target server to attributes used on the proxy for acl checking. +There is no risk of giving away such values; they are only used to +check permissions. +.B The acl\-authcDN identity is by no means implicitly used by the proxy +.B when the client connects anonymously. + +.TP +.B acl\-passwd +Password used with the +.B acl\-authcDN +above. + +.TP +.B bind\-timeout +This directive defines the timeout, in microseconds, used when polling +for response after an asynchronous bind connection. See +.B slapd\-meta(5) +for details. + +.TP +.B chase\-referrals {YES|no} +enable/disable automatic referral chasing, which is delegated to the +underlying libldap, with rebinding eventually performed if the +\fBrebind\-as\-user\fP directive is used. The default is to chase referrals. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B client\-pr {accept-unsolicited|DISABLE|} +This feature allows one to use RFC 2696 Paged Results control when performing +search operations with a specific target, +irrespective of the client's request. See +.B slapd\-meta(5) +for details. + +.TP +.B default\-target [] +The "default\-target" directive can also be used during target specification. +With no arguments it marks the current target as the default. +The optional number marks target as the default one, starting +from 1. +Target must be defined. + +.TP +.B filter +This directive allows specifying a +.BR regex (5) +pattern to indicate what search filter terms are actually served by a target. + +In a search request, if the search filter matches the \fIpattern\fP +the target is considered while fulfilling the request; otherwise +the target is ignored. There may be multiple occurrences of +the +.B filter +directive for each target. + +.TP +.B idassert\-authzFrom +if defined, selects what +.I local +identities are authorized to exploit the identity assertion feature. +The string +.B +follows the rules defined for the +.I authzFrom +attribute. +See +.BR slapd.conf (5), +section related to +.BR authz\-policy , +for details on the syntax of this field. + +.HP +.hy 0 +.B idassert\-bind +.B bindmethod=none|simple|sasl [binddn=] [credentials=] +.B [saslmech=] [secprops=] [realm=] +.B [authcId=] [authzId=] +.B [authz={native|proxyauthz}] [mode=] [flags=] +.B [starttls=no|yes|critical] +.B [tls_cert=] +.B [tls_key=] +.B [tls_cacert=] +.B [tls_cacertdir=] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=] +.B [tls_ecname=] +.B [tls_protocol_min=[.]] +.B [tls_crlcheck=none|peer|all] +Allows one to define the parameters of the authentication method that is +internally used by the proxy to authorize connections that are +authenticated by other databases. See +.B slapd\-meta(5) +for details. + +.TP +.B idle\-timeout