diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 16:35:32 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 16:35:32 +0000 |
| commit | 5ea77a75dd2d2158401331879f3c8f47940a732c (patch) | |
| tree | d89dc06e9f4850a900f161e25f84e922c4f86cc8 /doc/man/man5 | |
| parent | Initial commit. (diff) | |
| download | openldap-upstream.tar.xz openldap-upstream.zip | |
Adding upstream version 2.5.13+dfsg.upstream/2.5.13+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/man/man5')
52 files changed, 18110 insertions, 0 deletions
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 <http://www.openldap.org/>. +## +## 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 +## <http://www.OpenLDAP.org/license.html>. + +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<option-name> +.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<uppercase option name>. +.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 <ldap[si]://[name[:port]] ...> +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 <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 <dn> +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 <when> +Specifies how alias dereferencing is done when performing a search. The +.B <when> +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 <name[:port] ...> +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 <integer> +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 <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 <on/true/yes/off/false/no> +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 <on/true/yes/off/false/no> +.\"Determines whether the library should implicitly restart connections (FIXME). +.TP +.B SIZELIMIT <integer> +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 <IP> +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 <integer> +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 <integer> +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 <mechanism> +Specifies the SASL mechanism to use. +.TP +.B SASL_REALM <realm> +Specifies the SASL realm. +.TP +.B SASL_AUTHCID <authcid> +Specifies the authentication identity. +.B This is a user-only option. +.TP +.B SASL_AUTHZID <authcid> +Specifies the proxy authorization identity. +.B This is a user-only option. +.TP +.B SASL_SECPROPS <properties> +Specifies Cyrus SASL security properties. The +.B <properties> +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=<factor> +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=<factor> +specifies the maximum acceptable +.I security strength factor +as an integer (see +.B minssf +description). The default is +.BR INT_MAX . +.TP +.B maxbufsize=<factor> +specifies the maximum security layer receive buffer +size allowed. 0 disables security layers. The default is 65536. +.RE +.TP +.B SASL_NOCANON <on/true/yes/off/false/no> +Do not perform reverse DNS lookups to canonicalize SASL host names. The default is off. +.TP +.B SASL_CBINDING <none/tls-unique/tls-endpoint> +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 <on/true/yes/off/false/no> +Specifies if GSSAPI signing (GSS_C_INTEG_FLAG) should be used. +The default is off. +.TP +.B GSSAPI_ENCRYPT <on/true/yes/off/false/no> +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 <on/true/yes/off/false/no> +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 <filename> +Specifies the file that contains certificates for all of the Certificate +Authorities the client will recognize. +.TP +.B TLS_CACERTDIR <path> +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 <filename> +Specifies the file that contains the client certificate. +.B This is a user-only option. +.TP +.B TLS_ECNAME <name> +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 <filename> +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 <cipher-suite-spec> +Specifies acceptable cipher suite and preference order. +<cipher-suite-spec> 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 <cipher-suite-spec> +.fi + +With GnuTLS the available specs can be found in the manual page of +.BR gnutls\-cli (1) +(see the description of the +option +.BR \-\-priority ). + +In older versions of GnuTLS, where gnutls\-cli does not support the option +\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling: + +.nf + gnutls\-cli \-l +.fi +.RE +.TP +.B TLS_PROTOCOL_MIN <major>[.<minor>] +Specifies minimum SSL/TLS protocol version that will be negotiated. +If the server doesn't support at least that version, +the SSL handshake will fail. +To require TLS 1.x or higher, set this option to 3.(x+1), +e.g., + +.nf + 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 <filename> +Specifies the file to obtain random bits from when /dev/[u]random is +not available. Generally set to the name of the EGD/PRNGD socket. +The environment variable RANDFILE can also be used to specify the filename. +This parameter is ignored with GnuTLS. +.TP +.B TLS_REQCERT <level> +Specifies what checks to perform on server certificates in a TLS session. +The +.B <level> +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 <level> +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 <level> +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 <level> +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 <level> +can be specified as one of the following keywords: +.RS +.TP +.B none +No CRL checks are performed +.TP +.B peer +Check the CRL of the peer certificate +.TP +.B all +Check the CRL for a whole certificate chain +.RE +.TP +.B TLS_CRLFILE <filename> +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<option-name> +Set <option-name> 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: <distinguished name> + <attrdesc>: <attrvalue> + <attrdesc>: <attrvalue> + <attrdesc>:: <base64-encoded-value> + <attrdesc>:< <URL> + ... +.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 <attrtype> 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 <attrtype> 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: <distinguishedname> +.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: <attributetype> + <attrdesc>: <value1> + <attrdesc>: <value2> + ... + \- +.fi +.LP +Or, for a replace modification: +.LP +.nf + replace: <attributetype> + <attrdesc>: <value1> + <attrdesc>: <value2> + ... + \- +.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: <attributetype> + <attrdesc>: <value1> + <attrdesc>: <value2> + ... + \- +.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 + <attrdesc1>: <value1> + <attrdesc1>: <value2> + ... + <attrdescN>: <value1> + <attrdescN>: <value2> +.fi +.LP +For a \fIchangetype\fP of \fImodrdn\fP or \fImoddn\fP, +the format is: +.LP +.nf + newrdn: <newrdn> + deleteoldrdn: 0 | 1 + newsuperior: <DN> +.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 + <global configuration options> + # first backend definition + backend-server <backend 1 definition> + # 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 "<listen URIs>" +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 <filename> +The (absolute) name of a file that will hold the +.B lloadd +server's command line (program name and options). +.TP +.B concurrency <integer> +Specify a desired level of concurrency. Provided to the underlying +thread system as a hint. The default is not to provide any hint. +.\" .TP +.\" .B gentlehup { on | off } +.\" A SIGHUP signal will only cause a 'gentle' shutdown-attempt: +.\" .B Lloadd +.\" will stop listening for new connections, but will not close the +.\" connections to the current clients. Future write operations return +.\" unwilling-to-perform, though. Lloadd terminates when all clients +.\" have closed their connections (if they ever do), or - as before - +.\" if it receives a SIGTERM signal. This can be useful if you wish to +.\" terminate the server and start a new +.\" .B lloadd +.\" server +.\" .B with another database, +.\" without disrupting the currently active clients. +.\" The default is off. You may wish to use +.\" .B idletimeout +.\" along with this option. +.\" .TP +.\" .B idletimeout <integer> +.\" Specify the number of seconds to wait before forcibly closing +.\" an idle client connection. A idletimeout of 0 disables this +.\" feature. The default is 0. You may also want to set the +.\" .B iotimeout +.\" option. +.TP +.B feature <feature> [...] +Switch additional features supported by the LDAP Load Balancer on. +Supported features are: +.RS +.RS +.PD 0 +.TP +.B proxyauthz +when proxying an operation, pass the client's authorized identity using +the proxy authorization control (RFC 4370). 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 <filename> +Read additional configuration information from the given file before +continuing with the next line of the current file. +.TP +.B io-threads <integer> +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 <filename> +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 <integer> [...] +Specify the level at which debugging statements and operation +statistics should be syslogged (currently logged to the +.BR syslogd (8) +LOG_LOCAL4 facility). +They must be considered subsystems rather than increasingly verbose +log levels. +Some messages with higher priority are logged regardless +of the configured loglevel as soon as any logging is configured. +Log levels are additive, and available levels are: +.RS +.RS +.PD 0 +.TP +.B 1 +.B (0x1 trace) +trace function calls +.TP +.B 2 +.B (0x2 packets) +debug packet handling +.TP +.B 4 +.B (0x4 args) +heavy trace debugging (function args) +.TP +.B 8 +.B (0x8 conns) +connection management +.TP +.B 16 +.B (0x10 BER) +print out packets sent and received +.\" .TP +.\" .B 32 +.\" .B (0x20 filter) +.\" search filter processing +.TP +.B 64 +.B (0x40 config) +configuration file processing +.\" .TP +.\" .B 128 +.\" .B (0x80 ACL) +.\" access control list processing +.TP +.B 256 +.B (0x100 stats) +connections, LDAP operations, results (recommended) +.TP +.B 512 +.B (0x200 stats2) +stats log entries sent +.\" .TP +.\" .B 1024 +.\" .B (0x400 shell) +.\" print communication with shell backends +.\" .TP +.\" .B 2048 +.\" .B (0x800 parse) +.\" entry parsing +\".TP +\".B 4096 +\".B (0x1000 cache) +\"caching (unused) +\".TP +\".B 8192 +\".B (0x2000 index) +\"data indexing (unused) +.\" .TP +.\" .B 16384 +.\" .B (0x4000 sync) +.\" LDAPSync replication +.TP +.B 32768 +.B (0x8000 none) +only messages that get logged whatever log level is set +.PD +.RE +The desired log level can be input as a single integer that combines +the (ORed) desired levels, both in decimal or in hexadecimal notation, +as a list of integers (that are ORed internally), +or as a list of the names that are shown between parentheses, such that +.LP +.nf + loglevel 513 + loglevel 0x201 + loglevel 512 1 + loglevel 0x200 0x1 + loglevel stats trace +.fi +.LP +are equivalent. +The keyword +.B any +can be used as a shortcut to enable logging at all levels (equivalent to \-1). +The keyword +.BR none , +or the equivalent integer representation, causes those messages +that are logged regardless of the configured loglevel to be logged. +In fact, if loglevel is set to 0, no logging occurs, +so at least the +.B none +level is required to have high priority messages logged. + +The loglevel defaults to \fBstats\fP. +This level should usually also be included when using other loglevels, to +help analyze the logs. +.RE +.TP +.B pidfile <filename> +The (absolute) name of a file that will hold the +.B lloadd +server's process ID (see +.BR getpid (2)). +.TP +.B sockbuf_max_incoming_client <integer> +Specify the maximum LDAP PDU size accepted coming from clients. +The default is 262143. +.TP +.B sockbuf_max_incoming_upstream <integer> +Specify the maximum LDAP PDU size accepted coming from upstream +connections. +The default is 4194303. +.TP +.B tcp-buffer [listener=<URL>] [{read|write}=]<size> +Specify the size of the TCP buffer. +A global value for both read and write TCP buffers related to any listener +is defined, unless the listener is explicitly specified, +or either the read or write qualifiers are used. +See +.BR tcp (7) +for details. +Note that some OS-es implement automatic TCP buffer tuning. +.TP +.B threads <integer> +Specify the maximum size of the primary thread pool. +The default is 16; the minimum value is 2. +.TP +.B threadqueues <integer> +Specify the number of work queues to use for the primary thread pool. +The default is 1 and this is typically adequate for up to 8 CPU cores. +The value should not exceed the number of CPUs in the system. +.TP +.B max_pdus_per_cycle <integer> +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 <integer> +Will cause the load balancer to limit the number unfinished operations for each +client connection. The default is 0, unlimited. +.TP +.B iotimeout <integer> +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 <cipher-suite-spec> +Permits configuring what ciphers will be accepted and the preference order. +<cipher-suite-spec> should be a cipher specification for the TLS library +in use (OpenSSL, GnuTLS, or Mozilla NSS). +Example: +.RS +.RS +.TP +.I OpenSSL: +TLSCipherSuite HIGH:MEDIUM:+SSLv2 +.TP +.I GnuTLS: +TLSCiphersuite SECURE256:!AES-128-CBC +.RE + +To check what ciphers a given spec selects in OpenSSL, use: + +.nf + openssl ciphers \-v <cipher-suite-spec> +.fi + +With GnuTLS the available specs can be found in the manual page of +.BR gnutls\-cli (1) +(see the description of the +option +.BR \-\-priority ). + +In older versions of GnuTLS, where gnutls\-cli does not support the option +\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling: + +.nf + gnutls\-cli \-l +.fi + +When using Mozilla NSS, the OpenSSL cipher suite specifications are used and +translated into the format used internally by Mozilla NSS. There isn't an easy +way to list the cipher suites from the command line. The authoritative list +is in the source code for Mozilla NSS in the file sslinfo.c in the structure +.nf + static const SSLCipherSuiteInfo suiteInfo[] +.fi +.RE +.TP +.B TLSCACertificateFile <filename> +Specifies the file that contains certificates for all of the Certificate +Authorities that +.B lloadd +will recognize. The certificate for +the CA that signed the server certificate must be included among +these certificates. If the signing CA was not a top-level (root) CA, +certificates for the entire sequence of CA's from the signing CA to +the top-level CA should be present. Multiple certificates are simply +appended to the file; the order is not significant. +.TP +.B TLSCACertificatePath <path> +Specifies the path of a directory that contains Certificate Authority +certificates in separate individual files. Usually only one of this +or the TLSCACertificateFile is used. This directive is not supported +when using GnuTLS. + +When using Mozilla NSS, <path> may contain a Mozilla NSS cert/key +database. If <path> contains a Mozilla NSS cert/key database and +CA cert files, OpenLDAP will use the cert/key database and will +ignore the CA cert files. +.TP +.B TLSCertificateFile <filename> +Specifies the file that contains the +.B lloadd +server certificate. + +When using Mozilla NSS, if using a cert/key database (specified with +TLSCACertificatePath), TLSCertificateFile specifies +the name of the certificate to use: +.nf + TLSCertificateFile Server-Cert +.fi +If using a token other than the internal built in token, specify the +token name first, followed by a colon: +.nf + TLSCertificateFile my hardware device:Server-Cert +.fi +Use certutil \-L to list the certificates by name: +.nf + certutil \-d /path/to/certdbdir \-L +.fi +.TP +.B TLSCertificateKeyFile <filename> +Specifies the file that contains the +.B lloadd +server private key that matches the certificate stored in the +.B TLSCertificateFile +file. Currently, the private key must not be protected with a password, so +it is of critical importance that it is protected carefully. + +When using Mozilla NSS, TLSCertificateKeyFile specifies the name of +a file that contains the password for the key for the certificate specified with +TLSCertificateFile. The modutil command can be used to turn off password +protection for the cert/key database. For example, if TLSCACertificatePath +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 <filename> +This directive specifies the file that contains parameters for Diffie-Hellman +ephemeral key exchange. This is required in order to use a DSA certificate on +the server, or an RSA certificate missing the "key encipherment" key usage. +Note that setting this option may also enable +Anonymous Diffie-Hellman key exchanges in certain non-default cipher suites. +Anonymous key exchanges should generally be avoided since they provide no +actual client or server authentication and provide no protection against +man-in-the-middle attacks. +You should append "!ADH" to your cipher suites to ensure that these suites +are not used. +When using Mozilla NSS these parameters are always generated randomly +so this directive is ignored. +.TP +.B TLSECName <name> +Specify the name of a curve to use for Elliptic curve Diffie-Hellman +ephemeral key exchange. This is required to enable ECDHE algorithms in +OpenSSL. This option is not used with GnuTLS; the curves may be +chosen in the GnuTLS ciphersuite specification. This option is also +ignored for Mozilla NSS. +.TP +.B TLSProtocolMin <major>[.<minor>] +Specifies minimum SSL/TLS protocol version that will be negotiated. +If the server doesn't support at least that version, +the SSL handshake will fail. +To require TLS 1.x or higher, set this option to 3.(x+1), +e.g., + +.nf + TLSProtocolMin 3.2 +.fi + +would require TLS 1.1. +Specifying a minimum that is higher than that supported by the +OpenLDAP implementation will result in it requiring the +highest level that it does support. +This directive is ignored with GnuTLS. +.TP +.B TLSRandFile <filename> +Specifies the file to obtain random bits from when /dev/[u]random +is not available. Generally set to the name of the EGD/PRNGD socket. +The environment variable RANDFILE can also be used to specify the filename. +This directive is ignored with GnuTLS and Mozilla NSS. +.TP +.B TLSVerifyClient <level> +Specifies what checks to perform on client certificates in an +incoming TLS session, if any. +The +.B <level> +can be specified as one of the following keywords: +.RS +.TP +.B never +This is the default. +.B lloadd +will not ask the client for a certificate. +.TP +.B allow +The client certificate is requested. If no certificate is provided, +the session proceeds normally. If a bad certificate is provided, +it will be ignored and the session proceeds normally. +.TP +.B try +The client certificate is requested. If no certificate is provided, +the session proceeds normally. If a bad certificate is provided, +the session is immediately terminated. +.TP +.B demand | hard | true +These keywords are all equivalent, for compatibility reasons. +The client certificate is requested. If no certificate is provided, +or a bad certificate is provided, the session is immediately terminated. +.TP +.B TLSCRLCheck <level> +Specifies if the Certificate Revocation List (CRL) of the CA should be +used to verify if the client certificates have not been revoked. This +requires +.B TLSCACertificatePath +parameter to be set. This directive is ignored with GnuTLS and Mozilla NSS. +.B <level> +can be specified as one of the following keywords: +.RS +.TP +.B none +No CRL checks are performed +.TP +.B peer +Check the CRL of the peer certificate +.TP +.B all +Check the CRL for a whole certificate chain +.RE +.TP +.B TLSCRLFile <filename> +Specifies a file containing a Certificate Revocation List to be used +for verifying that certificates have not been revoked. This directive is +only valid when using GnuTLS and Mozilla NSS. + +.SH 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=<dn>] +.B [saslmech=<mech>] +.B [authcid=<identity>] +.B [authzid=<identity>] +.B [credentials=<passwd>] +.B [realm=<realm>] +.B [secprops=<properties>] +.B [timeout=<seconds>] +.B [network\-timeout=<seconds>] +.B [tcp\-user\-timeout=<milliseconds>] + +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]://<hostname>[:port] +.B [retry=<retry interval in ms>] +.B [keepalive=<idle>:<probes>:<interval>] +.B [starttls=yes|critical] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_crlcheck=none|peer|all] +.B [tls_protocol_min=<major>[.<minor>]] +.B [numconns=<conns>] +.B [bindconns=<conns>] +.B [max-pending-ops=<ops>] +.B [conn-max-pending=<ops>] + +Marks the beginning of a backend definition. + +.B uri +specifies the backend as an LDAP URI. If <port> is not given, the standard +LDAP port number (389 or 636) is used. + +Lloadd will attempt to maintain +.B numconns +active connections and +.\" unless the +.\" .B vc +.\" feature is enabled, +also +.B bindconns +active connections dedicated to handling client bind requests. + +If an error occurs on a working connection, a new connection attempt is +made immediately, if one happens on establishing a new connection to this +backend, lloadd will wait before a new reconnect attempt is made +according to the +.B retry +parameter (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 <oplist> +.\" Specify a whitespace separated list of operations that are restricted. +.\" If defined inside a database specification, restrictions apply only +.\" to that database, otherwise they are global. +.\" Operations can be any of +.\" .BR add , +.\" .BR bind , +.\" .BR compare , +.\" .BR delete , +.\" .BR extended[=<OID>] , +.\" .BR modify , +.\" .BR rename , +.\" .BR search , +.\" or the special pseudo-operations +.\" .B read +.\" and +.\" .BR write , +.\" which respectively summarize read and write operations. +.\" The use of +.\" .I restrict write +.\" is equivalent to +.\" .I readonly on +.\" (see above). +.\" The +.\" .B extended +.\" keyword allows one to indicate the OID of the specific operation +.\" to be restricted. + +.SH EXAMPLES +.LP +Here is a short example of a configuration file: +.LP +.RS +.nf +argsfile LOCALSTATEDIR/run/lloadd.args +pidfile LOCALSTATEDIR/run/lloadd.pid + +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|<ttl>} +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 <number> +Specify the number of consecutive timed out requests, +after which the connection will be considered faulty and dropped. + +.TP +.B max\-pending\-ops <number> +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 <number> +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 <NO|yes> +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 <NO|yes> +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 <interval>,<num>[;<interval>,<num>[...]] +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 <protocol>://[<host>]/<naming context> [...] +Identical to +.B meta. +See +.B slapd\-meta(5) +for details. + +.TP +.B acl\-authcDN "<administrative DN for access control purposes>" +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> +Password used with the +.B acl\-authcDN +above. + +.TP +.B bind\-timeout <microseconds> +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|<size>} +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 [<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 <target> as the default one, starting +from 1. +Target <target> must be defined. + +.TP +.B filter <pattern> +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 <authz-regexp> +if defined, selects what +.I local +identities are authorized to exploit the identity assertion feature. +The string +.B <authz-regexp> +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=<simple DN>] [credentials=<simple password>] +.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>] +.B [authcId=<authentication ID>] [authzId=<authorization ID>] +.B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>] +.B [starttls=no|yes|critical] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_protocol_min=<major>[.<minor>]] +.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 <time> +This directive causes a a persistent connection to be dropped after +it has been idle for the specified time. The connection will be re-created +the next time it is selected for use. A connection is considered idle if no +attempts have been made by the backend to use it to send a request to +the backend server. If there are still pending requests in +its queue, the connection will be dropped after the last +request one has either received a result or has timed out. + +[<d>d][<h>h][<m>m][<s>[s]] + +where <d>, <h>, <m> and <s> are respectively treated as days, hours, +minutes and seconds. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B keepalive <idle>:<probes>:<interval> +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. + +.TP +.B tcp\-user\-timeout <milliseconds> +If non-zero, corresponds to the +.B TCP_USER_TIMEOUT +set on the target 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. + +.TP +.B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}" +This maps object classes and attributes as in the LDAP backend. +See +.BR slapd\-ldap (5). + +.TP +.B network\-timeout <time> +Sets the network timeout value after which +.BR poll (2)/ select (2) +following a +.BR connect (2) +returns in case of no activity while sending an operation to the remote target. +The value is in milliseconds, and it can be specified as for +.BR idle\-timeout . +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B nretries {forever|never|<nretries>} +This directive defines how many times forwarding an operation should be retried +in case of temporary failure in contacting a target. The number of retries +is per operation, so if a bind to the target is necessary first, the remaining +number is decremented. If defined +before any target specification, it applies to all targets (by default, +.BR 3 +times); +the global value can be overridden by redefinitions inside each target +specification. + +.TP +.B rewrite* ... +The rewrite options are identical to the +.B meta +backend. See the +.B REWRITING +section of +.B slapd\-meta(5). + +.TP +.B subtree\-{exclude|include} "<rule>" +This directive allows one to indicate what subtrees are actually served +by a target. See +.B slapd\-meta(5) +for details. + +.TP +.B suffixmassage "<local suffix>" "<remote suffix>" +.B slapd\-asyncmeta +does not support the rewrite engine used by +the LDAP and META backends. +.B suffixmassage +can be used to perform DN suffix rewriting, the same way as the obsoleted suffixmassage directive +previously used by the LDAP backend. + +.TP +.B t\-f\-support {NO|yes|discover} +enable if the remote server supports absolute filters +(see \fIRFC 4526\fP for details). +If set to +.BR discover , +support is detected by reading the remote server's root DSE. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B timeout [<op>=]<val> [...] +This directive allows one to set per-operation timeouts. +Operations can be + +\fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP + +By default, the timeout for all operations is 2 seconds. + +See +.B slapd\-meta(5) +for details. + +.TP +.B tls {none|[try\-]start|[try\-]propagate|ldaps} +B [starttls=no] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_crlcheck=none|peer|all] +.RS +Specify TLS settings regular connections. + +If the first parameter is not "none" then this configures the TLS +settings to be used for regular connections. +The StartTLS extended operation will be used when establishing the +connection unless the URI directive protocol scheme is \fBldaps://\fP. +In that case this keyword may only be set to "ldaps" and the StartTLS +operation will not be used. + +With \fBpropagate\fP, the proxy issues the StartTLS operation only if +the original connection has a TLS layer set up. +The \fBtry\-\fP prefix instructs the proxy to continue operations +if the StartTLS operation failed; its use is \fBnot\fP recommended. + +The TLS settings default to the same as the main slapd TLS settings, +except for +.B tls_reqcert +which defaults to "demand", +.B tls_reqsan +which defaults to "allow", and +.B starttls +which is overshadowed by the first keyword and thus ignored. + +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. +.RE + +.SH SCENARIOS +See +.B slapd\-meta(5) +for configuration scenarios. + +.SH ACLs +ACL behavior is identical to meta. See +.B slapd\-meta(5). + +.SH ACCESS CONTROL +The +.B asyncmeta +backend does not honor all ACL semantics as described in +.BR slapd.access (5). +In general, access checking is delegated to the remote server(s). +Only +.B read (=r) +access to the +.B entry +pseudo-attribute and to the other attribute values of the entries +returned by the +.B search +operation is honored, which is performed by the frontend. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-ldap (5), +.BR slapd\-meta (5), +.BR slapo\-pcache (5), +.BR slapd (8), +.BR regex (7), +.BR re_format (7). +.SH AUTHOR +Nadezhda Ivanova, based on back-meta by Pierangelo Masarati. diff --git a/doc/man/man5/slapd-config.5 b/doc/man/man5/slapd-config.5 new file mode 100644 index 0000000..d402340 --- /dev/null +++ b/doc/man/man5/slapd-config.5 @@ -0,0 +1,2274 @@ +.TH SLAPD-CONFIG 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-config \- configuration backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.d +.SH DESCRIPTION +The +.B config +backend manages all of the configuration information for the +.BR slapd (8) +daemon. This configuration information is also used by the SLAPD tools +.BR slapacl (8), +.BR slapadd (8), +.BR slapauth (8), +.BR slapcat (8), +.BR slapdn (8), +.BR slapindex (8), +.BR slapmodify (8), +and +.BR slaptest (8). +.LP +The +.B config +backend is backward compatible with the older +.BR slapd.conf (5) +file but provides the ability to change the configuration dynamically +at runtime. If slapd is run with only a +.B slapd.conf +file dynamic changes will be allowed but they will not persist across +a server restart. Dynamic changes are only saved when slapd is running +from a +.B slapd.d +configuration directory. +.LP + +Unlike other backends, there can only be one instance of the +.B config +backend, and most of its structure is predefined. The root of the +database is hardcoded to +.B "cn=config" +and this root entry contains +global settings for slapd. Multiple child entries underneath the +root entry are used to carry various other settings: +.RS +.TP +.B cn=Module +dynamically loaded modules +.TP +.B cn=Schema +schema definitions +.TP +.B olcBackend=xxx +backend-specific settings +.TP +.B olcDatabase=xxx +database-specific settings +.RE + +The +.B cn=Module +entries will only appear in configurations where slapd +was built with support for dynamically loaded modules. There can be +multiple entries, one for each configured module path. Within each +entry there will be values recorded for each module loaded on a +given path. These entries have no children. + +The +.B cn=Schema +entry contains all of the hardcoded schema elements. +The children of this entry contain all user-defined schema elements. +In schema that were loaded from include files, the child entry will +be named after the include file from which the schema was loaded. +Typically the first child in this subtree will be +.BR cn=core,cn=schema,cn=config . + +.B olcBackend +entries are for storing settings specific to a single +backend type (and thus global to all database instances of that type). +At present, only back-mdb implements any options of this type, so this +setting is not needed for any other backends. + +.B olcDatabase +entries store settings specific to a single database +instance. These entries may have +.B olcOverlay +child entries corresponding +to any overlays configured on the database. The olcDatabase and +olcOverlay entries may also have miscellaneous child entries for +other settings as needed. There are two special database entries +that are predefined \- one is an entry for the config database itself, +and the other is for the "frontend" database. Settings in the +frontend database are inherited by the other databases, unless +they are explicitly overridden in a specific database. +.LP +The specific configuration options available are discussed below in the +Global Configuration Options, General Backend Options, and General Database +Options. Options are set by defining LDAP attributes with specific values. +In general the names of the LDAP attributes are the same as the corresponding +.B slapd.conf +keyword, with an "olc" prefix added on. + +The parser for many of these attributes is the same as used for parsing +the slapd.conf keywords. As such, slapd.conf keywords that allow multiple +items to be specified on one line, separated by whitespace, will allow +multiple items to be specified in one attribute value. However, when +reading the attribute via LDAP, the items will be returned as individual +attribute values. + +Backend-specific options are discussed in the +.B slapd\-<backend>(5) +manual pages. Refer to the "OpenLDAP Administrator's Guide" for more +details on configuring slapd. +.SH GLOBAL CONFIGURATION OPTIONS +Options described in this section apply to the server as a whole. +Arguments that should be replaced by +actual text are shown in brackets <>. + +These options may only be specified in the +.B cn=config +entry. This entry must have an objectClass of +.BR olcGlobal . + +.TP +.B olcAllows: <features> +Specify a set of features to allow (default none). +.B bind_v2 +allows acceptance of LDAPv2 bind requests. Note that +.BR slapd (8) +does not truly implement LDAPv2 (RFC 1777), now Historic (RFC 3494). +.B bind_anon_cred +allows anonymous bind when credentials are not empty (e.g. +when DN is empty). +.B bind_anon_dn +allows unauthenticated (anonymous) bind when DN is not empty. +.B update_anon +allows unauthenticated (anonymous) update operations to be processed +(subject to access controls and other administrative limits). +.B proxy_authz_anon +allows unauthenticated (anonymous) proxy authorization control to be processed +(subject to access controls, authorization and other administrative limits). +.TP +.B olcArgsFile: <filename> +The (absolute) name of a file that will hold the +.B slapd +server's command line (program name and options). +.TP +.B olcAttributeOptions: <option-name>... +Define tagging attribute options or option tag/range prefixes. +Options must not end with `\-', prefixes must end with `\-'. +The `lang\-' prefix is predefined. +If you use the +.B olcAttributeOptions +directive, `lang\-' will no longer be defined and you must specify it +explicitly if you want it defined. + +An attribute description with a tagging option is a subtype of that +attribute description without the option. +Except for that, options defined this way have no special semantics. +Prefixes defined this way work like the `lang\-' options: +They define a prefix for tagging options starting with the prefix. +That is, if you define the prefix `x\-foo\-', you can use the option +`x\-foo\-bar'. +Furthermore, in a search or compare, a prefix or range name (with +a trailing `\-') matches all options starting with that name, as well +as the option with the range name sans the trailing `\-'. +That is, `x\-foo\-bar\-' matches `x\-foo\-bar' and `x\-foo\-bar\-baz'. + +RFC 4520 reserves options beginning with `x\-' for private experiments. +Other options should be registered with IANA, see RFC 4520 section 3.5. +OpenLDAP also has the `binary' option built in, but this is a transfer +option, not a tagging option. +.TP +.B olcAuthIDRewrite: <rewrite\-rule> +Used by the authentication framework to convert simple user names +to an LDAP DN used for authorization purposes. +Its purpose is analogous to that of +.BR olcAuthzRegexp +(see below). +The +.B rewrite\-rule +is a set of rules analogous to those described in +.BR slapo\-rwm (5) +for data rewriting (after stripping the \fIrwm\-\fP prefix). +.B olcAuthIDRewrite +and +.B olcAuthzRegexp +should not be intermixed. +.TP +.B olcAuthzPolicy: <policy> +Used to specify which rules to use for Proxy Authorization. Proxy +authorization allows a client to authenticate to the server using one +user's credentials, but specify a different identity to use for authorization +and access control purposes. It essentially allows user A to login as user +B, using user A's password. +The +.B none +flag disables proxy authorization. This is the default setting. +The +.B from +flag will use rules in the +.I authzFrom +attribute of the authorization DN. +The +.B to +flag will use rules in the +.I authzTo +attribute of the authentication DN. +The +.B any +flag, an alias for the deprecated value of +.BR both , +will allow any of the above, whatever succeeds first (checked in +.BR to , +.B from +sequence. +The +.B all +flag requires both authorizations to succeed. +.LP +.RS +The rules are mechanisms to specify which identities are allowed +to perform proxy authorization. +The +.I authzFrom +attribute in an entry specifies which other users +are allowed to proxy login to this entry. The +.I authzTo +attribute in +an entry specifies which other users this user can authorize as. Use of +.I authzTo +rules can be easily +abused if users are allowed to write arbitrary values to this attribute. +In general the +.I authzTo +attribute must be protected with ACLs such that +only privileged users can modify it. +The value of +.I authzFrom +and +.I authzTo +describes an +.B identity +or a set of identities; it can take five forms: +.RS +.TP +.B ldap:///<base>??[<scope>]?<filter> +.RE +.RS +.B dn[.<dnstyle>]:<pattern> +.RE +.RS +.B u[.<mech>[<realm>]]:<pattern> +.RE +.RS +.B group[/objectClass[/attributeType]]:<pattern> +.RE +.RS +.B <pattern> +.RE +.RS + +.B <dnstyle>:={exact|onelevel|children|subtree|regex} + +.RE +The first form is a valid LDAP +.B URI +where the +.IR <host>:<port> , +the +.I <attrs> +and the +.I <extensions> +portions must be absent, so that the search occurs locally on either +.I authzFrom +or +.IR authzTo . + +.LP +The second form is a +.BR DN , +with the optional style modifiers +.IR exact , +.IR onelevel , +.IR children , +and +.I subtree +for exact, onelevel, children and subtree matches, which cause +.I <pattern> +to be normalized according to the DN normalization rules, or the special +.I regex +style, which causes the +.I <pattern> +to be treated as a POSIX (''extended'') regular expression, as +discussed in +.BR regex (7) +and/or +.BR re_format (7). +A pattern of +.I * +means any non-anonymous DN. + +.LP +The third form is a SASL +.BR id , +with the optional fields +.I <mech> +and +.I <realm> +that allow to specify a SASL +.BR mechanism , +and eventually a SASL +.BR realm , +for those mechanisms that support one. +The need to allow the specification of a mechanism is still debated, +and users are strongly discouraged to rely on this possibility. + +.LP +The fourth form is a group specification. +It consists of the keyword +.BR group , +optionally followed by the specification of the group +.B objectClass +and +.BR attributeType . +The +.B objectClass +defaults to +.IR groupOfNames . +The +.B attributeType +defaults to +.IR member . +The group with DN +.B <pattern> +is searched with base scope, filtered on the specified +.BR objectClass . +The values of the resulting +.B attributeType +are searched for the asserted DN. + +.LP +The fifth form is provided for backwards compatibility. If no identity +type is provided, i.e. only +.B <pattern> +is present, an +.I exact DN +is assumed; as a consequence, +.B <pattern> +is subjected to DN normalization. + +.LP +Since the interpretation of +.I authzFrom +and +.I authzTo +can impact security, users are strongly encouraged +to explicitly set the type of identity specification that is being used. +A subset of these rules can be used as third arg in the +.B olcAuthzRegexp +statement (see below); significantly, the +.IR URI , +provided it results in exactly one entry, +and the +.I dn.exact:<dn> +forms. +.RE +.TP +.B olcAuthzRegexp: <match> <replace> +Used by the authentication framework to convert simple user names, +such as provided by SASL subsystem, or extracted from certificates +in case of cert-based SASL EXTERNAL, or provided within the RFC 4370 +"proxied authorization" control, to an LDAP DN used for +authorization purposes. Note that the resulting DN need not refer +to an existing entry to be considered valid. When an authorization +request is received from the SASL subsystem, the SASL +.BR USERNAME , +.BR REALM , +and +.B MECHANISM +are taken, when available, and combined into a name of the form +.RS +.RS +.TP +.B UID=<username>[[,CN=<realm>],CN=<mechanism>],CN=auth + +.RE +This name is then compared against the +.B match +POSIX (''extended'') regular expression, and if the match is successful, +the name is replaced with the +.B replace +string. If there are wildcard strings in the +.B match +regular expression that are enclosed in parenthesis, e.g. +.RS +.TP +.B UID=([^,]*),CN=.* + +.RE +then the portion of the name that matched the wildcard will be stored +in the numbered placeholder variable $1. If there are other wildcard strings +in parenthesis, the matching strings will be in $2, $3, etc. up to $9. The +placeholders can then be used in the +.B replace +string, e.g. +.RS +.TP +.B UID=$1,OU=Accounts,DC=example,DC=com + +.RE +The replaced name can be either a DN, i.e. a string prefixed by "dn:", +or an LDAP URI. +If the latter, the server will use the URI to search its own database(s) +and, if the search returns exactly one entry, the name is +replaced by the DN of that entry. The LDAP URI must have no +hostport, attrs, or extensions components, but the filter is mandatory, +e.g. +.RS +.TP +.B ldap:///OU=Accounts,DC=example,DC=com??one?(UID=$1) + +.RE +The protocol portion of the URI must be strictly +.BR ldap . +Note that this search is subject to access controls. Specifically, +the authentication identity must have "auth" access in the subject. + +Multiple +.B olcAuthzRegexp +values can be specified to allow for multiple matching +and replacement patterns. The matching patterns are checked in the order they +appear in the attribute, stopping at the first successful match. + +.\".B Caution: +.\"Because the plus sign + is a character recognized by the regular expression engine, +.\"and it will appear in names that include a REALM, be careful to escape the +.\"plus sign with a backslash \\+ to remove the character's special meaning. +.RE +.TP +.B olcConcurrency: <integer> +Specify a desired level of concurrency. Provided to the underlying +thread system as a hint. The default is not to provide any hint. This setting +is only meaningful on some platforms where there is not a one to one +correspondence between user threads and kernel threads. +.TP +.B olcConnMaxPending: <integer> +Specify the maximum number of pending requests for an anonymous session. +If requests are submitted faster than the server can process them, they +will be queued up to this limit. If the limit is exceeded, the session +is closed. The default is 100. +.TP +.B olcConnMaxPendingAuth: <integer> +Specify the maximum number of pending requests for an authenticated session. +The default is 1000. +.TP +.B olcDisallows: <features> +Specify a set of features to disallow (default none). +.B bind_anon +disables acceptance of anonymous bind requests. Note that this setting +does not prohibit anonymous directory access (See "require authc"). +.B bind_simple +disables simple (bind) authentication. +.B tls_2_anon +disables forcing session to anonymous status (see also +.BR tls_authc ) +upon StartTLS operation receipt. +.B tls_authc +disallows the StartTLS operation if authenticated (see also +.BR tls_2_anon ). +.B proxy_authz_non_critical +disables acceptance of the proxied authorization control (RFC4370) +with criticality set to FALSE. +.B dontusecopy_non_critical +disables acceptance of the dontUseCopy control (a work in progress) +with criticality set to FALSE. +.TP +.B olcGentleHUP: { TRUE | FALSE } +A SIGHUP signal will only cause a 'gentle' shutdown-attempt: +.B Slapd +will stop listening for new connections, but will not close the +connections to the current clients. Future write operations return +unwilling-to-perform, though. Slapd 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 slapd +server +.B with another database, +without disrupting the currently active clients. +The default is FALSE. You may wish to use +.B olcIdleTimeout +along with this option. +.TP +.B olcIdleTimeout: <integer> +Specify the number of seconds to wait before forcibly closing +an idle client connection. A setting of 0 disables this +feature. The default is 0. You may also want to set the +.B olcWriteTimeout +option. +.TP +.B olcIndexHash64: { on | off } +Use a 64 bit hash for indexing. The default is to use 32 bit hashes. +These hashes are used for equality and substring indexing. The 64 bit +version may be needed to avoid index collisions when the number of +indexed values exceeds ~64 million. (Note that substring indexing +generates multiple index values per actual attribute value.) +Indices generated with 32 bit hashes are incompatible with the 64 bit +version, and vice versa. Any existing databases must be fully reloaded +when changing this setting. This directive is only supported on 64 bit CPUs. +.TP +.B olcIndexIntLen: <integer> +Specify the key length for ordered integer indices. The most significant +bytes of the binary integer will be used for index keys. The default +value is 4, which provides exact indexing for 31 bit values. +A floating point representation is used to index too large values. +.TP +.B olcIndexSubstrIfMaxlen: <integer> +Specify the maximum length for subinitial and subfinal indices. Only +this many characters of an attribute value will be processed by the +indexing functions; any excess characters are ignored. The default is 4. +.TP +.B olcIndexSubstrIfMinlen: <integer> +Specify the minimum length for subinitial and subfinal indices. An +attribute value must have at least this many characters in order to be +processed by the indexing functions. The default is 2. +.TP +.B olcIndexSubstrAnyLen: <integer> +Specify the length used for subany indices. An attribute value must have +at least this many characters in order to be processed. Attribute values +longer than this length will be processed in segments of this length. The +default is 4. The subany index will also be used in subinitial and +subfinal index lookups when the filter string is longer than the +.I olcIndexSubstrIfMaxlen +value. +.TP +.B olcIndexSubstrAnyStep: <integer> +Specify the steps used in subany index lookups. This value sets the offset +for the segments of a filter string that are processed for a subany index +lookup. The default is 2. For example, with the default values, a search +using this filter "cn=*abcdefgh*" would generate index lookups for +"abcd", "cdef", and "efgh". + +.LP +Note: Indexing support depends on the particular backend in use. Also, +changing these settings will generally require deleting any indices that +depend on these parameters and recreating them with +.BR slapindex (8). + +.TP +.B olcListenerThreads: <integer> +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 olcLocalSSF: <SSF> +Specifies the Security Strength Factor (SSF) to be given local LDAP sessions, +such as those to the ldapi:// listener. For a description of SSF values, +see +.BR olcSaslSecProps 's +.B minssf +option description. The default is 71. +.TP +.B olcLogFile: <filename> +Specify a file for recording slapd 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 olcLogLevel: <integer> [...] +Specify the level at which debugging statements and operation +statistics should be syslogged (currently logged to the +.BR syslogd (8) +LOG_LOCAL4 facility). +They must be considered subsystems rather than increasingly verbose +log levels. +Some messages with higher priority are logged regardless +of the configured loglevel as soon as any logging is configured. +Log levels are additive, and available levels are: +.RS +.RS +.PD 0 +.TP +.B 1 +.B (0x1 trace) +trace function calls +.TP +.B 2 +.B (0x2 packets) +debug packet handling +.TP +.B 4 +.B (0x4 args) +heavy trace debugging (function args) +.TP +.B 8 +.B (0x8 conns) +connection management +.TP +.B 16 +.B (0x10 BER) +print out packets sent and received +.TP +.B 32 +.B (0x20 filter) +search filter processing +.TP +.B 64 +.B (0x40 config) +configuration file processing +.TP +.B 128 +.B (0x80 ACL) +access control list processing +.TP +.B 256 +.B (0x100 stats) +connections, LDAP operations, results (recommended) +.TP +.B 512 +.B (0x200 stats2) +stats2 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 parenthesis, such that +.LP +.nf + olcLogLevel: 129 + olcLogLevel: 0x81 + olcLogLevel: 128 1 + olcLogLevel: 0x80 0x1 + olcLogLevel: acl 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 olcLogLevel to be logged. +In fact, if no olcLogLevel (or a 0 level) is defined, no logging occurs, +so at least the +.B none +level is required to have high priority messages logged. + +Note that the +.BR packets , +.BR BER , +and +.B parse +levels are only available as debug output on stderr, and are not +sent to syslog. + +This setting defaults to \fBstats\fP. +This level should usually also be included when using other loglevels, to +help analyze the logs. +.RE +.TP +.B olcMaxFilterDepth: <integer> +Specify the maximum depth of nested filters in search requests. +The default is 1000. +.TP +.B olcPasswordCryptSaltFormat: <format> +Specify the format of the salt passed to +.BR crypt (3) +when generating {CRYPT} passwords (see +.BR olcPasswordHash ) +during processing of LDAP Password Modify Extended Operations (RFC 3062). + +This string needs to be in +.BR sprintf (3) +format and may include one (and only one) %s conversion. +This conversion will be substituted with a string of random +characters from [A\-Za\-z0\-9./]. For example, "%.2s" +provides a two character salt and "$1$%.8s" tells some +versions of crypt(3) to use an MD5 algorithm and provides +8 random characters of salt. The default is "%s", which +provides 31 characters of salt. +.TP +.B olcPidFile: <filename> +The (absolute) name of a file that will hold the +.B slapd +server's process ID (see +.BR getpid (2)). +.TP +.B olcPluginLogFile: <filename> +The ( absolute ) name of a file that will contain log +messages from +.B SLAPI +plugins. See +.BR slapd.plugin (5) +for details. +.TP +.B olcReferral: <url> +Specify the referral to pass back when +.BR slapd (8) +cannot find a local database to handle a request. +If multiple values are specified, each url is provided. +.TP +.B olcReverseLookup: TRUE | FALSE +Enable/disable client name unverified reverse lookup (default is +.BR FALSE +if compiled with \-\-enable\-rlookups). +.TP +.B olcRootDSE: <file> +Specify the name of an LDIF(5) file containing user defined attributes +for the root DSE. These attributes are returned in addition to the +attributes normally produced by slapd. + +The root DSE is an entry with information about the server and its +capabilities, in operational attributes. +It has the empty DN, and can be read with e.g.: +.ti +4 +ldapsearch \-x \-b "" \-s base "+" +.br +See RFC 4512 section 5.1 for details. +.TP +.B olcSaslAuxprops: <plugin> [...] +Specify which auxprop plugins to use for authentication lookups. The +default is empty, which just uses slapd's internal support. Usually +no other auxprop plugins are needed. +.TP +.B olcSaslAuxpropsDontUseCopy: <attr> [...] +Specify which attribute(s) should be subject to the don't use copy control. This +is necessary for some SASL mechanisms such as OTP to work in a replicated +environment. The attribute "cmusaslsecretOTP" is the default value. +.TP +.B olcSaslAuxpropsDontUseCopyIgnore TRUE | FALSE +Used to disable replication of the attribute(s) defined by +olcSaslAuxpropsDontUseCopy and instead use a local value for the attribute. This +allows the SASL mechanism to continue to work if the provider is offline. This can +cause replication inconsistency. Defaults to FALSE. +.TP +.B olcSaslHost: <fqdn> +Used to specify the fully qualified domain name used for SASL processing. +.TP +.B olcSaslRealm: <realm> +Specify SASL realm. Default is empty. +.TP +.B olcSaslCbinding: none | tls-unique | tls-endpoint +Specify the channel-binding type, see also LDAP_OPT_X_SASL_CBINDING. +Default is none. +.TP +.B olcSaslSecProps: <properties> +Used to specify Cyrus SASL security properties. +The +.B none +flag (without any other properties) causes the flag properties +default, "noanonymous,noplain", to be cleared. +The +.B noplain +flag disables mechanisms susceptible to simple passive attacks. +The +.B noactive +flag disables mechanisms susceptible to active attacks. +The +.B nodict +flag disables mechanisms susceptible to passive dictionary attacks. +The +.B noanonymous +flag disables mechanisms which support anonymous login. +The +.B forwardsec +flag require forward secrecy between sessions. +The +.B passcred +require mechanisms which pass client credentials (and allow +mechanisms which can pass credentials to do so). +The +.B minssf=<factor> +property 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. +The +.B maxssf=<factor> +property specifies the maximum acceptable +.I security strength factor +as an integer (see minssf description). The default is INT_MAX. +The +.B maxbufsize=<size> +property specifies the maximum security layer receive buffer +size allowed. 0 disables security layers. The default is 65536. +.TP +.B olcServerID: <integer> [<URL>] +Specify an integer ID from 0 to 4095 for this server. The ID may also be +specified as a hexadecimal ID by prefixing the value with "0x". +Non-zero IDs are required when using multi-provider replication and each +provider must have a unique non-zero ID. Note that this requirement also +applies to separate providers contributing to a glued set of databases. +If the URL is provided, this directive may be specified +multiple times, providing a complete list of participating servers +and their IDs. The fully qualified hostname of each server should be +used in the supplied URLs. The IDs are used in the "replica id" field +of all CSNs generated by the specified server. The default value is zero, which +is only valid for single provider replication. +Example: +.LP +.nf + olcServerID: 1 ldap://ldap1.example.com + olcServerID: 2 ldap://ldap2.example.com +.fi +.TP +.B olcSockbufMaxIncoming: <integer> +Specify the maximum incoming LDAP PDU size for anonymous sessions. +The default is 262143. +.TP +.B olcSockbufMaxIncomingAuth: <integer> +Specify the maximum incoming LDAP PDU size for authenticated sessions. +The default is 4194303. +.TP +.B olcTCPBuffer [listener=<URL>] [{read|write}=]<size> +Specify the size of the TCP buffer. +A global value for both read and write TCP buffers related to any listener +is defined, unless the listener is explicitly specified, +or either the read or write qualifiers are used. +See +.BR tcp (7) +for details. +Note that some OS-es implement automatic TCP buffer tuning. +.TP +.B olcThreads: <integer> +Specify the maximum size of the primary thread pool. +The default is 16; the minimum value is 2. +.TP +.B olcThreadQueues: <integer> +Specify the number of work queues to use for the primary thread pool. +The default is 1 and this is typically adequate for up to 8 CPU cores. +The value should not exceed the number of CPUs in the system. +.TP +.B olcToolThreads: <integer> +Specify the maximum number of threads to use in tool mode. +This should not be greater than the number of CPUs in the system. +The default is 1. +.TP +.B olcWriteTimeout: <integer> +Specify the number of seconds to wait before forcibly closing +a connection with an outstanding write. This allows recovery from +various network hang conditions. A setting of 0 disables this +feature. The default is 0. +.SH TLS OPTIONS +If +.B slapd +is built with support for Transport Layer Security, there are more options +you can specify. +.TP +.B olcTLSCipherSuite: <cipher-suite-spec> +Permits configuring what ciphers will be accepted and the preference order. +<cipher-suite-spec> should be a cipher specification for the TLS library +in use (OpenSSL or GnuTLS). +Example: +.RS +.RS +.TP +.I OpenSSL: +olcTLSCipherSuite: HIGH:MEDIUM:+SSLv2 +.TP +.I GnuTLS: +olcTLSCiphersuite: SECURE256:!AES-128-CBC +.RE + +To check what ciphers a given spec selects in OpenSSL, use: + +.nf + openssl ciphers \-v <cipher-suite-spec> +.fi + +With GnuTLS the available specs can be found in the manual page of +.BR gnutls\-cli (1) +(see the description of the +option +.BR \-\-priority ). + +In older versions of GnuTLS, where gnutls\-cli does not support the option +\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling: + +.nf + gnutls\-cli \-l +.fi +.RE +.TP +.B olcTLSCACertificateFile: <filename> +Specifies the file that contains certificates for all of the Certificate +Authorities that +.B slapd +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 olcTLSCACertificatePath: <path> +Specifies the path of a directory that contains Certificate Authority +certificates in separate individual files. Usually only one of this +or the olcTLSCACertificateFile is defined. If both are specified, both +locations will be used. +.TP +.B olcTLSCertificateFile: <filename> +Specifies the file that contains the +.B slapd +server certificate. + +When using OpenSSL that file may also contain any number of intermediate +certificates after the server certificate. +.TP +.B olcTLSCertificateKeyFile: <filename> +Specifies the file that contains the +.B slapd +server private key that matches the certificate stored in the +.B olcTLSCertificateFile +file. If the private key is protected with a password, the password must +be manually typed in when slapd starts. Usually the private key is not +protected with a password, to allow slapd to start without manual +intervention, so +it is of critical importance that the file is protected carefully. +.TP +.B olcTLSDHParamFile: <filename> +This directive specifies the file that contains parameters for Diffie-Hellman +ephemeral key exchange. This is required in order to use a DSA certificate on +the server, or an RSA certificate missing the "key encipherment" key usage. +Note that setting this option may also enable +Anonymous Diffie-Hellman key exchanges in certain non-default cipher suites. +Anonymous key exchanges should generally be avoided since they provide no +actual client or server authentication and provide no protection against +man-in-the-middle attacks. +You should append "!ADH" to your cipher suites to ensure that these suites +are not used. +.TP +.B olcTLSECName: <name> +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 olcTLSProtocolMin: <major>[.<minor>] +Specifies minimum SSL/TLS protocol version that will be negotiated. +If the server doesn't support at least that version, +the SSL handshake will fail. +To require TLS 1.x or higher, set this option to 3.(x+1), +e.g., + +.nf + olcTLSProtocolMin: 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 olcTLSRandFile: <filename> +Specifies the file to obtain random bits from when /dev/[u]random +is not available. Generally set to the name of the EGD/PRNGD socket. +The environment variable RANDFILE can also be used to specify the filename. +This directive is ignored with GnuTLS. +.TP +.B olcTLSVerifyClient: <level> +Specifies what checks to perform on client certificates in an +incoming TLS session, if any. +The +.B <level> +can be specified as one of the following keywords: +.RS +.TP +.B never +This is the default. +.B slapd +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. + +Note that a valid client certificate is required in order to use the +SASL EXTERNAL authentication mechanism with a TLS session. As such, +a non-default +.B olcTLSVerifyClient +setting must be chosen to enable SASL EXTERNAL authentication. +.RE +.TP +.B olcTLSCRLCheck: <level> +Specifies if the Certificate Revocation List (CRL) of the CA should be +used to verify if the client certificates have not been revoked. This +requires +.B olcTLSCACertificatePath +parameter to be set. This parameter is ignored with GnuTLS. +.B <level> +can be specified as one of the following keywords: +.RS +.TP +.B none +No CRL checks are performed +.TP +.B peer +Check the CRL of the peer certificate +.TP +.B all +Check the CRL for a whole certificate chain +.RE +.TP +.B olcTLSCRLFile: <filename> +Specifies a file containing a Certificate Revocation List to be used +for verifying that certificates have not been revoked. This parameter is +only valid when using GnuTLS. +.SH DYNAMIC MODULE OPTIONS +If +.B slapd +is compiled with \-\-enable\-modules then the module-related entries will +be available. These entries are named +.B cn=module{x},cn=config +and +must have the olcModuleList objectClass. One entry should be created +per +.B olcModulePath. +Normally the config engine generates the "{x}" index in the RDN +automatically, so it can be omitted when initially loading these entries. +.TP +.B olcModuleLoad: <filename> [<arguments>...] +Specify the name of a dynamically loadable module to load and any +additional arguments if supported by the module. The filename +may be an absolute path name or a simple filename. Non-absolute names +are searched for in the directories specified by the +.B olcModulePath +option. +.TP +.B olcModulePath: <pathspec> +Specify a list of directories to search for loadable modules. Typically +the path is colon-separated but this depends on the operating system. +The default is MODULEDIR, which is where the standard OpenLDAP install +will place its modules. +.SH SCHEMA OPTIONS +Schema definitions are created as entries in the +.B cn=schema,cn=config +subtree. These entries must have the olcSchemaConfig objectClass. +As noted above, the actual +.B cn=schema,cn=config +entry is predefined and any values specified for it are ignored. + +.HP +.hy 0 +.B olcAttributetypes: "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [SUP\ <oid>]\ + [EQUALITY\ <oid>]\ + [ORDERING\ <oid>]\ + [SUBSTR\ <oid>]\ + [SYNTAX\ <oidlen>]\ + [SINGLE\-VALUE]\ + [COLLECTIVE]\ + [NO\-USER\-MODIFICATION]\ + [USAGE\ <attributeUsage>]\ )" +.RS +Specify an attribute type using the LDAPv3 syntax defined in RFC 4512. +The slapd parser extends the RFC 4512 definition by allowing string +forms as well as numeric OIDs to be used for the attribute OID and +attribute syntax OID. +(See the +.B olcObjectIdentifier +description.) +.RE + +.HP +.hy 0 +.B olcDitContentRules: "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [AUX\ <oids>]\ + [MUST\ <oids>]\ + [MAY\ <oids>]\ + [NOT\ <oids>]\ )" +.RS +Specify an DIT Content Rule using the LDAPv3 syntax defined in RFC 4512. +The slapd parser extends the RFC 4512 definition by allowing string +forms as well as numeric OIDs to be used for the attribute OID and +attribute syntax OID. +(See the +.B olcObjectIdentifier +description.) +.RE + +.HP +.hy 0 +.B olcLdapSyntaxes "(\ <oid>\ + [DESC\ <description>]\ + [X\-SUBST <substitute-syntax>]\ )" +.RS +Specify an LDAP syntax using the LDAPv3 syntax defined in RFC 4512. +The slapd parser extends the RFC 4512 definition by allowing string +forms as well as numeric OIDs to be used for the syntax OID. +(See the +.B objectidentifier +description.) +The slapd parser also honors the +.B X\-SUBST +extension (an OpenLDAP-specific extension), which allows one to use the +.B olcLdapSyntaxes +attribute to define a non-implemented syntax along with another syntax, +the extension value +.IR substitute-syntax , +as its temporary replacement. +The +.I substitute-syntax +must be defined. +This allows one to define attribute types that make use of non-implemented syntaxes +using the correct syntax OID. +Unless +.B X\-SUBST +is used, this configuration statement would result in an error, +since no handlers would be associated to the resulting syntax structure. +.RE + +.HP +.hy 0 +.B olcObjectClasses: "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [SUP\ <oids>]\ + [{ ABSTRACT | STRUCTURAL | AUXILIARY }]\ + [MUST\ <oids>] [MAY\ <oids>] )" +.RS +Specify an objectclass using the LDAPv3 syntax defined in RFC 4512. +The slapd parser extends the RFC 4512 definition by allowing string +forms as well as numeric OIDs to be used for the object class OID. +(See the +.B +olcObjectIdentifier +description.) Object classes are "STRUCTURAL" by default. +.RE +.TP +.B olcObjectIdentifier: <name> "{ <oid> | <name>[:<suffix>] }" +Define a string name that equates to the given OID. The string can be used +in place of the numeric OID in objectclass and attribute definitions. The +name can also be used with a suffix of the form ":xx" in which case the +value "oid.xx" will be used. + +.SH GENERAL BACKEND OPTIONS +Options in these entries only apply to the configuration of a single +type of backend. All backends may support this class of options, but +currently only back-mdb does. +The entry must be named +.B olcBackend=<databasetype>,cn=config +and must have the olcBackendConfig objectClass. +<databasetype> +should be one of +.BR asyncmeta , +.BR config , +.BR dnssrv , +.BR ldap , +.BR ldif , +.BR mdb , +.BR meta , +.BR monitor , +.BR ndb , +.BR null , +.BR passwd , +.BR perl , +.BR relay , +.BR sock , +.BR sql , +or +.BR wt . +At present, only back-mdb implements any options of this type, so this +entry should not be used for any other backends. + +.SH DATABASE OPTIONS +Database options are set in entries named +.B olcDatabase={x}<databasetype>,cn=config +and must have the olcDatabaseConfig objectClass. Normally the config +engine generates the "{x}" index in the RDN automatically, so it +can be omitted when initially loading these entries. + +The special frontend database is always numbered "{\-1}" and the config +database is always numbered "{0}". + +.SH GLOBAL DATABASE OPTIONS +Options in this section may be set in the special "frontend" database +and inherited in all the other databases. These options may be altered +by further settings in each specific database. The frontend entry must +be named +.B olcDatabase=frontend,cn=config +and must have the olcFrontendConfig objectClass. +.TP +.B olcAccess: to <what> "[ by <who> <access> <control> ]+" +Grant access (specified by <access>) to a set of entries and/or +attributes (specified by <what>) by one or more requestors (specified +by <who>). +If no access controls are present, the default policy +allows anyone and everyone to read anything but restricts +updates to rootdn. (e.g., "olcAccess: to * by * read"). +See +.BR slapd.access (5) +and the "OpenLDAP Administrator's Guide" for details. + +Access controls set in the frontend are appended to any access +controls set on the specific databases. +The rootdn of a database can always read and write EVERYTHING +in that database. + +Extra special care must be taken with the access controls on the +config database. Unlike other databases, the default policy for the +config database is to only allow access to the rootdn. Regular users +should not have read access, and write access should be granted very +carefully to privileged administrators. + +.TP +.B olcDefaultSearchBase: <dn> +Specify a default search base to use when client submits a +non-base search request with an empty base DN. +Base scoped search requests with an empty base DN are not affected. +This setting is only allowed in the frontend entry. +.TP +.B olcExtraAttrs: <attr> +Lists what attributes need to be added to search requests. +Local storage backends return the entire entry to the frontend. +The frontend takes care of only returning the requested attributes +that are allowed by ACLs. +However, features like access checking and so may need specific +attributes that are not automatically returned by remote storage +backends, like proxy backends and so on. +.B <attr> +is an attribute that is needed for internal purposes +and thus always needs to be collected, even when not explicitly +requested by clients. +This attribute is multi-valued. +.TP +.B olcPasswordHash: <hash> [<hash>...] +This option configures one or more hashes to be used in generation of user +passwords stored in the userPassword attribute during processing of +LDAP Password Modify Extended Operations (RFC 3062). +The <hash> must be one of +.BR {SSHA} , +.BR {SHA} , +.BR {SMD5} , +.BR {MD5} , +.BR {CRYPT} , +and +.BR {CLEARTEXT} . +The default is +.BR {SSHA} . + +.B {SHA} +and +.B {SSHA} +use the SHA-1 algorithm (FIPS 160-1), the latter with a seed. + +.B {MD5} +and +.B {SMD5} +use the MD5 algorithm (RFC 1321), the latter with a seed. + +.B {CRYPT} +uses the +.BR crypt (3). + +.B {CLEARTEXT} +indicates that the new password should be +added to userPassword as clear text. + +Note that this option does not alter the normal user applications +handling of userPassword during LDAP Add, Modify, or other LDAP operations. +This setting is only allowed in the frontend entry. +.TP +.B olcReadOnly: TRUE | FALSE +This option puts the database into "read-only" mode. Any attempts to +modify the database will return an "unwilling to perform" error. By +default, olcReadOnly is FALSE. Note that when this option is set +TRUE on the frontend, it cannot be reset without restarting the +server, since further writes to the config database will be rejected. +.TP +.B olcRequires: <conditions> +Specify a set of conditions to require (default none). +The directive may be specified globally and/or per-database; +databases inherit global conditions, so per-database specifications +are additive. +.B bind +requires bind operation prior to directory operations. +.B LDAPv3 +requires session to be using LDAP version 3. +.B authc +requires authentication prior to directory operations. +.B SASL +requires SASL authentication prior to directory operations. +.B strong +requires strong authentication prior to directory operations. +The strong keyword allows protected "simple" authentication +as well as SASL authentication. +.B none +may be used to require no conditions (useful to clear out globally +set conditions within a particular database); it must occur first +in the list of conditions. +.TP +.B olcRestrict: <oplist> +Specify a list of operations that are restricted. +Restrictions on a specific database override any frontend setting. +Operations can be any of +.BR add , +.BR bind , +.BR compare , +.BR delete , +.BR extended[=<OID>] , +.BR modify , +.BR rename , +.BR search , +or the special pseudo-operations +.B read +and +.BR write , +which respectively summarize read and write operations. +The use of +.I restrict write +is equivalent to +.I olcReadOnly: TRUE +(see above). +The +.B extended +keyword allows one to indicate the OID of the specific operation +to be restricted. +.TP +.B olcSchemaDN: <dn> +Specify the distinguished name for the subschema subentry that +controls the entries on this server. The default is "cn=Subschema". +.TP +.B olcSecurity: <factors> +Specify a set of security strength factors (separated by white space) +to require (see +.BR olcSaslSecprops 's +.B minssf +option for a description of security strength factors). +The directive may be specified globally and/or per-database. +.B ssf=<n> +specifies the overall security strength factor. +.B transport=<n> +specifies the transport security strength factor. +.B tls=<n> +specifies the TLS security strength factor. +.B sasl=<n> +specifies the SASL security strength factor. +.B update_ssf=<n> +specifies the overall security strength factor to require for +directory updates. +.B update_transport=<n> +specifies the transport security strength factor to require for +directory updates. +.B update_tls=<n> +specifies the TLS security strength factor to require for +directory updates. +.B update_sasl=<n> +specifies the SASL security strength factor to require for +directory updates. +.B simple_bind=<n> +specifies the security strength factor required for +.I simple +username/password authentication. +Note that the +.B transport +factor is measure of security provided by the underlying transport, +e.g. ldapi:// (and eventually IPSEC). It is not normally used. +.TP +.B olcSizeLimit: {<integer>|unlimited} +.TP +.B olcSizeLimit: size[.{soft|hard}]=<integer> [...] +Specify the maximum number of entries to return from a search operation. +The default size limit is 500. +Use +.B unlimited +to specify no limits. +The second format allows a fine grain setting of the size limits. +If no special qualifiers are specified, both soft and hard limits are set. +Extra args can be added in the same value. +Additional qualifiers are available; see +.BR olcLimits +for an explanation of all of the different flags. +.TP +.B olcSortVals: <attr> [...] +Specify a list of multi-valued attributes whose values will always +be maintained in sorted order. Using this option will allow Modify, +Compare, and filter evaluations on these attributes to be performed +more efficiently. The resulting sort order depends on the +attributes' syntax and matching rules and may not correspond to +lexical order or any other recognizable order. +This setting is only allowed in the frontend entry. +.TP +.B olcTimeLimit: {<integer>|unlimited} +.TP +.B olcTimeLimit: time[.{soft|hard}]=<integer> [...] +Specify the maximum number of seconds (in real time) +.B slapd +will spend answering a search request. The default time limit is 3600. +Use +.B unlimited +to specify no limits. +The second format allows a fine grain setting of the time limits. +Extra args can be added in the same value. See +.BR olcLimits +for an explanation of the different flags. + +.SH GENERAL DATABASE OPTIONS +Options in this section only apply to the specific database for +which they are defined. They are supported by every +type of backend. All of the Global Database Options may also be +used here. +.TP +.B olcAddContentAcl: TRUE | FALSE +Controls whether Add operations will perform ACL checks on +the content of the entry being added. This check is off +by default. See the +.BR slapd.access (5) +manual page for more details on ACL requirements for +Add operations. +.TP +.B olcHidden: TRUE | FALSE +Controls whether the database will be used to answer +queries. A database that is hidden will never be +selected to answer any queries, and any suffix configured +on the database will be ignored in checks for conflicts +with other databases. By default, olcHidden is FALSE. +.TP +.B olcLastMod: TRUE | FALSE +Controls whether +.B slapd +will automatically maintain the +modifiersName, modifyTimestamp, creatorsName, and +createTimestamp attributes for entries. It also controls +the entryCSN and entryUUID attributes, which are needed +by the syncrepl provider. By default, olcLastMod is TRUE. +.TP +.B olcLastBind: TRUE | FALSE +Controls whether +.B slapd +will automatically maintain the pwdLastSuccess attribute for +entries. By default, olcLastBind is FALSE. +.TP +.B olcLimits: <selector> <limit> [<limit> [...]] +Specify time and size limits based on the operation's initiator or +base DN. +The argument +.B <selector> +can be any of +.RS +.RS +.TP +anonymous | users | [<dnspec>=]<pattern> | group[/oc[/at]]=<pattern> + +.RE +with +.RS +.TP +<dnspec> ::= dn[.<type>][.<style>] +.TP +<type> ::= self | this +.TP +<style> ::= exact | base | onelevel | subtree | children | regex | anonymous + +.RE +DN type +.B self +is the default and means the bound user, while +.B this +means the base DN of the operation. +The term +.B anonymous +matches all unauthenticated clients. +The term +.B users +matches all authenticated clients; +otherwise an +.B exact +dn pattern is assumed unless otherwise specified by qualifying +the (optional) key string +.B dn +with +.B exact +or +.B base +(which are synonyms), to require an exact match; with +.BR onelevel , +to require exactly one level of depth match; with +.BR subtree , +to allow any level of depth match, including the exact match; with +.BR children , +to allow any level of depth match, not including the exact match; +.BR regex +explicitly requires the (default) match based on POSIX (''extended'') +regular expression pattern. +Finally, +.B anonymous +matches unbound operations; the +.B pattern +field is ignored. +The same behavior is obtained by using the +.B anonymous +form of the +.B <selector> +clause. +The term +.BR group , +with the optional objectClass +.B oc +and attributeType +.B at +fields, followed by +.BR pattern , +sets the limits for any DN listed in the values of the +.B at +attribute (default +.BR member ) +of the +.B oc +group objectClass (default +.BR groupOfNames ) +whose DN exactly matches +.BR pattern . + +The currently supported limits are +.B size +and +.BR time . + +The syntax for time limits is +.BR time[.{soft|hard}]=<integer> , +where +.I integer +is the number of seconds slapd will spend answering a search request. +If no time limit is explicitly requested by the client, the +.BR soft +limit is used; if the requested time limit exceeds the +.BR hard +.\"limit, an +.\".I "Administrative limit exceeded" +.\"error is returned. +limit, the value of the limit is used instead. +If the +.BR hard +limit is set to the keyword +.IR soft , +the soft limit is used in either case; if it is set to the keyword +.IR unlimited , +no hard limit is enforced. +Explicit requests for time limits smaller or equal to the +.BR hard +limit are honored. +If no limit specifier is set, the value is assigned to the +.BR soft +limit, and the +.BR hard +limit is set to +.IR soft , +to preserve the original behavior. + +The syntax for size limits is +.BR size[.{soft|hard|unchecked}]=<integer> , +where +.I integer +is the maximum number of entries slapd will return answering a search +request. +If no size limit is explicitly requested by the client, the +.BR soft +limit is used; if the requested size limit exceeds the +.BR hard +.\"limit, an +.\".I "Administrative limit exceeded" +.\"error is returned. +limit, the value of the limit is used instead. +If the +.BR hard +limit is set to the keyword +.IR soft , +the soft limit is used in either case; if it is set to the keyword +.IR unlimited , +no hard limit is enforced. +Explicit requests for size limits smaller or equal to the +.BR hard +limit are honored. +The +.BR unchecked +specifier sets a limit on the number of candidates a search request is allowed +to examine. +The rationale behind it is that searches for non-properly indexed +attributes may result in large sets of candidates, which must be +examined by +.BR slapd (8) +to determine whether they match the search filter or not. +The +.B unchecked +limit provides a means to drop such operations before they are even +started. +If the selected candidates exceed the +.BR unchecked +limit, the search will abort with +.IR "Unwilling to perform" . +If it is set to the keyword +.IR unlimited , +no limit is applied (the default). +If it is set to +.IR disabled , +the search is not even performed; this can be used to disallow searches +for a specific set of users. +If no limit specifier is set, the value is assigned to the +.BR soft +limit, and the +.BR hard +limit is set to +.IR soft , +to preserve the original behavior. + +In case of no match, the global limits are used. +The default values are the same as for +.B olcSizeLimit +and +.BR olcTimeLimit ; +no limit is set on +.BR unchecked . + +If +.B pagedResults +control is requested, the +.B hard +size limit is used by default, because the request of a specific page size +is considered an explicit request for a limitation on the number +of entries to be returned. +However, the size limit applies to the total count of entries returned within +the search, and not to a single page. +Additional size limits may be enforced; the syntax is +.BR size.pr={<integer>|noEstimate|unlimited} , +where +.I integer +is the max page size if no explicit limit is set; the keyword +.I noEstimate +inhibits the server from returning an estimate of the total number +of entries that might be returned +(note: the current implementation does not return any estimate). +The keyword +.I unlimited +indicates that no limit is applied to the pagedResults control page size. +The syntax +.B size.prtotal={<integer>|hard|unlimited|disabled} +allows one to set a limit on the total number of entries that the pagedResults +control will return. +By default it is set to the +.B hard +limit which will use the size.hard value. +When set, +.I integer +is the max number of entries that the whole search with pagedResults control +can return. +Use +.I unlimited +to allow unlimited number of entries to be returned, e.g. to allow +the use of the pagedResults control as a means to circumvent size +limitations on regular searches; the keyword +.I disabled +disables the control, i.e. no paged results can be returned. +Note that the total number of entries returned when the pagedResults control +is requested cannot exceed the +.B hard +size limit of regular searches unless extended by the +.B prtotal +switch. + +The \fBolcLimits\fP statement is typically used to let an unlimited +number of entries be returned by searches performed +with the identity used by the consumer for synchronization purposes +by means of the RFC 4533 LDAP Content Synchronization protocol +(see \fBolcSyncrepl\fP for details). + +When using subordinate databases, it is necessary for any limits that +are to be applied across the parent and its subordinates to be defined in +both the parent and its subordinates. Otherwise the settings on the +subordinate databases are not honored. +.RE +.TP +.B olcMaxDerefDepth: <depth> +Specifies the maximum number of aliases to dereference when trying to +resolve an entry, used to avoid infinite alias loops. The default is 15. +.TP +.B olcMultiProvider: TRUE | FALSE +This option puts a consumer database into Multi-Provider mode. Update +operations will be accepted from any user, not just the updatedn. The +database must already be configured as a syncrepl consumer +before this keyword may be set. This mode also requires a +.B olcServerID +(see above) to be configured. +By default, this setting is FALSE. +.TP +.B olcMonitoring: TRUE | FALSE +This option enables database-specific monitoring in the entry related +to the current database in the "cn=Databases,cn=Monitor" subtree +of the monitor database, if the monitor database is enabled. +Currently, only the MDB database provides database-specific monitoring. +If monitoring is supported by the backend it defaults to TRUE, otherwise +FALSE. +.TP +.B olcPlugin: <plugin_type> <lib_path> <init_function> [<arguments>] +Configure a SLAPI plugin. See the +.BR slapd.plugin (5) +manpage for more details. +.TP +.B olcRootDN: <dn> +Specify the distinguished name that is not subject to access control +or administrative limit restrictions for operations on this database. +This DN may or may not be associated with an entry. An empty root +DN (the default) specifies no root access is to be granted. It is +recommended that the rootdn only be specified when needed (such as +when initially populating a database). If the rootdn is within +a namingContext (suffix) of the database, a simple bind password +may also be provided using the +.B olcRootPW +directive. Many optional features, including syncrepl, require the +rootdn to be defined for the database. +The +.B olcRootDN +of the +.B cn=config +database defaults to +.B cn=config +itself. +.TP +.B olcRootPW: <password> +Specify a password (or hash of the password) for the rootdn. The +password can only be set if the rootdn is within the namingContext +(suffix) of the database. +This option accepts all RFC 2307 userPassword formats known to +the server (see +.B olcPasswordHash +description) as well as cleartext. +.BR slappasswd (8) +may be used to generate a hash of a password. Cleartext +and \fB{CRYPT}\fP passwords are not recommended. If empty +(the default), authentication of the root DN is by other means +(e.g. SASL). Use of SASL is encouraged. +.TP +.B olcSubordinate: [TRUE | FALSE | advertise] +Specify that the current backend database is a subordinate of another +backend database. A subordinate database may have only one suffix. This +option may be used to glue multiple databases into a single namingContext. +If the suffix of the current database is within the namingContext of a +superior database, searches against the superior database will be +propagated to the subordinate as well. All of the databases +associated with a single namingContext should have identical rootdns. +Behavior of other LDAP operations is unaffected by this setting. In +particular, it is not possible to use moddn to move an entry from +one subordinate to another subordinate within the namingContext. + +If the optional \fBadvertise\fP flag is supplied, the naming context of +this database is advertised in the root DSE. The default is to hide this +database context, so that only the superior context is visible. + +If the slap tools +.BR slapcat (8), +.BR slapadd (8), +.BR slapmodify (8), +or +.BR slapindex (8) +are used on the superior database, any glued subordinates that support +these tools are opened as well. + +Databases that are glued together should usually be configured with the +same indices (assuming they support indexing), even for attributes that +only exist in some of these databases. In general, all of the glued +databases should be configured as similarly as possible, since the intent +is to provide the appearance of a single directory. + +Note that the subordinate functionality is implemented internally +by the \fIglue\fP overlay and as such its behavior will interact with other +overlays in use. By default, the glue overlay is automatically configured as +the last overlay on the superior database. Its position on the database +can be explicitly configured by setting an \fBoverlay glue\fP directive +at the desired position. This explicit configuration is necessary e.g. +when using the \fIsyncprov\fP overlay, which needs to follow \fIglue\fP +in order to work over all of the glued databases. E.g. +.RS +.nf + dn: olcDatabase={1}mdb,cn=config + olcSuffix: dc=example,dc=com + ... + + dn: olcOverlay={0}glue,olcDatabase={1}mdb,cn=config + ... + + dn: olcOverlay={1}syncprov,olcDatabase={1}mdb,cn=config + ... +.fi +.RE +See the Overlays section below for more details. +.TP +.B olcSuffix: <dn suffix> +Specify the DN suffix of queries that will be passed to this +backend database. Multiple suffix lines can be given and at least one is +required for each database definition. + +If the suffix of one database is "inside" that of another, the database +with the inner suffix must come first in the configuration file. +You may also want to glue such databases together with the +.B olcSubordinate +attribute. +.TP +.B olcSyncUseSubentry: TRUE | FALSE +Store the syncrepl contextCSN in a subentry instead of the context entry +of the database. The subentry's RDN will be "cn=ldapsync". The default is +FALSE, meaning the contextCSN is stored in the context entry. +.HP +.hy 0 +.B olcSyncrepl: rid=<replica ID> +.B provider=ldap[s]://<hostname>[:port] +.B searchbase=<base DN> +.B [type=refreshOnly|refreshAndPersist] +.B [interval=dd:hh:mm:ss] +.B [retry=[<retry interval> <# of retries>]+] +.B [filter=<filter str>] +.B [scope=sub|one|base|subord] +.B [attrs=<attr list>] +.B [exattrs=<attr list>] +.B [attrsonly] +.B [sizelimit=<limit>] +.B [timelimit=<limit>] +.B [schemachecking=on|off] +.B [network\-timeout=<seconds>] +.B [timeout=<seconds>] +.B [tcp\-user\-timeout=<milliseconds>] +.B [bindmethod=simple|sasl] +.B [binddn=<dn>] +.B [saslmech=<mech>] +.B [authcid=<identity>] +.B [authzid=<identity>] +.B [credentials=<passwd>] +.B [realm=<realm>] +.B [secprops=<properties>] +.B [keepalive=<idle>:<probes>:<interval>] +.B [starttls=yes|critical] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_crlcheck=none|peer|all] +.B [tls_protocol_min=<major>[.<minor>]] +.B [suffixmassage=<real DN>] +.B [logbase=<base DN>] +.B [logfilter=<filter str>] +.B [syncdata=default|accesslog|changelog] +.B [lazycommit] +.RS +Specify the current database as a consumer which is kept up-to-date with the +provider content by establishing the current +.BR slapd (8) +as a replication consumer site running a +.B syncrepl +replication engine. +The consumer content is kept synchronized to the provider content using +the LDAP Content Synchronization protocol. Refer to the +"OpenLDAP Administrator's Guide" for detailed information on +setting up a replicated +.B slapd +directory service using the +.B syncrepl +replication engine. + +.B rid +identifies the current +.B syncrepl +directive within the replication consumer site. +It is a non-negative integer not greater than 999 (limited +to three decimal digits). + +.B provider +specifies the replication provider site containing the provider content +as an LDAP URI. If <port> is not given, the standard LDAP port number +(389 or 636) is used. + +The content of the +.B syncrepl +consumer is defined using a search +specification as its result set. The consumer +.B slapd +will send search requests to the provider +.B slapd +according to the search specification. The search specification includes +.BR searchbase ", " scope ", " filter ", " attrs ", " attrsonly ", " sizelimit ", " +and +.B timelimit +parameters as in the normal search specification. The +.B exattrs +option may also be used to specify attributes that should be omitted +from incoming entries. +The \fBscope\fP defaults to \fBsub\fP, the \fBfilter\fP defaults to +\fB(objectclass=*)\fP, and there is no default \fBsearchbase\fP. The +\fBattrs\fP list defaults to \fB"*,+"\fP to return all user and operational +attributes, and \fBattrsonly\fP and \fBexattrs\fP are unset by default. +The \fBsizelimit\fP and \fBtimelimit\fP only +accept "unlimited" and positive integers, and both default to "unlimited". +The \fBsizelimit\fP and \fBtimelimit\fP parameters define +a consumer requested limitation on the number of entries that can be returned +by the LDAP Content Synchronization operation; these should be left unchanged +from the default otherwise replication may never succeed. +Note, however, that any provider-side limits for the replication identity +will be enforced by the provider regardless of the limits requested +by the LDAP Content Synchronization operation, much like for any other +search operation. + +The LDAP Content Synchronization protocol has two operation types. +In the +.B refreshOnly +operation, the next synchronization search operation +is periodically rescheduled at an interval time (specified by +.B interval +parameter; 1 day by default) +after each synchronization operation finishes. +In the +.B refreshAndPersist +operation, a synchronization search remains persistent in the provider slapd. +Further updates to the provider will generate +.B searchResultEntry +to the consumer slapd as the search responses to the persistent +synchronization search. If the initial search fails due to an error, the +next synchronization search operation is periodically rescheduled at an +interval time (specified by +.B interval +parameter; 1 day by default) + +If an error occurs during replication, the consumer will attempt to +reconnect according to the +.B retry +parameter which is a list of the <retry interval> and <# of retries> pairs. +For example, retry="60 10 300 3" lets the consumer retry every 60 seconds +for the first 10 times and then retry every 300 seconds for the next 3 +times before stop retrying. The `+' in <# of retries> means indefinite +number of retries until success. +If no +.B retry +is specified, by default syncrepl retries every hour forever. + +The schema checking can be enforced at the LDAP Sync +consumer site by turning on the +.B schemachecking +parameter. The default is \fBoff\fP. +Schema checking \fBon\fP means that replicated entries must have +a structural objectClass, must obey to objectClass requirements +in terms of required/allowed attributes, and that naming attributes +and distinguished values must be present. +As a consequence, schema checking should be \fBoff\fP when partial +replication is used. + +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). +The +.B tcp\-user\-timeout +parameter, if non-zero, corresponds to the +.B TCP_USER_TIMEOUT +set on the target 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. + +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 identity used for synchronization by the consumer should be allowed +to receive an unlimited number of entries in response to a search request. +The provider, other than allowing authentication of the syncrepl identity, +should grant that identity appropriate access privileges to the data +that is being replicated (\fBaccess\fP directive), and appropriate time +and size limits. +This can be accomplished by either allowing unlimited \fBsizelimit\fP +and \fBtimelimit\fP, or by setting an appropriate \fBlimits\fP statement +in the consumer's configuration (see \fBsizelimit\fP and \fBlimits\fP +for details). + +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 +.B tls_reqcert +setting defaults to "demand", the +.B tls_reqsan +setting defaults to "allow", and the other TLS settings +default to the same as the main slapd TLS settings. + +The +.B suffixmassage +parameter allows the consumer to pull entries from a remote directory +whose DN suffix differs from the local directory. The portion of the +remote entries' DNs that matches the \fIsearchbase\fP will be replaced +with the suffixmassage DN. + +Rather than replicating whole entries, the consumer can query logs of +data modifications. This mode of operation is referred to as \fIdelta +syncrepl\fP. In addition to the above parameters, the +.B logbase +and +.B logfilter +parameters must be set appropriately for the log that will be used. The +.B syncdata +parameter must be set to either "accesslog" if the log conforms to the +.BR slapo\-accesslog (5) +log format, or "changelog" if the log conforms +to the obsolete \fIchangelog\fP format. If the +.B syncdata +parameter is omitted or set to "default" then the log parameters are +ignored. + +The +.B lazycommit +parameter tells the underlying database that it can store changes without +performing a full flush after each change. This may improve performance +for the consumer, while sacrificing safety or durability. +.RE +.TP +.B olcUpdateDN: <dn> +This option is only applicable in a replica +database. +It specifies the DN permitted to update (subject to access controls) +the replica. It is only needed in certain push-mode +replication scenarios. Generally, this DN +.I should not +be the same as the +.B rootdn +used at the provider. +.TP +.B olcUpdateRef: <url> +Specify the referral to pass back when +.BR slapd (8) +is asked to modify a replicated local database. +If multiple values are specified, each url is provided. + +.SH DATABASE-SPECIFIC OPTIONS +Each database may allow specific configuration options; they are +documented separately in the backends' manual pages. See the +.BR slapd.backends (5) +manual page for an overview of available backends. +.SH OVERLAYS +An overlay is a piece of +code that intercepts database operations in order to extend or change +them. Overlays are pushed onto +a stack over the database, and so they will execute in the reverse +of the order in which they were configured and the database itself +will receive control last of all. + +Overlays must be configured as child entries of a specific database. The +entry's RDN must be of the form +.B olcOverlay={x}<overlaytype> +and the entry must have the olcOverlayConfig objectClass. Normally the +config engine generates the "{x}" index in the RDN automatically, so +it can be omitted when initially loading these entries. + +See the +.BR slapd.overlays (5) +manual page for an overview of available overlays. +.SH EXAMPLES +.LP +Here is a short example of a configuration in LDIF suitable for use with +.BR slapadd (8) +: +.LP +.RS +.nf +dn: cn=config +objectClass: olcGlobal +cn: config +olcPidFile: LOCALSTATEDIR/run/slapd.pid +olcAttributeOptions: x\-hidden lang\- + +dn: cn=schema,cn=config +objectClass: olcSchemaConfig +cn: schema + +include: file://SYSCONFDIR/schema/core.ldif + +dn: olcDatabase=frontend,cn=config +objectClass: olcDatabaseConfig +objectClass: olcFrontendConfig +olcDatabase: frontend +# Subtypes of "name" (e.g. "cn" and "ou") with the +# option ";x\-hidden" can be searched for/compared, +# but are not shown. See \fBslapd.access\fP(5). +olcAccess: to attrs=name;x\-hidden by * =cs +# Protect passwords. See \fBslapd.access\fP(5). +olcAccess: to attrs=userPassword by * auth +# Read access to other attributes and entries. +olcAccess: to * by * read + +# set a rootpw for the config database so we can bind. +# deny access to everyone else. +dn: olcDatabase=config,cn=config +objectClass: olcDatabaseConfig +olcDatabase: config +olcRootPW: {SSHA}XKYnrjvGT3wZFQrDD5040US592LxsdLy +olcAccess: to * by * none + +dn: olcDatabase=mdb,cn=config +objectClass: olcDatabaseConfig +objectClass: olcMdbConfig +olcDatabase: mdb +olcSuffix: "dc=our\-domain,dc=com" +# The database directory MUST exist prior to +# running slapd AND should only be accessible +# by the slapd/tools. Mode 0700 recommended. +olcDbDirectory: LOCALSTATEDIR/openldap\-data +# Indices to maintain +olcDbIndex: objectClass eq +olcDbIndex: cn,sn,mail pres,eq,approx,sub + +# We serve small clients that do not handle referrals, +# so handle remote lookups on their behalf. +dn: olcDatabase=ldap,cn=config +objectClass: olcDatabaseConfig +objectClass: olcLdapConfig +olcDatabase: ldap +olcSuffix: "" +olcDbUri: ldap://ldap.some\-server.com/ +.fi +.RE +.LP +Assuming the above data was saved in a file named "config.ldif" and the +ETCDIR/slapd.d directory has been created, this command will initialize +the configuration: +.RS +.nf +slapadd \-F ETCDIR/slapd.d \-n 0 \-l config.ldif +.fi +.RE + +.LP +"OpenLDAP Administrator's Guide" contains a longer annotated +example of a slapd configuration. + +Alternatively, an existing slapd.conf file can be converted to the new +format using slapd or any of the slap tools: +.RS +.nf +slaptest \-f ETCDIR/slapd.conf \-F ETCDIR/slapd.d +.fi +.RE + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +ETCDIR/slapd.d +default slapd configuration directory +.SH SEE ALSO +.BR ldap (3), +.BR ldif (5), +.BR gnutls\-cli (1), +.BR slapd.access (5), +.BR slapd.backends (5), +.BR slapd.conf (5), +.BR slapd.overlays (5), +.BR slapd.plugin (5), +.BR slapd (8), +.BR slapacl (8), +.BR slapadd (8), +.BR slapauth (8), +.BR slapcat (8), +.BR slapdn (8), +.BR slapindex (8), +.BR slapmodify (8), +.BR slappasswd (8), +.BR slaptest (8). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapd-dnssrv.5 b/doc/man/man5/slapd-dnssrv.5 new file mode 100644 index 0000000..f29c620 --- /dev/null +++ b/doc/man/man5/slapd-dnssrv.5 @@ -0,0 +1,49 @@ +.TH SLAPD-DNSSRV 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-dnssrv \- DNS SRV referral backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The DNSSRV backend to +.BR slapd (8) +serves up referrals based upon SRV resource records held in +the Domain Name System. +.LP +This backend is experimental. +.SH CONFIGURATION +The DNSSRV backend has no backend nor database specific options. +It is configured simply by "database dnssrv" followed a suffix +directive, e.g. suffix "". +.SH ACCESS CONTROL +The +.B dnssrv +backend does not honor all ACL semantics as described in +.BR slapd.access (5). +In fact, this backend only implements the +.B search +operation when the +.B manageDSAit +control (RFC 3296) is used, otherwise for every operation a referral, +whenever appropriate, or an error is returned. +Currently, there is no means to condition the returning of the referral +by means of ACLs; no access control is implemented, except for +.B read (=r) +access to the returned entries, which is actually provided by the frontend. +Note, however, that the information returned by this backend is collected +through the DNS, so it is public by definition. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.br +.SH SEE ALSO +\fB"OpenLDAP Root Service - An experimental LDAP referral +service"\fR [RFC 3088], +.br +\fB"OpenLDAP LDAP Root Service"\fR <http://www.openldap.org/faq/?file=393)>, +.br +.BR slapd.conf (5), +.BR slapd (8) diff --git a/doc/man/man5/slapd-ldap.5 b/doc/man/man5/slapd-ldap.5 new file mode 100644 index 0000000..ffcbe81 --- /dev/null +++ b/doc/man/man5/slapd-ldap.5 @@ -0,0 +1,700 @@ +.TH SLAPD-LDAP 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-ldap \- LDAP backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The LDAP backend to +.BR slapd (8) +is not an actual database; instead it acts as a proxy to forward incoming +requests to another LDAP server. While processing requests it will also +chase referrals, so that referrals are fully processed instead of being +returned to the slapd client. + +Sessions that explicitly Bind to the back-ldap database always create their +own private connection to the remote LDAP server. Anonymous sessions will +share a single anonymous connection to the remote server. For sessions bound +through other mechanisms, all sessions with the same DN will share the +same connection. This connection pooling strategy can enhance the proxy's +efficiency by reducing the overhead of repeatedly making/breaking multiple +connections. + +The ldap database can also act as an information service, i.e. the identity +of locally authenticated clients is asserted to the remote server, possibly +in some modified form. +For this purpose, the proxy binds to the remote server with some +administrative identity, and, if required, authorizes the asserted identity. +See the +.IR idassert\- * +rules below. +The administrative identity of the proxy, on the remote server, must be +allowed to authorize by means of appropriate +.B authzTo +rules; see +.BR slapd.conf (5) +for details. + +The proxy instance of +.BR slapd (8) +must contain schema information for the attributes and objectClasses +used in filters, request DNs and request-related data in general. +It should also contain schema information for the data returned +by the proxied server. +It is the responsibility of the proxy administrator to keep the schema +of the proxy lined up with that of the proxied server. + +.LP +Note: When looping back to the same instance of +.BR slapd (8), +each connection requires a new thread; as a consequence, the +.BR slapd (8) +\fBthreads\fP parameter may need some tuning. In those cases, +one may consider using +.BR slapd\-relay (5) +instead, which performs the relayed operation +internally and thus reuses the same connection. + +.SH CONFIGURATION +These +.B slapd.conf +options apply to the LDAP backend database. +That is, they must follow a "database ldap" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. + +.LP +Note: In early versions of back-ldap it was recommended to always set +.LP +.RS +.nf +lastmod off +.fi +.RE +.LP +for +.B ldap +and +.B meta +databases. +This was required because operational attributes related to entry creation +and modification should not be proxied, as they could be mistakenly written +to the target server(s), generating an error. +The current implementation automatically sets lastmod to \fBoff\fP, +so its use is redundant and should be omitted. + +.TP +.B uri <ldapurl> +LDAP server to use. Multiple URIs can be set in a single +.B ldapurl +argument, resulting in the underlying library automatically +calling the first server of the list that responds, e.g. + +\fBuri "ldap://host/ ldap://backup\-host/"\fP + +The URI list is space- or comma-separated. +Whenever the server that responds is not the first one in the list, +the list is rearranged and the responsive server is moved to the head, +so that it will be first contacted the next time a connection +needs to be created. +.HP +.hy 0 +.B acl\-bind +.B bindmethod=simple|sasl [binddn=<simple DN>] [credentials=<simple password>] +.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>] +.B [authcId=<authentication ID>] [authzId=<authorization ID>] +.B [starttls=no|yes|critical] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_protocol_min=<major>[.<minor>]] +.B [tls_crlcheck=none|peer|all] +.RS +Allows one to define the parameters of the authentication method that is +internally used by the proxy to collect info related to access control, +and whenever an operation occurs with the identity of the rootdn +of the LDAP proxy database. +The identity defined by this directive, according to the properties +associated to the authentication method, 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. +The default is to use +.BR simple +bind, with empty \fIbinddn\fP and \fIcredentials\fP, +which means that the related operations will be performed anonymously. +If not set, and if \fBidassert\-bind\fP is defined, this latter identity +is used instead. See \fBidassert\-bind\fP for details. + +The connection between the proxy database and the remote server +associated to this identity is cached regardless of the lifespan +of the client-proxy connection that first established it. + +.B This identity is not implicitly used by the proxy +.B when the client connects anonymously. +The +.B idassert\-bind +feature, instead, in some cases can be crafted to implement that behavior, +which is \fIintrinsically unsafe and should be used with extreme care\fP. + +The TLS settings default to the same as the main slapd TLS settings, +except for +.B tls_reqcert +which defaults to "demand", and +.B tls_reqsan +which defaults to "allow". +.RE + +.TP +.B cancel {ABANDON|ignore|exop[\-discover]} +Defines how to handle operation cancellation. +By default, +.B abandon +is invoked, so the operation is abandoned immediately. +If set to +.BR ignore , +no action is taken and any further response is ignored; this may result +in further response messages to be queued for that connection, so it is +recommended that long lasting connections are timed out either by +.I idle\-timeout +or +.IR conn\-ttl , +so that resources eventually get released. +If set to +.BR exop , +a +.I cancel +operation (RFC 3909) is issued, resulting in the cancellation +of the current operation; the +.I cancel +operation waits for remote server response, so its use +may not be recommended. +If set to +.BR exop\-discover , +support of the +.I cancel +extended operation is detected by reading the remote server's root DSE. + +.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. + +.TP +.B conn\-pool\-max <int> +This directive defines the maximum size of the privileged connections pool. + +.TP +.B conn\-ttl <time> +This directive causes a cached connection to be dropped and recreated +after a given ttl, regardless of being idle or not. + +.TP +.B idassert\-authzFrom <authz-regexp> +if defined, selects what +.I local +identities are authorized to exploit the identity assertion feature. +The string +.B <authz-regexp> +mostly 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. This parameter differs from +the documented behavior in relation to the meaning of *, which in this +case allows anonymous rather than denies. + +.HP +.hy 0 +.B idassert\-bind +.B bindmethod=none|simple|sasl [binddn=<simple DN>] [credentials=<simple password>] +.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>] +.B [authcId=<authentication ID>] [authzId=<authorization ID>] +.B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>] +.B [starttls=no|yes|critical] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_protocol_min=<version>] +.B [tls_crlcheck=none|peer|all] +.RS +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. +Direct binds are always proxied without any idassert handling. + +The identity defined by this directive, according to the properties +associated to the authentication method, is supposed to have auth access +on the target server to attributes used on the proxy for authentication +and authorization, and to be allowed to authorize the users. +This requires to have +.B proxyAuthz +privileges on a wide set of DNs, e.g. +.BR authzTo=dn.subtree:"" , +and the remote server to have +.B authz\-policy +set to +.B to +or +.BR both . +See +.BR slapd.conf (5) +for details on these statements and for remarks and drawbacks about +their usage. +The supported bindmethods are + +\fBnone|simple|sasl\fP + +where +.B none +is the default, i.e. no \fIidentity assertion\fP is performed. + +The +.B authz +parameter is used to instruct the SASL bind to exploit +.B native +SASL authorization, if available; since connections are cached, +this should only be used when authorizing with a fixed identity +(e.g. by means of the +.B authzDN +or +.B authzID +parameters). +Otherwise, the default +.B proxyauthz +is used, i.e. the proxyAuthz control (Proxied Authorization, RFC 4370) +is added to all operations. + +The supported modes are: + +\fB<mode> := {legacy|anonymous|none|self}\fP + +If +.B <mode> +is not present, and +.B authzId +is given, the proxy always authorizes that identity. +.B <authorization ID> +can be + +\fBu:<user>\fP + +\fB[dn:]<DN>\fP + +The former is supposed to be expanded by the remote server according +to the authz rules; see +.BR slapd.conf (5) +for details. +In the latter case, whether or not the +.B dn: +prefix is present, the string must pass DN validation and normalization. + +The default mode is +.BR legacy , +which implies that the proxy will either perform a simple bind as the +.I authcDN +or a SASL bind as the +.I authcID +and assert the client's identity when it is not anonymous. +The other modes imply that the proxy will always either perform a simple bind +as the +.IR authcDN +or a SASL bind as the +.IR authcID , +unless restricted by +.BR idassert\-authzFrom +rules (see below), in which case the operation will fail; +eventually, it will assert some other identity according to +.BR <mode> . +Other identity assertion modes are +.BR anonymous +and +.BR self , +which respectively mean that the +.I empty +or the +.IR client 's +identity +will be asserted; +.BR none , +which means that no proxyAuthz control will be used, so the +.I authcDN +or the +.I authcID +identity will be asserted. +For all modes that require the use of the +.I proxyAuthz +control, on the remote server the proxy identity must have appropriate +.I authzTo +permissions, or the asserted identities must have appropriate +.I authzFrom +permissions. Note, however, that the ID assertion feature is mostly +useful when the asserted identities do not exist on the remote server. + +Flags can be + +\fBoverride,[non\-]prescriptive,proxy\-authz\-[non\-]critical,dn\-{authzid|whoami}\fP + +When the +.B override +flag is used, identity assertion takes place even when the database +is authorizing for the identity of the client, i.e. after binding +with the provided identity, and thus authenticating it, the proxy +performs the identity assertion using the configured identity and +authentication method. + +When the +.B prescriptive +flag is used (the default), operations fail with +\fIinappropriateAuthentication\fP +for those identities whose assertion is not allowed by the +.B idassert\-authzFrom +patterns. +If the +.B non\-prescriptive +flag is used, operations are performed anonymously for those identities +whose assertion is not allowed by the +.B idassert\-authzFrom +patterns. + +When the +.B proxy\-authz\-non\-critical +flag is used (the default), the proxyAuthz control is not marked as critical, +in violation of RFC 4370. Use of +.B proxy\-authz\-critical +is recommended. + +When the +.B dn\-authzid +flag is used, RFC 3829 LDAP Authorization Identity Controls +is used to retrieve the identity associated to the SASL identity; +when the +.B dn\-whoami +flag is used, RFC 4532 LDAP Who am I? Operation is performed +after the bind for the same purpose. + +The TLS settings default to the same as the main slapd TLS settings, +except for +.B tls_reqcert +which defaults to "demand", and +.B tls_reqsan +which defaults to "allow". + +The identity associated to this directive is also used for privileged +operations whenever \fBidassert\-bind\fP is defined and \fBacl\-bind\fP +is not. See \fBacl\-bind\fP for details. + +.TP +.B idassert-passthru <authz-regexp> +if defined, selects what +.I local +identities bypass the identity assertion feature. +Those identities need to be known by the remote host. +The string +.B <authz-regexp> +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. + +.TP +.B idle\-timeout <time> +This directive causes a cached connection to be dropped an recreated +after it has been idle for the specified time. + +.TP +.B keepalive <idle>:<probes>:<interval> +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. + +.TP +.B tcp\-user\-timeout <milliseconds> +If non-zero, corresponds to the +.B TCP_USER_TIMEOUT +set on the target 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. + +.TP +.B network\-timeout <time> +Sets the network timeout value after which +.BR poll (2)/ select (2) +following a +.BR connect (2) +returns in case of no activity. +The value is in seconds, and it can be specified as for +.BR idle\-timeout . + +.TP +.B norefs <NO|yes> +If +.BR yes , +do not return search reference responses. +By default, they are returned unless request is LDAPv2. + +.TP +.B omit-unknown-schema <NO|yes> +If +.BR yes , +do not return objectClasses or attributes that are not known to the local server. +The default is to return all schema elements. + +.TP +.B noundeffilter <NO|yes> +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. + +.TP +.B onerr {CONTINUE|stop} +This directive allows one to select the behavior in case an error is returned +by the remote server during a search. +The default, \fBcontinue\fP, consists in returning success. +If the value is set to \fBstop\fP, the error is returned to the client. + +.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. + +.TP +.B proxy\-whoami {NO|yes} +Turns on proxying of the WhoAmI extended operation. If this option is +given, back-ldap will replace slapd's original WhoAmI routine with its +own. On slapd sessions that were authenticated by back-ldap, the WhoAmI +request will be forwarded to the remote LDAP server. Other sessions will +be handled by the local slapd, as before. This option is mainly useful +in conjunction with Proxy Authorization. + +.TP +.B quarantine <interval>,<num>[;<interval>,<num>[...]] +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. +The process can be restarted by resetting the \fIolcDbQuarantine\fP +attribute of the database entry in the configuration backend. + +.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. + +.TP +.B single\-conn {NO|yes} +Discards current cached connection when the client rebinds. + +.TP +.B t\-f\-support {NO|yes|discover} +enable if the remote server supports absolute filters +(see \fIRFC 4526\fP for details). +If set to +.BR discover , +support is detected by reading the remote server's root DSE. + +.TP +.B timeout [<op>=]<val> [...] +This directive allows one to set per-operation timeouts. +Operations can be + +\fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP + +The overall duration of the \fBsearch\fP operation is controlled either +by the \fBtimelimit\fP parameter or by server-side enforced +time limits (see \fBtimelimit\fP and \fBlimits\fP in +.BR slapd.conf (5) +for details). +This \fBtimeout\fP parameter controls how long the target can be +irresponsive before the operation is aborted. +Timeout is meaningless for the remaining operations, +\fBunbind\fP and \fBabandon\fP, which do not imply any response, +while it is not yet implemented in currently supported \fBextended\fP +operations. +If no operation is specified, the timeout \fBval\fP affects all +supported operations. + +Note: if the timelimit is exceeded, the operation is cancelled +(according to the \fBcancel\fP directive); +the protocol does not provide any means to rollback operations, +so the client will not be notified about the result of the operation, +which may eventually succeeded or not. +In case the timeout is exceeded during a bind operation, the connection +is destroyed, according to RFC4511. + +Note: in some cases, this backend may issue binds prior +to other operations (e.g. to bind anonymously or with some prescribed +identity according to the \fBidassert\-bind\fP directive). +In this case, the timeout of the operation that resulted in the bind +is used. + +.HP +.hy 0 +.B tls {none|[try\-]start|[try\-]propagate|ldaps} +.B [starttls=no] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_crlcheck=none|peer|all] +.RS +Specify TLS settings for regular connections. + +If the first parameter is not "none" then this configures the TLS +settings to be used for regular connections. +The StartTLS extended operation will be used when establishing the +connection unless the URI directive protocol scheme is \fBldaps://\fP. +In that case this keyword may only be set to "ldaps" and the StartTLS +operation will not be used. + +With \fBpropagate\fP, the proxy issues the StartTLS operation only if +the original connection has a TLS layer set up. +The \fBtry\-\fP prefix instructs the proxy to continue operations +if the StartTLS operation failed; its use is \fBnot\fP recommended. + +The TLS settings default to the same as the main slapd TLS settings, +except for +.B tls_reqcert +which defaults to "demand", +.B tls_reqsan +which defaults to "allow", and +.B starttls +which is overshadowed by the first keyword and thus ignored. +.RE + +.TP +.B use\-temporary\-conn {NO|yes} +when set to +.BR yes , +create a temporary connection whenever competing with other threads +for a shared one; otherwise, wait until the shared connection is available. + +.SH ACCESS CONTROL +The +.B ldap +backend does not honor all ACL semantics as described in +.BR slapd.access (5). +In general, access checking is delegated to the remote server(s). +Only +.B read (=r) +access to the +.B entry +pseudo-attribute and to the other attribute values of the entries +returned by the +.B search +operation is honored, which is performed by the frontend. + +.SH OVERLAYS +The LDAP backend provides basic proxying functionalities to many overlays. +The +.B chain +overlay, described in +.BR slapo\-chain (5), +and the +.B translucent +overlay, described in +.BR slapo\-translucent (5), +deserve a special mention. + +Conversely, there are many overlays that are best used in conjunction +with the LDAP backend. +The +.B proxycache +overlay allows caching of LDAP search requests (queries) +in a local database. +See +.BR slapo\-pcache (5) +for details. +The +.B rwm +overlay provides DN rewrite and attribute/objectClass mapping +capabilities to the underlying database. +See +.BR slapo\-rwm (5) +for details. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd\-meta (5), +.BR slapo\-chain (5), +.BR slapo\-pcache (5), +.BR slapo\-rwm (5), +.BR slapo\-translucent (5), +.BR slapd (8), +.BR ldap (3). +.SH AUTHOR +Howard Chu, with enhancements by Pierangelo Masarati diff --git a/doc/man/man5/slapd-ldif.5 b/doc/man/man5/slapd-ldif.5 new file mode 100644 index 0000000..3209fc4 --- /dev/null +++ b/doc/man/man5/slapd-ldif.5 @@ -0,0 +1,54 @@ +.TH SLAPD-LDIF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-ldif \- LDIF backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The LDIF backend to +.BR slapd (8) +is a basic storage backend that stores entries in text files in LDIF format, +and exploits the filesystem to create the tree structure of the database. +It is intended as a cheap, low performance easy to use backend, and it is +exploited by higher-level internal structures to provide a permanent +storage. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the LDIF backend database. +That is, they must follow a "database ldif" line and come before +any subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. +.TP +.B directory <dir> +Specify the directory where the database tree starts. The directory +must exist and grant appropriate permissions (rwx) to the identity slapd +is running with. +.SH ACCESS CONTROL +The +.B LDIF +backend does not honor any of the access control semantics described in +.BR slapd.access (5). +Only +.B read (=r) +access to the +.B entry +pseudo-attribute and to the other attribute values of the entries +returned by the +.B search +operation is honored, which is performed by the frontend. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8), +.BR ldif (5). +.SH AUTHOR +Eric Stokes diff --git a/doc/man/man5/slapd-mdb.5 b/doc/man/man5/slapd-mdb.5 new file mode 100644 index 0000000..a6bb77c --- /dev/null +++ b/doc/man/man5/slapd-mdb.5 @@ -0,0 +1,241 @@ +.TH SLAPD-MDB 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2011-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-mdb \- Memory-Mapped DB backend to slapd +.SH SYNOPSIS +.B ETCDIR/slapd.conf +.SH DESCRIPTION +The \fBmdb\fP backend to +.BR slapd (8) +uses OpenLDAP's Lightning Memory-Mapped DB (LMDB) library to store data. +It relies completely on the underlying operating system for memory +management and does no caching of its own. It is the recommended +primary database backend. +.LP +The \fBmdb\fP backend uses a hierarchical database layout which +supports subtree renames. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the \fBmdb\fP backend. +That is, they must follow a "backend mdb" line and +come before any subsequent "backend" or "database" lines. +.TP +.BI idlexp \ <exp> +Specify a power of 2 for the maximum size of an index slot. +The default is 16, yielding a maximum slot size of 2^16 or 65536. +Once set, this option applies to every \fBmdb\fP database instance. +The specified value must be in the range of 16-30. +.LP + +These +.B slapd.conf +options apply to the \fBmdb\fP backend database. +That is, they must follow a "database mdb" line and +come before any subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. +.TP +.BI checkpoint \ <kbyte>\ <min> +Specify the frequency for flushing the database disk buffers. +This setting is only needed if the \fBdbnosync\fP option is used. +The checkpoint will occur if either \fI<kbyte>\fP data has been written or +\fI<min>\fP minutes have passed since the last checkpoint. +Both arguments default to zero, in which case they are ignored. When +the \fI<min>\fP argument is non-zero, an internal task will run every +\fI<min>\fP minutes to perform the checkpoint. +Note: currently the \fI<kbyte>\fP setting is unimplemented. +.TP +.B dbnosync +Specify that on-disk database contents should not be immediately +synchronized with in memory changes. +Enabling this option may improve performance at the expense of data +security. In particular, if the operating system crashes before changes are +flushed, some number of transactions may be lost. +By default, a full data flush/sync is performed when each +transaction is committed. +.TP +.BI directory \ <directory> +Specify the directory where the LMDB files containing this database and +associated indexes live. +A separate directory must be specified for each database. +The default is +.BR LOCALSTATEDIR/openldap\-data . +.TP +\fBenvflags \fR{\fBnosync\fR,\fBnometasync\fR,\fBwritemap\fR,\fBmapasync\fR,\fBnordahead\fR} +Specify flags for finer-grained control of the LMDB library's operation. +.RS +.TP +.B nosync +This is exactly the same as the +.I dbnosync +directive. +.RE +.RS +.TP +.B nometasync +Flush the data on a commit, but skip the sync of the meta page. This mode is +slightly faster than doing a full sync, but can potentially lose the last +committed transaction if the operating system crashes. If both +.I nometasync +and +.I nosync +are set, the +.I nosync +flag takes precedence. +.RE +.RS +.TP +.B writemap +Use a writable memory map instead of just read-only. This speeds up write operations +but makes the database vulnerable to corruption in case any bugs in slapd +cause stray writes into the mmap region. +.RE +.RS +.TP +.B mapasync +When using a writable memory map and performing flushes on each commit, use an +asynchronous flush instead of a synchronous flush (the default). This option +has no effect if +.I writemap +has not been set. It also has no effect if +.I nosync +is set. +.RE +.RS +.TP +.B nordahead +Turn off file readahead. Usually the OS performs readahead on every read +request. This usually boosts read performance but can be harmful to +random access read performance if the system's memory is full and the DB +is larger than RAM. This option is not implemented on Windows. +.RE + +.TP +\fBindex \fR{\fI<attrlist>\fR|\fBdefault\fR} [\fBpres\fR,\fBeq\fR,\fBapprox\fR,\fBsub\fR,\fI<special>\fR] +Specify the indexes to maintain for the given attribute (or +list of attributes). +Some attributes only support a subset of indexes. +If only an \fI<attr>\fP is given, the indices specified for \fBdefault\fR +are maintained. +Note that setting a default does not imply that all attributes will be +indexed. Also, for best performance, an +.B eq +index should always be configured for the +.B objectClass +attribute. + +A number of special index parameters may be specified. +The index type +.B sub +can be decomposed into +.BR subinitial , +.BR subany ,\ and +.B subfinal +indices. +The special type +.B nolang +may be specified to disallow use of this index by language subtypes. +The special type +.B nosubtypes +may be specified to disallow use of this index by named subtypes. +Note: changing \fBindex\fP settings in +.BR slapd.conf (5) +requires rebuilding indices, see +.BR slapindex (8); +changing \fBindex\fP settings +dynamically by LDAPModifying "cn=config" automatically causes rebuilding +of the indices online in a background task. +.TP +.BI maxentrysize \ <bytes> +Specify the maximum size of an entry in bytes. Attempts to store +an entry larger than this size will be rejected with the error +LDAP_ADMINLIMIT_EXCEEDED. The default is 0, which is unlimited. +.TP +.BI maxreaders \ <integer> +Specify the maximum number of threads that may have concurrent read access +to the database. Tools such as slapcat count as a single thread, +in addition to threads in any active slapd processes. The +default is 126. +.TP +.BI maxsize \ <bytes> +Specify the maximum size of the database in bytes. A memory map of this +size is allocated at startup time and the database will not be allowed +to grow beyond this size. The default is 10485760 bytes. This setting +may be changed upward if the configured limit needs to be increased. + +Note: It is important to set this to as large a value as possible, +(relative to anticipated growth of the actual data over time) since +growing the size later may not be practical when the system is under +heavy load. +.TP +.BI mode \ <integer> +Specify the file protection mode that newly created database +files should have. +The default is 0600. +.TP +\fBmultival \fR{\fI<attrlist>\fR|\fBdefault\fR} \fI<integer hi>\fR,\fI<integer lo> +Specify the number of values for which a multivalued attribute is +stored in a separate table. Normally entries are stored as a single +blob inside the database. When an entry gets very large or contains +attributes with a very large number of values, modifications on that +entry may get very slow. Splitting the large attributes out to a separate +table can improve the performance of modification operations. +The threshold is specified as a pair of integers. If the number of +values exceeds the hi threshold the values will be split out. If +a modification deletes enough values to bring an attribute below +the lo threshold the values will be removed from the separate +table and merged back into the main entry blob. +The threshold can be set for a specific list of attributes, or +the default can be configured for all other attributes. +The default value for both hi and lo thresholds is UINT_MAX, which keeps +all attributes in the main blob. +.TP +.BI rtxnsize \ <entries> +Specify the maximum number of entries to process in a single read +transaction when executing a large search. Long-lived read transactions +prevent old database pages from being reused in write transactions, and +so can cause significant growth of the database file when there is +heavy write traffic. This setting causes the read transaction in +large searches to be released and reacquired after the given number +of entries has been read, to give writers the opportunity to +reclaim old database pages. The default is 10000. +.TP +.BI searchstack \ <depth> +Specify the depth of the stack used for search filter evaluation. +Search filters are evaluated on a stack to accommodate nested AND / OR +clauses. An individual stack is assigned to each server thread. +The depth of the stack determines how complex a filter can be +evaluated without requiring any additional memory allocation. Filters that +are nested deeper than the search stack depth will cause a separate +stack to be allocated for that particular search operation. These +allocations can have a major negative impact on server performance, +but specifying too much stack will also consume a great deal of memory. +Each search stack uses 512K bytes per level. The default stack depth +is 16, thus 8MB per thread is used. +.SH ACCESS CONTROL +The +.B mdb +backend honors access control semantics as indicated in +.BR slapd.access (5). +.SH FILES +.TP +.B ETCDIR/slapd.conf +default +.B slapd +configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8), +.BR slapadd (8), +.BR slapcat (8), +.BR slapindex (8), +.BR slapmodify (8), +OpenLDAP LMDB documentation. +.SH ACKNOWLEDGEMENTS +.so ../Project +Written by Howard Chu. diff --git a/doc/man/man5/slapd-meta.5 b/doc/man/man5/slapd-meta.5 new file mode 100644 index 0000000..2134ff6 --- /dev/null +++ b/doc/man/man5/slapd-meta.5 @@ -0,0 +1,1378 @@ +.TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it> +.\" $OpenLDAP$ +.\" +.\" Portions of this document should probably be moved to slapd-ldap(5) +.\" and maybe manual pages for librewrite. +.\" +.SH NAME +slapd\-meta \- metadirectory backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B meta +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 basic knowledge of the functionality of the +.BR slapd\-ldap (5) +backend is recommended. +This backend has been designed as an enhancement of the ldap backend. +The two backends share many features (actually they also share +portions of code). +While the +.B ldap +backend is intended to proxy operations directed to a single server, the +.B meta +backend is mainly intended for proxying of multiple servers and possibly +naming context masquerading. +These features, although useful in many scenarios, may result in +excessive overhead for some applications, so its use should be +carefully considered. +In the examples section, some typical scenarios will be discussed. + +The proxy instance of +.BR slapd (8) +must contain schema information for the attributes and objectClasses +used in filters, request DN and request-related data in general. +It should also contain schema information for the data returned +by the proxied server. +It is the responsibility of the proxy administrator to keep the schema +of the proxy lined up with that of the proxied server. + +.LP +Note: When looping back to the same instance of \fBslapd\fP(8), +each connection requires a new thread; as a consequence, the \fBslapd\fP(8) +\fBthreads\fP parameter may need some tuning. In those cases, unless the +multiple target feature is required, one may consider using \fBslapd\-relay\fP(5) instead, +which performs the relayed operation internally and thus reuses +the same connection. + +.SH EXAMPLES +There are examples in various places in this document, as well as in the +slapd/back-meta/data/ directory in the OpenLDAP source tree. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the META backend database. +That is, they must follow a "database meta" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. +.LP +Note: In early versions of back-ldap and back-meta it was recommended to always set +.LP +.RS +.nf +lastmod off +.fi +.RE +.LP +for +.B ldap +and +.B meta +databases. +This was required because operational attributes related to entry creation +and modification should not be proxied, as they could be mistakenly written +to the target server(s), generating an error. +The current implementation automatically sets lastmod to \fBoff\fP, +so its use is redundant and should be omitted. + +.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 conn\-pool\-max <int> +This directive defines the maximum size of the privileged connections pool. + +.TP +.B conn\-ttl <time> +This directive causes a cached connection to be dropped an recreated +after a given ttl, regardless of being idle or not. + +.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|<ttl>} +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 norefs <NO|yes> +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 <NO|yes> +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 <interval>,<num>[;<interval>,<num>[...]] +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. + +.TP +.B single\-conn {NO|yes} +Discards current cached connection when the client rebinds. + +.TP +.B use\-temporary\-conn {NO|yes} +when set to +.BR yes , +create a temporary connection whenever competing with other threads +for a shared one; otherwise, wait until the shared connection is available. + +.SH TARGET SPECIFICATION +Target specification starts with a "uri" directive: + +.TP +.B uri <protocol>://[<host>]/<naming context> [...] +The <protocol> part can be anything +.BR ldap_initialize (3) +accepts ({ldap|ldaps|ldapi} and variants); the <host> may be +omitted, defaulting to whatever is set in +.BR ldap.conf (5). +The <naming context> part is \fImandatory\fP for the first URI, +but it \fImust be omitted\fP for subsequent ones, if any. +The naming context part must be within the naming context defined for the backend, +e.g.: +.LP +.RS +.nf +suffix "\fBdc=foo,dc=com\fP" +uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP" +.fi + +.RE +.RS +The <naming context> part doesn't need to be unique across the targets; +it may also match one of the values of the "suffix" directive. +Multiple URIs may be defined in a single URI statement. +The additional URIs must be separate arguments and must not have any +<naming context> part. This causes the underlying library +to contact the first server of the list that responds. +For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows +of the same server, the directive +.LP +.nf +suffix "\fBdc=foo,dc=com\fP" +uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP" "ldap://l2.foo.com/" +.fi + +.RE +.RS +causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP +does not respond. +In that case, the URI list is internally rearranged, by moving unavailable +URIs to the end, so that further connection attempts occur with respect to +the last URI that succeeded. +.RE + +.TP +.B acl\-authcDN "<administrative DN for access control purposes>" +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> +Password used with the +.B acl\-authcDN +above. + +.TP +.B bind\-timeout <microseconds> +This directive defines the timeout, in microseconds, used when polling +for response after an asynchronous bind connection. The initial call +to ldap_result(3) is performed with a trade-off timeout of 100000 us; +if that results in a timeout exceeded, subsequent calls use the value +provided with +.BR bind\-timeout . +The default value is used also for subsequent calls if +.B bind\-timeout +is not specified. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.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|<size>} +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. +When set to a numeric value, Paged Results control is always +used with \fIsize\fP as the page size. +When set to \fIaccept\-unsolicited\fP, unsolicited Paged Results +control responses are accepted and honored +for compatibility with broken remote DSAs. +The client is not exposed to paged results handling +between +.BR slapd\-meta (5) +and the remote servers. +By default (disabled), Paged Results control is not used +and responses are not accepted. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B default\-target [<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 <target> as the default one, starting +from 1. +Target <target> must be defined. + +.TP +.B filter <pattern> +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 <authz-regexp> +if defined, selects what +.I local +identities are authorized to exploit the identity assertion feature. +The string +.B <authz\-regexp> +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=<simple DN>] [credentials=<simple password>] +.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>] +.B [authcId=<authentication ID>] [authzId=<authorization ID>] +.B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>] +.B [starttls=no|yes|critical] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<ciphers>] +.B [tls_protocol_min=<major>[.<minor>]] +.B [tls_crlcheck=none|peer|all] +.RS +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. +The identity defined by this directive, according to the properties +associated to the authentication method, is supposed to have auth access +on the target server to attributes used on the proxy for authentication +and authorization, and to be allowed to authorize the users. +This requires to have +.B proxyAuthz +privileges on a wide set of DNs, e.g. +.BR authzTo=dn.subtree:"" , +and the remote server to have +.B authz\-policy +set to +.B to +or +.BR both . +See +.BR slapd.conf (5) +for details on these statements and for remarks and drawbacks about +their usage. +The supported bindmethods are + +\fBnone|simple|sasl\fP + +where +.B none +is the default, i.e. no \fIidentity assertion\fP is performed. + +The +.B authz +parameter is used to instruct the SASL bind to exploit +.B native +SASL authorization, if available; since connections are cached, +this should only be used when authorizing with a fixed identity +(e.g. by means of the +.B authzDN +or +.B authzID +parameters). +Otherwise, the default +.B proxyauthz +is used, i.e. the proxyAuthz control (Proxied Authorization, RFC 4370) +is added to all operations. + +The supported modes are: + +\fB<mode> := {legacy|anonymous|none|self}\fP + +If +.B <mode> +is not present, and +.B authzId +is given, the proxy always authorizes that identity. +.B <authorization ID> +can be + +\fBu:<user>\fP + +\fB[dn:]<DN>\fP + +The former is supposed to be expanded by the remote server according +to the authz rules; see +.BR slapd.conf (5) +for details. +In the latter case, whether or not the +.B dn: +prefix is present, the string must pass DN validation and normalization. + +The default mode is +.BR legacy , +which implies that the proxy will either perform a simple bind as the +.I authcDN +or a SASL bind as the +.I authcID +and assert the client's identity when it is not anonymous. +Direct binds are always proxied. +The other modes imply that the proxy will always either perform a simple bind +as the +.IR authcDN +or a SASL bind as the +.IR authcID , +unless restricted by +.BR idassert\-authzFrom +rules (see below), in which case the operation will fail; +eventually, it will assert some other identity according to +.BR <mode> . +Other identity assertion modes are +.BR anonymous +and +.BR self , +which respectively mean that the +.I empty +or the +.IR client 's +identity +will be asserted; +.BR none , +which means that no proxyAuthz control will be used, so the +.I authcDN +or the +.I authcID +identity will be asserted. +For all modes that require the use of the +.I proxyAuthz +control, on the remote server the proxy identity must have appropriate +.I authzTo +permissions, or the asserted identities must have appropriate +.I authzFrom +permissions. Note, however, that the ID assertion feature is mostly +useful when the asserted identities do not exist on the remote server. +When +.I bindmethod +is +.BR SASL , +the +.I authcDN +must be specified in addition to the +.IR authcID , +although it is not used within the authentication process. + +Flags can be + +\fBoverride,[non\-]prescriptive,proxy\-authz\-[non\-]critical\fP + +When the +.B override +flag is used, identity assertion takes place even when the database +is authorizing for the identity of the client, i.e. after binding +with the provided identity, and thus authenticating it, the proxy +performs the identity assertion using the configured identity and +authentication method. + +When the +.B prescriptive +flag is used (the default), operations fail with +\fIinappropriateAuthentication\fP +for those identities whose assertion is not allowed by the +.B idassert\-authzFrom +patterns. +If the +.B non\-prescriptive +flag is used, operations are performed anonymously for those identities +whose assertion is not allowed by the +.B idassert\-authzFrom +patterns. + +When the +.B proxy\-authz\-non\-critical +flag is used (the default), the proxyAuthz control is not marked as critical, +in violation of RFC 4370. Use of +.B proxy\-authz\-critical +is recommended. + +The TLS settings default to the same as the main slapd TLS settings, +except for +.B tls_reqcert +which defaults to "demand", and +.B tls_reqsan +which defaults to "allow".. + +The identity associated to this directive is also used for privileged +operations whenever \fBidassert\-bind\fP is defined and \fBacl\-bind\fP +is not. See \fBacl\-bind\fP for details. +.RE + +.TP +.B idle\-timeout <time> +This directive causes a cached connection to be dropped an recreated +after it has been idle for the specified time. +The value can be specified as + +[<d>d][<h>h][<m>m][<s>[s]] + +where <d>, <h>, <m> and <s> are respectively treated as days, hours, +minutes and seconds. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B keepalive <idle>:<probes>:<interval> +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. + +.TP +.B tcp\-user\-timeout <milliseconds> +If non-zero, corresponds to the +.B TCP_USER_TIMEOUT +set on the target 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. + +.TP +.B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}" +This maps object classes and attributes as in the LDAP backend. +See +.BR slapd\-ldap (5). + +.TP +.B network\-timeout <time> +Sets the network timeout value after which +.BR poll (2)/ select (2) +following a +.BR connect (2) +returns in case of no activity. +The value is in seconds, and it can be specified as for +.BR idle\-timeout . +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B nretries {forever|never|<nretries>} +This directive defines how many times a bind should be retried +in case of temporary failure in contacting a target. If defined +before any target specification, it applies to all targets (by default, +.BR 3 +times); +the global value can be overridden by redefinitions inside each target +specification. + +.TP +.B rewrite* ... +The rewrite options are described in the "REWRITING" section. + +.TP +.B subtree\-{exclude|include} "<rule>" +This directive allows one to indicate what subtrees are actually served +by a target. +The syntax of the supported rules is + +\fB<rule>: [dn[.<style>]:]<pattern>\fP + +\fB<style>: subtree|children|regex\fP + +When \fB<style>\fP is either \fBsubtree\fP or \fBchildren\fP +the \fB<pattern>\fP is a DN that must be within the naming context +served by the target. +When \fB<style>\fP is \fBregex\fP the \fB<pattern>\fP is a +.BR regex (5) +pattern. +If the \fBdn.<style>:\fP prefix is omitted, \fBdn.subtree:\fP +is implicitly assumed for backward compatibility. + +In the +.B subtree\-exclude +form if the \fIrequest DN\fP matches at least one rule, +the target is not considered while fulfilling the request; +otherwise, the target is considered based on the value of the \fIrequest DN\fP. +When the request is a search, also the \fIscope\fP is considered. + +In the +.B subtree\-include +form if the \fIrequest DN\fP matches at least one rule, +the target is considered while fulfilling the request; +otherwise the target is ignored. + +.LP +.RS +.nf + | match | exclude | + +---------+---------+-------------------+ + | T | T | not candidate | + | F | T | continue checking | + +---------+---------+-------------------+ + | T | F | candidate | + | F | F | not candidate | + +---------+---------+-------------------+ +.fi + +.RE +.RS +There may be multiple occurrences of the +.B subtree\-exclude +or +.B subtree\-include +directive for each of the targets, but they are mutually exclusive. +.RE + +.TP +.B suffixmassage "<virtual naming context>" "<real naming context>" +All the directives starting with "rewrite" refer to the rewrite engine +that has been added to slapd. +The "suffixmassage" directive was introduced in the LDAP backend to +allow suffix massaging while proxying. +It has been obsoleted by the rewriting tools. +However, both for backward compatibility and for ease of configuration +when simple suffix massage is required, it has been preserved. +It wraps the basic rewriting instructions that perform suffix +massaging. See the "REWRITING" section for a detailed list +of the rewrite rules it implies. + +.TP +.B t\-f\-support {NO|yes|discover} +enable if the remote server supports absolute filters +(see \fIRFC 4526\fP for details). +If set to +.BR discover , +support is detected by reading the remote server's root DSE. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B timeout [<op>=]<val> [...] +This directive allows one to set per-operation timeouts. +Operations can be + +\fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP + +The overall duration of the \fBsearch\fP operation is controlled either +by the \fBtimelimit\fP parameter or by server-side enforced +time limits (see \fBtimelimit\fP and \fBlimits\fP in +.BR slapd.conf (5) +for details). +This \fBtimeout\fP parameter controls how long the target can be +irresponsive before the operation is aborted. +Timeout is meaningless for the remaining operations, +\fBunbind\fP and \fBabandon\fP, which do not imply any response, +while it is not yet implemented in currently supported \fBextended\fP +operations. +If no operation is specified, the timeout \fBval\fP affects all +supported operations. +If specified before any target definition, it affects all targets +unless overridden by per-target directives. + +Note: if the timeout is exceeded, the operation is cancelled +(according to the \fBcancel\fP directive); +the protocol does not provide any means to rollback operations, +so the client will not be notified about the result of the operation, +which may eventually succeeded or not. +In case the timeout is exceeded during a bind operation, the connection +is destroyed, according to RFC4511. + +.TP +.B tls {none|[try\-]start|[try\-]propagate|ldaps} +.B [starttls=no] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_crlcheck=none|peer|all] +.RS +Specify TLS settings regular connections. + +If the first parameter is not "none" then this configures the TLS +settings to be used for regular connections. +The StartTLS extended operation will be used when establishing the +connection unless the URI directive protocol scheme is \fBldaps://\fP. +In that case this keyword may only be set to "ldaps" and the StartTLS +operation will not be used. + +With \fBpropagate\fP, the proxy issues the StartTLS operation only if +the original connection has a TLS layer set up. +The \fBtry\-\fP prefix instructs the proxy to continue operations +if the StartTLS operation failed; its use is \fBnot\fP recommended. + +The TLS settings default to the same as the main slapd TLS settings, +except for +.B tls_reqcert +which defaults to "demand", +.B tls_reqsan +which defaults to "allow", and +.B starttls +which is overshadowed by the first keyword and thus ignored. + +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. +.RE + +.SH SCENARIOS +A powerful (and in some sense dangerous) rewrite engine has been added +to both the LDAP and Meta backends. +While the former can gain limited beneficial effects from rewriting +stuff, the latter can become an amazingly powerful tool. +.LP +Consider a couple of scenarios first. +.LP +1) Two directory servers share two levels of naming context; +say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com". +Then, an unambiguous Meta database can be configured as: +.LP +.RS +.nf +database meta +suffix "\fBdc=foo,dc=com\fP" +uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP" +uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP" +.fi +.RE +.LP +Operations directed to a specific target can be easily resolved +because there are no ambiguities. +The only operation that may resolve to multiple targets is a search +with base "dc=foo,dc=com" and scope at least "one", which results in +spawning two searches to the targets. +.LP +2a) Two directory servers don't share any portion of naming context, +but they'd present as a single DIT +[Caveat: uniqueness of (massaged) entries among the two servers is +assumed; integrity checks risk to incur in excessive overhead and have +not been implemented]. +Say we have "dc=bar,dc=org" and "o=Foo,c=US", +and we'd like them to appear as branches of "dc=foo,dc=com", say +"dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com". +Then we need to configure our Meta backend as: +.LP +.RS +.nf +database meta +suffix "dc=foo,dc=com" + +uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP" +suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org" + +uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP" +suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US" +.fi +.RE +.LP +Again, operations can be resolved without ambiguity, although +some rewriting is required. +Notice that the virtual naming context of each target is a branch of +the database's naming context; it is rewritten back and forth when +operations are performed towards the target servers. +What "back and forth" means will be clarified later. +.LP +When a search with base "dc=foo,dc=com" is attempted, if the +scope is "base" it fails with "no such object"; in fact, the +common root of the two targets (prior to massaging) does not +exist. +If the scope is "one", both targets are contacted with the base +replaced by each target's base; the scope is derated to "base". +In general, a scope "one" search is honored, and the scope is derated, +only when the incoming base is at most one level lower of a target's +naming context (prior to massaging). +.LP +Finally, if the scope is "sub" the incoming base is replaced +by each target's unmassaged naming context, and the scope +is not altered. +.LP +2b) Consider the above reported scenario with the two servers +sharing the same naming context: +.LP +.RS +.nf +database meta +suffix "\fBdc=foo,dc=com\fP" + +uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP" +suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org" + +uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP" +suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US" +.fi +.RE +.LP +All the previous considerations hold, except that now there is +no way to unambiguously resolve a DN. +In this case, all the operations that require an unambiguous target +selection will fail unless the DN is already cached or a default +target has been set. +Practical configurations may result as a combination of all the +above scenarios. +.SH ACLs +Note on ACLs: at present you may add whatever ACL rule you desire +to the Meta (and LDAP) backends. +However, the meaning of an ACL on a proxy may require some +considerations. +Two philosophies may be considered: +.LP +a) the remote server dictates the permissions; the proxy simply passes +back what it gets from the remote server. +.LP +b) the remote server unveils "everything"; the proxy is responsible +for protecting data from unauthorized access. +.LP +Of course the latter sounds unreasonable, but it is not. +It is possible to imagine scenarios in which a remote host discloses +data that can be considered "public" inside an intranet, and a proxy +that connects it to the internet may impose additional constraints. +To this purpose, the proxy should be able to comply with all the ACL +matching criteria that the server supports. +This has been achieved with regard to all the criteria supported by +slapd except a special subtle case (please file an ITS if you can +find other exceptions: <http://www.openldap.org/its/>). +The rule +.LP +.RS +.nf +access to dn="<dn>" attrs=<attr> + by dnattr=<dnattr> read + by * none +.fi +.RE +.LP +cannot be matched iff the attribute that is being requested, <attr>, +is NOT <dnattr>, and the attribute that determines membership, +<dnattr>, has not been requested (e.g. in a search) +.LP +In fact this ACL is resolved by slapd using the portion of entry it +retrieved from the remote server without requiring any further +intervention of the backend, so, if the <dnattr> attribute has not +been fetched, the match cannot be assessed because the attribute is +not present, not because no value matches the requirement! +.LP +Note on ACLs and attribute mapping: ACLs are applied to the mapped +attributes; for instance, if the attribute locally known as "foo" is +mapped to "bar" on a remote server, then local ACLs apply to attribute +"foo" and are totally unaware of its remote name. +The remote server will check permissions for "bar", and the local +server will possibly enforce additional restrictions to "foo". +.\" +.\" If this section is moved, also update the reference in +.\" libraries/librewrite/RATIONALE. +.\" +.SH REWRITING +A string is rewritten according to a set of rules, called a `rewrite +context'. +The rules are based on POSIX (''extended'') regular expressions (regex) +with substring matching; basic variable substitution and map resolution +of substrings is allowed by specific mechanisms detailed in the following. +The behavior of pattern matching/substitution can be altered by a set +of flags. +.LP +The underlying concept is to build a lightweight rewrite module +for the slapd server (initially dedicated to the LDAP backend). +.SH Passes +An incoming string is matched against a set of rules. +Rules are made of a regex match pattern, a substitution pattern +and a set of actions, described by a set of flags. +In case of match a string rewriting is performed according to the +substitution pattern that allows one to refer to substrings matched in the +incoming string. +The actions, if any, are finally performed. +The substitution pattern allows map resolution of substrings. +A map is a generic object that maps a substitution pattern to a value. +The flags are divided in "Pattern matching Flags" and "Action Flags"; +the former alter the regex match pattern behavior while the latter +alter the action that is taken after substitution. +.SH "Pattern Matching Flags" +.TP +.B `C' +honors case in matching (default is case insensitive) +.TP +.B `R' +use POSIX ''basic'' regular expressions (default is ''extended'') +.TP +.B `M{n}' +allow no more than +.B n +recursive passes for a specific rule; does not alter the max total count +of passes, so it can only enforce a stricter limit for a specific rule. +.SH "Action Flags" +.TP +.B `:' +apply the rule once only (default is recursive) +.TP +.B `@' +stop applying rules in case of match; the current rule is still applied +recursively; combine with `:' to apply the current rule only once +and then stop. +.TP +.B `#' +stop current operation if the rule matches, and issue an `unwilling to +perform' error. +.TP +.B `G{n}' +jump +.B n +rules back and forth (watch for loops!). +Note that `G{1}' is implicit in every rule. +.TP +.B `I' +ignores errors in rule; this means, in case of error, e.g. issued by a +map, the error is treated as a missed match. +The `unwilling to perform' is not overridden. +.TP +.B `U{n}' +uses +.B +n +as return code if the rule matches; the flag does not alter the recursive +behavior of the rule, so, to have it performed only once, it must be used +in combination with `:', e.g. +.B `:U{16}' +returns the value `16' after exactly one execution of the rule, if the +pattern matches. +As a consequence, its behavior is equivalent to `@', with the return +code set to +.BR n ; +or, in other words, `@' is equivalent to `U{0}'. +By convention, the freely available codes are above 16 included; +the others are reserved. +.LP +The ordering of the flags can be significant. +For instance: `IG{2}' means ignore errors and jump two lines ahead +both in case of match and in case of error, while `G{2}I' means ignore +errors, but jump two lines ahead only in case of match. +.LP +More flags (mainly Action Flags) will be added as needed. +.SH "Pattern matching:" +See +.BR regex (7) +and/or +.BR re_format (7). +.SH "Substitution Pattern Syntax:" +Everything starting with `%' requires substitution; +.LP +the only obvious exception is `%%', which is left as is; +.LP +the basic substitution is `%d', where `d' is a digit; +0 means the whole string, while 1-9 is a submatch; +.LP +a `%' followed by a `{' invokes an advanced substitution. +The pattern is: +.LP +.RS +`%' `{' [ <op> ] <name> `(' <substitution> `)' `}' +.RE +.LP +where <name> must be a legal name for the map, i.e. +.LP +.RS +.nf +<name> ::= [a-z][a-z0-9]* (case insensitive) +<op> ::= `>' `|' `&' `&&' `*' `**' `$' +.fi +.RE +.LP +and <substitution> must be a legal substitution +pattern, with no limits on the nesting level. +.LP +The operators are: +.TP +.B > +sub context invocation; <name> must be a legal, already defined +rewrite context name +.TP +.B | +external command invocation; <name> must refer to a legal, already +defined command name (NOT IMPL.) +.TP +.B & +variable assignment; <name> defines a variable in the running +operation structure which can be dereferenced later; operator +.B & +assigns a variable in the rewrite context scope; operator +.B && +assigns a variable that scopes the entire session, e.g. its value +can be dereferenced later by other rewrite contexts +.TP +.B * +variable dereferencing; <name> must refer to a variable that is +defined and assigned for the running operation; operator +.B * +dereferences a variable scoping the rewrite context; operator +.B ** +dereferences a variable scoping the whole session, e.g. the value +is passed across rewrite contexts +.TP +.B $ +parameter dereferencing; <name> must refer to an existing parameter; +the idea is to make some run-time parameters set by the system +available to the rewrite engine, as the client host name, the bind DN +if any, constant parameters initialized at config time, and so on; +no parameter is currently set by either +.B back\-ldap +or +.BR back\-meta , +but constant parameters can be defined in the configuration file +by using the +.B rewriteParam +directive. +.LP +Substitution escaping has been delegated to the `%' symbol, +which is used instead of `\e' in string substitution patterns +because `\e' is already escaped by slapd's low level parsing routines; +as a consequence, regex escaping requires two `\e' symbols, +e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'. +.\" +.\" The symbol can be altered at will by redefining the related macro in +.\" "rewrite-int.h". +.\" +.SH "Rewrite context:" +A rewrite context is a set of rules which are applied in sequence. +The basic idea is to have an application initialize a rewrite +engine (think of Apache's mod_rewrite ...) with a set of rewrite +contexts; when string rewriting is required, one invokes the +appropriate rewrite context with the input string and obtains the +newly rewritten one if no errors occur. +.LP +Each basic server operation is associated to a rewrite context; +they are divided in two main groups: client \-> server and +server \-> client rewriting. +.LP +client \-> server: +.LP +.RS +.nf +(default) if defined and no specific context + is available +bindDN bind +searchBase search +searchFilter search +searchFilterAttrDN search +compareDN compare +compareAttrDN compare AVA +addDN add +addAttrDN add AVA +modifyDN modify +modifyAttrDN modify AVA +modrDN modrdn +newSuperiorDN modrdn +deleteDN delete +exopPasswdDN password modify extended operation DN if proxy +.fi +.RE +.LP +server \-> client: +.LP +.RS +.nf +searchResult search (only if defined; no default; + acts on DN and DN-syntax attributes + of search results) +searchAttrDN search AVA +matchedDN all ops (only if applicable) +.fi +.RE +.LP +.SH "Basic configuration syntax" +.TP +.B rewriteEngine { on | off } +If `on', the requested rewriting is performed; if `off', no +rewriting takes place (an easy way to stop rewriting without +altering too much the configuration file). +.TP +.B rewriteContext <context name> "[ alias <aliased context name> ]" +<Context name> is the name that identifies the context, i.e. the name +used by the application to refer to the set of rules it contains. +It is used also to reference sub contexts in string rewriting. +A context may alias another one. +In this case the alias context contains no rule, and any reference to +it will result in accessing the aliased one. +.TP +.B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]" +Determines how a string can be rewritten if a pattern is matched. +Examples are reported below. +.SH "Additional configuration syntax:" +.TP +.B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]" +Allows one to define a map that transforms substring rewriting into +something else. +The map is referenced inside the substitution pattern of a rule. +.TP +.B rewriteParam <param name> <param value> +Sets a value with global scope, that can be dereferenced by the +command `%{$paramName}'. +.TP +.B rewriteMaxPasses <number of passes> [<number of passes per rule>] +Sets the maximum number of total rewriting passes that can be +performed in a single rewrite operation (to avoid loops). +A safe default is set to 100; note that reaching this limit is still +treated as a success; recursive invocation of rules is simply +interrupted. +The count applies to the rewriting operation as a whole, not +to any single rule; an optional per-rule limit can be set. +This limit is overridden by setting specific per-rule limits +with the `M{n}' flag. +.SH "Configuration examples:" +.nf +# set to `off' to disable rewriting +rewriteEngine on + +# the rules the "suffixmassage" directive implies +rewriteEngine on +# all dataflow from client to server referring to DNs +rewriteContext default +rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":" +# empty filter rule +rewriteContext searchFilter +# all dataflow from server to client +rewriteContext searchResult +rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":" +rewriteContext searchAttrDN alias searchResult +rewriteContext matchedDN alias searchResult + +# Everything defined here goes into the `default' context. +# This rule changes the naming context of anything sent +# to `dc=home,dc=net' to `dc=OpenLDAP, dc=org' + +rewriteRule "(.*)dc=home,[ ]?dc=net" + "%1dc=OpenLDAP, dc=org" ":" + +# since a pretty/normalized DN does not include spaces +# after rdn separators, e.g. `,', this rule suffices: + +rewriteRule "(.*)dc=home,dc=net" + "%1dc=OpenLDAP,dc=org" ":" + +# Start a new context (ends input of the previous one). +# This rule adds blanks between DN parts if not present. +rewriteContext addBlanks +rewriteRule "(.*),([^ ].*)" "%1, %2" + +# This one eats blanks +rewriteContext eatBlanks +rewriteRule "(.*),[ ](.*)" "%1,%2" + +# Here control goes back to the default rewrite +# context; rules are appended to the existing ones. +# anything that gets here is piped into rule `addBlanks' +rewriteContext default +rewriteRule ".*" "%{>addBlanks(%0)}" ":" + +.\" # Anything with `uid=username' is looked up in +.\" # /etc/passwd for gecos (I know it's nearly useless, +.\" # but it is there just as a guideline to implementing +.\" # custom maps). +.\" # Note the `I' flag that leaves `uid=username' in place +.\" # if `username' does not have a valid account, and the +.\" # `:' that forces the rule to be processed exactly once. +.\" rewriteContext uid2Gecos +.\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)" +.\" "%1cn=%2{xpasswd},%3" "I:" +.\" +.\" # Finally, in a bind, if one uses a `uid=username' DN, +.\" # it is rewritten in `cn=name surname' if possible. +.\" rewriteContext bindDN +.\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":" +.\" +# Rewrite the search base according to `default' rules. +rewriteContext searchBase alias default + +# Search results with OpenLDAP DN are rewritten back with +# `dc=home,dc=net' naming context, with spaces eaten. +rewriteContext searchResult +rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org" + "%{>eatBlanks(%1)}dc=home,dc=net" ":" + +# Bind with email instead of full DN: we first need +# an ldap map that turns attributes into a DN (the +# argument used when invoking the map is appended to +# the URI and acts as the filter portion) +rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub" + +# Then we need to detect DN made up of a single email, +# e.g. `mail=someone@example.com'; note that the rule +# in case of match stops rewriting; in case of error, +# it is ignored. In case we are mapping virtual +# to real naming contexts, we also need to rewrite +# regular DNs, because the definition of a bindDn +# rewrite context overrides the default definition. +rewriteContext bindDN +rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I" + +# This is a rather sophisticated example. It massages a +# search filter in case who performs the search has +# administrative privileges. First we need to keep +# track of the bind DN of the incoming request, which is +# stored in a variable called `binddn' with session scope, +# and left in place to allow regular binding: +rewriteContext bindDN +rewriteRule ".+" "%{&&binddn(%0)}%0" ":" + +# A search filter containing `uid=' is rewritten only +# if an appropriate DN is bound. +# To do this, in the first rule the bound DN is +# dereferenced, while the filter is decomposed in a +# prefix, in the value of the `uid=<arg>' AVA, and +# in a suffix. A tag `<>' is appended to the DN. +# If the DN refers to an entry in the `ou=admin' subtree, +# the filter is rewritten OR-ing the `uid=<arg>' with +# `cn=<arg>'; otherwise it is left as is. This could be +# useful, for instance, to allow apache's auth_ldap-1.4 +# module to authenticate users with both `uid' and +# `cn', but only if the request comes from a possible +# `cn=Web auth,ou=admin,dc=home,dc=net' user. +rewriteContext searchFilter +rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)" + "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}" + ":I" +rewriteRule "[^,]+,ou=admin,dc=home,dc=net" + "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I" +rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":" + +# This example shows how to strip unwanted DN-valued +# attribute values from a search result; the first rule +# matches DN values below "ou=People,dc=example,dc=com"; +# in case of match the rewriting exits successfully. +# The second rule matches everything else and causes +# the value to be rejected. +rewriteContext searchResult +rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@" +rewriteRule ".*" "" "#" +.fi +.SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):" +In case the rewritten DN is an LDAP URI, the operation is initiated +towards the host[:port] indicated in the uri, if it does not refer +to the local server. +E.g.: +.LP +.nf + rewriteRule '^cn=root,.*' '%0' 'G{3}' + rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@' + rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@' + rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@' +.fi +.LP +(Rule 1 is simply there to illustrate the `G{n}' action; it could have +been written: +.LP +.nf + rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@' +.fi +.LP +with the advantage of saving one rewrite pass ...) + +.SH ACCESS CONTROL +The +.B meta +backend does not honor all ACL semantics as described in +.BR slapd.access (5). +In general, access checking is delegated to the remote server(s). +Only +.B read (=r) +access to the +.B entry +pseudo-attribute and to the other attribute values of the entries +returned by the +.B search +operation is honored, which is performed by the frontend. + +.SH PROXY CACHE OVERLAY +The proxy cache overlay +allows caching of LDAP search requests (queries) in a local database. +See +.BR slapo\-pcache (5) +for details. + +.SH DEPRECATED STATEMENTS +The following statements have been deprecated and should no longer be used. + +.TP +.B pseudorootdn "<substitute DN in case of rootdn bind>" +Use +.B idassert\-bind +instead. + +.TP +.B pseudorootpw "<substitute password in case of rootdn bind>" +Use +.B idassert\-bind +instead. + + + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-asyncmeta (5), +.BR slapd\-ldap (5), +.BR slapo\-pcache (5), +.BR slapd (8), +.BR regex (7), +.BR re_format (7). +.SH AUTHOR +Pierangelo Masarati, based on back-ldap by Howard Chu diff --git a/doc/man/man5/slapd-monitor.5 b/doc/man/man5/slapd-monitor.5 new file mode 100644 index 0000000..84a85ba --- /dev/null +++ b/doc/man/man5/slapd-monitor.5 @@ -0,0 +1,126 @@ +.TH SLAPD-MONITOR 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-monitor \- Monitor backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B monitor +backend to +.BR slapd (8) +is not an actual database; if enabled, it is automatically generated +and dynamically maintained by +.B slapd +with information about the running status of the daemon. +.LP +To inspect all monitor information, issue a subtree search with base +cn=Monitor, requesting that attributes "+" and "*" are returned. +The monitor backend produces mostly operational attributes, and LDAP +only returns operational attributes that are explicitly requested. +Requesting attribute "+" is an extension which requests all operational +attributes. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the +.B monitor +backend database. +That is, they must follow a "database monitor" line and come before any +subsequent "backend" or "database" lines. +.LP +As opposed to most databases, the +.B monitor +database can be instantiated only once, i.e. only one occurrence +of "database monitor" can occur in the +.BR slapd.conf (5) +file. +Moreover, the suffix of the database cannot be explicitly set by means +of the +.B suffix +directive. +The suffix is automatically set +to "\fIcn=Monitor\fP". +.LP +The +.B monitor +database honors the +.B rootdn +and the +.B rootpw +directives, and the usual ACL directives, e.g. the +.B access +directive. +.\".LP +.\"The following directives can be used: +.\".TP +.\".BI l \ <locality> +.\"The additional argument \fI<locality>\fP, +.\"a string, is added to the "\fIcn=Monitor\fP" entry as value of the +.\".B l +.\"attribute (Note: this may be subjected to changes). +.LP +Other database options are described in the +.BR slapd.conf (5) +manual page. +.SH USAGE +The usage is: +.TP +1) enable the \fBmonitor\fP backend at configure: +.LP +.RS +.nf +configure \-\-enable\-monitor +.fi +.RE +.TP +2) activate the \fBmonitor\fP database in the \fBslapd.conf\fP(5) file: +.LP +.RS +.nf +database monitor +.fi +.RE +.TP +3) add ACLs as detailed in \fBslapd.access\fP(5) to control access to the database, e.g.: +.LP +.RS +.nf +access to dn.subtree="cn=Monitor" + by dn.exact="uid=Admin,dc=my,dc=org" write + by users read + by * none +.fi +.RE +.TP +4) ensure that the \fBcore.schema\fP file is loaded. +The +.B monitor +backend relies on some standard track attributeTypes +that must be already defined when the backend is started. +.SH ACCESS CONTROL +The +.B monitor +backend honors access control semantics as indicated in +.BR slapd.access (5), +including the +.B disclose +access privilege, on all currently implemented operations. +.SH KNOWN LIMITATIONS +The +.B monitor +backend does not honor size/time limits in search operations. +.SH FILES +.TP +.B ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd.access (5), +.BR slapd (8), +.BR ldap (3). +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapd-ndb.5 b/doc/man/man5/slapd-ndb.5 new file mode 100644 index 0000000..ead0651 --- /dev/null +++ b/doc/man/man5/slapd-ndb.5 @@ -0,0 +1,127 @@ +.TH SLAPD-NDB 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2008-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-ndb \- MySQL NDB backend to slapd +.SH SYNOPSIS +.B ETCDIR/slapd.conf +.SH DESCRIPTION +The \fBndb\fP backend to +.BR slapd (8) +uses the MySQL Cluster package to store data, through its NDB API. +It provides fault tolerance with extreme scalability, along with +a degree of SQL compatibility. +.LP +This backend is designed to store LDAP information using tables that +are also visible from SQL. It uses a higher level SQL API for creating +these tables, while using the low level NDB API for storing and +retrieving the data within these tables. The NDB Cluster engine +allows data to be partitioned across multiple data nodes, and this +backend allows multiple slapd instances to operate against a given +database concurrently. +.LP +The general approach is to use distinct tables for each LDAP object class. +Entries comprised of multiple object classes will have their data +spread across multiple tables. The data tables use a 64 bit entryID +as their primary key. The DIT hierarchy is maintained in a separate +table, which maps DNs to entryIDs. +.LP +This backend is experimental. While intended to be a general-purpose +backend, it is currently missing a number of common LDAP features. +See the \fBTODO\fP file in the source directory for details. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the \fBndb\fP backend database. +That is, they must follow a "database ndb" line and +come before any subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. + +.SH DATA SOURCE CONFIGURATION + +.TP +.B dbhost <hostname> +The name or IP address of the host running the MySQL server. The default +is "localhost". On Unix systems, the connection to a local server is made +using a Unix Domain socket, whose path is specified using the +.B dbsocket +directive. +.TP +.B dbuser <username> +The MySQL login ID to use when connecting to the MySQL server. The chosen +user must have sufficient privileges to manipulate the SQL tables in the +target database. +.TP +.B dbpasswd <password> +The password for the \fBdbuser\fP. +.TP +.B dbname <database name> +The name of the MySQL database to use. +.TP +.B dbport <port> +The port number to use for the TCP connection to the MySQL server. +.TP +.B dbsocket <path> +The socket to be used for connecting to a local MySQL server. +.TP +.B dbflag <integer> +Client flags for the MySQL session. See the MySQL documentation for details. +.TP +.B dbconnect <connectstring> +The name or IP address of the host running the cluster manager. The default +is "localhost". +.TP +.B dbconnections <integer> +The number of cluster connections to establish. Using up to 4 may improve +performance under heavier load. The default is 1. + +.SH SCHEMA CONFIGURATION +.TP +.B attrlen <attribute> <length> +Specify the column length to use for a particular attribute. LDAP attributes are +stored in individual columns of the SQL tables. The maximum column lengths for +each column must be specified when creating these tables. If a length constraint +was specified in the attribute's LDAP schema definition, that value will be used +by default. If the schema didn't specify a constraint, the default is 128 bytes. +Currently the maximum is 1024. +.TP +.B index <attr[,attr...]> +Specify a list of attributes for which indexing should be maintained. +Currently there is no support for substring indexing; a single index structure +provides presence, equality, and inequality indexing for the specified attributes. +.TP +.B attrset <set> <attrs> +Specify a list of attributes to be treated as an attribute set. This directive +creates a table named \fIset\fP which will contain all of the listed attributes. +Ordinarily an attribute resides in a table named by an object class that uses +the attribute. However, attributes are only allowed to appear in a single table. +For attributes that are derived from an inherited object class definition, +the attribute will only be stored in the superior class's table. +Attribute sets should be defined for any attributes that are used in multiple +unrelated object classes, i.e., classes that are not connected by a simple +inheritance chain. +.SH ACCESS CONTROL +The +.B ndb +backend honors most access control semantics as indicated in +.BR slapd.access (5). +.SH FILES +.TP +.B ETCDIR/slapd.conf +default +.B slapd +configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8), +.BR slapadd (8), +.BR slapcat (8), +.BR slapindex (8), +.BR slapmodify (8), +MySQL Cluster documentation. +.SH AUTHOR +Howard Chu, with assistance from Johan Andersson et al @ MySQL. diff --git a/doc/man/man5/slapd-null.5 b/doc/man/man5/slapd-null.5 new file mode 100644 index 0000000..f091ed6 --- /dev/null +++ b/doc/man/man5/slapd-null.5 @@ -0,0 +1,72 @@ +.TH SLAPD-NULL 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2002-2022 The OpenLDAP Foundation. All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-null \- Null backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Null backend to +.BR slapd (8) +is surely the most useful part of +.BR slapd : +.br +- Searches return success but no entries. +.br +- Compares return compareFalse. +.br +- Updates return success (unless readonly is on) but do nothing. +.br +- Binds other than as the rootdn fail unless the database option "bind +on" is given. +.br +- The +.BR slapadd (8) +and +.BR slapcat (8) +tools are equally exciting. +.br +Inspired by the /dev/null device. +.SH CONFIGURATION +This +.B slapd.conf +option applies to the NULL backend database. +That is, it must follow a "database null" line and come before +any subsequent "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. +.TP +.B bind <on/off> +Allow binds as any DN in this backend's suffix, with any password. +The default is "off". +.TP +.B dosearch <on/off> +If enabled, a single entry will be returned on all search requests. +The entry's DN will be the same as the database suffix. +The default is "off". +.SH EXAMPLE +Here is a possible slapd.conf extract using the Null backend: +.LP +.RS +.nf +database null +suffix "cn=Nothing" +bind on +.fi +.RE +.SH ACCESS CONTROL +The +.B null +backend does not honor any of the access control semantics described in +.BR slapd.access (5). +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd (8), +.BR slapadd (8), +.BR slapcat (8). diff --git a/doc/man/man5/slapd-passwd.5 b/doc/man/man5/slapd-passwd.5 new file mode 100644 index 0000000..6b51333 --- /dev/null +++ b/doc/man/man5/slapd-passwd.5 @@ -0,0 +1,56 @@ +.TH SLAPD-PASSWD 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-passwd \- /etc/passwd backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The PASSWD backend to +.BR slapd (8) +serves up the user account information listed in the system +.BR passwd (5) +file. This backend is provided for demonstration purposes only. +The DN of each entry is "uid=<username>,<suffix>". +Note that non-base searches scan the entire passwd file, and +are best suited for hosts with small passwd files. +.SH CONFIGURATION +This +.B slapd.conf +option applies to the PASSWD backend database. +That is, it must follow a "database passwd" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. +.TP +.B file <filename> +Specifies an alternate passwd file to use. +The default is +.BR /etc/passwd . +.SH ACCESS CONTROL +The +.B passwd +backend does not honor any of the access control semantics described in +.BR slapd.access (5). +Only +.B read (=r) +access to the +.B entry +pseudo-attribute and to the other attribute values of the entries +returned by the +.B search +operation is honored, which is performed by the frontend. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +/etc/passwd +user account information +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd (8), +.BR passwd (5). diff --git a/doc/man/man5/slapd-perl.5 b/doc/man/man5/slapd-perl.5 new file mode 100644 index 0000000..f0fddd5 --- /dev/null +++ b/doc/man/man5/slapd-perl.5 @@ -0,0 +1,199 @@ +.TH SLAPD-PERL 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.SH NAME +slapd\-perl \- Perl backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Perl backend to +.BR slapd (8) +works by embedding a +.BR perl (1) +interpreter into +.BR slapd (8). +Any perl database section of the configuration file +.BR slapd.conf (5) +must then specify what Perl module to use. +.B Slapd +then creates a new Perl object that handles all the requests for that +particular instance of the backend. +.LP +You will need to create a method for each one of the +following actions: +.LP +.nf + * new # creates a new object, + * search # performs the ldap search, + * compare # does a compare, + * modify # modifies an entry, + * add # adds an entry to backend, + * modrdn # modifies an entry's rdn, + * delete # deletes an ldap entry, + * config # module-specific config directives, + * init # called after backend is initialized. +.fi +.LP +Unless otherwise specified, the methods return the result code +which will be returned to the client. Unimplemented actions +can just return unwillingToPerform (53). +.TP +.B new +This method is called when the configuration file encounters a +.B perlmod +line. +The module in that line is then effectively `use'd into the perl +interpreter, then the \fBnew\fR method is called to create a new +object. +Note that multiple instances of that object may be instantiated, as +with any perl object. +.\" .LP +The +.B new +method receives the class name as argument. +.TP +.B search +This method is called when a search request comes from a client. +It arguments are as follows: +.nf + * object reference + * base DN + * scope + * alias dereferencing policy + * size limit + * time limit + * filter string + * attributes only flag (1 for yes) + * list of attributes to return (may be empty) +.fi +.LP +Return value: (resultcode, ldif-entry, ldif-entry, ...) +.TP +.B compare +This method is called when a compare request comes from a client. +Its arguments are as follows. +.nf + * object reference + * dn + * attribute assertion string +.fi +.LP +.TP +.B modify +This method is called when a modify request comes from a client. +Its arguments are as follows. +.nf + * object reference + * dn + * a list formatted as follows + ({ "ADD" | "DELETE" | "REPLACE" }, + attributetype, value...)... +.fi +.LP +.TP +.B add +This method is called when a add request comes from a client. +Its arguments are as follows. +.nf + * object reference + * entry in string format +.fi +.LP +.TP +.B modrdn +This method is called when a modrdn request comes from a client. +Its arguments are as follows. +.nf + * object reference + * dn + * new rdn + * delete old dn flag (1 means yes) +.fi +.LP +.TP +.B delete +This method is called when a delete request comes from a client. +Its arguments are as follows. +.nf + * object reference + * dn +.fi +.LP +.TP +.B config +This method is called once for each perlModuleConfig line in the +.BR slapd.conf (5) +configuration file. +Its arguments are as follows. +.nf + * object reference + * array of arguments on line +.fi +.LP +Return value: nonzero if this is not a valid option. +.TP +.B init +This method is called after backend is initialized. +Its argument is as follows. +.nf + * object reference +.fi +.LP +Return value: nonzero if initialization failed. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the PERL backend database. +That is, they must follow a "database perl" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. +.TP +.B perlModulePath /path/to/libs +Add the path to the @INC variable. +.TP +.B perlModule ModName +`Use' the module name ModName from ModName.pm +.TP +.B filterSearchResults +Search results are candidates that need to be filtered (with the +filter in the search request), rather than search results to be +returned directly to the client. +.TP +.B perlModuleConfig <arguments> +Invoke the module's config method with the given arguments. +.SH EXAMPLE +There is an example Perl module `SampleLDAP' in the slapd/back\-perl/ +directory in the OpenLDAP source tree. +.SH ACCESS CONTROL +The +.B perl +backend does not honor any of the access control semantics described in +.BR slapd.access (5); +all access control is delegated to the underlying PERL scripting. +Only +.B read (=r) +access to the +.B entry +pseudo-attribute and to the other attribute values of the entries +returned by the +.B search +operation is honored, which is performed by the frontend. +.SH WARNING +The interface of this backend to the perl module MAY change. +Any suggestions would greatly be appreciated. + +Note: in previous versions, any unrecognized lines in the slapd.conf +file were passed to the perl module's config method. This behavior is +deprecated (but still allowed for backward compatibility), and the +perlModuleConfig directive should instead be used to invoke the +module's config method. This compatibility feature will be removed at +some future date. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd (8), +.BR perl (1). diff --git a/doc/man/man5/slapd-relay.5 b/doc/man/man5/slapd-relay.5 new file mode 100644 index 0000000..057d3d4 --- /dev/null +++ b/doc/man/man5/slapd-relay.5 @@ -0,0 +1,207 @@ +.TH SLAPD-RELAY 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-relay \- relay backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The primary purpose of this +.BR slapd (8) +backend is to map a naming context defined in a database +running in the same +.BR slapd (8) +instance into a virtual naming context, with attributeType +and objectClass manipulation, if required. +It requires the +.BR slapo\-rwm (5) +overlay. +.LP +This backend and the above mentioned overlay are experimental. +.SH CONFIGURATION +The following +.B slapd.conf +directives apply to the relay backend database. +That is, they must follow a "database relay" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page; only the +.B suffix +directive is allowed by the +.I relay +backend. +.TP +.B relay <real naming context> +The naming context of the database that is presented +under a virtual naming context. +The presence of this directive implies that one specific database, +i.e. the one serving the +.BR "real naming context" , +will be presented under a virtual naming context. + +.SH MASSAGING +The +.B relay +database does not automatically rewrite the naming context +of requests and responses. +For this purpose, the +.BR slapo\-rwm (5) +overlay must be explicitly instantiated, and configured +as appropriate. +Usually, the +.B rwm\-suffixmassage +directive suffices if only naming context rewriting is required. + +.SH ACCESS RULES +One important issue is that access rules are based on the identity +that issued the operation. +After massaging from the virtual to the real naming context, the +frontend sees the operation as performed by the identity in the +real naming context. +Moreover, since +.B back\-relay +bypasses the real database frontend operations by short-circuiting +operations through the internal backend API, the original database +access rules do not apply but in selected cases, i.e. when the +backend itself applies access control. +As a consequence, the instances of the relay database must provide +own access rules that are consistent with those of the original +database, possibly adding further specific restrictions. +So, access rules in the +.B relay +database must refer to identities in the real naming context. +Examples are reported in the EXAMPLES section. + +.SH SCENARIOS +.LP +If no +.B relay +directive is given, the +.I relay +database does not refer to any specific database, but the most +appropriate one is looked-up after rewriting the request DN +for the operation that is being handled. +.LP +This allows one to write carefully crafted rewrite rules that +cause some of the requests to be directed to one database, and +some to another; e.g., authentication can be mapped to one +database, and searches to another, or different target databases +can be selected based on the DN of the request, and so. +.LP +Another possibility is to map the same operation to different +databases based on details of the virtual naming context, +e.g. groups on one database and persons on another. +.LP +.SH EXAMPLES +To implement a plain virtual naming context mapping +that refers to a single database, use +.LP +.nf + database relay + suffix "dc=virtual,dc=naming,dc=context" + relay "dc=real,dc=naming,dc=context" + overlay rwm + rwm\-suffixmassage "dc=real,dc=naming,dc=context" +.fi +.LP +To implement a plain virtual naming context mapping +that looks up the real naming context for each operation, use +.LP +.nf + database relay + suffix "dc=virtual,dc=naming,dc=context" + overlay rwm + rwm\-suffixmassage "dc=real,dc=naming,dc=context" +.fi +.LP +This is useful, for instance, to relay different databases that +share the terminal portion of the naming context (the one that +is rewritten). +.LP +To implement the old-fashioned suffixalias, e.g. mapping +the virtual to the real naming context, but not the results +back from the real to the virtual naming context, use +.LP +.nf + database relay + suffix "dc=virtual,dc=naming,dc=context" + relay "dc=real,dc=naming,dc=context" + overlay rwm + rwm\-rewriteEngine on + rwm\-rewriteContext default + rwm\-rewriteRule "dc=virtual,dc=naming,dc=context" + "dc=real,dc=naming,dc=context" ":@" + rwm\-rewriteContext searchFilter + rwm\-rewriteContext searchEntryDN + rwm\-rewriteContext searchAttrDN + rwm\-rewriteContext matchedDN +.fi +.LP +Note that the +.BR slapo\-rwm (5) +overlay is instantiated, but the rewrite rules are written explicitly, +rather than automatically as with the +.B rwm\-suffixmassage +statement, to map all the virtual to real naming context data flow, +but none of the real to virtual. +.LP +Access rules: +.LP +.nf + database mdb + suffix "dc=example,dc=com" + # skip... + access to dn.subtree="dc=example,dc=com" + by dn.exact="cn=Supervisor,dc=example,dc=com" write + by * read + + database relay + suffix "o=Example,c=US" + relay "dc=example,dc=com" + overlay rwm + rwm\-suffixmassage "dc=example,dc=com" + # skip ... + access to dn.subtree="o=Example,c=US" + by dn.exact="cn=Supervisor,dc=example,dc=com" write + by dn.exact="cn=Relay Supervisor,dc=example,dc=com" write + by * read +.fi +.LP +Note that, in both databases, the identities (the +.B <who> +clause) are in the +.BR "real naming context" , +i.e. +.BR "`dc=example,dc=com'" , +while the targets (the +.B <what> +clause) are in the +.B real +and in the +.BR "virtual naming context" , +respectively. +.SH ACCESS CONTROL +The +.B relay +backend does not honor any of the access control semantics described in +.BR slapd.access (5); +all access control is delegated to the relayed database(s). +Only +.B read (=r) +access to the +.B entry +pseudo-attribute and to the other attribute values of the entries +returned by the +.B search +operation is honored, which is performed by the frontend. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapo\-rwm (5), +.BR slapd (8). diff --git a/doc/man/man5/slapd-sock.5 b/doc/man/man5/slapd-sock.5 new file mode 100644 index 0000000..f68ea52 --- /dev/null +++ b/doc/man/man5/slapd-sock.5 @@ -0,0 +1,329 @@ +.TH SLAPD-SOCK 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2007-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-sock \- Socket backend/overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Socket backend to +.BR slapd (8) +uses an external program to handle queries, similarly to +.BR slapd\-shell (5). +However, in this case the external program listens on a Unix domain socket. +This makes it possible to have a pool of processes, which persist between +requests. This allows multithreaded operation and a higher level of +efficiency. The external program must have been started independently; +.BR slapd (8) +itself will not start it. + +This module may also be used as an overlay on top of some other database. +Use as an overlay allows external actions to be triggered in response to +operations on the main database. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the SOCK backend database. +That is, they must follow a "database sock" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. + +Alternatively, to use this module as an overlay, these directives must +follow an "overlay sock" line within an existing database definition. +.TP +.B extensions [ binddn | peername | ssf | connid ]* +Enables the sending of additional meta-attributes with each request. +.nf +binddn: <bound DN> +peername: IP=<address>:<port> +ssf: <SSF value> +connid: <connection ID> +.fi +.TP +.B socketpath <pathname> +Gives the path to a Unix domain socket to which the commands will +be sent and from which replies are received. + +When used as an overlay, these additional directives are defined: +.TP +.B sockops [ bind | unbind | search | compare | modify | modrdn | add | delete | extended ]* +Specify which request types to send to the external program. The default is +empty (no requests are sent). +.TP +.B sockresps [ result | search ]* +Specify which response types to send to the external program. "result" +sends just the results of an operation. "search" sends all entries that +the database returned for a search request. The default is empty +(no responses are sent). +.TP +.B sockdnpat <regexp> +Specify DN patterns for which the overlay will act. Only operations on +DNs matching the specified regular expression will be processed. The default +is empty (all DNs are processed). + +.SH PROTOCOL +The protocol is essentially the same as +.BR slapd\-shell (5) +with the addition of a newline to terminate the command parameters. The +following commands are sent: +.RS +.nf +ADD +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +<entry in LDIF format> +<blank line> +.fi +.RE +.PP +.RS +.nf +BIND +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +method: <method number> +credlen: <length of <credentials>> +cred: <credentials> +<blank line> +.fi +.RE +.PP +.RS +.nf +COMPARE +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +<attribute>: <value> +<blank line> +.fi +.RE +.PP +.RS +.nf +DELETE +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +<blank line> +.fi +.RE +.PP +.RS +.nf +EXTENDED +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +oid: <OID> +value: <base64-value> +<blank line> +.fi +.RE +.PP +.RS +.nf +MODIFY +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +<repeat { + <"add"/"delete"/"replace">: <attribute> + <repeat { <attribute>: <value> }> + \- +}> +<blank line> +.fi +.RE +.PP +.RS +.nf +MODRDN +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +newrdn: <new RDN> +deleteoldrdn: <0 or 1> +<if new superior is specified: "newSuperior: <DN>"> +<blank line> +.fi +.RE +.PP +.RS +.nf +SEARCH +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +base: <base DN> +scope: <0-2, see ldap.h> +deref: <0-3, see ldap.h> +sizelimit: <size limit> +timelimit: <time limit> +filter: <filter> +attrsonly: <0 or 1> +attrs: <"all" or space-separated attribute list> +<blank line> +.fi +.RE +.PP +.RS +.nf +UNBIND +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +<blank line> +.fi +.RE +.LP +The commands - except \fBunbind\fP - should output: +.RS +.nf +RESULT +code: <integer> +matched: <matched DN> +info: <text> +.fi +.RE +where only RESULT is mandatory, and then close the socket. +The \fBsearch\fP RESULT should be preceded by the entries in LDIF +format, each entry followed by a blank line. +Lines starting with `#' or `DEBUG:' are ignored. + +When used as an overlay, the external program should return a +CONTINUE response if request processing should continue normally, or +a regular RESULT response if the external program wishes to bypass the +underlying database. + +If the overlay is configured to send response messages to the external +program, they will appear as an extended RESULT message or as an +ENTRY message, defined below. The RESULT message is similar to +the one above, but also includes the msgid and any configured +extensions: +.RS +.nf +RESULT +msgid: <message id> +code: <integer> +matched: <matched DN> +info: <text> +<blank line> +.fi +.RE + +Typically both the msgid and the connid will be needed to match +a result message to a request. The ENTRY message has the form +.RS +.nf +ENTRY +msgid: <message id> +<entry in LDIF format> +<blank line> +.fi +.RE + +.SH KNOWN LIMITATIONS +The +.B sock +backend does not process extended operation results from an external program. + +.SH ACCESS CONTROL +The +.B sock +backend does not honor all ACL semantics as described in +.BR slapd.access (5). +In general, access to objects is checked by using a dummy object +that contains only the DN, so access rules that rely on the contents +of the object are not honored. +In detail: +.LP +The +.B add +operation does not require +.B write (=w) +access to the +.B children +pseudo-attribute of the parent entry. +.LP +The +.B bind +operation requires +.B auth (=x) +access to the +.B entry +pseudo-attribute of the entry whose identity is being assessed; +.B auth (=x) +access to the credentials is not checked, but rather delegated +to the underlying program. +.LP +The +.B compare +operation requires +.B compare (=c) +access to the +.B entry +pseudo-attribute +of the object whose value is being asserted; +.B compare (=c) +access to the attribute whose value is being asserted is not checked. +.LP +The +.B delete +operation does not require +.B write (=w) +access to the +.B children +pseudo-attribute of the parent entry. +.LP +The +.B modify +operation requires +.B write (=w) +access to the +.B entry +pseudo-attribute; +.B write (=w) +access to the specific attributes that are modified is not checked. +.LP +The +.B modrdn +operation does not require +.B write (=w) +access to the +.B children +pseudo-attribute of the parent entry, nor to that of the new parent, +if different; +.B write (=w) +access to the distinguished values of the naming attributes +is not checked. +.LP +The +.B search +operation does not require +.B search (=s) +access to the +.B entry +pseudo_attribute of the searchBase; +.B search (=s) +access to the attributes and values used in the filter is not checked. +.LP +The +.B extended +operation does not require any access special rights. +The external program has to implement any sort of access control. + +.SH EXAMPLE +There is an example script in the slapd/back\-sock/ directory +in the OpenLDAP source tree. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8). +.SH AUTHOR +Brian Candler, with enhancements by Howard Chu diff --git a/doc/man/man5/slapd-sock.5.links b/doc/man/man5/slapd-sock.5.links new file mode 100644 index 0000000..b5f4e45 --- /dev/null +++ b/doc/man/man5/slapd-sock.5.links @@ -0,0 +1 @@ +slapo-sock.5 diff --git a/doc/man/man5/slapd-sql.5 b/doc/man/man5/slapd-sql.5 new file mode 100644 index 0000000..8e1f40b --- /dev/null +++ b/doc/man/man5/slapd-sql.5 @@ -0,0 +1,699 @@ +.TH SLAPD-SQL 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.SH NAME +slapd\-sql \- SQL backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The primary purpose of this +.BR slapd (8) +backend is to PRESENT information stored in some RDBMS as an LDAP subtree +without any programming (some SQL and maybe stored procedures can't be +considered programming, anyway ;). +.LP +That is, for example, when you (some ISP) have account information you +use in an RDBMS, and want to use modern solutions that expect such +information in LDAP (to authenticate users, make email lookups etc.). +Or you want to synchronize or distribute information between different +sites/applications that use RDBMSes and/or LDAP. +Or whatever else... +.LP +It is NOT designed as a general-purpose backend that uses RDBMS instead +of LMDB (as the standard MDB backend does), though it can be +used as such with several limitations. +You can take a look at +.B http://www.openldap.org/faq/index.cgi?file=378 +(OpenLDAP FAQ\-O\-Matic/General LDAP FAQ/Directories vs. conventional +databases) to find out more on this point. +.LP +The idea (detailed below) is to use some meta-information to translate +LDAP queries to SQL queries, leaving relational schema untouched, so +that old applications can continue using it without any +modifications. +This allows SQL and LDAP applications to inter-operate without +replication, and exchange data as needed. +.LP +The SQL backend is designed to be tunable to virtually any relational +schema without having to change source (through that meta-information +mentioned). +Also, it uses ODBC to connect to RDBMSes, and is highly configurable +for SQL dialects RDBMSes may use, so it may be used for integration +and distribution of data on different RDBMSes, OSes, hosts etc., in +other words, in highly heterogeneous environment. +.LP +This backend is \fIexperimental\fP. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the SQL backend database, which means that +they must follow a "database sql" line and come before any +subsequent "backend" or "database" lines. +Other database options not specific to this backend are described +in the +.BR slapd.conf (5) +manual page. +.SH DATA SOURCE CONFIGURATION + +.TP +.B dbname <datasource name> +The name of the ODBC datasource to use. +.LP +.B dbhost <hostname> +.br +.B dbpasswd <password> +.br +.B dbuser <username> +.RS +The three above options are generally unneeded, because this information +is taken from the datasource specified by the +.B dbname +directive. +They allow to override datasource settings. +Also, several RDBMS' drivers tend to require explicit passing of user/password, +even if those are given in datasource (Note: +.B dbhost +is currently ignored). +.RE +.SH SCOPING CONFIGURATION +These options specify SQL query templates for scoping searches. + +.TP +.B subtree_cond <SQL expression> +Specifies a where-clause template used to form a subtree search condition +(dn="(.+,)?<dn>$"). +It may differ from one SQL dialect to another (see samples). +By default, it is constructed based on the knowledge about +how to normalize DN values (e.g. +\fB"<upper_func>(ldap_entries.dn) LIKE CONCAT('%',?)"\fP); +see \fBupper_func\fP, \fBupper_needs_cast\fP, \fBconcat_pattern\fP +and \fBstrcast_func\fP in "HELPER CONFIGURATION" for details. + +.TP +.B children_cond <SQL expression> +Specifies a where-clause template used to form a children search condition +(dn=".+,<dn>$"). +It may differ from one SQL dialect to another (see samples). +By default, it is constructed based on the knowledge about +how to normalize DN values (e.g. +\fB"<upper_func>(ldap_entries.dn) LIKE CONCAT('%,',?)"\fP); +see \fBupper_func\fP, \fBupper_needs_cast\fP, \fBconcat_pattern\fP +and \fBstrcast_func\fP in "HELPER CONFIGURATION" for details. + +.TP +.B use_subtree_shortcut { YES | no } +Do not use the subtree condition when the searchBase is the database +suffix, and the scope is subtree; rather collect all entries. + +.RE +.SH STATEMENT CONFIGURATION +These options specify SQL query templates for loading schema mapping +meta-information, adding and deleting entries to ldap_entries, etc. +All these and subtree_cond should have the given default values. +For the current value it is recommended to look at the sources, +or in the log output when slapd starts with "\-d 5" or greater. +Note that the parameter number and order must not be changed. + +.TP +.B oc_query <SQL expression> +The query that is used to collect the objectClass mapping data +from table \fIldap_oc_mappings\fP; see "METAINFORMATION USED" for details. +The default is +\fB"SELECT id, name, keytbl, keycol, create_proc, delete_proc, expect_return +FROM ldap_oc_mappings"\fP. + +.TP +.B at_query <SQL expression> +The query that is used to collect the attributeType mapping data +from table \fIldap_attr_mappings\fP; see "METAINFORMATION USED" for details. +The default is +\fB"SELECT name, sel_expr, from_tbls, join_where, add_proc, delete_proc, +param_order, expect_return FROM ldap_attr_mappings WHERE oc_map_id=?"\fP. + +.TP +.B id_query <SQL expression> +The query that is used to map a DN to an entry +in table \fIldap_entries\fP; see "METAINFORMATION USED" for details. +The default is +\fB"SELECT id,keyval,oc_map_id,dn FROM ldap_entries WHERE <DN match expr>"\fP, +where \fB<DN match expr>\fP is constructed based on the knowledge about +how to normalize DN values (e.g. \fB"dn=?"\fP if no means to uppercase +strings are available; typically, \fB"<upper_func>(dn)=?"\fP is used); +see \fBupper_func\fP, \fBupper_needs_cast\fP, \fBconcat_pattern\fP +and \fBstrcast_func\fP in "HELPER CONFIGURATION" for details. + +.TP +.B insentry_stmt <SQL expression> +The statement that is used to insert a new entry +in table \fIldap_entries\fP; see "METAINFORMATION USED" for details. +The default is +\fB"INSERT INTO ldap_entries (dn, oc_map_id, parent, keyval) VALUES +(?, ?, ?, ?)"\fP. + +.TP +.B delentry_stmt <SQL expression> +The statement that is used to delete an existing entry +from table \fIldap_entries\fP; see "METAINFORMATION USED" for details. +The default is +\fB"DELETE FROM ldap_entries WHERE id=?"\fP. + +.TP +.B delobjclasses_stmt <SQL expression> +The statement that is used to delete an existing entry's ID +from table \fIldap_objclasses\fP; see "METAINFORMATION USED" for details. +The default is +\fB"DELETE FROM ldap_entry_objclasses WHERE entry_id=?"\fP. + +.RE +.SH HELPER CONFIGURATION +These statements are used to modify the default behavior of the backend +according to issues of the dialect of the RDBMS. +The first options essentially refer to string and DN normalization +when building filters. +LDAP normalization is more than upper- (or lower-)casing everything; +however, as a reasonable trade-off, for case-sensitive RDBMSes the backend +can be instructed to uppercase strings and DNs by providing +the \fBupper_func\fP directive. +Some RDBMSes, to use functions on arbitrary data types, e.g. string +constants, requires a cast, which is triggered +by the \fBupper_needs_cast\fP directive. +If required, a string cast function can be provided as well, +by using the \fBstrcast_func\fP directive. +Finally, a custom string concatenation pattern may be required; +it is provided by the \fBconcat_pattern\fP directive. + +.TP +.B upper_func <SQL function name> +Specifies the name of a function that converts a given value to uppercase. +This is used for case insensitive matching when the RDBMS is case sensitive. +It may differ from one SQL dialect to another (e.g. \fBUCASE\fP, \fBUPPER\fP +or whatever; see samples). By default, none is used, i.e. strings are not +uppercased, so matches may be case sensitive. + +.TP +.B upper_needs_cast { NO | yes } +Set this directive to +.B yes +if +.B upper_func +needs an explicit cast when applied to literal strings. +A cast in the form +.B CAST (<arg> AS VARCHAR(<max DN length>)) +is used, where +.B <max DN length> +is builtin in back-sql; see macro +.B BACKSQL_MAX_DN_LEN +(currently 255; note that slapd's builtin limit, in macro +.BR SLAP_LDAPDN_MAXLEN , +is set to 8192). +This is \fIexperimental\fP and may change in future releases. + +.TP +.B strcast_func <SQL function name> +Specifies the name of a function that converts a given value to a string +for appropriate ordering. This is used in "SELECT DISTINCT" statements +for strongly typed RDBMSes with little implicit casting (like PostgreSQL), +when a literal string is specified. +This is \fIexperimental\fP and may change in future releases. + +.TP +.B concat_pattern <pattern> +This statement defines the +.B pattern +that is used to concatenate strings. The +.B pattern +MUST contain two question marks, '?', that will be replaced +by the two strings that must be concatenated. The default value is +.BR "CONCAT(?,?)"; +a form that is known to be highly portable (IBM db2, PostgreSQL) is +.BR "?||?", +but an explicit cast may be required when operating on literal strings: +.BR "CAST(?||? AS VARCHAR(<length>))". +On some RDBMSes (IBM db2, MSSQL) the form +.B "?+?" +is known to work as well. +Carefully check the documentation of your RDBMS or stay with the examples +for supported ones. +This is \fIexperimental\fP and may change in future releases. + +.TP +.B aliasing_keyword <string> +Define the aliasing keyword. Some RDBMSes use the word "\fIAS\fP" +(the default), others don't use any. + +.TP +.B aliasing_quote <string> +Define the quoting char of the aliasing keyword. Some RDBMSes +don't require any (the default), others may require single +or double quotes. + +.TP +.B has_ldapinfo_dn_ru { NO | yes } +Explicitly inform the backend whether the dn_ru column +(DN in reverse uppercased form) is present in table \fIldap_entries\fP. +Overrides automatic check (this is required, for instance, +by PostgreSQL/unixODBC). +This is \fIexperimental\fP and may change in future releases. + +.TP +.B fail_if_no_mapping { NO | yes } +When set to +.B yes +it forces \fIattribute\fP write operations to fail if no appropriate +mapping between LDAP attributes and SQL data is available. +The default behavior is to ignore those changes that cannot be mapped. +It has no impact on objectClass mapping, i.e. if the +.I structuralObjectClass +of an entry cannot be mapped to SQL by looking up its name +in ldap_oc_mappings, an +.I add +operation will fail regardless of the +.B fail_if_no_mapping +switch; see section "METAINFORMATION USED" for details. +This is \fIexperimental\fP and may change in future releases. + +.TP +.B allow_orphans { NO | yes } +When set to +.B yes +orphaned entries (i.e. without the parent entry in the database) +can be added. This option should be used with care, possibly +in conjunction with some special rule on the RDBMS side that +dynamically creates the missing parent. + +.TP +.B baseObject [ <filename> ] +Instructs the database to create and manage an in-memory baseObject +entry instead of looking for one in the RDBMS. +If the (optional) +.B <filename> +argument is given, the entry is read from that file in +.BR LDIF (5) +format; otherwise, an entry with objectClass \fBextensibleObject\fP +is created based on the contents of the RDN of the \fIbaseObject\fP. +This is particularly useful when \fIldap_entries\fP +information is stored in a view rather than in a table, and +.B union +is not supported for views, so that the view can only specify +one rule to compute the entry structure for one objectClass. +This topic is discussed further in section "METAINFORMATION USED". +This is \fIexperimental\fP and may change in future releases. + +.TP +.B create_needs_select { NO | yes } +Instructs the database whether or not entry creation +in table \fIldap_entries\fP needs a subsequent select to collect +the automatically assigned ID, instead of being returned +by a stored procedure. + +.LP +.B fetch_attrs <attrlist> +.br +.B fetch_all_attrs { NO | yes } +.RS +The first statement allows one to provide a list of attributes that +must always be fetched in addition to those requested by any specific +operation, because they are required for the proper usage of the +backend. For instance, all attributes used in ACLs should be listed +here. The second statement is a shortcut to require all attributes +to be always loaded. Note that the dynamically generated attributes, +e.g. \fIhasSubordinates\fP, \fIentryDN\fP and other implementation +dependent attributes are \fBNOT\fP generated at this point, for +consistency with the rest of slapd. This may change in the future. +.RE + +.TP +.B check_schema { YES | no } +Instructs the database to check schema adherence of entries after +modifications, and structural objectClass chain when entries are built. +By default it is set to +.BR yes . + +.TP +.B sqllayer <name> [...] +Loads the layer \fB<name>\fP onto a stack of helpers that are used +to map DNs from LDAP to SQL representation and vice-versa. +Subsequent args are passed to the layer configuration routine. +This is \fIhighly experimental\fP and should be used with extreme care. +The API of the layers is not frozen yet, so it is unpublished. + +.TP +.B autocommit { NO | yes } +Activates autocommit; by default, it is off. + +.SH METAINFORMATION USED +.LP +Almost everything mentioned later is illustrated in examples located +in the +.B servers/slapd/back\-sql/rdbms_depend/ +directory in the OpenLDAP source tree, and contains scripts for +generating sample database for Oracle, MS SQL Server, mySQL and more +(including PostgreSQL and IBM db2). +.LP +The first thing that one must arrange is what set of LDAP +object classes can present your RDBMS information. +.LP +The easiest way is to create an objectClass for each entity you had in +ER-diagram when designing your relational schema. +Any relational schema, no matter how normalized it is, was designed +after some model of your application's domain (for instance, accounts, +services etc. in ISP), and is used in terms of its entities, not just +tables of normalized schema. +It means that for every attribute of every such instance there is an +effective SQL query that loads its values. +.LP +Also you might want your object classes to conform to some of the standard +schemas like inetOrgPerson etc. +.LP +Nevertheless, when you think it out, we must define a way to translate +LDAP operation requests to (a series of) SQL queries. +Let us deal with the SEARCH operation. +.LP +Example: +Let's suppose that we store information about persons working in our +organization in two tables: +.LP +.nf + PERSONS PHONES + ---------- ------------- + id integer id integer + first_name varchar pers_id integer references persons(id) + last_name varchar phone + middle_name varchar + ... +.fi +.LP +(PHONES contains telephone numbers associated with persons). +A person can have several numbers, then PHONES contains several +records with corresponding pers_id, or no numbers (and no records in +PHONES with such pers_id). +An LDAP objectclass to present such information could look like this: +.LP +.nf + person + ------- + MUST cn + MAY telephoneNumber $ firstName $ lastName + ... +.fi +.LP +To fetch all values for cn attribute given person ID, we construct the +query: +.LP +.nf + SELECT CONCAT(persons.first_name,' ',persons.last_name) + AS cn FROM persons WHERE persons.id=? +.fi +.LP +for telephoneNumber we can use: +.LP +.nf + SELECT phones.phone AS telephoneNumber FROM persons,phones + WHERE persons.id=phones.pers_id AND persons.id=? +.fi +.LP +If we wanted to service LDAP requests with filters like +(telephoneNumber=123*), we would construct something like: +.LP +.nf + SELECT ... FROM persons,phones + WHERE persons.id=phones.pers_id + AND persons.id=? + AND phones.phone like '%1%2%3%' +.fi +.LP +(note how the telephoneNumber match is expanded in multiple wildcards +to account for interspersed ininfluential chars like spaces, dashes +and so; this occurs by design because telephoneNumber is defined after +a specially recognized syntax). +So, if we had information about what tables contain values for each +attribute, how to join these tables and arrange these values, we could +try to automatically generate such statements, and translate search +filters to SQL WHERE clauses. +.LP +To store such information, we add three more tables to our schema +and fill it with data (see samples): +.LP +.nf + ldap_oc_mappings (some columns are not listed for clarity) + --------------- + id=1 + name="person" + keytbl="persons" + keycol="id" +.fi +.LP +This table defines a mapping between objectclass (its name held in the +"name" column), and a table that holds the primary key for corresponding +entities. +For instance, in our example, the person entity, which we are trying +to present as "person" objectclass, resides in two tables (persons and +phones), and is identified by the persons.id column (that we will call +the primary key for this entity). +Keytbl and keycol thus contain "persons" (name of the table), and "id" +(name of the column). +.LP +.nf + ldap_attr_mappings (some columns are not listed for clarity) + ----------- + id=1 + oc_map_id=1 + name="cn" + sel_expr="CONCAT(persons.first_name,' ',persons.last_name)" + from_tbls="persons" + join_where=NULL + ************ + id=<n> + oc_map_id=1 + name="telephoneNumber" + sel_expr="phones.phone" + from_tbls="persons,phones" + join_where="phones.pers_id=persons.id" +.fi +.LP +This table defines mappings between LDAP attributes and SQL queries +that load their values. +Note that, unlike LDAP schema, these are not +.B attribute types +- the attribute "cn" for "person" objectclass can +have its values in different tables than "cn" for some other objectclass, +so attribute mappings depend on objectclass mappings (unlike attribute +types in LDAP schema, which are indifferent to objectclasses). +Thus, we have oc_map_id column with link to oc_mappings table. +.LP +Now we cut the SQL query that loads values for a given attribute into 3 parts. +First goes into sel_expr column - this is the expression we had +between SELECT and FROM keywords, which defines WHAT to load. +Next is table list - text between FROM and WHERE keywords. +It may contain aliases for convenience (see examples). +The last is part of the where clause, which (if it exists at all) expresses the +condition for joining the table containing values with the table +containing the primary key (foreign key equality and such). +If values are in the same table as the primary key, then this column is +left NULL (as for cn attribute above). +.LP +Having this information in parts, we are able to not only construct +queries that load attribute values by id of entry (for this we could +store SQL query as a whole), but to construct queries that load id's +of objects that correspond to a given search filter (or at least part of +it). +See below for examples. +.LP +.nf + ldap_entries + ------------ + id=1 + dn=<dn you choose> + oc_map_id=... + parent=<parent record id> + keyval=<value of primary key> +.fi +.LP +This table defines mappings between DNs of entries in your LDAP tree, +and values of primary keys for corresponding relational data. +It has recursive structure (parent column references id column of the +same table), which allows you to add any tree structure(s) to your +flat relational data. +Having id of objectclass mapping, we can determine table and column +for primary key, and keyval stores value of it, thus defining the exact +tuple corresponding to the LDAP entry with this DN. +.LP +Note that such design (see exact SQL table creation query) implies one +important constraint - the key must be an integer. +But all that I know about well-designed schemas makes me think that it's +not very narrow ;) If anyone needs support for different types for +keys - he may want to write a patch, and submit it to OpenLDAP ITS, +then I'll include it. +.LP +Also, several users complained that they don't really need very +structured trees, and they don't want to update one more table every +time they add or delete an instance in the relational schema. +Those people can use a view instead of a real table for ldap_entries, something +like this (by Robin Elfrink): +.LP +.nf + CREATE VIEW ldap_entries (id, dn, oc_map_id, parent, keyval) + AS + SELECT 0, UPPER('o=MyCompany,c=NL'), + 3, 0, 'baseObject' FROM unixusers WHERE userid='root' + UNION + SELECT (1000000000+userid), + UPPER(CONCAT(CONCAT('cn=',gecos),',o=MyCompany,c=NL')), + 1, 0, userid FROM unixusers + UNION + SELECT (2000000000+groupnummer), + UPPER(CONCAT(CONCAT('cn=',groupname),',o=MyCompany,c=NL')), + 2, 0, groupnummer FROM groups; +.fi + +.LP +If your RDBMS does not support +.B unions +in views, only one objectClass can be mapped in +.BR ldap_entries , +and the baseObject cannot be created; in this case, see the +.B baseObject +directive for a possible workaround. + +.LP +.SH TYPICAL SQL BACKEND OPERATION +Having meta-information loaded, the SQL backend uses these tables to +determine a set of primary keys of candidates (depending on search +scope and filter). +It tries to do it for each objectclass registered in ldap_objclasses. +.LP +Example: +for our query with filter (telephoneNumber=123*) we would get the following +query generated (which loads candidate IDs) +.LP +.nf + SELECT ldap_entries.id,persons.id, 'person' AS objectClass, + ldap_entries.dn AS dn + FROM ldap_entries,persons,phones + WHERE persons.id=ldap_entries.keyval + AND ldap_entries.objclass=? + AND ldap_entries.parent=? + AND phones.pers_id=persons.id + AND (phones.phone LIKE '%1%2%3%') +.fi +.LP +(for ONELEVEL search) +or "... AND dn=?" (for BASE search) +or "... AND dn LIKE '%?'" (for SUBTREE) +.LP +Then, for each candidate, we load the requested attributes using +per-attribute queries like +.LP +.nf + SELECT phones.phone AS telephoneNumber + FROM persons,phones + WHERE persons.id=? AND phones.pers_id=persons.id +.fi +.LP +Then, we use test_filter() from the frontend API to test the entry for a full +LDAP search filter match (since we cannot effectively make sense of +SYNTAX of corresponding LDAP schema attribute, we translate the filter +into the most relaxed SQL condition to filter candidates), and send it to +the user. +.LP +ADD, DELETE, MODIFY and MODRDN operations are also performed on per-attribute +meta-information (add_proc etc.). +In those fields one can specify an SQL statement or stored procedure +call which can add, or delete given values of a given attribute, using +the given entry keyval (see examples -- mostly PostgreSQL, ORACLE and MSSQL +- since as of this writing there are no stored procs in MySQL). +.LP +We just add more columns to ldap_oc_mappings and ldap_attr_mappings, holding +statements to execute (like create_proc, add_proc, del_proc etc.), and +flags governing the order of parameters passed to those statements. +Please see samples to find out what are the parameters passed, and other +information on this matter - they are self-explanatory for those familiar +with the concepts expressed above. +.LP +.SH COMMON TECHNIQUES +First of all, let's recall that among other major differences to the +complete LDAP data model, the above illustrated concept does not directly +support such features as multiple objectclasses per entry, and referrals. +Fortunately, they are easy to adopt in this scheme. +The SQL backend requires that one more table is added to the schema: +ldap_entry_objectclasses(entry_id,oc_name). +.LP +That table contains any number of objectclass names that corresponding +entries will possess, in addition to that mentioned in mapping. +The SQL backend automatically adds attribute mapping for the "objectclass" +attribute to each objectclass mapping that loads values from this table. +So, you may, for instance, have a mapping for inetOrgPerson, and use it +for queries for "person" objectclass... +.LP +Referrals used to be implemented in a loose manner by adding an extra +table that allowed any entry to host a "ref" attribute, along with +a "referral" extra objectClass in table ldap_entry_objclasses. +In the current implementation, referrals are treated like any other +user-defined schema, since "referral" is a structural objectclass. +The suggested practice is to define a "referral" entry in ldap_oc_mappings, +holding a naming attribute, e.g. "ou" or "cn", a "ref" attribute, +containing the url; in case multiple referrals per entry are needed, +a separate table for urls can be created, where urls are mapped +to the respective entries. +The use of the naming attribute usually requires to add +an "extensibleObject" value to ldap_entry_objclasses. + +.LP +.SH CAVEATS +As previously stated, this backend should not be considered +a replacement of other data storage backends, but rather a gateway +to existing RDBMS storages that need to be published in LDAP form. +.LP +The \fBhasSubordinates\fP operational attribute is honored by back-sql +in search results and in compare operations; it is partially honored +also in filtering. Owing to design limitations, a (brain-dead?) filter +of the form +\fB(!(hasSubordinates=TRUE))\fP +will give no results instead of returning all the leaf entries, because +it actually expands into \fB... AND NOT (1=1)\fP. +If you need to find all the leaf entries, please use +\fB(hasSubordinates=FALSE)\fP +instead. +.LP +A directoryString value of the form "__First___Last_" +(where underscores mean spaces, ASCII 0x20 char) corresponds +to its prettified counterpart "First_Last"; this is not currently +honored by back-sql if non-prettified data is written via RDBMS; +when non-prettified data is written through back-sql, the prettified +values are actually used instead. + +.LP +.SH BUGS +When the +.B ldap_entry_objclasses +table is empty, filters on the +.B objectClass +attribute erroneously result in no candidates. +A workaround consists in adding at least one row to that table, +no matter if valid or not. + +.LP +.SH PROXY CACHE OVERLAY +The proxy cache overlay +allows caching of LDAP search requests (queries) in a local database. +See +.BR slapo\-pcache (5) +for details. +.SH EXAMPLES +There are example SQL modules in the slapd/back\-sql/rdbms_depend/ +directory in the OpenLDAP source tree. +.SH ACCESS CONTROL +The +.B sql +backend honors access control semantics as indicated in +.BR slapd.access (5) +(including the +.B disclose +access privilege when enabled at compile time). +.SH FILES + +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd (8). diff --git a/doc/man/man5/slapd-wt.5 b/doc/man/man5/slapd-wt.5 new file mode 100644 index 0000000..e83301a --- /dev/null +++ b/doc/man/man5/slapd-wt.5 @@ -0,0 +1,97 @@ +.TH SLAPD-WT 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2011-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-wt \- WiredTiger backend to slapd +.SH SYNOPSIS +.B ETCDIR/slapd.conf +.SH DESCRIPTION +The \fBwt\fP backend to +.BR slapd (8) +uses WiredTiger database library to store data. +.LP +The \fBwt\fP backend is experimental module that have potential high +write performance and high concurrency performance. +This backend have not some basic feature yet. Please backup data using +slapcat before update the module. + +.SH CONFIGURATION +These +.B slapd.conf +options apply to the \fBwt\fP backend database. +That is, they must follow a "database wt" line and +come before any subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. +.TP +.BI directory \ <directory> +Specify WiredTiger home directory that containing this database and +associated indexes live. +A separate directory must be specified for each database. +The default is +.BR LOCALSTATEDIR/openldap\-data . +.TP +.BI idlcache \ <boolean> +Use the in-memory idlcache. The default is true. +.TP +\fBindex \fR{\fI<attrlist>\fR|\fBdefault\fR} [\fBpres\fR,\fBeq\fR,\fBapprox\fR,\fBsub\fR,\fI<special>\fR] +Specify the indexes to maintain for the given attribute (or +list of attributes). +Some attributes only support a subset of indexes. +If only an \fI<attr>\fP is given, the indices specified for \fBdefault\fR +are maintained. +Note that setting a default does not imply that all attributes will be +indexed. Also, for best performance, an +.B eq +index should always be configured for the +.B objectClass +attribute. +.TP +.BI mode \ <integer> +back-wt does not support mode option. use umask instead. +.TP +\fBwtconfig \fR{\fBcreate\fR,\fBcache_size=512M\fR,\fBasync=(enabled)\fR} +Specify configuration for wiredtiger, This parameter is pass to +.BR wiredtiger_open (3). +.RS +.TP +.B create +create the database if it does not exist. +.RE +.RS +.TP +.B cache_size +maximum heap memory to allocate for the cache. +.RE +.RS +.TP +.B async +asynchronous operations configuration options. disabled by default. +.RE +.RS + +.SH ACCESS CONTROL +The +.B wt +backend honors access control semantics as indicated in +.BR slapd.access (5). +.SH FILES +.TP +.B ETCDIR/slapd.conf +default +.B slapd +configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8), +.BR slapadd (8), +.BR slapcat (8), +.BR slapindex (8), +.BR slapmodify (8), +WiredTiger documentation. +.SH ACKNOWLEDGEMENTS +.so ../Project +Written by HAMANO Tsukasa <hamano@osstech.co.jp>. diff --git a/doc/man/man5/slapd.access.5 b/doc/man/man5/slapd.access.5 new file mode 100644 index 0000000..171a73b --- /dev/null +++ b/doc/man/man5/slapd.access.5 @@ -0,0 +1,1205 @@ +.TH SLAPD.ACCESS 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd.access \- access configuration for slapd, the stand-alone LDAP daemon +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.BR slapd.conf (5) +file contains configuration information for the +.BR slapd (8) +daemon. This configuration file is also used by the SLAPD tools +.BR slapacl (8), +.BR slapadd (8), +.BR slapauth (8), +.BR slapcat (8), +.BR slapdn (8), +.BR slapindex (8), +.BR slapmodify (8), +and +.BR slaptest (8). +.LP +The +.B slapd.conf +file consists of a series of global configuration options that apply to +.B slapd +as a whole (including all backends), followed by zero or more database +backend definitions that contain information specific to a backend +instance. +.LP +The general format of +.B slapd.conf +is as follows: +.LP +.nf + # comment - these options apply to every database + <global configuration options> + # first database definition & configuration options + database <backend 1 type> + <configuration options specific to backend 1> + # subsequent database definitions & configuration options + ... +.fi +.LP +Both the global configuration and each backend-specific section can +contain access information. Backend-specific access control +directives are used for those entries that belong to the backend, +according to their naming context. In case no access control +directives are defined for a backend or those which are defined are +not applicable, the directives from the global configuration section +are then used. +.LP +If no access controls are present, the default policy +allows anyone and everyone to read anything but restricts +updates to rootdn. (e.g., "access to * by * read"). +.LP +When dealing with an access list, because the global access list is +effectively appended to each per-database list, if the resulting +list is non-empty then the access list will end with an implicit +.B access to * by * none +directive. If there are no access directives applicable to a backend, +then a default read is used. +.LP +.B Be warned: the rootdn can always read and write EVERYTHING! +.LP +For entries not held in any backend (such as a root DSE), the +global directives are used. +.LP +Arguments that should be replaced by actual text are shown in +brackets <>. +.SH THE ACCESS DIRECTIVE +The structure of the access control directives is +.TP +.B access to <what> "[ by <who> [ <access> ] [ <control> ] ]+" +Grant access (specified by +.BR <access> ) +to a set of entries and/or attributes (specified by +.BR <what> ) +by one or more requestors (specified by +.BR <who> ). + +.LP +Lists of access directives are evaluated in the order they appear +in \fIslapd.conf\fP. +When a +.B <what> +clause matches the datum whose access is being evaluated, its +.B <who> +clause list is checked. +When a +.B <who> +clause matches the accessor's properties, its +.B <access> +and +.B <control> +clauses are evaluated. + +.LP +Access control checking stops at the first match of the +.B <what> +and +.B <who> +clause, unless otherwise dictated by the +.B <control> +clause. +Each +.B <who> +clause list is implicitly terminated by a +.LP +.nf + by * none stop +.fi +.LP +.B <control> +clause. This implicit +.B <control> +stops access directive evaluation with no more access privileges +granted to anyone else. +To stop access directive evaluation only when both +.B <who> +and +.B <what> +match, add an explicit +.LP +.nf + by * break +.fi +.LP +to the end of the +.B <who> +clause list. + +.LP +Each +.B <what> +clause list is implicitly terminated by a +.LP +.nf + access to * + by * none +.fi +.LP +clause that results in granting no access privileges to an otherwise +unspecified datum. +.SH THE <WHAT> FIELD +The field +.BR <what> +specifies the entity the access control directive applies to. +It can have the forms +.LP +.nf + dn[.<dnstyle>]=<dnpattern> + filter=<ldapfilter> + attrs=<attrlist>[ val[/matchingRule][.<attrstyle>]=<attrval>] +.fi +.LP +with +.LP +.nf + <dnstyle>={{exact|base(object)}|regex + |one(level)|sub(tree)|children} + <attrlist>={<attr>|[{!|@}]<objectClass>}[,<attrlist>] + <attrstyle>={{exact|base(object)}|regex + |one(level)|sub(tree)|children} +.fi +.LP +The statement +.B dn=<dnpattern> +selects the entries based on their naming context. +The +.B <dnpattern> +is a string representation of the entry's DN. +The wildcard +.B * +stands for all the entries, and it is implied if no +.B dn +form is given. +.LP +The +.B <dnstyle> +is optional; however, it is recommended to specify it to avoid ambiguities. +.B Base +(synonym of +.BR baseObject ), +the default, +or +.B exact +(an alias of +.BR base ) +indicates the entry whose DN is equal to the +.BR <dnpattern> ; +.B one +(synonym of +.BR onelevel ) +indicates all the entries immediately below the +.BR <dnpattern> , +.B sub +(synonym of +.BR subtree ) +indicates all entries in the subtree at the +.BR <dnpattern> , +.B children +indicates all the entries below (subordinate to) the +.BR <dnpattern> . +.LP +If the +.B <dnstyle> +qualifier is +.BR regex , +then +.B <dnpattern> +is a POSIX (''extended'') regular expression pattern, +as detailed in +.BR regex (7) +and/or +.BR re_format (7), +matching a normalized string representation of the entry's DN. +The regex form of the pattern does not (yet) support UTF-8. +.LP +The statement +.B filter=<ldapfilter> +selects the entries based on a valid LDAP filter as described in RFC 4515. +A filter of +.B (objectClass=*) +is implied if no +.B filter +form is given. +.LP +The statement +.B attrs=<attrlist> +selects the attributes the access control rule applies to. +It is a comma-separated list of attribute types, plus the special names +.BR entry , +indicating access to the entry itself, and +.BR children , +indicating access to the entry's children. ObjectClass names may also +be specified in this list, which will affect all the attributes that +are required and/or allowed by that objectClass. +Actually, names in +.B <attrlist> +that are prefixed by +.B @ +are directly treated as objectClass names. A name prefixed by +.B ! +is also treated as an objectClass, but in this case the access rule +affects the attributes that are not required nor allowed +by that objectClass. +If no +.B attrs +form is given, +.B attrs=@extensibleObject +is implied, i.e. all attributes are addressed. +.LP +Using the form +.B attrs=<attr> val[/matchingRule][.<attrstyle>]=<attrval> +specifies access to a particular value of a single attribute. +In this case, only a single attribute type may be given. The +.B <attrstyle> +.B exact +(the default) uses the attribute's equality matching rule to compare the +value, unless a different (and compatible) matching rule is specified. If the +.B <attrstyle> +is +.BR regex , +the provided value is used as a POSIX (''extended'') regular +expression pattern. If the attribute has DN syntax, the +.B <attrstyle> +can be any of +.BR base , +.BR onelevel , +.B subtree +or +.BR children , +resulting in base, onelevel, subtree or children match, respectively. +.LP +The dn, filter, and attrs statements are additive; they can be used in sequence +to select entities the access rule applies to based on naming context, +value and attribute type simultaneously. +Submatches resulting from +.B regex +matching can be dereferenced in the +.B <who> +field using the syntax +.IR ${v<n>} , +where +.I <n> +is the submatch number. +The default syntax, +.IR $<n> , +is actually an alias for +.IR ${d<n>} , +that corresponds to dereferencing submatches from the +.B dnpattern +portion of the +.B <what> +field. +.SH THE <WHO> FIELD +The field +.B <who> +indicates whom the access rules apply to. +Multiple +.B <who> +statements can appear in an access control statement, indicating the +different access privileges to the same resource that apply to different +accessee. +It can have the forms +.LP +.nf + * + anonymous + users + self[.<selfstyle>] + + dn[.<dnstyle>[,<modifier>]]=<DN> + dnattr=<attrname> + + realanonymous + realusers + realself[.<selfstyle>] + + realdn[.<dnstyle>[,<modifier>]]=<DN> + realdnattr=<attrname> + + group[/<objectclass>[/<attrname>]] + [.<groupstyle>]=<group> + peername[.<peernamestyle>]=<peername> + sockname[.<style>]=<sockname> + domain[.<domainstyle>[,<modifier>]]=<domain> + sockurl[.<style>]=<sockurl> + set[.<setstyle>]=<pattern> + + ssf=<n> + transport_ssf=<n> + tls_ssf=<n> + sasl_ssf=<n> + + dynacl/<name>[/<options>][.<dynstyle>][=<pattern>] +.fi +.LP +with +.LP +.nf + <style>={exact|regex|expand} + <selfstyle>={level{<n>}} + <dnstyle>={{exact|base(object)}|regex + |one(level)|sub(tree)|children|level{<n>}} + <groupstyle>={exact|expand} + <peernamestyle>={<style>|ip|ipv6|path} + <domainstyle>={exact|regex|sub(tree)} + <setstyle>={exact|expand} + <modifier>={expand} + <name>=aci <pattern>=<attrname>] +.fi +.LP +They may be specified in combination. +.LP +.nf +.fi +.LP +The wildcard +.B * +refers to everybody. +.LP +The keywords prefixed by +.B real +act as their counterparts without prefix; the checking respectively occurs +with the \fIauthentication\fP DN and the \fIauthorization\fP DN. +.LP +The keyword +.B anonymous +means access is granted to unauthenticated clients; it is mostly used +to limit access to authentication resources (e.g. the +.B userPassword +attribute) to unauthenticated clients for authentication purposes. +.LP +The keyword +.B users +means access is granted to authenticated clients. +.LP +The keyword +.B self +means access to an entry is allowed to the entry itself (e.g. the entry +being accessed and the requesting entry must be the same). +It allows the +.B level{<n>} +style, where \fI<n>\fP indicates what ancestor of the DN +is to be used in matches. +A positive value indicates that the <n>-th ancestor of the user's DN +is to be considered; a negative value indicates that the <n>-th ancestor +of the target is to be considered. +For example, a "\fIby self.level{1} ...\fP" clause would match +when the object "\fIdc=example,dc=com\fP" is accessed +by "\fIcn=User,dc=example,dc=com\fP". +A "\fIby self.level{-1} ...\fP" clause would match when the same user +accesses the object "\fIou=Address Book,cn=User,dc=example,dc=com\fP". +.LP +The statement +.B dn=<DN> +means that access is granted to the matching DN. +The optional style qualifier +.B dnstyle +allows the same choices of the dn form of the +.B <what> +field. In addition, the +.B regex +style can exploit substring substitution of submatches in the +.B <what> +dn.regex clause by using the form +.BR $<digit> , +with +.B digit +ranging from 0 to 9 (where 0 matches the entire string), +or the form +.BR ${<digit>+} , +for submatches higher than 9. +Substring substitution from attribute value can +be done in +using the form +.BR ${v<digit>+} . +Since the dollar character is used to indicate a substring replacement, +the dollar character that is used to indicate match up to the end of +the string must be escaped by a second dollar character, e.g. +.LP +.nf + access to dn.regex="^(.+,)?uid=([^,]+),dc=[^,]+,dc=com$" + by dn.regex="^uid=$2,dc=[^,]+,dc=com$$" write +.fi +.LP +The style qualifier +allows an optional +.BR modifier . +At present, the only type allowed is +.BR expand , +which causes substring substitution of submatches to take place +even if +.B dnstyle +is not +.BR regex . +Note that the +.B regex +dnstyle in the above example may be of use only if the +.B <by> +clause needs to be a regex; otherwise, if the +value of the second (from the right) +.B dc= +portion of the DN in the above example were fixed, the form +.LP +.nf + access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$" + by dn.exact,expand="uid=$2,dc=example,dc=com" write +.fi +.LP +could be used; if it had to match the value in the +.B <what> +clause, the form +.LP +.nf + access to dn.regex="^(.+,)?uid=([^,]+),dc=([^,]+),dc=com$" + by dn.exact,expand="uid=$2,dc=$3,dc=com" write +.fi +.LP +could be used. +.LP +Forms of the +.B <what> +clause other than regex may provide submatches as well. +The +.BR base(object) , +the +.BR sub(tree) , +the +.BR one(level) , +and the +.BR children +forms provide +.B $0 +as the match of the entire string. +The +.BR sub(tree) , +the +.BR one(level) , +and the +.BR children +forms also provide +.B $1 +as the match of the rightmost part of the DN as defined in the +.B <what> +clause. +This may be useful, for instance, to provide access to all the +ancestors of a user by defining +.LP +.nf + access to dn.subtree="dc=com" + by dn.subtree,expand="$1" read +.fi +.LP +which means that only access to entries that appear in the DN of the +.B <by> +clause is allowed. +.LP +The +.BR level{<n>} +form is an extension and a generalization of the +.BR onelevel +form, which matches all DNs whose <n>-th ancestor is the pattern. +So, \fIlevel{1}\fP is equivalent to \fIonelevel\fP, +and \fIlevel{0}\fP is equivalent to \fIbase\fP. +.LP +It is perfectly useless to give any access privileges to a DN +that exactly matches the +.B rootdn +of the database the ACLs apply to, because it implicitly +possesses write privileges for the entire tree of that database. +Actually, access control is bypassed for the +.BR rootdn , +to solve the intrinsic chicken-and-egg problem. +.LP +The statement +.B dnattr=<attrname> +means that access is granted to requests whose DN is listed in the +entry being accessed under the +.B <attrname> +attribute. +.LP +The statement +.B group=<group> +means that access is granted to requests whose DN is listed +in the group entry whose DN is given by +.BR <group> . +The optional parameters +.B <objectclass> +and +.B <attrname> +define the objectClass and the member attributeType of the group entry. +The defaults are +.B groupOfNames +and +.BR member , +respectively. +The optional style qualifier +.B <style> +can be +.BR expand , +which means that +.B <group> +will be expanded as a replacement string (but not as a regular expression) +according to +.BR regex (7) +and/or +.BR re_format (7), +and +.BR exact , +which means that exact match will be used. +If the style of the DN portion of the +.B <what> +clause is regex, the submatches are made available according to +.BR regex (7) +and/or +.BR re_format (7); +other styles provide limited submatches as discussed above about +the DN form of the +.B <by> +clause. +.LP +For static groups, the specified attributeType must have +.B DistinguishedName +or +.B NameAndOptionalUID +syntax. For dynamic groups the attributeType must +be a subtype of the +.B labeledURI +attributeType. Only LDAP URIs of the form +.B ldap:///<base>??<scope>?<filter> +will be evaluated in a dynamic group, by searching the local server only. +.LP +The statements +.BR peername=<peername> , +.BR sockname=<sockname> , +.BR domain=<domain> , +and +.BR sockurl=<sockurl> +mean that the contacting host IP (in the form +.BR "IP=<ip>:<port>" +for IPv4, or +.BR "IP=[<ipv6>]:<port>" +for IPv6) +or the contacting host named pipe file name (in the form +.B "PATH=<path>" +if connecting through a named pipe) for +.BR peername , +the named pipe file name for +.BR sockname , +the contacting host name for +.BR domain , +and the contacting URL for +.BR sockurl +are compared against +.B pattern +to determine access. +The same +.B style +rules for pattern match described for the +.B group +case apply, plus the +.B regex +style, which implies submatch +.B expand +and regex match of the corresponding connection parameters. +The +.B exact +style of the +.BR <peername> +clause (the default) implies a case-exact match on the client's +.BR IP , +including the +.B "IP=" +prefix and the trailing +.BR ":<port>" , +or the client's +.BR path , +including the +.B "PATH=" +prefix if connecting through a named pipe. +The special +.B ip +style interprets the pattern as +.BR <peername>=<ip>[%<mask>][{<n>}] , +where +.B <ip> +and +.B <mask> +are dotted digit representations of the IP and the mask, while +.BR <n> , +delimited by curly brackets, is an optional port. +The same applies to IPv6 addresses when the special +.B ipv6 +style is used. +When checking access privileges, the IP portion of the +.BR peername +is extracted, eliminating the +.B "IP=" +prefix and the +.B ":<port>" +part, and it is compared against the +.B <ip> +portion of the pattern after masking with +.BR <mask> : +\fI((peername & <mask>) == <ip>)\fP. +As an example, +.B peername.ip=127.0.0.1 +and +.B peername.ipv6=::1 +allow connections only from localhost, +.B peername.ip=192.168.1.0%255.255.255.0 +allows connections from any IP in the 192.168.1 class C domain, and +.B peername.ip=192.168.1.16%255.255.255.240{9009} +allows connections from any IP in the 192.168.1.[16-31] range +of the same domain, only if port 9009 is used. +The special +.B path +style eliminates the +.B "PATH=" +prefix from the +.B peername +when connecting through a named pipe, and performs an exact match +on the given pattern. +The +.BR <domain> +clause also allows the +.B subtree +style, which succeeds when a fully qualified name exactly matches the +.BR domain +pattern, or its trailing part, after a +.BR dot , +exactly matches the +.BR domain +pattern. +The +.B expand +style is allowed, implying an +.B exact +match with submatch expansion; the use of +.B expand +as a style modifier is considered more appropriate. +As an example, +.B domain.subtree=example.com +will match www.example.com, but will not match www.anotherexample.com. +The +.B domain +of the contacting host is determined by performing a DNS reverse lookup. +As this lookup can easily be spoofed, use of the +.B domain +statement is strongly discouraged. By default, reverse lookups are disabled. +The optional +.B domainstyle +qualifier of the +.B <domain> +clause allows a +.B modifier +option; the only value currently supported is +.BR expand , +which causes substring substitution of submatches to take place even if +the +.B domainstyle +is not +.BR regex , +much like the analogous usage in +.B <dn> +clause. +.LP +The statement +.B set=<pattern> +is undocumented yet. +.LP +The statement +.B dynacl/<name>[/<options>][.<dynstyle>][=<pattern>] +means that access checking is delegated to the admin-defined method +indicated by +.BR <name> , +which can be registered at run-time by means of the +.B moduleload +statement. +The fields +.BR <options> , +.B <dynstyle> +and +.B <pattern> +are optional, and are directly passed to the registered parsing routine. +Dynacl is experimental; it must be enabled at compile time. +.LP +The statement +.B dynacl/aci[=<attrname>] +means that the access control is determined by the values in the +.B attrname +of the entry itself. +The optional +.B <attrname> +indicates what attributeType holds the ACI information in the entry. +By default, the +.B OpenLDAPaci +operational attribute is used. +ACIs are experimental; they must be enabled at compile time. +.LP +The statements +.BR ssf=<n> , +.BR transport_ssf=<n> , +.BR tls_ssf=<n> , +and +.BR sasl_ssf=<n> +set the minimum required Security Strength Factor (ssf) needed +to grant access. The value should be positive integer. +.SH THE <ACCESS> FIELD +The optional field +.B <access> ::= [[real]self]{<level>|<priv>} +determines the access level or the specific access privileges the +.B who +field will have. +Its component are defined as +.LP +.nf + <level> ::= none|disclose|auth|compare|search|read|{write|add|delete}|manage + <priv> ::= {=|+|\-}{0|d|x|c|s|r|{w|a|z}|m}+ +.fi +.LP +The modifier +.B self +allows special operations like having a certain access level or privilege +only in case the operation involves the name of the user that's requesting +the access. +It implies the user that requests access is authorized. +The modifier +.B realself +refers to the authenticated DN as opposed to the authorized DN of the +.B self +modifier. +An example is the +.B selfwrite +access to the member attribute of a group, which allows one to add/delete +its own DN from the member list of a group, while being not allowed +to affect other members. +.LP +The +.B level +access model relies on an incremental interpretation of the access +privileges. +The possible levels are +.BR none , +.BR disclose , +.BR auth , +.BR compare , +.BR search , +.BR read , +.BR write , +and +.BR manage . +Each access level implies all the preceding ones, thus +.B manage +grants all access including administrative access. This access +allows some modifications which would otherwise be prohibited by the +LDAP data model or the directory schema, e.g. changing the +structural objectclass of an entry, or modifying an operational +attribute that is defined as not user modifiable. +The +.BR write +access is actually the combination of +.BR add +and +.BR delete , +which respectively restrict the write privilege to add or delete +the specified +.BR <what> . + +.LP +The +.B none +access level disallows all access including disclosure on error. +.LP +The +.B disclose +access level allows disclosure of information on error. +.LP +The +.B auth +access level means that one is allowed access to an attribute to perform +authentication/authorization operations (e.g. +.BR bind ) +with no other access. +This is useful to grant unauthenticated clients the least possible +access level to critical resources, like passwords. +.LP +The +.B priv +access model relies on the explicit setting of access privileges +for each clause. +The +.B = +sign resets previously defined accesses; as a consequence, the final +access privileges will be only those defined by the clause. +The +.B + +and +.B \- +signs add/remove access privileges to the existing ones. +The privileges are +.B m +for manage, +.B w +for write, +.B a +for add, +.B z +for delete, +.B r +for read, +.B s +for search, +.B c +for compare, +.B x +for authentication, and +.B d +for disclose. +More than one of the above privileges can be added in one statement. +.B 0 +indicates no privileges and is used only by itself (e.g., +0). +Note that +.B +az +is equivalent to +.BR +w . +.LP +If no access is given, it defaults to +.BR +0 . +.SH THE <CONTROL> FIELD +The optional field +.B <control> +controls the flow of access rule application. +It can have the forms +.LP +.nf + stop + continue + break +.fi +.LP +where +.BR stop , +the default, means access checking stops in case of match. +The other two forms are used to keep on processing access clauses. +In detail, the +.B continue +form allows for other +.B <who> +clauses in the same +.B <access> +clause to be considered, so that they may result in incrementally altering +the privileges, while the +.B break +form allows for other +.B <access> +clauses that match the same target to be processed. +Consider the (silly) example +.LP +.nf + access to dn.subtree="dc=example,dc=com" attrs=cn + by * =cs break + + access to dn.subtree="ou=People,dc=example,dc=com" + by * +r +.fi +.LP +which allows search and compare privileges to everybody under +the "dc=example,dc=com" tree, with the second rule allowing +also read in the "ou=People" subtree, +or the (even more silly) example +.LP +.nf + access to dn.subtree="dc=example,dc=com" attrs=cn + by * =cs continue + by users +r +.fi +.LP +which grants everybody search and compare privileges, and adds read +privileges to authenticated clients. +.LP +One useful application is to easily grant write privileges to an +.B updatedn +that is different from the +.BR rootdn . +In this case, since the +.B updatedn +needs write access to (almost) all data, one can use +.LP +.nf + access to * + by dn.exact="cn=The Update DN,dc=example,dc=com" write + by * break +.fi +.LP +as the first access rule. +As a consequence, unless the operation is performed with the +.B updatedn +identity, control is passed straight to the subsequent rules. + +.SH OPERATION REQUIREMENTS +Operations require different privileges on different portions of entries. +The following summary applies to primary MDB database backend. Requirements +for other backends may (and often do) differ. + +.LP +The +.B add +operation requires +.B add (=a) +privileges on the pseudo-attribute +.B entry +of the entry being added, and +.B add (=a) +privileges on the pseudo-attribute +.B children +of the entry's parent. +When adding the suffix entry of a database, +.B add +access to +.B children +of the empty DN ("") is required. Also if +Add content ACL checking has been configured on +the database (see the +.BR slapd.conf (5) +or +.BR slapd\-config (5) +manual page), +.B add (=a) +will be required on all of the attributes being added. + +.LP +The +.B bind +operation, when credentials are stored in the directory, requires +.B auth (=x) +privileges on the attribute the credentials are stored in (usually +.BR userPassword ). + +.LP +The +.B compare +operation requires +.B compare (=c) +privileges on the attribute that is being compared. + +.LP +The +.B delete +operation requires +.B delete (=z) +privileges on the pseudo-attribute +.B entry +of the entry being deleted, and +.B delete (=d) +privileges on the +.B children +pseudo-attribute of the entry's parent. + +.LP +The +.B modify +operation requires +.B write (=w) +privileges on the attributes being modified. +In detail, +.B add (=a) +is required to add new values, +.B delete (=z) +is required to delete existing values, +and both +.B delete +and +.BR "add (=az)" , +or +.BR "write (=w)" , +are required to replace existing values. + +.LP +The +.B modrdn +operation requires +.B write (=w) +privileges on the pseudo-attribute +.B entry +of the entry whose relative DN is being modified, +.B delete (=z) +privileges on the pseudo-attribute +.B children +of the old entry's parents, +.B add (=a) +privileges on the pseudo-attribute +.B children +of the new entry's parents, and +.B add (=a) +privileges on the attributes that are present in the new relative DN. +.B Delete (=z) +privileges are also required on the attributes that are present +in the old relative DN if +.B deleteoldrdn +is set to 1. + +.LP +The +.B search +operation, requires +.B search (=s) +privileges on the +.B entry +pseudo-attribute of the searchBase +(NOTE: this was introduced with OpenLDAP 2.4). +Then, for each entry, it requires +.B search (=s) +privileges on the attributes that are defined in the filter. +The resulting entries are finally tested for +.B read (=r) +privileges on the pseudo-attribute +.B entry +(for read access to the entry itself) +and for +.B read (=r) +access on each value of each attribute that is requested. +Also, for each +.B referral +object used in generating continuation references, the operation requires +.B read (=r) +access on the pseudo-attribute +.B entry +(for read access to the referral object itself), +as well as +.B read (=r) +access to the attribute holding the referral information +(generally the +.B ref +attribute). + +.LP +Some internal operations and some +.B controls +require specific access privileges. +The +.B authzID +mapping and the +.B proxyAuthz +control require +.B auth (=x) +privileges on all the attributes that are present in the search filter +of the URI regexp maps (the right-hand side of the +.B authz-regexp +directives). +.B Auth (=x) +privileges are also required on the +.B authzTo +attribute of the authorizing identity and/or on the +.B authzFrom +attribute of the authorized identity. +In general, when an internal lookup is performed for authentication +or authorization purposes, search-specific privileges (see the access +requirements for the search operation illustrated above) are relaxed to +.BR auth . + +.LP +Access control to search entries is checked by the frontend, +so it is fully honored by all backends; for all other operations +and for the discovery phase of the search operation, +full ACL semantics is only supported by the primary backends, i.e. +.BR back\-mdb (5). + +Some other backend, like +.BR back\-sql (5), +may fully support them; others may only support a portion of the +described semantics, or even differ in some aspects. +The relevant details are described in the backend-specific man pages. + +.SH CAVEATS +It is strongly recommended to explicitly use the most appropriate +.B <dnstyle> +in +.B <what> +and +.B <who> +clauses, to avoid possible incorrect specifications of the access rules +as well as for performance (avoid unnecessary regex matching when an exact +match suffices) reasons. +.LP +An administrator might create a rule of the form: +.LP +.nf + access to dn.regex="dc=example,dc=com" + by ... +.fi +.LP +expecting it to match all entries in the subtree "dc=example,dc=com". +However, this rule actually matches any DN which contains anywhere +the substring "dc=example,dc=com". That is, the rule matches both +"uid=joe,dc=example,dc=com" and "dc=example,dc=com,uid=joe". +.LP +To match the desired subtree, the rule would be more precisely +written: +.LP +.nf + access to dn.regex="^(.+,)?dc=example,dc=com$" + by ... +.fi +.LP +For performance reasons, it would be better to use the subtree style. +.LP +.nf + access to dn.subtree="dc=example,dc=com" + by ... +.fi +.LP +When writing submatch rules, it may be convenient to avoid unnecessary +.B regex +.B <dnstyle> +use; for instance, to allow access to the subtree of the user +that matches the +.B <what> +clause, one could use +.LP +.nf + access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$" + by dn.regex="^uid=$2,dc=example,dc=com$$" write + by ... +.fi +.LP +However, since all that is required in the +.B <by> +clause is substring expansion, a more efficient solution is +.LP +.nf + access to dn.regex="^(.+,)?uid=([^,]+),dc=example,dc=com$" + by dn.exact,expand="uid=$2,dc=example,dc=com" write + by ... +.fi +.LP +In fact, while a +.B <dnstyle> +of +.B regex +implies substring expansion, +.BR exact , +as well as all the other DN specific +.B <dnstyle> +values, does not, so it must be explicitly requested. +.LP +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd (8), +.BR slapd\-* (5), +.BR slapacl (8), +.BR regex (7), +.BR re_format (7) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapd.backends.5 b/doc/man/man5/slapd.backends.5 new file mode 100644 index 0000000..641dbe4 --- /dev/null +++ b/doc/man/man5/slapd.backends.5 @@ -0,0 +1,140 @@ +.TH SLAPD.BACKENDS 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2006-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd.backends \- backends for slapd, the stand-alone LDAP daemon +.SH DESCRIPTION +The +.BR slapd (8) +daemon can use a variety of different backends for serving LDAP requests. +Backends may be compiled statically into slapd, or when module support +is enabled, they may be dynamically loaded. Multiple instances of a +backend can be configured, to serve separate databases from the same +slapd server. + + +Configuration options for each backend are documented separately in the +corresponding +.BR slapd\-<backend> (5) +manual pages. +.TP +.B asyncmeta +This backend performs basic LDAP proxying with respect to a set of +remote LDAP servers. It is an enhancement of the +.B ldap +backend that operates asynchronously, to prevent tying up slapd threads +while waiting for operations to complete. +.TP +.B config +This backend is used to manage the configuration of slapd at run-time. +Unlike other backends, only a single instance of the +.B config +backend may be defined. It also instantiates itself automatically, +so it is always present even if not explicitly defined in the +.BR slapd.conf (5) +file. +.TP +.B dnssrv +This backend is experimental. +It serves up referrals based upon SRV resource records held in the +Domain Name System. +.TP +.B ldap +This backend acts as a proxy to forward incoming requests to another +LDAP server. +.TP +.B ldif +This database uses the filesystem to build the tree structure +of the database, using plain ascii files to store data. +Its usage should be limited to very simple databases, where performance +is not a requirement. This backend also supports subtree renames. +.TP +.B mdb +This is the recommended primary backend. +This backend uses OpenLDAP's own MDB transactional database +library. This backend also supports subtree renames. +.TP +.B meta +This backend performs basic LDAP proxying with respect to a set of +remote LDAP servers. It is an enhancement of the +.B ldap +backend. +.TP +.B monitor +This backend provides information about the running status of the slapd +daemon. Only a single instance of the +.B monitor +backend may be defined. +.TP +.B ndb +This backend is experimental, incomplete, and deprecated. +It uses the transactional database interface of the MySQL Cluster Engine +(NDB) to store data. Note that Oracle, which now owns MySQL, has withdrawn +support for NDB and this backend is unlikely to be developed any further. +.TP +.B null +Operations in this backend succeed but do nothing. +.TP +.B passwd +This backend is provided for demonstration purposes only. +It serves up user account information from the system +.BR passwd (5) +file. +.TP +.B perl +This backend embeds a +.BR perl (1) +interpreter into slapd. +It runs Perl subroutines to implement LDAP operations. +This backend is deprecated. +.TP +.B relay +This backend is experimental. +It redirects LDAP operations to another database +in the same server, based on the naming context of the request. +Its use requires the +.B rwm +overlay (see +.BR slapo\-rwm (5) +for details) to rewrite the naming context of the request. +It is primarily intended to implement virtual views on databases +that actually store data. +.TP +.B sql +This backend is experimental and deprecated. +It services LDAP requests from an SQL database. +.TP +.B wiredtiger +This backend is experimental. +It services LDAP requests from a wiredtiger database. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +ETCDIR/slapd.d +default slapd configuration directory +.SH SEE ALSO +.BR ldap (3), +.BR slapd\-asyncmeta (5), +.BR slapd\-config (5), +.BR slapd\-dnssrv (5), +.BR slapd\-ldap (5), +.BR slapd\-ldif (5), +.BR slapd\-mdb (5), +.BR slapd\-meta (5), +.BR slapd\-monitor (5), +.BR slapd\-ndb (5), +.BR slapd\-null (5), +.BR slapd\-passwd (5), +.BR slapd\-perl (5), +.BR slapd\-relay (5), +.BR slapd\-sql (5), +.BR slapd\-wt (5), +.BR slapd.conf (5), +.BR slapd.overlays (5), +.BR slapd (8). +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapd.conf.5 b/doc/man/man5/slapd.conf.5 new file mode 100644 index 0000000..6ec19c5 --- /dev/null +++ b/doc/man/man5/slapd.conf.5 @@ -0,0 +1,2140 @@ +.TH SLAPD.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd.conf \- configuration file for slapd, the stand-alone LDAP daemon +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The file +.B ETCDIR/slapd.conf +contains configuration information for the +.BR slapd (8) +daemon. This configuration file is also used by the SLAPD tools +.BR slapacl (8), +.BR slapadd (8), +.BR slapauth (8), +.BR slapcat (8), +.BR slapdn (8), +.BR slapindex (8), +.BR slapmodify (8), +and +.BR slaptest (8). +.LP +The +.B slapd.conf +file consists of a series of global configuration options that apply to +.B slapd +as a whole (including all backends), followed by zero or more database +backend definitions that contain information specific to a backend +instance. +The configuration options are case-insensitive; +their value, on a case by case basis, may be case-sensitive. +.LP +The general format of +.B slapd.conf +is as follows: +.LP +.nf + # comment - these options apply to every database + <global configuration options> + # first database definition & configuration options + database <backend 1 type> + <configuration options specific to backend 1> + # subsequent database 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 slapd.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, General Backend Options, and General Database +Options. Backend-specific options are discussed in the +.B slapd\-<backend>(5) +manual pages. Refer to the "OpenLDAP Administrator's Guide" for more +details on the slapd 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 access to <what> "[ by <who> <access> <control> ]+" +Grant access (specified by <access>) to a set of entries and/or +attributes (specified by <what>) by one or more requestors (specified +by <who>). +If no access controls are present, the default policy +allows anyone and everyone to read anything but restricts +updates to rootdn. (e.g., "access to * by * read"). +The rootdn can always read and write EVERYTHING! +See +.BR slapd.access (5) +and the "OpenLDAP's Administrator's Guide" for details. +.TP +.B allow <features> +Specify a set of features (separated by white space) to +allow (default none). +.B bind_v2 +allows acceptance of LDAPv2 bind requests. Note that +.BR slapd (8) +does not truly implement LDAPv2 (RFC 1777), now Historic (RFC 3494). +.B bind_anon_cred +allows anonymous bind when credentials are not empty (e.g. +when DN is empty). +.B bind_anon_dn +allows unauthenticated (anonymous) bind when DN is not empty. +.B update_anon +allows unauthenticated (anonymous) update operations to be processed +(subject to access controls and other administrative limits). +.B proxy_authz_anon +allows unauthenticated (anonymous) proxy authorization control to be processed +(subject to access controls, authorization and other administrative limits). +.TP +.B argsfile <filename> +The (absolute) name of a file that will hold the +.B slapd +server's command line (program name and options). +.TP +.B attributeoptions [option-name]... +Define tagging attribute options or option tag/range prefixes. +Options must not end with `\-', prefixes must end with `\-'. +The `lang\-' prefix is predefined. +If you use the +.B attributeoptions +directive, `lang\-' will no longer be defined and you must specify it +explicitly if you want it defined. + +An attribute description with a tagging option is a subtype of that +attribute description without the option. +Except for that, options defined this way have no special semantics. +Prefixes defined this way work like the `lang\-' options: +They define a prefix for tagging options starting with the prefix. +That is, if you define the prefix `x\-foo\-', you can use the option +`x\-foo\-bar'. +Furthermore, in a search or compare, a prefix or range name (with +a trailing `\-') matches all options starting with that name, as well +as the option with the range name sans the trailing `\-'. +That is, `x\-foo\-bar\-' matches `x\-foo\-bar' and `x\-foo\-bar\-baz'. + +RFC 4520 reserves options beginning with `x\-' for private experiments. +Other options should be registered with IANA, see RFC 4520 section 3.5. +OpenLDAP also has the `binary' option built in, but this is a transfer +option, not a tagging option. +.HP +.hy 0 +.B attributetype "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [SUP\ <oid>]\ + [EQUALITY\ <oid>]\ + [ORDERING\ <oid>]\ + [SUBSTR\ <oid>]\ + [SYNTAX\ <oidlen>]\ + [SINGLE\-VALUE]\ + [COLLECTIVE]\ + [NO\-USER\-MODIFICATION]\ + [USAGE\ <attributeUsage>]\ )" +.RS +Specify an attribute type using the LDAPv3 syntax defined in RFC 4512. +The slapd parser extends the RFC 4512 definition by allowing string +forms as well as numeric OIDs to be used for the attribute OID and +attribute syntax OID. +(See the +.B objectidentifier +description.) +.RE +.TP +.B authid\-rewrite<cmd> <args> +Used by the authentication framework to convert simple user names +to an LDAP DN used for authorization purposes. +Its purpose is analogous to that of +.BR authz-regexp +(see below). +The prefix \fIauthid\-\fP is followed by a set of rules analogous +to those described in +.BR slapo\-rwm (5) +for data rewriting (replace the \fIrwm\-\fP prefix with \fIauthid\-\fP). +.B authid\-rewrite<cmd> +and +.B authz\-regexp +rules should not be intermixed. +.TP +.B authz\-policy <policy> +Used to specify which rules to use for Proxy Authorization. Proxy +authorization allows a client to authenticate to the server using one +user's credentials, but specify a different identity to use for authorization +and access control purposes. It essentially allows user A to login as user +B, using user A's password. +The +.B none +flag disables proxy authorization. This is the default setting. +The +.B from +flag will use rules in the +.I authzFrom +attribute of the authorization DN. +The +.B to +flag will use rules in the +.I authzTo +attribute of the authentication DN. +The +.B any +flag, an alias for the deprecated value of +.BR both , +will allow any of the above, whatever succeeds first (checked in +.BR to , +.B from +sequence. +The +.B all +flag requires both authorizations to succeed. +.LP +.RS +The rules are mechanisms to specify which identities are allowed +to perform proxy authorization. +The +.I authzFrom +attribute in an entry specifies which other users +are allowed to proxy login to this entry. The +.I authzTo +attribute in +an entry specifies which other users this user can authorize as. Use of +.I authzTo +rules can be easily +abused if users are allowed to write arbitrary values to this attribute. +In general the +.I authzTo +attribute must be protected with ACLs such that +only privileged users can modify it. +The value of +.I authzFrom +and +.I authzTo +describes an +.B identity +or a set of identities; it can take five forms: +.RS +.TP +.B ldap:///<base>??[<scope>]?<filter> +.RE +.RS +.B dn[.<dnstyle>]:<pattern> +.RE +.RS +.B u[.<mech>[/<realm>]]:<pattern> +.RE +.RS +.B group[/objectClass[/attributeType]]:<pattern> +.RE +.RS +.B <pattern> +.RE +.RS + +.B <dnstyle>:={exact|onelevel|children|subtree|regex} + +.RE +The first form is a valid LDAP +.B URI +where the +.IR <host>:<port> , +the +.I <attrs> +and the +.I <extensions> +portions must be absent, so that the search occurs locally on either +.I authzFrom +or +.IR authzTo . + +.LP +The second form is a +.BR DN . +The optional +.B dnstyle +modifiers +.IR exact , +.IR onelevel , +.IR children , +and +.I subtree +provide exact, onelevel, children and subtree matches, which cause +.I <pattern> +to be normalized according to the DN normalization rules. +The special +.B dnstyle +modifier +.I regex +causes the +.I <pattern> +to be treated as a POSIX (''extended'') regular expression, as +discussed in +.BR regex (7) +and/or +.BR re_format (7). +A pattern of +.I * +means any non-anonymous DN. + +.LP +The third form is a SASL +.BR id . +The optional fields +.I <mech> +and +.I <realm> +allow specification of a SASL +.BR mechanism , +and eventually a SASL +.BR realm , +for those mechanisms that support one. +The need to allow the specification of a mechanism is still debated, +and users are strongly discouraged to rely on this possibility. + +.LP +The fourth form is a group specification. +It consists of the keyword +.BR group , +optionally followed by the specification of the group +.B objectClass +and +.BR attributeType . +The +.B objectClass +defaults to +.IR groupOfNames . +The +.B attributeType +defaults to +.IR member . +The group with DN +.B <pattern> +is searched with base scope, filtered on the specified +.BR objectClass . +The values of the resulting +.B attributeType +are searched for the asserted DN. + +.LP +The fifth form is provided for backwards compatibility. If no identity +type is provided, i.e. only +.B <pattern> +is present, an +.I exact DN +is assumed; as a consequence, +.B <pattern> +is subjected to DN normalization. + +.LP +Since the interpretation of +.I authzFrom +and +.I authzTo +can impact security, users are strongly encouraged +to explicitly set the type of identity specification that is being used. +A subset of these rules can be used as third arg in the +.B authz\-regexp +statement (see below); significantly, the +.IR URI , +provided it results in exactly one entry, +and the +.I dn.exact:<dn> +forms. +.RE +.TP +.B authz\-regexp <match> <replace> +Used by the authentication framework to convert simple user names, +such as provided by SASL subsystem, or extracted from certificates +in case of cert-based SASL EXTERNAL, or provided within the RFC 4370 +"proxied authorization" control, to an LDAP DN used for +authorization purposes. Note that the resulting DN need not refer +to an existing entry to be considered valid. When an authorization +request is received from the SASL subsystem, the SASL +.BR USERNAME , +.BR REALM , +and +.B MECHANISM +are taken, when available, and combined into a name of the form +.RS +.RS +.TP +.B UID=<username>[[,CN=<realm>],CN=<mechanism>],CN=auth + +.RE +This name is then compared against the +.B match +POSIX (''extended'') regular expression, and if the match is successful, +the name is replaced with the +.B replace +string. If there are wildcard strings in the +.B match +regular expression that are enclosed in parenthesis, e.g. +.RS +.TP +.B UID=([^,]*),CN=.* + +.RE +then the portion of the name that matched the wildcard will be stored +in the numbered placeholder variable $1. If there are other wildcard strings +in parenthesis, the matching strings will be in $2, $3, etc. up to $9. The +placeholders can then be used in the +.B replace +string, e.g. +.RS +.TP +.B UID=$1,OU=Accounts,DC=example,DC=com + +.RE +The replaced name can be either a DN, i.e. a string prefixed by "dn:", +or an LDAP URI. +If the latter, the server will use the URI to search its own database(s) +and, if the search returns exactly one entry, the name is +replaced by the DN of that entry. The LDAP URI must have no +hostport, attrs, or extensions components, but the filter is mandatory, +e.g. +.RS +.TP +.B ldap:///OU=Accounts,DC=example,DC=com??one?(UID=$1) + +.RE +The protocol portion of the URI must be strictly +.BR ldap . +Note that this search is subject to access controls. Specifically, +the authentication identity must have "auth" access in the subject. + +Multiple +.B authz\-regexp +options can be given in the configuration file to allow for multiple matching +and replacement patterns. The matching patterns are checked in the order they +appear in the file, stopping at the first successful match. + +.\".B Caution: +.\"Because the plus sign + is a character recognized by the regular expression engine, +.\"and it will appear in names that include a REALM, be careful to escape the +.\"plus sign with a backslash \\+ to remove the character's special meaning. +.RE +.TP +.B concurrency <integer> +Specify a desired level of concurrency. Provided to the underlying +thread system as a hint. The default is not to provide any hint. This setting +is only meaningful on some platforms where there is not a one to one +correspondence between user threads and kernel threads. +.TP +.B conn_max_pending <integer> +Specify the maximum number of pending requests for an anonymous session. +If requests are submitted faster than the server can process them, they +will be queued up to this limit. If the limit is exceeded, the session +is closed. The default is 100. +.TP +.B conn_max_pending_auth <integer> +Specify the maximum number of pending requests for an authenticated session. +The default is 1000. +.TP +.B defaultsearchbase <dn> +Specify a default search base to use when client submits a +non-base search request with an empty base DN. +Base scoped search requests with an empty base DN are not affected. +.TP +.B disallow <features> +Specify a set of features (separated by white space) to +disallow (default none). +.B bind_anon +disables acceptance of anonymous bind requests. Note that this setting +does not prohibit anonymous directory access (See "require authc"). +.B bind_simple +disables simple (bind) authentication. +.B tls_2_anon +disables forcing session to anonymous status (see also +.BR tls_authc ) +upon StartTLS operation receipt. +.B tls_authc +disallows the StartTLS operation if authenticated (see also +.BR tls_2_anon ). +.B proxy_authz_non_critical +disables acceptance of the proxied authorization control (RFC4370) +with criticality set to FALSE. +.B dontusecopy_non_critical +disables acceptance of the dontUseCopy control (a work in progress) +with criticality set to FALSE. +.HP +.hy 0 +.B ditcontentrule "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [AUX\ <oids>]\ + [MUST\ <oids>]\ + [MAY\ <oids>]\ + [NOT\ <oids>]\ )" +.RS +Specify an DIT Content Rule using the LDAPv3 syntax defined in RFC 4512. +The slapd parser extends the RFC 4512 definition by allowing string +forms as well as numeric OIDs to be used for the attribute OID and +attribute syntax OID. +(See the +.B objectidentifier +description.) +.RE +.TP +.B gentlehup { on | off } +A SIGHUP signal will only cause a 'gentle' shutdown-attempt: +.B Slapd +will stop listening for new connections, but will not close the +connections to the current clients. Future write operations return +unwilling-to-perform, though. Slapd 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 slapd +server +.B with another database, +without disrupting the currently active clients. +The default is off. You may wish to use +.B idletimeout +along with this option. +.TP +.B idletimeout <integer> +Specify the number of seconds to wait before forcibly closing +an idle client connection. A setting of 0 disables this +feature. The default is 0. You may also want to set the +.B writetimeout +option. +.TP +.B include <filename> +Read additional configuration information from the given file before +continuing with the next line of the current file. +.TP +.B index_hash64 { on | off } +Use a 64 bit hash for indexing. The default is to use 32 bit hashes. +These hashes are used for equality and substring indexing. The 64 bit +version may be needed to avoid index collisions when the number of +indexed values exceeds ~64 million. (Note that substring indexing +generates multiple index values per actual attribute value.) +Indices generated with 32 bit hashes are incompatible with the 64 bit +version, and vice versa. Any existing databases must be fully reloaded +when changing this setting. This directive is only supported on 64 bit CPUs. +.TP +.B index_intlen <integer> +Specify the key length for ordered integer indices. The most significant +bytes of the binary integer will be used for index keys. The default +value is 4, which provides exact indexing for 31 bit values. +A floating point representation is used to index too large values. +.TP +.B index_substr_if_maxlen <integer> +Specify the maximum length for subinitial and subfinal indices. Only +this many characters of an attribute value will be processed by the +indexing functions; any excess characters are ignored. The default is 4. +.TP +.B index_substr_if_minlen <integer> +Specify the minimum length for subinitial and subfinal indices. An +attribute value must have at least this many characters in order to be +processed by the indexing functions. The default is 2. +.TP +.B index_substr_any_len <integer> +Specify the length used for subany indices. An attribute value must have +at least this many characters in order to be processed. Attribute values +longer than this length will be processed in segments of this length. The +default is 4. The subany index will also be used in subinitial and +subfinal index lookups when the filter string is longer than the +.I index_substr_if_maxlen +value. +.TP +.B index_substr_any_step <integer> +Specify the steps used in subany index lookups. This value sets the offset +for the segments of a filter string that are processed for a subany index +lookup. The default is 2. For example, with the default values, a search +using this filter "cn=*abcdefgh*" would generate index lookups for +"abcd", "cdef", and "efgh". + +.LP +Note: Indexing support depends on the particular backend in use. Also, +changing these settings will generally require deleting any indices that +depend on these parameters and recreating them with +.BR slapindex (8). + +.HP +.hy 0 +.B ldapsyntax "(\ <oid>\ + [DESC\ <description>]\ + [X\-SUBST <substitute-syntax>]\ )" +.RS +Specify an LDAP syntax using the LDAPv3 syntax defined in RFC 4512. +The slapd parser extends the RFC 4512 definition by allowing string +forms as well as numeric OIDs to be used for the syntax OID. +(See the +.B objectidentifier +description.) +The slapd parser also honors the +.B X\-SUBST +extension (an OpenLDAP-specific extension), which allows one to use the +.B ldapsyntax +statement to define a non-implemented syntax along with another syntax, +the extension value +.IR substitute-syntax , +as its temporary replacement. +The +.I substitute-syntax +must be defined. +This allows one to define attribute types that make use of non-implemented syntaxes +using the correct syntax OID. +Unless +.B X\-SUBST +is used, this configuration statement would result in an error, +since no handlers would be associated to the resulting syntax structure. +.RE + +.TP +.B listener-threads <integer> +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 localSSF <SSF> +Specifies the Security Strength Factor (SSF) to be given local LDAP sessions, +such as those to the ldapi:// listener. For a description of SSF values, +see +.BR sasl-secprops 's +.B minssf +option description. The default is 71. +.TP +.B logfile <filename> +Specify a file for recording slapd 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 <integer> [...] +Specify the level at which debugging statements and operation +statistics should be syslogged (currently logged to the +.BR syslogd (8) +LOG_LOCAL4 facility). +They must be considered subsystems rather than increasingly verbose +log levels. +Some messages with higher priority are logged regardless +of the configured loglevel as soon as any logging is configured. +Log levels are additive, and available levels are: +.RS +.RS +.PD 0 +.TP +.B 1 +.B (0x1 trace) +trace function calls +.TP +.B 2 +.B (0x2 packets) +debug packet handling +.TP +.B 4 +.B (0x4 args) +heavy trace debugging (function args) +.TP +.B 8 +.B (0x8 conns) +connection management +.TP +.B 16 +.B (0x10 BER) +print out packets sent and received +.TP +.B 32 +.B (0x20 filter) +search filter processing +.TP +.B 64 +.B (0x40 config) +configuration file processing +.TP +.B 128 +.B (0x80 ACL) +access control list processing +.TP +.B 256 +.B (0x100 stats) +connections, LDAP operations, results (recommended) +.TP +.B 512 +.B (0x200 stats2) +stats2 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 129 + loglevel 0x81 + loglevel 128 1 + loglevel 0x80 0x1 + loglevel acl 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. + +Note that the +.BR packets , +.BR BER , +and +.B parse +levels are only available as debug output on stderr, and are not +sent to syslog. + +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 maxfilterdepth <integer> +Specify the maximum depth of nested filters in search requests. +The default is 1000. +.TP +.B moduleload <filename> [<arguments>...] +Specify the name of a dynamically loadable module to load and any +additional arguments if supported by the module. The filename +may be an absolute path name or a simple filename. Non-absolute names +are searched for in the directories specified by the +.B modulepath +option. This option and the +.B modulepath +option are only usable if slapd was compiled with \-\-enable\-modules. +.TP +.B modulepath <pathspec> +Specify a list of directories to search for loadable modules. Typically +the path is colon-separated but this depends on the operating system. +The default is MODULEDIR, which is where the standard OpenLDAP install +will place its modules. +.HP +.hy 0 +.B objectclass "(\ <oid>\ + [NAME\ <name>]\ + [DESC\ <description>]\ + [OBSOLETE]\ + [SUP\ <oids>]\ + [{ ABSTRACT | STRUCTURAL | AUXILIARY }]\ + [MUST\ <oids>] [MAY\ <oids>] )" +.RS +Specify an objectclass using the LDAPv3 syntax defined in RFC 4512. +The slapd parser extends the RFC 4512 definition by allowing string +forms as well as numeric OIDs to be used for the object class OID. +(See the +.B +objectidentifier +description.) Object classes are "STRUCTURAL" by default. +.RE +.TP +.B objectidentifier <name> "{ <oid> | <name>[:<suffix>] }" +Define a string name that equates to the given OID. The string can be used +in place of the numeric OID in objectclass and attribute definitions. The +name can also be used with a suffix of the form ":xx" in which case the +value "oid.xx" will be used. +.TP +.B password\-hash <hash> [<hash>...] +This option configures one or more hashes to be used in generation of user +passwords stored in the userPassword attribute during processing of +LDAP Password Modify Extended Operations (RFC 3062). +The <hash> must be one of +.BR {SSHA} , +.BR {SHA} , +.BR {SMD5} , +.BR {MD5} , +.BR {CRYPT} , +and +.BR {CLEARTEXT} . +The default is +.BR {SSHA} . + +.B {SHA} +and +.B {SSHA} +use the SHA-1 algorithm (FIPS 160-1), the latter with a seed. + +.B {MD5} +and +.B {SMD5} +use the MD5 algorithm (RFC 1321), the latter with a seed. + +.B {CRYPT} +uses the +.BR crypt (3). + +.B {CLEARTEXT} +indicates that the new password should be +added to userPassword as clear text. + +Note that this option does not alter the normal user applications +handling of userPassword during LDAP Add, Modify, or other LDAP operations. +.TP +.B password\-crypt\-salt\-format <format> +Specify the format of the salt passed to +.BR crypt (3) +when generating {CRYPT} passwords (see +.BR password\-hash ) +during processing of LDAP Password Modify Extended Operations (RFC 3062). + +This string needs to be in +.BR sprintf (3) +format and may include one (and only one) %s conversion. +This conversion will be substituted with a string of random +characters from [A\-Za\-z0\-9./]. For example, "%.2s" +provides a two character salt and "$1$%.8s" tells some +versions of crypt(3) to use an MD5 algorithm and provides +8 random characters of salt. The default is "%s", which +provides 31 characters of salt. +.TP +.B pidfile <filename> +The (absolute) name of a file that will hold the +.B slapd +server's process ID (see +.BR getpid (2)). +.TP +.B pluginlog: <filename> +The ( absolute ) name of a file that will contain log +messages from +.B SLAPI +plugins. See +.BR slapd.plugin (5) +for details. +.TP +.B referral <url> +Specify the referral to pass back when +.BR slapd (8) +cannot find a local database to handle a request. +If specified multiple times, each url is provided. +.TP +.B require <conditions> +Specify a set of conditions (separated by white space) to +require (default none). +The directive may be specified globally and/or per-database; +databases inherit global conditions, so per-database specifications +are additive. +.B bind +requires bind operation prior to directory operations. +.B LDAPv3 +requires session to be using LDAP version 3. +.B authc +requires authentication prior to directory operations. +.B SASL +requires SASL authentication prior to directory operations. +.B strong +requires strong authentication prior to directory operations. +The strong keyword allows protected "simple" authentication +as well as SASL authentication. +.B none +may be used to require no conditions (useful to clear out globally +set conditions within a particular database); it must occur first +in the list of conditions. +.TP +.B reverse\-lookup on | off +Enable/disable client name unverified reverse lookup (default is +.BR off +if compiled with \-\-enable\-rlookups). +.TP +.B rootDSE <file> +Specify the name of an LDIF(5) file containing user defined attributes +for the root DSE. These attributes are returned in addition to the +attributes normally produced by slapd. + +The root DSE is an entry with information about the server and its +capabilities, in operational attributes. +It has the empty DN, and can be read with e.g.: +.ti +4 +ldapsearch \-x \-b "" \-s base "+" +.br +See RFC 4512 section 5.1 for details. +.TP +.B sasl\-auxprops <plugin> [...] +Specify which auxprop plugins to use for authentication lookups. The +default is empty, which just uses slapd's internal support. Usually +no other auxprop plugins are needed. +.TP +.B sasl\-auxprops\-dontusecopy <attr> [...] +Specify which attribute(s) should be subject to the don't use copy control. This +is necessary for some SASL mechanisms such as OTP to work in a replicated +environment. The attribute "cmusaslsecretOTP" is the default value. +.TP +.B sasl\-auxprops\-dontusecopy\-ignore on | off +Used to disable replication of the attribute(s) defined by +sasl-auxprops-dontusecopy and instead use a local value for the attribute. This +allows the SASL mechanism to continue to work if the provider is offline. This can +cause replication inconsistency. Defaults to off. +.TP +.B sasl\-host <fqdn> +Used to specify the fully qualified domain name used for SASL processing. +.TP +.B sasl\-realm <realm> +Specify SASL realm. Default is empty. +.TP +.B sasl\-cbinding none | tls-unique | tls-endpoint +Specify the channel-binding type, see also LDAP_OPT_X_SASL_CBINDING. +Default is none. +.TP +.B sasl\-secprops <properties> +Used to specify Cyrus SASL security properties. +The +.B none +flag (without any other properties) causes the flag properties +default, "noanonymous,noplain", to be cleared. +The +.B noplain +flag disables mechanisms susceptible to simple passive attacks. +The +.B noactive +flag disables mechanisms susceptible to active attacks. +The +.B nodict +flag disables mechanisms susceptible to passive dictionary attacks. +The +.B noanonymous +flag disables mechanisms which support anonymous login. +The +.B forwardsec +flag require forward secrecy between sessions. +The +.B passcred +require mechanisms which pass client credentials (and allow +mechanisms which can pass credentials to do so). +The +.B minssf=<factor> +property 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. +The +.B maxssf=<factor> +property specifies the maximum acceptable +.I security strength factor +as an integer (see minssf description). The default is INT_MAX. +The +.B maxbufsize=<size> +property specifies the maximum security layer receive buffer +size allowed. 0 disables security layers. The default is 65536. +.TP +.B schemadn <dn> +Specify the distinguished name for the subschema subentry that +controls the entries on this server. The default is "cn=Subschema". +.TP +.B security <factors> +Specify a set of security strength factors (separated by white space) +to require (see +.BR sasl\-secprops 's +.B minssf +option for a description of security strength factors). +The directive may be specified globally and/or per-database. +.B ssf=<n> +specifies the overall security strength factor. +.B transport=<n> +specifies the transport security strength factor. +.B tls=<n> +specifies the TLS security strength factor. +.B sasl=<n> +specifies the SASL security strength factor. +.B update_ssf=<n> +specifies the overall security strength factor to require for +directory updates. +.B update_transport=<n> +specifies the transport security strength factor to require for +directory updates. +.B update_tls=<n> +specifies the TLS security strength factor to require for +directory updates. +.B update_sasl=<n> +specifies the SASL security strength factor to require for +directory updates. +.B simple_bind=<n> +specifies the security strength factor required for +.I simple +username/password authentication. +Note that the +.B transport +factor is measure of security provided by the underlying transport, +e.g. ldapi:// (and eventually IPSEC). It is not normally used. +.TP +.B serverID <integer> [<URL>] +Specify an integer ID from 0 to 4095 for this server. The ID may also be +specified as a hexadecimal ID by prefixing the value with "0x". +Non-zero IDs are required when using multi-provider replication and each +provider must have a unique non-zero ID. Note that this requirement also +applies to separate providers contributing to a glued set of databases. +If the URL is provided, this directive may be specified +multiple times, providing a complete list of participating servers +and their IDs. The fully qualified hostname of each server should be +used in the supplied URLs. The IDs are used in the "replica id" field +of all CSNs generated by the specified server. The default value is zero, which +is only valid for single provider replication. +Example: +.LP +.nf + serverID 1 ldap://ldap1.example.com + serverID 2 ldap://ldap2.example.com +.fi +.TP +.B sizelimit {<integer>|unlimited} +.TP +.B sizelimit size[.{soft|hard}]=<integer> [...] +Specify the maximum number of entries to return from a search operation. +The default size limit is 500. +Use +.B unlimited +to specify no limits. +The second format allows a fine grain setting of the size limits. +If no special qualifiers are specified, both soft and hard limits are set. +Extra args can be added on the same line. +Additional qualifiers are available; see +.BR limits +for an explanation of all of the different flags. +.TP +.B sockbuf_max_incoming <integer> +Specify the maximum incoming LDAP PDU size for anonymous sessions. +The default is 262143. +.TP +.B sockbuf_max_incoming_auth <integer> +Specify the maximum incoming LDAP PDU size for authenticated sessions. +The default is 4194303. +.TP +.B sortvals <attr> [...] +Specify a list of multi-valued attributes whose values will always +be maintained in sorted order. Using this option will allow Modify, +Compare, and filter evaluations on these attributes to be performed +more efficiently. The resulting sort order depends on the +attributes' syntax and matching rules and may not correspond to +lexical order or any other recognizable order. +.TP +.B tcp-buffer [listener=<URL>] [{read|write}=]<size> +Specify the size of the TCP buffer. +A global value for both read and write TCP buffers related to any listener +is defined, unless the listener is explicitly specified, +or either the read or write qualifiers are used. +See +.BR tcp (7) +for details. +Note that some OS-es implement automatic TCP buffer tuning. +.TP +.B threads <integer> +Specify the maximum size of the primary thread pool. +The default is 16; the minimum value is 2. +.TP +.B threadqueues <integer> +Specify the number of work queues to use for the primary thread pool. +The default is 1 and this is typically adequate for up to 8 CPU cores. +The value should not exceed the number of CPUs in the system. +.TP +.B timelimit {<integer>|unlimited} +.TP +.B timelimit time[.{soft|hard}]=<integer> [...] +Specify the maximum number of seconds (in real time) +.B slapd +will spend answering a search request. The default time limit is 3600. +Use +.B unlimited +to specify no limits. +The second format allows a fine grain setting of the time limits. +Extra args can be added on the same line. See +.BR limits +for an explanation of the different flags. +.TP +.B tool\-threads <integer> +Specify the maximum number of threads to use in tool mode. +This should not be greater than the number of CPUs in the system. +The default is 1. +.TP +.B writetimeout <integer> +Specify the number of seconds to wait before forcibly closing +a connection with an outstanding write. This allows recovery from +various network hang conditions. A writetimeout of 0 disables this +feature. The default is 0. +.SH TLS OPTIONS +If +.B slapd +is built with support for Transport Layer Security, there are more options +you can specify. +.TP +.B TLSCipherSuite <cipher-suite-spec> +Permits configuring what ciphers will be accepted and the preference order. +<cipher-suite-spec> should be a cipher specification for the TLS library +in use (OpenSSL or GnuTLS). +Example: +.RS +.RS +.TP +.I OpenSSL: +TLSCipherSuite HIGH:MEDIUM:+SSLv2 +.TP +.I GnuTLS: +TLSCiphersuite SECURE256:!AES-128-CBC +.RE + +To check what ciphers a given spec selects in OpenSSL, use: + +.nf + openssl ciphers \-v <cipher-suite-spec> +.fi + +With GnuTLS the available specs can be found in the manual page of +.BR gnutls\-cli (1) +(see the description of the +option +.BR \-\-priority ). + +In older versions of GnuTLS, where gnutls\-cli does not support the option +\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling: + +.nf + gnutls\-cli \-l +.fi +.RE +.TP +.B TLSCACertificateFile <filename> +Specifies the file that contains certificates for all of the Certificate +Authorities that +.B slapd +will recognize. The certificate for +the CA that signed the server certificate must(GnuTLS)/may(OpenSSL) be included among +these certificates. If the signing CA was not a top-level (root) CA, +certificates for the entire sequence of CA's from the signing CA to +the top-level CA should be present. Multiple certificates are simply +appended to the file; the order is not significant. +.TP +.B TLSCACertificatePath <path> +Specifies the path of a directory that contains Certificate Authority +certificates in separate individual files. Usually only one of this +or the TLSCACertificateFile is used. If both are specified, both +locations will be used. +.TP +.B TLSCertificateFile <filename> +Specifies the file that contains the +.B slapd +server certificate. + +When using OpenSSL that file may also contain any number of intermediate +certificates after the server certificate. +.TP +.B TLSCertificateKeyFile <filename> +Specifies the file that contains the +.B slapd +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. +.TP +.B TLSDHParamFile <filename> +This directive specifies the file that contains parameters for Diffie-Hellman +ephemeral key exchange. This is required in order to use a DSA certificate on +the server, or an RSA certificate missing the "key encipherment" key usage. +Note that setting this option may also enable +Anonymous Diffie-Hellman key exchanges in certain non-default cipher suites. +Anonymous key exchanges should generally be avoided since they provide no +actual client or server authentication and provide no protection against +man-in-the-middle attacks. +You should append "!ADH" to your cipher suites to ensure that these suites +are not used. +.TP +.B TLSECName <name> +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 TLSProtocolMin <major>[.<minor>] +Specifies minimum SSL/TLS protocol version that will be negotiated. +If the server doesn't support at least that version, +the SSL handshake will fail. +To require TLS 1.x or higher, set this option to 3.(x+1), +e.g., + +.nf + TLSProtocolMin 3.2 +.fi + +would require TLS 1.1. +Specifying a minimum that is higher than that supported by the +OpenLDAP implementation will result in it requiring the +highest level that it does support. +This directive is ignored with GnuTLS. +.TP +.B TLSRandFile <filename> +Specifies the file to obtain random bits from when /dev/[u]random +is not available. Generally set to the name of the EGD/PRNGD socket. +The environment variable RANDFILE can also be used to specify the filename. +This directive is ignored with GnuTLS. +.TP +.B TLSVerifyClient <level> +Specifies what checks to perform on client certificates in an +incoming TLS session, if any. +The +.B <level> +can be specified as one of the following keywords: +.RS +.TP +.B never +This is the default. +.B slapd +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. + +Note that a valid client certificate is required in order to use the +SASL EXTERNAL authentication mechanism with a TLS session. As such, +a non-default +.B TLSVerifyClient +setting must be chosen to enable SASL EXTERNAL authentication. +.RE +.TP +.B TLSCRLCheck <level> +Specifies if the Certificate Revocation List (CRL) of the CA should be +used to verify if the client certificates have not been revoked. This +requires +.B TLSCACertificatePath +parameter to be set. This directive is ignored with GnuTLS. +.B <level> +can be specified as one of the following keywords: +.RS +.TP +.B none +No CRL checks are performed +.TP +.B peer +Check the CRL of the peer certificate +.TP +.B all +Check the CRL for a whole certificate chain +.RE +.TP +.B TLSCRLFile <filename> +Specifies a file containing a Certificate Revocation List to be used +for verifying that certificates have not been revoked. This directive is +only valid when using GnuTLS. +.SH GENERAL BACKEND OPTIONS +Options in this section only apply to the configuration file section +of all instances of the specified backend. All backends may support +this class of options, but currently only back-mdb does. +.TP +.B backend <databasetype> +Mark the beginning of a backend definition. <databasetype> +should be one of +.BR asyncmeta , +.BR config , +.BR dnssrv , +.BR ldap , +.BR ldif , +.BR mdb , +.BR meta , +.BR monitor , +.BR ndb , +.BR null , +.BR passwd , +.BR perl , +.BR relay , +.BR sock , +.BR sql , +or +.BR wt . +At present, only back-mdb implements any options of this type, so this +setting is not needed for any other backends. + +.SH GENERAL DATABASE OPTIONS +Options in this section only apply to the configuration file section +for the database in which they are defined. They are supported by every +type of backend. Note that the +.B database +and at least one +.B suffix +option are mandatory for each database. +.TP +.B database <databasetype> +Mark the beginning of a new database instance definition. <databasetype> +should be one of +.BR asyncmeta , +.BR config , +.BR dnssrv , +.BR ldap , +.BR ldif , +.BR mdb , +.BR meta , +.BR monitor , +.BR ndb , +.BR null , +.BR passwd , +.BR perl , +.BR relay , +.BR sock , +.BR sql , +or +.BR wt , +depending on which backend will serve the database. + +LDAP operations, even subtree searches, normally access only one +database. +That can be changed by gluing databases together with the +.B subordinate +keyword. +Access controls and some overlays can also involve multiple databases. +.TP +.B add_content_acl on | off +Controls whether Add operations will perform ACL checks on +the content of the entry being added. This check is off +by default. See the +.BR slapd.access (5) +manual page for more details on ACL requirements for +Add operations. +.TP +.B extra_attrs <attrlist> +Lists what attributes need to be added to search requests. +Local storage backends return the entire entry to the frontend. +The frontend takes care of only returning the requested attributes +that are allowed by ACLs. +However, features like access checking and so may need specific +attributes that are not automatically returned by remote storage +backends, like proxy backends and so on. +.B <attrlist> +is a list of attributes that are needed for internal purposes +and thus always need to be collected, even when not explicitly +requested by clients. +.TP +.B hidden on | off +Controls whether the database will be used to answer +queries. A database that is hidden will never be +selected to answer any queries, and any suffix configured +on the database will be ignored in checks for conflicts +with other databases. By default, hidden is off. +.TP +.B lastmod on | off +Controls whether +.B slapd +will automatically maintain the +modifiersName, modifyTimestamp, creatorsName, and +createTimestamp attributes for entries. It also controls +the entryCSN and entryUUID attributes, which are needed +by the syncrepl provider. By default, lastmod is on. +.TP +.B lastbind on | off +Controls whether +.B slapd +will automatically maintain the pwdLastSuccess attribute for +entries. By default, lastbind is off. +.TP +.B limits <selector> <limit> [<limit> [...]] +Specify time and size limits based on the operation's initiator or +base DN. +The argument +.B <selector> +can be any of +.RS +.RS +.TP +anonymous | users | [<dnspec>=]<pattern> | group[/oc[/at]]=<pattern> + +.RE +with +.RS +.TP +<dnspec> ::= dn[.<type>][.<style>] +.TP +<type> ::= self | this +.TP +<style> ::= exact | base | onelevel | subtree | children | regex | anonymous + +.RE +DN type +.B self +is the default and means the bound user, while +.B this +means the base DN of the operation. +The term +.B anonymous +matches all unauthenticated clients. +The term +.B users +matches all authenticated clients; +otherwise an +.B exact +dn pattern is assumed unless otherwise specified by qualifying +the (optional) key string +.B dn +with +.B exact +or +.B base +(which are synonyms), to require an exact match; with +.BR onelevel , +to require exactly one level of depth match; with +.BR subtree , +to allow any level of depth match, including the exact match; with +.BR children , +to allow any level of depth match, not including the exact match; +.BR regex +explicitly requires the (default) match based on POSIX (''extended'') +regular expression pattern. +Finally, +.B anonymous +matches unbound operations; the +.B pattern +field is ignored. +The same behavior is obtained by using the +.B anonymous +form of the +.B <selector> +clause. +The term +.BR group , +with the optional objectClass +.B oc +and attributeType +.B at +fields, followed by +.BR pattern , +sets the limits for any DN listed in the values of the +.B at +attribute (default +.BR member ) +of the +.B oc +group objectClass (default +.BR groupOfNames ) +whose DN exactly matches +.BR pattern . + +The currently supported limits are +.B size +and +.BR time . + +The syntax for time limits is +.BR time[.{soft|hard}]=<integer> , +where +.I integer +is the number of seconds slapd will spend answering a search request. +If no time limit is explicitly requested by the client, the +.BR soft +limit is used; if the requested time limit exceeds the +.BR hard +.\"limit, an +.\".I "Administrative limit exceeded" +.\"error is returned. +limit, the value of the limit is used instead. +If the +.BR hard +limit is set to the keyword +.IR soft , +the soft limit is used in either case; if it is set to the keyword +.IR unlimited , +no hard limit is enforced. +Explicit requests for time limits smaller or equal to the +.BR hard +limit are honored. +If no limit specifier is set, the value is assigned to the +.BR soft +limit, and the +.BR hard +limit is set to +.IR soft , +to preserve the original behavior. + +The syntax for size limits is +.BR size[.{soft|hard|unchecked}]=<integer> , +where +.I integer +is the maximum number of entries slapd will return answering a search +request. +If no size limit is explicitly requested by the client, the +.BR soft +limit is used; if the requested size limit exceeds the +.BR hard +.\"limit, an +.\".I "Administrative limit exceeded" +.\"error is returned. +limit, the value of the limit is used instead. +If the +.BR hard +limit is set to the keyword +.IR soft , +the soft limit is used in either case; if it is set to the keyword +.IR unlimited , +no hard limit is enforced. +Explicit requests for size limits smaller or equal to the +.BR hard +limit are honored. +The +.BR unchecked +specifier sets a limit on the number of candidates a search request is allowed +to examine. +The rationale behind it is that searches for non-properly indexed +attributes may result in large sets of candidates, which must be +examined by +.BR slapd (8) +to determine whether they match the search filter or not. +The +.B unchecked +limit provides a means to drop such operations before they are even +started. +If the selected candidates exceed the +.BR unchecked +limit, the search will abort with +.IR "Unwilling to perform" . +If it is set to the keyword +.IR unlimited , +no limit is applied (the default). +If it is set to +.IR disabled , +the search is not even performed; this can be used to disallow searches +for a specific set of users. +If no limit specifier is set, the value is assigned to the +.BR soft +limit, and the +.BR hard +limit is set to +.IR soft , +to preserve the original behavior. + +In case of no match, the global limits are used. +The default values are the same as for +.B sizelimit +and +.BR timelimit ; +no limit is set on +.BR unchecked . + +If +.B pagedResults +control is requested, the +.B hard +size limit is used by default, because the request of a specific page size +is considered an explicit request for a limitation on the number +of entries to be returned. +However, the size limit applies to the total count of entries returned within +the search, and not to a single page. +Additional size limits may be enforced; the syntax is +.BR size.pr={<integer>|noEstimate|unlimited} , +where +.I integer +is the max page size if no explicit limit is set; the keyword +.I noEstimate +inhibits the server from returning an estimate of the total number +of entries that might be returned +(note: the current implementation does not return any estimate). +The keyword +.I unlimited +indicates that no limit is applied to the pagedResults control page size. +The syntax +.B size.prtotal={<integer>|hard|unlimited|disabled} +allows one to set a limit on the total number of entries that the pagedResults +control will return. +By default it is set to the +.B hard +limit which will use the size.hard value. +When set, +.I integer +is the max number of entries that the whole search with pagedResults control +can return. +Use +.I unlimited +to allow unlimited number of entries to be returned, e.g. to allow +the use of the pagedResults control as a means to circumvent size +limitations on regular searches; the keyword +.I disabled +disables the control, i.e. no paged results can be returned. +Note that the total number of entries returned when the pagedResults control +is requested cannot exceed the +.B hard +size limit of regular searches unless extended by the +.B prtotal +switch. + +The \fBlimits\fP statement is typically used to let an unlimited +number of entries be returned by searches performed +with the identity used by the consumer for synchronization purposes +by means of the RFC 4533 LDAP Content Synchronization protocol +(see \fBsyncrepl\fP for details). + +When using subordinate databases, it is necessary for any limits that +are to be applied across the parent and its subordinates to be defined in +both the parent and its subordinates. Otherwise the settings on the +subordinate databases are not honored. +.RE +.TP +.B maxderefdepth <depth> +Specifies the maximum number of aliases to dereference when trying to +resolve an entry, used to avoid infinite alias loops. The default is 15. +.TP +.B multiprovider on | off +This option puts a consumer database into Multi-Provider mode. Update +operations will be accepted from any user, not just the updatedn. The +database must already be configured as a syncrepl consumer +before this keyword may be set. This mode also requires a +.B serverID +(see above) to be configured. +By default, multiprovider is off. +.TP +.B monitoring on | off +This option enables database-specific monitoring in the entry related +to the current database in the "cn=Databases,cn=Monitor" subtree +of the monitor database, if the monitor database is enabled. +Currently, only the MDB database provides database-specific monitoring. +If monitoring is supported by the backend it defaults to on, otherwise +off. +.TP +.B overlay <overlay-name> +Add the specified overlay to this database. An overlay is a piece of +code that intercepts database operations in order to extend or change +them. Overlays are pushed onto +a stack over the database, and so they will execute in the reverse +of the order in which they were configured and the database itself +will receive control last of all. See the +.BR slapd.overlays (5) +manual page for an overview of the available overlays. +Note that all of the database's +regular settings should be configured before any overlay settings. +.TP +.B readonly on | off +This option puts the database into "read-only" mode. Any attempts to +modify the database will return an "unwilling to perform" error. By +default, readonly is off. +.TP +.B restrict <oplist> +Specify a whitespace separated list of operations that are restricted. +If defined inside a database specification, restrictions apply only +to that database, otherwise they are global. +Operations can be any of +.BR add , +.BR bind , +.BR compare , +.BR delete , +.BR extended[=<OID>] , +.BR modify , +.BR rename , +.BR search , +or the special pseudo-operations +.B read +and +.BR write , +which respectively summarize read and write operations. +The use of +.I restrict write +is equivalent to +.I readonly on +(see above). +The +.B extended +keyword allows one to indicate the OID of the specific operation +to be restricted. +.TP +.B rootdn <dn> +Specify the distinguished name that is not subject to access control +or administrative limit restrictions for operations on this database. +This DN may or may not be associated with an entry. An empty root +DN (the default) specifies no root access is to be granted. It is +recommended that the rootdn only be specified when needed (such as +when initially populating a database). If the rootdn is within +a namingContext (suffix) of the database, a simple bind password +may also be provided using the +.B rootpw +directive. Many optional features, including syncrepl, require the +rootdn to be defined for the database. +.TP +.B rootpw <password> +Specify a password (or hash of the password) for the rootdn. The +password can only be set if the rootdn is within the namingContext +(suffix) of the database. +This option accepts all RFC 2307 userPassword formats known to +the server (see +.B password\-hash +description) as well as cleartext. +.BR slappasswd (8) +may be used to generate a hash of a password. Cleartext +and \fB{CRYPT}\fP passwords are not recommended. If empty +(the default), authentication of the root DN is by other means +(e.g. SASL). Use of SASL is encouraged. +.TP +.B suffix <dn suffix> +Specify the DN suffix of queries that will be passed to this +backend database. Multiple suffix lines can be given and at least one is +required for each database definition. + +If the suffix of one database is "inside" that of another, the database +with the inner suffix must come first in the configuration file. +You may also want to glue such databases together with the +.B subordinate +keyword. +.TP +.B subordinate [advertise] +Specify that the current backend database is a subordinate of another +backend database. A subordinate database may have only one suffix. This +option may be used to glue multiple databases into a single namingContext. +If the suffix of the current database is within the namingContext of a +superior database, searches against the superior database will be +propagated to the subordinate as well. All of the databases +associated with a single namingContext should have identical rootdns. +Behavior of other LDAP operations is unaffected by this setting. In +particular, it is not possible to use moddn to move an entry from +one subordinate to another subordinate within the namingContext. + +If the optional \fBadvertise\fP flag is supplied, the naming context of +this database is advertised in the root DSE. The default is to hide this +database context, so that only the superior context is visible. + +If the slap tools +.BR slapcat (8), +.BR slapadd (8), +.BR slapmodify (8), +or +.BR slapindex (8) +are used on the superior database, any glued subordinates that support +these tools are opened as well. + +Databases that are glued together should usually be configured with the +same indices (assuming they support indexing), even for attributes that +only exist in some of these databases. In general, all of the glued +databases should be configured as similarly as possible, since the intent +is to provide the appearance of a single directory. + +Note that the \fIsubordinate\fP functionality is implemented internally +by the \fIglue\fP overlay and as such its behavior will interact with other +overlays in use. By default, the glue overlay is automatically configured as +the last overlay on the superior backend. Its position on the backend +can be explicitly configured by setting an \fBoverlay glue\fP directive +at the desired position. This explicit configuration is necessary e.g. +when using the \fIsyncprov\fP overlay, which needs to follow \fIglue\fP +in order to work over all of the glued databases. E.g. +.RS +.nf + database mdb + suffix dc=example,dc=com + ... + overlay glue + overlay syncprov +.fi +.RE +.TP +.B sync_use_subentry +Store the syncrepl contextCSN in a subentry instead of the context entry +of the database. The subentry's RDN will be "cn=ldapsync". By default +the contextCSN is stored in the context entry. +.HP +.hy 0 +.B syncrepl rid=<replica ID> +.B provider=ldap[s]://<hostname>[:port] +.B searchbase=<base DN> +.B [type=refreshOnly|refreshAndPersist] +.B [interval=dd:hh:mm:ss] +.B [retry=[<retry interval> <# of retries>]+] +.B [filter=<filter str>] +.B [scope=sub|one|base|subord] +.B [attrs=<attr list>] +.B [exattrs=<attr list>] +.B [attrsonly] +.B [sizelimit=<limit>] +.B [timelimit=<limit>] +.B [schemachecking=on|off] +.B [network\-timeout=<seconds>] +.B [timeout=<seconds>] +.B [tcp\-user\-timeout=<milliseconds>] +.B [bindmethod=simple|sasl] +.B [binddn=<dn>] +.B [saslmech=<mech>] +.B [authcid=<identity>] +.B [authzid=<identity>] +.B [credentials=<passwd>] +.B [realm=<realm>] +.B [secprops=<properties>] +.B [keepalive=<idle>:<probes>:<interval>] +.B [starttls=yes|critical] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_crlcheck=none|peer|all] +.B [tls_protocol_min=<major>[.<minor>]] +.B [suffixmassage=<real DN>] +.B [logbase=<base DN>] +.B [logfilter=<filter str>] +.B [syncdata=default|accesslog|changelog] +.B [lazycommit] +.RS +Specify the current database as a consumer which is kept up-to-date with the +provider content by establishing the current +.BR slapd (8) +as a replication consumer site running a +.B syncrepl +replication engine. +The consumer content is kept synchronized to the provider content using +the LDAP Content Synchronization protocol. Refer to the +"OpenLDAP Administrator's Guide" for detailed information on +setting up a replicated +.B slapd +directory service using the +.B syncrepl +replication engine. + +.B rid +identifies the current +.B syncrepl +directive within the replication consumer site. +It is a non-negative integer not greater than 999 (limited +to three decimal digits). + +.B provider +specifies the replication provider site containing the provider content +as an LDAP URI. If <port> is not given, the standard LDAP port number +(389 or 636) is used. + +The content of the +.B syncrepl +consumer is defined using a search +specification as its result set. The consumer +.B slapd +will send search requests to the provider +.B slapd +according to the search specification. The search specification includes +.BR searchbase ", " scope ", " filter ", " attrs ", " attrsonly ", " sizelimit ", " +and +.B timelimit +parameters as in the normal search specification. The +.B exattrs +option may also be used to specify attributes that should be omitted +from incoming entries. +The \fBscope\fP defaults to \fBsub\fP, the \fBfilter\fP defaults to +\fB(objectclass=*)\fP, and there is no default \fBsearchbase\fP. The +\fBattrs\fP list defaults to \fB"*,+"\fP to return all user and operational +attributes, and \fBattrsonly\fP and \fBexattrs\fP are unset by default. +The \fBsizelimit\fP and \fBtimelimit\fP only +accept "unlimited" and positive integers, and both default to "unlimited". +The \fBsizelimit\fP and \fBtimelimit\fP parameters define +a consumer requested limitation on the number of entries that can be returned +by the LDAP Content Synchronization operation; these should be left unchanged +from the default otherwise replication may never succeed. +Note, however, that any provider-side limits for the replication identity +will be enforced by the provider regardless of the limits requested +by the LDAP Content Synchronization operation, much like for any other +search operation. + +The LDAP Content Synchronization protocol has two operation types. +In the +.B refreshOnly +operation, the next synchronization search operation +is periodically rescheduled at an interval time (specified by +.B interval +parameter; 1 day by default) +after each synchronization operation finishes. +In the +.B refreshAndPersist +operation, a synchronization search remains persistent in the provider slapd. +Further updates to the provider will generate +.B searchResultEntry +to the consumer slapd as the search responses to the persistent +synchronization search. If the initial search fails due to an error, the +next synchronization search operation is periodically rescheduled at an +interval time (specified by +.B interval +parameter; 1 day by default) + +If an error occurs during replication, the consumer will attempt to +reconnect according to the +.B retry +parameter which is a list of the <retry interval> and <# of retries> pairs. +For example, retry="60 10 300 3" lets the consumer retry every 60 seconds +for the first 10 times and then retry every 300 seconds for the next 3 +times before stop retrying. The `+' in <# of retries> means indefinite +number of retries until success. +If no +.B retry +is specified, by default syncrepl retries every hour forever. + +The schema checking can be enforced at the LDAP Sync +consumer site by turning on the +.B schemachecking +parameter. The default is \fBoff\fP. +Schema checking \fBon\fP means that replicated entries must have +a structural objectClass, must obey to objectClass requirements +in terms of required/allowed attributes, and that naming attributes +and distinguished values must be present. +As a consequence, schema checking should be \fBoff\fP when partial +replication is used. + +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). +The +.B tcp\-user\-timeout +parameter, if non-zero, corresponds to the +.B TCP_USER_TIMEOUT +set on the target 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. + +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 identity used for synchronization by the consumer should be allowed +to receive an unlimited number of entries in response to a search request. +The provider, other than allowing authentication of the syncrepl identity, +should grant that identity appropriate access privileges to the data +that is being replicated (\fBaccess\fP directive), and appropriate time +and size limits. +This can be accomplished by either allowing unlimited \fBsizelimit\fP +and \fBtimelimit\fP, or by setting an appropriate \fBlimits\fP statement +in the consumer's configuration (see \fBsizelimit\fP and \fBlimits\fP +for details). + +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 +.B tls_reqcert +setting defaults to "demand", the +.B tls_reqsan +setting defaults to "allow", and the other TLS settings +default to the same as the main slapd TLS settings. + +The +.B suffixmassage +parameter allows the consumer to pull entries from a remote directory +whose DN suffix differs from the local directory. The portion of the +remote entries' DNs that matches the \fIsearchbase\fP will be replaced +with the suffixmassage DN. + +Rather than replicating whole entries, the consumer can query logs of +data modifications. This mode of operation is referred to as \fIdelta +syncrepl\fP. In addition to the above parameters, the +.B logbase +and +.B logfilter +parameters must be set appropriately for the log that will be used. The +.B syncdata +parameter must be set to either "accesslog" if the log conforms to the +.BR slapo\-accesslog (5) +log format, or "changelog" if the log conforms +to the obsolete \fIchangelog\fP format. If the +.B syncdata +parameter is omitted or set to "default" then the log parameters are +ignored. + +The +.B lazycommit +parameter tells the underlying database that it can store changes without +performing a full flush after each change. This may improve performance +for the consumer, while sacrificing safety or durability. +.RE +.TP +.B updatedn <dn> +This option is only applicable in a replica +database. +It specifies the DN permitted to update (subject to access controls) +the replica. It is only needed in certain push-mode +replication scenarios. Generally, this DN +.I should not +be the same as the +.B rootdn +used at the provider. +.TP +.B updateref <url> +Specify the referral to pass back when +.BR slapd (8) +is asked to modify a replicated local database. +If specified multiple times, each url is provided. + +.SH DATABASE-SPECIFIC OPTIONS +Each database may allow specific configuration options; they are +documented separately in the backends' manual pages. See the +.BR slapd.backends (5) +manual page for an overview of available backends. +.SH EXAMPLES +.LP +Here is a short example of a configuration file: +.LP +.RS +.nf +include SYSCONFDIR/schema/core.schema +pidfile LOCALSTATEDIR/run/slapd.pid + +# Subtypes of "name" (e.g. "cn" and "ou") with the +# option ";x\-hidden" can be searched for/compared, +# but are not shown. See \fBslapd.access\fP(5). +attributeoptions x\-hidden lang\- +access to attrs=name;x\-hidden by * =cs + +# Protect passwords. See \fBslapd.access\fP(5). +access to attrs=userPassword by * auth +# Read access to other attributes and entries. +access to * by * read + +database mdb +suffix "dc=our\-domain,dc=com" +# The database directory MUST exist prior to +# running slapd AND should only be accessible +# by the slapd/tools. Mode 0700 recommended. +directory LOCALSTATEDIR/openldap\-data +# Indices to maintain +index objectClass eq +index cn,sn,mail pres,eq,approx,sub + +# We serve small clients that do not handle referrals, +# so handle remote lookups on their behalf. +database ldap +suffix "" +uri ldap://ldap.some\-server.com/ +lastmod off +.fi +.RE +.LP +"OpenLDAP Administrator's Guide" contains a longer annotated +example of a configuration file. +The original ETCDIR/slapd.conf is another example. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR ldap (3), +.BR gnutls\-cli (1), +.BR slapd\-config (5), +.BR slapd.access (5), +.BR slapd.backends (5), +.BR slapd.overlays (5), +.BR slapd.plugin (5), +.BR slapd (8), +.BR slapacl (8), +.BR slapadd (8), +.BR slapauth (8), +.BR slapcat (8), +.BR slapdn (8), +.BR slapindex (8), +.BR slapmodify (8), +.BR slappasswd (8), +.BR slaptest (8). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapd.overlays.5 b/doc/man/man5/slapd.overlays.5 new file mode 100644 index 0000000..307a28a --- /dev/null +++ b/doc/man/man5/slapd.overlays.5 @@ -0,0 +1,204 @@ +.TH SLAPD.OVERLAYS 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2006-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd.overlays \- overlays for slapd, the stand-alone LDAP daemon +.SH DESCRIPTION +The +.BR slapd (8) +daemon can use a variety of different overlays to alter or extend +the normal behavior of a database backend. +Overlays may be compiled statically into slapd, or when module support +is enabled, they may be dynamically loaded. Most of the overlays +are only allowed to be configured on individual databases, but some +may also be configured globally. + +Configuration options for each overlay are documented separately in the +corresponding +.BR slapo\-<overlay> (5) +manual pages. +.TP +.B accesslog +Access Logging. +This overlay can record accesses to a given backend database on another +database. +.TP +.B auditlog +Audit Logging. +This overlay records changes on a given backend database to an LDIF log +file. +By default it is not built. +.TP +.B autoca +Automatic Certificate Authority overlay. +This overlay can generate X.509 certificate/key pairs for +entries in the directory if slapd is linked to OpenSSL. +By default it is not built. +.TP +.B chain +Chaining. +This overlay allows automatic referral chasing when a referral would +have been returned, either when configured by the server or when +requested by the client. +.TP +.B collect +Collective Attributes. +This overlay implements RFC 3671 collective attributes; these +attributes share common values over all the members of the collection +as inherited from an ancestor entry. +.TP +.B constraint +Constraint. +This overlay enforces a regular expression constraint on all values +of specified attributes. It is used to enforce a more rigorous +syntax when the underlying attribute syntax is too general. +.TP +.B dds +Dynamic Directory Services. +This overlay supports dynamic objects, which have a limited life after +which they expire and are automatically deleted. +.TP +.B deref +Dereference Control. +This overlay implements the draft Dereference control. The overlay can be +used with any backend or globally for all backends. +.TP +.B dyngroup +Dynamic Group. +This is a demo overlay which extends the Compare operation to detect +members of a dynamic group. +It has no effect on any other operations. +.TP +.B dynlist +Dynamic List. +This overlay allows expansion of dynamic groups and more. +.TP +.B homedir +Home Directory Provisioning. +This overlay manages creation/deletion of home directories for LDAP-based +Unix accounts. +.TP +.B memberof +MemberOf. +This overlay maintains automatic reverse group membership values, +typically stored in an attribute called memberOf. This overlay +is deprecated and should be replaced with dynlist. +.TP +.B otp +OATH One-Time Password module. +This module allows time-based one-time password, AKA "authenticator-style", +and HMAC-based one-time password authentication to be used in conjunction +with a standard LDAP password for two factor authentication. +.TP +.B pbind +Proxybind. +This overlay forwards simple bind requests on a local database to a +remote LDAP server. +.TP +.B pcache +Proxycache. +This overlay allows caching of LDAP search requests in a local database. +It is most often used with the +.BR slapd\-ldap (5) +or +.BR slapd\-meta (5) +backends. +.TP +.B ppolicy +Password Policy. +This overlay provides a variety of password control mechanisms, +e.g. password aging, password reuse and duplication control, mandatory +password resets, etc. +.TP +.B refint +Referential Integrity. +This overlay can be used with a backend database such as +.BR slapd\-mdb (5) +to maintain the cohesiveness of a schema which utilizes reference +attributes. +.TP +.B remoteauth +Remote Authentication. +This overlay delegates authentication requests to remote directories. +.TP +.B retcode +Return Code. +This overlay is useful to test the behavior of clients when +server-generated erroneous and/or unusual responses occur. +.TP +.B rwm +Rewrite/remap. +This overlay is experimental. +It performs basic DN/data rewrite and +objectClass/attributeType mapping. +.TP +.B sssvlv +Server Side Sorting and Virtual List Views. +This overlay implements the RFC2891 server-side sorting control and +virtual list view controls, and replaces the RFC2696 paged-results +implementation to ensure it works with the sorting technique. +.TP +.B syncprov +Syncrepl Provider. +This overlay implements the provider-side support for +.B syncrepl +replication, including persistent search functionality. +.TP +.B translucent +Translucent Proxy. +This overlay can be used with a backend database such as +.BR slapd\-mdb (5) +to create a "translucent proxy". +Content of entries retrieved from a remote LDAP server can be partially +overridden by the database. +.TP +.B unique +Attribute Uniqueness. +This overlay can be used with a backend database such as +.BR slapd\-mdb (5) +to enforce the uniqueness of some or all attributes within a subtree. +.TP +.B valsort +Value Sorting. +This overlay can be used to enforce a specific order for the values +of an attribute when it is returned in a search. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +ETCDIR/slapd.d +default slapd configuration directory +.SH SEE ALSO +.BR ldap (3), +.BR slapo\-accesslog (5), +.BR slapo\-auditlog (5), +.BR slapo\-autoca (5), +.BR slapo\-chain (5), +.BR slapo\-collect (5), +.BR slapo\-constraint (5), +.BR slapo\-dds (5), +.BR slapo\-deref (5), +.BR slapo\-dyngroup (5), +.BR slapo\-dynlist (5), +.BR slapo\-memberof (5), +.BR slapo\-pbind (5), +.BR slapo\-pcache (5), +.BR slapo\-ppolicy (5), +.BR slapo\-refint (5), +.BR slapo\-remoteauth (5), +.BR slapo\-retcode (5), +.BR slapo\-rwm (5), +.BR slapo\-sssvlv (5), +.BR slapo\-syncprov (5), +.BR slapo\-translucent (5), +.BR slapo\-unique (5). +.BR slapo\-valsort (5). +.BR slapd\-config (5), +.BR slapd.conf (5), +.BR slapd.backends (5), +.BR slapd (8). +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapd.plugin.5 b/doc/man/man5/slapd.plugin.5 new file mode 100644 index 0000000..145ff87 --- /dev/null +++ b/doc/man/man5/slapd.plugin.5 @@ -0,0 +1,124 @@ +.TH SLAPD.PLUGIN 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2002-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +slapd.plugin \- plugin configuration for slapd, the stand-alone LDAP daemon +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.BR slapd.conf (5) +file contains configuration information for the +.BR slapd (8) +daemon. This configuration file is also used by the SLAPD tools +.BR slapadd (8), +.BR slapcat (8), +.BR slapmodify (8), +and +.BR slapindex (8). +.LP +The +.B slapd.conf +file consists of a series of global configuration options that apply to +.B slapd +as a whole (including all backends), followed by zero or more database +backend definitions that contain information specific to a backend +instance. +.LP +The general format of +.B slapd.conf +is as follows: +.LP +.nf + # comment - these options apply to every database + <global configuration options> + # first database definition & configuration options + database <backend 1 type> + <configuration options specific to backend 1> + # subsequent database definitions & configuration options + ... +.fi +.LP +If slapd is compiled with \fI\-\-enable\-slapi\fP, support for plugins +according to \fINetscape's Directory Server Plug-Ins\fP. +Version 4 of the API is currently implemented, with some extensions +from version 5. +.LP +Both global and database specific data may contain plugin information. +Plugins associated with a specific database are called before global +plugins. +This manpage details the +.BR slapd (8) +configuration statements that affect the loading of SLAPI \fIplugins\fP. +.LP +Arguments that should be replaced by actual text are shown in brackets <>. +.LP +The structure of the plugin directives is +.TP +.B plugin "<type> <lib_path> <init_function> [<arguments>]" +Load a plugin of the specified type for the current database. +.LP +The +.BR <type> +can be one of +.BR preoperation , +that is executed before processing the operation for the specified +database, +.BR postoperation , +that is executed after the operation for the specified database +has been processed, +.BR extendedop , +that is used when executing an extended operation, or +.BR object . +The latter is used for miscellaneous types such as ACL, computed +attribute and search filter rewriter plugins. +.LP +The +.BR <libpath> +argument specifies the path to the plugin loadable object; if a relative +path is given, the object is looked for according to the underlying +dynamic loading package (libtool's ltdl is used). +.LP +The +.BR <init_function> +argument specifies what symbol must be called when the plugin is first +loaded. +This function should register the functions provided by the plugin +for the desired operations. It should be noted that it is this +init function, not the plugin type specified as the first argument, +that determines when and for what operations the plugin will be invoked. +The optional +.BR <arguments> +list is passed to the init function. +.TP +.B pluginlog <file> +Specify an alternative path for the plugin log file (default is +LOCALSTATEDIR/errors). +.TP +.B modulepath <pathspec> +This statement sets the module load path for dynamically loadable +backends, as described in +.BR slapd.conf (5); +however, since both the dynamically loadable backends +and the SLAPI plugins use the same underlying library (libtool's ltdl) +its value also affects the plugin search path. +In general the search path is made of colon-separated paths; usually +the user-defined path is searched first; then the value of the +\fILTDL_LIBRARY_PATH\fP environment variable, if defined, is used; +finally, the system-specific dynamic load path is attempted (e.g. on +Linux the value of the environment variable \fILD_LIBRARY_PATH\fP). +Please carefully read the documentation of ltdl because its behavior +is very platform dependent. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +LOCALSTATEDIR/errors +default plugin log file +.SH SEE ALSO +.BR slapd (8), +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapo-accesslog.5 b/doc/man/man5/slapo-accesslog.5 new file mode 100644 index 0000000..a21f7d2 --- /dev/null +++ b/doc/man/man5/slapo-accesslog.5 @@ -0,0 +1,514 @@ +.TH SLAPO-ACCESSLOG 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2005-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-accesslog \- Access Logging overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Access Logging overlay can be used to record all accesses to a given +backend database on another database. This allows all of the activity on +a given database to be reviewed using arbitrary LDAP queries, instead of +just logging to local flat text files. Configuration options are available +for selecting a subset of operation types to log, and to automatically +prune older log records from the logging database. Log records are stored +with audit schema (see below) to assure their readability whether viewed +as LDIF or in raw form. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the Access Logging overlay. +They should appear after the +.B overlay +directive. +.TP +.B logdb <suffix> +Specify the suffix of a database to be used for storing the log records. +The specified database must be defined elsewhere in the configuration and +must support an ordered return of results such as +.BR slapd\-mdb (5) +The access controls +on the log database should prevent general access. The suffix entry +of the log database will be created automatically by this overlay. The log +entries will be generated as the immediate children of the suffix entry. +.TP +.B logops <operations> +Specify which types of operations to log. The valid operation types are +abandon, add, bind, compare, delete, extended, modify, modrdn, search, +and unbind. Aliases for common sets of operations are also available: +.RS +.TP +.B writes +add, delete, modify, modrdn +.TP +.B reads +compare, search +.TP +.B session +abandon, bind, unbind +.TP +.B all +all operations +.RE +.TP +.B logbase <operations> <baseDN> +Specify a set of operations that will only be logged if they occur under +a specific subtree of the database. The operation types are as above for +the +.B logops +setting, and delimited by a '|' character. +.TP +.B logold <filter> +Specify a filter for matching against Deleted and Modified entries. If +the entry matches the filter, the old contents of the entry will be +logged along with the current request. +.TP +.B logoldattr <attr> ... +Specify a list of attributes whose old contents are always logged in +Modify and ModRDN requests that match any of the filters configured in +.BR logold . +Usually only the contents of attributes that were +actually modified will be logged; by default no old attributes are logged +for ModRDN requests. +.TP +.B logpurge <age> <interval> +Specify the maximum age for log entries to be retained in the database, +and how often to scan the database for old entries. Both the +.B age +and +.B interval +are specified as a time span in days, hours, minutes, and seconds. The +time format is [ddd+]hh:mm[:ss] i.e., the days and seconds components are +optional but hours and minutes are required. Except for days, which can +be up to 5 digits, each numeric field must be exactly two digits. For example +.RS +.RS +.PD 0 +.TP +logpurge 2+00:00 1+00:00 +.RE +.PD +would specify that the log database should be scanned every day for old +entries, and entries older than two days should be deleted. When using a +log database that supports ordered indexing on generalizedTime attributes, +specifying an eq index on the +.B reqStart +attribute will greatly benefit the performance of the purge operation. +.RE +.TP +.B logsuccess TRUE | FALSE +If set to TRUE then log records will only be generated for successful +requests, i.e., requests that produce a result code of 0 (LDAP_SUCCESS). +If FALSE, log records are generated for all requests whether they +succeed or not. The default is FALSE. + +.SH EXAMPLES +.LP +.nf + database mdb + suffix dc=example,dc=com + \... + overlay accesslog + logdb cn=log + logops writes reads + logbase search|compare ou=testing,dc=example,dc=com + logold (objectclass=person) + + database mdb + suffix cn=log + \... + index reqStart eq + access to * + by dn.base="cn=admin,dc=example,dc=com" read +.fi + +.SH SCHEMA +The +.B accesslog +overlay utilizes the "audit" schema described herein. +This schema is specifically designed for +.B accesslog +auditing and is not intended to be used otherwise. It is also +noted that the schema described here is +.I a work in +.IR progress , +and hence subject to change without notice. +The schema is loaded automatically by the overlay. + +The schema includes a number of object classes and associated +attribute types as described below. + +The root entry of the underlying accesslog database makes use +of the +.B auditContainer +class which is as follows: +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.0 + NAME 'auditContainer' + DESC 'AuditLog container' + SUP top STRUCTURAL + MAY ( cn $ reqStart $ reqEnd ) ) +.RE +.P + +There is +a basic +.B auditObject +class from which two additional classes, +.B auditReadObject +and +.B auditWriteObject +are derived. Object classes for each type of LDAP operation are further +derived from these classes. This object class hierarchy is designed to +allow flexible yet efficient searches of the log based on either a specific +operation type's class, or on more general classifications. The definition +of the +.B auditObject +class is as follows: +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.1 + NAME 'auditObject' + DESC 'OpenLDAP request auditing' + SUP top STRUCTURAL + MUST ( reqStart $ reqType $ reqSession ) + MAY ( reqDN $ reqAuthzID $ reqControls $ reqRespControls $ + reqEnd $ reqResult $ reqMessage $ reqReferral $ reqEntryUUID ) ) +.RE +.P +Note that all of the OIDs used in the logging schema currently reside +under the OpenLDAP Experimental branch. It is anticipated that they +will migrate to a Standard branch in the future. + +An overview of the attributes follows: +.B reqStart +and +.B reqEnd +provide the start and end time of the operation, respectively. They use +generalizedTime syntax. The +.B reqStart +attribute is also used as the RDN for each log entry. + +The +.B reqType +attribute is a simple string containing the type of operation +being logged, e.g. +.BR add , +.BR delete , +.BR search , +etc. For extended operations, the type also includes the OID of the +extended operation, e.g. +.B extended(1.1.1.1) + +The +.B reqSession +attribute is an implementation-specific identifier that is common to +all the operations associated with the same LDAP session. Currently this +is slapd's internal connection ID, stored in decimal. + +The +.B reqDN +attribute is the distinguishedName of the target of the operation. E.g., for +a Bind request, this is the Bind DN. For an Add request, this is the DN +of the entry being added. For a Search request, this is the base DN of +the search. + +The +.B reqAuthzID +attribute is the distinguishedName of the user that performed the operation. +This will usually be the same name as was established at the start of a +session by a Bind request (if any) but may be altered in various +circumstances. + +The +.B reqControls +and +.B reqRespControls +attributes carry any controls sent by the client on the request and returned +by the server in the response, respectively. The attribute values are just +uninterpreted octet strings. + +The +.B reqResult +attribute is the numeric LDAP result code of the operation, indicating +either success or a particular LDAP error code. An error code may be +accompanied by a text error message which will be recorded in the +.B reqMessage +attribute. + +The +.B reqReferral +attribute carries any referrals that were returned with the result of the +request. + +The +.B reqEntryUUID +attribute records the entryUUID attribute of the entry operated on, for an Add +request, this is the entryUUID of the newly created entry. + +Operation-specific classes are defined with additional attributes to carry +all of the relevant parameters associated with the operation: + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.4 + NAME 'auditAbandon' + DESC 'Abandon operation' + SUP auditObject STRUCTURAL + MUST reqId ) +.RE +.P +For the +.B Abandon +operation the +.B reqId +attribute contains the message ID of the request that was abandoned. + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.5 + NAME 'auditAdd' + DESC 'Add operation' + SUP auditWriteObject STRUCTURAL + MUST reqMod ) +.RE +.P +The +.B Add +class inherits from the +.B auditWriteObject +class. The Add and Modify classes are very similar. The +.B reqMod +attribute carries all of the attributes of the original entry being added. +(Or in the case of a Modify operation, all of the modifications being +performed.) The values are formatted as +.RS +.PD 0 +.TP +attribute:<+|\-|=|#> [ value] +.RE +.RE +.PD +Where '+' indicates an Add of a value, '\-' for Delete, '=' for Replace, +and '#' for Increment. In an Add operation, all of the reqMod values will +have the '+' designator. +.P +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.6 + NAME 'auditBind' + DESC 'Bind operation' + SUP auditObject STRUCTURAL + MUST ( reqVersion $ reqMethod ) ) +.RE +.P +The +.B Bind +class includes the +.B reqVersion +attribute which contains the LDAP protocol version specified in the Bind +as well as the +.B reqMethod +attribute which contains the Bind Method used in the Bind. This will be +the string +.B SIMPLE +for LDAP Simple Binds or +.B SASL(<mech>) +for SASL Binds. +Note that unless configured as a global overlay, only Simple Binds using +DNs that reside in the current database will be logged. + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.7 + NAME 'auditCompare' + DESC 'Compare operation' + SUP auditObject STRUCTURAL + MUST reqAssertion ) +.RE +.P +For the +.B Compare +operation the +.B reqAssertion +attribute carries the Attribute Value Assertion used in the compare request. + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.8 + NAME 'auditDelete' + DESC 'Delete operation' + SUP auditWriteObject STRUCTURAL + MAY reqOld ) +.RE +.P +The +.B Delete +operation needs no further parameters. However, the +.B reqOld +attribute may optionally be used to record the contents of the entry prior +to its deletion. The values are formatted as +.RS +.PD 0 +.TP +attribute: value +.RE +.PD +The +.B reqOld +attribute is only populated if the entry being deleted matches the +configured +.B logold +filter. + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.9 + NAME 'auditModify' + DESC 'Modify operation' + SUP auditWriteObject STRUCTURAL + MAY ( reqOld $ reqMod ) ) +.RE +.P +The +.B Modify +operation contains a description of modifications in the +.B reqMod +attribute, which was already described above in the Add operation. It may +optionally contain the previous contents of any modified attributes in the +.B reqOld +attribute, using the same format as described above for the Delete operation. +The +.B reqOld +attribute is only populated if the entry being modified matches the +configured +.B logold +filter. + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.10 + NAME 'auditModRDN' + DESC 'ModRDN operation' + SUP auditWriteObject STRUCTURAL + MUST ( reqNewRDN $ reqDeleteOldRDN ) + MAY ( reqNewSuperior $ reqMod $ reqOld ) ) +.RE +.P +The +.B ModRDN +class uses the +.B reqNewRDN +attribute to carry the new RDN of the request. +The +.B reqDeleteOldRDN +attribute is a Boolean value showing +.B TRUE +if the old RDN was deleted from the entry, or +.B FALSE +if the old RDN was preserved. +The +.B reqNewSuperior +attribute carries the DN of the new parent entry if the request specified +the new parent. +The +.B reqOld +attribute is only populated if the entry being modified matches the +configured +.B logold +filter and contains attributes in the +.B logoldattr +list. + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.11 + NAME 'auditSearch' + DESC 'Search operation' + SUP auditReadObject STRUCTURAL + MUST ( reqScope $ reqDerefAliases $ reqAttrsOnly ) + MAY ( reqFilter $ reqAttr $ reqEntries $ reqSizeLimit $ + reqTimeLimit ) ) +.RE +.P +For the +.B Search +class the +.B reqScope +attribute contains the scope of the original search request, using the +values specified for the LDAP URL format. I.e. +.BR base , +.BR one , +.BR sub , +or +.BR subord . +The +.B reqDerefAliases +attribute is one of +.BR never , +.BR finding , +.BR searching , +or +.BR always , +denoting how aliases will be processed during the search. +The +.B reqAttrsOnly +attribute is a Boolean value showing +.B TRUE +if only attribute names were requested, or +.B FALSE +if attributes and their values were requested. +The +.B reqFilter +attribute carries the filter used in the search request. +The +.B reqAttr +attribute lists the requested attributes if specific attributes were +requested. +The +.B reqEntries +attribute is the integer count of how many entries were returned by +this search request. +The +.B reqSizeLimit +and +.B reqTimeLimit +attributes indicate what limits were requested on the search operation. + +.LP +.RS 4 +( 1.3.6.1.4.1.4203.666.11.5.2.12 + NAME 'auditExtended' + DESC 'Extended operation' + SUP auditObject STRUCTURAL + MAY reqData ) +.RE +.P +The +.B Extended +class represents an LDAP Extended Operation. As noted above, the actual OID of +the operation is included in the +.B reqType +attribute of the parent class. If any optional data was provided with the +request, it will be contained in the +.B reqData +attribute as an uninterpreted octet string. + +.SH NOTES +The Access Log implemented by this overlay may be used for a variety of +other tasks, e.g. as a ChangeLog for a replication mechanism, as well +as for security/audit logging purposes. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5). + +.SH ACKNOWLEDGEMENTS +.P +This module was written in 2005 by Howard Chu of Symas Corporation. diff --git a/doc/man/man5/slapo-auditlog.5 b/doc/man/man5/slapo-auditlog.5 new file mode 100644 index 0000000..6aeca87 --- /dev/null +++ b/doc/man/man5/slapo-auditlog.5 @@ -0,0 +1,98 @@ +.TH SLAPO-AUDITLOG 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2005-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-auditlog \- Audit Logging overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.TP +ETCDIR/slapd.d +.SH DESCRIPTION +The Audit Logging overlay can be used to record all changes on a given +backend database to a specified log file. Changes are logged as standard +LDIF, with an additional comment header providing six fields of +information about the change. A second comment header is added at the end +of the operation to note the termination of the change. +.LP +For Add and Modify operations the identity comes from the modifiersName +associated with the operation. This is usually the same as the requestor's +identity, but may be set by other overlays to reflect other values. +.SH CONFIGURATION +This +.B slapd.conf +option applies to the Audit Logging overlay. +It should appear after the +.B overlay +directive. +.TP +.B auditlog <filename> +Specify the fully qualified path for the log file. +.TP +.B olcAuditlogFile <filename> +For use with +.B cn=config +.SH COMMENT FIELD INFORMATION +The first field is the operation type. +.br +The second field is the timestamp of the operation in seconds since epoch. +.br +The third field is the suffix of the database. +.br +The fourth field is the recorded modifiersName. +.br +The fifth field is the originating IP address and port. +.br +The sixth field is the connection number. A connection number of -1 +indicates an internal slapd operation. +.SH EXAMPLE +The following LDIF could be used to add this overlay to +.B cn=config +(adjust to suit) +.LP +.RS +.nf +dn: olcOverlay=auditlog,olcDatabase={1}mdb,cn=config +changetype: add +objectClass: olcOverlayConfig +objectClass: olcAuditLogConfig +olcOverlay: auditlog +olcAuditlogFile: /tmp/auditlog.ldif +.fi +.RE +.LP +.LP +.SH EXAMPLE CHANGELOG +.LP +.RS +.nf +# modify 1614223245 dc=example,dc=com cn=admin,dc=example,dc=com IP=[::1]:47270 conn=1002 +dn: uid=joepublic,ou=people,dc=example,dc=com +changetype: modify +replace: displayName +displayName: Joe Public +- +replace: entryCSN +entryCSN: 20210225032045.045229Z#000000#001#000000 +- +replace: modifiersName +modifiersName: cn=admin,dc=example,dc=com +- +replace: modifyTimestamp +modifyTimestamp: 20210225032045Z +- +# end modify 1614223245 + +.fi +.RE +.LP +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +ETCDIR/slapd.d +default slapd configuration directory +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config(5). diff --git a/doc/man/man5/slapo-autoca.5 b/doc/man/man5/slapo-autoca.5 new file mode 100644 index 0000000..8e77cc8 --- /dev/null +++ b/doc/man/man5/slapo-autoca.5 @@ -0,0 +1,120 @@ +.TH SLAPO-AUTOCA 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2009-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copyright 2009-2018 Howard Chu All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-autoca \- Automatic Certificate Authority overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Automatic CA overlay generates X.509 certificate/key pairs for +entries in the directory. The DN of a generated certificate is +identical to the DN of the entry containing it. On startup it +looks for a CA certificate and key in the suffix entry of the +database which it will use to sign all subsequently generated +certificates. A new CA certificate and key will be generated +and stored in the suffix entry if none already exists. The CA +certificate is stored in the cACertificate;binary attribute of +the suffix entry, and the private key is stored in the +cAPrivateKey;binary attribute of the suffix entry. These +attributes may be overwritten if some other CA certificate/key +pair is desired for use. +.LP +Certificates for users and servers are generated on demand using +a Search request returning only the userCertificate;binary and +userPrivateKey;binary attributes. Any Search for anything besides +exactly these two attributes is ignored by the overlay. Note that +these values are stored in ASN.1 DER form in the directory so the +";binary" attribute option is mandatory. +.LP +Entries that do not belong to selected objectClasses will be +ignored by the overlay. By default, entries of objectClass +.B person +will be treated as users, and entries of objectClass +.B ipHost +will be treated as servers. There are slight differences in the +set of X.509V3 certificate extensions added to the certificate +between users and servers. +.LP +The CA's private key is stored in a +.B cAPrivateKey +attribute, and user and server private keys are stored in the +.B userPrivateKey +attribute. The private key values are encoded in PKCS#8 format. +It is essential that access to these attributes be +properly secured with ACLs. Both of these attributes inherit +from the +.B pKCS8PrivateKey +attribute, so it is sufficient to use a single ACL rule like + +.nf + access to attrs=pKCS8PrivateKey by self ssf=128 write +.fi + +at the beginning of the rules. +.LP +Currently there is no automated management for expiration or revocation. +Obsolete certificates and keys must be manually removed by deleting +an entry's userCertificate and userPrivateKey attributes. + +.SH CONFIGURATION +These +.B slapd.conf +options apply to the Automatic CA overlay. +They should appear after the +.B overlay +directive. +.TP +.B userClass <objectClass> +Specify the objectClass to be treated as user entries. +.TP +.B serverClass <objectClass> +Specify the objectClass to be treated as server entries. +.TP +.B userKeybits <integer> +Specify the size of the private key to use for user certificates. +The default is 2048 and the minimum is 512. +.TP +.B serverKeybits <integer> +Specify the size of the private key to use for server certificates. +The default is 2048 and the minimum is 512. +.TP +.B caKeybits <integer> +Specify the size of the private key to use for the CA certificate. +The default is 2048 and the minimum is 512. +.TP +.B userDays <integer> +Specify the duration for a user certificate's validity. +The default is 365, 1 year. +.TP +.B serverDays <integer> +Specify the duration for a server certificate's validity. +The default is 1826, 5 years. +.TP +.B caDays <integer> +Specify the duration for the CA certificate's validity. +The default is 3652, 10 years. +.TP +.B localDN <DN> +Specify the DN of an entry that represents this server. Requests +to generate a certificate/key pair for this DN will also install +the certificate and key into slapd's TLS settings in cn=config +for immediate use. + +.SH EXAMPLES +.nf + database mdb + ... + overlay autoca + caKeybits 4096 +.fi +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5). +.SH AUTHOR +Howard Chu diff --git a/doc/man/man5/slapo-chain.5 b/doc/man/man5/slapo-chain.5 new file mode 100644 index 0000000..eaaa2b2 --- /dev/null +++ b/doc/man/man5/slapo-chain.5 @@ -0,0 +1,152 @@ +.TH SLAPO-CHAIN 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.SH NAME +slapo\-chain \- chain overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B chain +overlay to +.BR slapd (8) +allows automatic referral chasing. +Any time a referral is returned (except for bind operations), +it is chased by using an instance of the ldap backend. +If operations are performed with an identity (i.e. after a bind), +that identity can be asserted while chasing the referrals +by means of the \fIidentity assertion\fP feature of back-ldap +(see +.BR slapd\-ldap (5) +for details), which is essentially based on the +.B proxied authorization +control [RFC 4370]. +Referral chasing can be controlled by the client by issuing the +\fBchaining\fP control +(see \fIdraft-sermersheim-ldap-chaining\fP for details.) + +.LP +The config directives that are specific to the +.B chain +overlay are prefixed by +.BR chain\- , +to avoid potential conflicts with directives specific to the underlying +database or to other stacked overlays. + +.LP +There are very few chain overlay specific directives; however, directives +related to the instances of the \fIldap\fP backend that may be implicitly +instantiated by the overlay may assume a special meaning when used +in conjunction with this overlay. They are described in +.BR slapd\-ldap (5), +and they also need to be prefixed by +.BR chain\- . + +Note: this overlay is built into the \fIldap\fP backend; it is not +a separate module. + +.TP +.B overlay chain +This directive adds the chain overlay to the current backend. +The chain overlay may be used with any backend, but it is mainly +intended for use with local storage backends that may return referrals. +It is useless in conjunction with the \fIslapd\-ldap\fP and \fIslapd\-meta\fP +backends because they already exploit the libldap specific referral chase +feature. +[Note: this may change in the future, as the \fBldap\fP(5) and +\fBmeta\fP(5) backends might no longer chase referrals on their own.] +.TP +.B chain\-cache\-uri {FALSE|true} +This directive instructs the \fIchain\fP overlay to cache +connections to URIs parsed out of referrals that are not predefined, +to be reused for later chaining. +These URIs inherit the properties configured for the underlying +\fBslapd\-ldap\fP(5) before any occurrence of the \fBchain\-uri\fP +directive; basically, they are chained anonymously. +.TP +.B chain\-chaining [resolve=<r>] [continuation=<c>] [critical] +This directive enables the \fIchaining\fP control +(see \fIdraft-sermersheim-ldap-chaining\fP for details) +with the desired resolve and continuation behaviors and criticality. +The \fBresolve\fP parameter refers to the behavior while discovering +a resource, namely when accessing the object indicated by the request DN; +the \fBcontinuation\fP parameter refers to the behavior while handling +intermediate responses, which is mostly significant for the search +operation, but may affect extended operations that return intermediate +responses. +The values \fBr\fP and \fBc\fP can be any of +.BR chainingPreferred , +.BR chainingRequired , +.BR referralsPreferred , +.BR referralsRequired . +If the \fBcritical\fP flag affects the control criticality if provided. +[This control is experimental and its support may change in the future.] +.TP +.B chain\-max\-depth <n> +In case a referral is returned during referral chasing, further chasing +occurs at most \fB<n>\fP levels deep. Set to \fB1\fP (the default) +to disable further referral chasing. +.TP +.B chain\-return\-error {FALSE|true} +In case referral chasing fails, the real error is returned instead +of the original referral. In case multiple referral URIs are present, +only the first error is returned. This behavior may not be always +appropriate nor desirable, since failures in referral chasing might be +better resolved by the client (e.g. when caused by distributed +authentication issues). +.TP +.B chain\-uri <ldapuri> +This directive instantiates a new underlying \fIldap\fP database +and instructs it about which URI to contact to chase referrals. +As opposed to what stated in \fBslapd\-ldap\fP(5), only one URI +can appear after this directive; all subsequent \fBslapd\-ldap\fP(5) +directives prefixed by \fBchain\-\fP refer to this specific instance +of a remote server. +.LP + +Directives for configuring the underlying ldap database may also +be required, as shown in this example: +.LP +.RS +.nf +overlay chain +chain\-rebind\-as\-user FALSE + +chain\-uri "ldap://ldap1.example.com" +chain\-rebind\-as\-user TRUE +chain\-idassert\-bind bindmethod="simple" + binddn="cn=Auth,dc=example,dc=com" + credentials="secret" + mode="self" + +chain\-uri "ldap://ldap2.example.com" +chain\-idassert\-bind bindmethod="simple" + binddn="cn=Auth,dc=example,dc=com" + credentials="secret" + mode="none" + +.fi +.RE +.LP +Any valid directives for the ldap database may be used; see +.BR slapd\-ldap (5) +for details. +Multiple occurrences of the \fBchain\-uri\fP directive may appear, +to define multiple "trusted" URIs where operations with +\fIidentity assertion\fP are chained. +All URIs not listed in the configuration are chained anonymously. +All \fBslapd\-ldap\fP(5) directives appearing before the first +occurrence of \fBchain\-uri\fP are inherited by all URIs, +unless specifically overridden inside each URI configuration. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd\-ldap (5), +.BR slapd (8). +.SH AUTHOR +Originally implemented by Howard Chu; extended by Pierangelo Masarati. diff --git a/doc/man/man5/slapo-collect.5 b/doc/man/man5/slapo-collect.5 new file mode 100644 index 0000000..443118a --- /dev/null +++ b/doc/man/man5/slapo-collect.5 @@ -0,0 +1,52 @@ +.TH SLAPO-COLLECT 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2003-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-collect \- Collective attributes overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The collect overlay is used to provide a relatively coarse +implementation of RFC 3671 collective attributes. +In X.500, a collective attribute is "a user attribute whose +values are the same for each member of an entry collection". + +Collective attributes are added to entries returned by a search operation +when the entry is within the scope of the related ancestor. +Collective attributes can only be modified when the modification affects +the related ancestor. + +.SH CONFIGURATION +This +.B slapd.conf +option applies to the collect overlay. +It should appear after the +.B overlay +directive. +.TP +.B collectinfo <DN> <attrlist> +Specify the +.B DN +of the ancestor entry and the set of related collective attributes, where +.B attrlist +is a comma-separated list of attributes. +The +.B DN +should be within the naming context of the database. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +The +.BR slapo\-collect (5) +overlay supports dynamic configuration via +.BR back-config . +.SH ACKNOWLEDGEMENTS +This module was written in 2003 by Howard Chu. +This man page was written in 2008 by Pierangelo Masarati. +.so ../Project diff --git a/doc/man/man5/slapo-constraint.5 b/doc/man/man5/slapo-constraint.5 new file mode 100644 index 0000000..240f713 --- /dev/null +++ b/doc/man/man5/slapo-constraint.5 @@ -0,0 +1,155 @@ +.TH SLAPO-CONSTRAINT 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2005-2006 Hewlett-Packard Company +.\" Copyright 2006-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-constraint \- Attribute Constraint Overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The constraint overlay is used to ensure that attribute values match +some constraints beyond basic LDAP syntax. Attributes can +have multiple constraints placed upon them, and all must be satisfied +when modifying an attribute value under constraint. +.LP +This overlay is intended to be used to force syntactic regularity upon +certain string represented data which have well known canonical forms, +like telephone numbers, post codes, FQDNs, etc. +.LP +It constrains only LDAP \fIadd\fP, \fImodify\fP and \fIrename\fP commands +and only seeks to control the \fIadd\fP and \fIreplace\fP values +of \fImodify\fP and \fIrename\fP requests. +.LP +No constraints are applied for operations performed with the +.I relax +control set. +.SH CONFIGURATION +This +.B slapd.conf +option applies to the constraint overlay. +It should appear after the +.B overlay +directive. +.TP +.B constraint_attribute <attribute_name>[,...] <type> <value> [<extra> [...]] +Specifies the constraint which should apply to the comma-separated +attribute list named as the first parameter. +Six types of constraint are currently supported - +.BR regex , +.BR negregex , +.BR size , +.BR count , +.BR uri , +and +.BR set . + +The parameter following the +.B regex +or +.B negregex +type is a Unix style regular expression (See +.BR regex (7) +). The parameter following the +.B uri +type is an LDAP URI. The URI will be evaluated using an internal search. +It must not include a hostname, and it must include a list of attributes +to evaluate. + +The parameter following the +.B set +type is a string that is interpreted according to the syntax in use +for ACL sets. This allows one to construct constraints based on the contents +of the entry. + +The +.B size +type can be used to enforce a limit on an attribute length, and the +.B count +type limits the number of values of an attribute. + +Extra parameters can occur in any order after those described above. +.RS +.TP +.B <extra> : restrict=<uri> +.RE + +.RS +This extra parameter allows one to restrict the application of the corresponding +constraint only to entries that match the +.IR base , +.I scope +and +.I filter +portions of the LDAP URI. +The +.IR base , +if present, must be within the naming context of the database. +The +.I scope +is only used when the +.I base +is present; it defaults to +.BR base . +The other parameters of the URI are not allowed. +.RE + +.LP +Any attempt to add or modify an attribute named as part of the +constraint overlay specification which does not fit the +constraint listed will fail with a +LDAP_CONSTRAINT_VIOLATION error. +.SH EXAMPLES +.LP +.RS +.nf +overlay constraint +constraint_attribute jpegPhoto size 131072 +constraint_attribute userPassword count 3 +constraint_attribute mail regex ^[[:alnum:]]+@mydomain.com$ +constraint_attribute mail negregex ^[[:alnum:]]+@notallowed.com$ +constraint_attribute title uri + ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog) +constraint_attribute cn,sn,givenName set + "(this/givenName + [ ] + this/sn) & this/cn" + restrict="ldap:///ou=People,dc=example,dc=com??sub?(objectClass=inetOrgPerson)" +.fi + +.RE +A specification like the above would reject any +.B mail +attribute which did not look like +.BR "<alphanumeric string>@mydomain.com" +or that looks like +.BR "<alphanumeric string>@notallowed.com" . +It would also reject any +.B title +attribute whose values were not listed in the +.B title +attribute of any +.B titleCatalog +entries in the given scope. (Note that the +"dc=catalog,dc=example,dc=com" subtree ought to reside +in a separate database, otherwise the initial set of +titleCatalog entries could not be populated while the +constraint is in effect.) +Finally, it requires the values of the attribute +.B cn +to be constructed by pairing values of the attributes +.B sn +and +.BR givenName , +separated by a space, but only for entries derived from the objectClass +.BR inetOrgPerson . +.RE +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.SH ACKNOWLEDGEMENTS +This module was written in 2005 by Neil Dunbar of Hewlett-Packard and subsequently +extended by Howard Chu and Emmanuel Dreyfus. +.so ../Project diff --git a/doc/man/man5/slapo-dds.5 b/doc/man/man5/slapo-dds.5 new file mode 100644 index 0000000..36218c8 --- /dev/null +++ b/doc/man/man5/slapo-dds.5 @@ -0,0 +1,271 @@ +.TH SLAPO-DDS 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2005-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.SH NAME +slapo\-dds \- Dynamic Directory Services overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B dds +overlay to +.BR slapd (8) +implements dynamic objects as per RFC 2589. +The name +.B dds +stands for +Dynamic Directory Services. +It allows one to define dynamic objects, characterized by the +.B dynamicObject +objectClass. + +Dynamic objects have a limited lifetime, determined by a time-to-live +(TTL) that can be refreshed by means of a specific +.B refresh +extended operation. +This operation allows one to set the Client Refresh Period (CRP), +namely the period between refreshes that is required to preserve the +dynamic object from expiration. +The expiration time is computed by adding the requested TTL to the +current time. +When dynamic objects reach the end of their lifetime without being +further refreshed, they are automatically deleted. +There is no guarantee of immediate deletion, so clients should not count +on it. + +Dynamic objects can have subordinates, provided these also are dynamic +objects. +RFC 2589 does not specify what the behavior of a dynamic directory +service should be when a dynamic object with (dynamic) subordinates +expires. +In this implementation, the lifetime of dynamic objects with subordinates +is prolonged until all the dynamic subordinates expire. + + +This +.BR slapd.conf (5) +directive adds the +.B dds +overlay to the current database: + +.TP +.B overlay dds + +.LP +The database must have a +.B rootdn +specified, otherwise, the +.B dds +overlay will not be able to delete expired objects. The +.B dds +overlay may be used with any backend that implements the +.BR add , +.BR modify , +.BR search , +and +.BR delete +operations. +Since its use may result in many internal entry lookups, adds +and deletes, it should be best used in conjunction with backends +that have reasonably good write performances. + +.LP +The config directives that are specific to the +.B dds +overlay are prefixed by +.BR dds\- , +to avoid potential conflicts with directives specific to the underlying +database or to other stacked overlays. + +.TP +.B dds\-max\-ttl <time> +Specifies the max TTL value. +This is also the default TTL newly created +dynamic objects receive, unless +.B dds\-default\-ttl +is set. +When the client with a refresh extended operation requests a TTL higher +than it, sizeLimitExceeded is returned. +This value must be between 86400 (1 day, the default) and 31557600 +(1 year plus 6 hours, as per RFC 2589). + +.TP +.B dds\-min\-ttl <time> +Specifies the min TTL value; clients requesting a lower TTL by means +of the refresh extended operation actually obtain this value as CRP. +If set to 0 (the default), no lower limit is set. + +.TP +.B dds\-default\-ttl <time> +Specifies the default TTL value that newly created dynamic objects get. +If set to 0 (the default), the +.B dds\-max\-ttl +is used. + +.TP +.B dds\-interval <time> +Specifies the interval between expiration checks; defaults to 1 hour. + +.TP +.B dds\-tolerance <time> +Specifies an extra time that is added to the timer that actually wakes up +the thread that will delete an expired dynamic object. +So the nominal lifetime of the entry is that specified in the +.B entryTtl +attribute, but its lifetime will actually be +.BR "entryTtl + tolerance" . +Note that there is no guarantee that the lifetime of a dynamic object +will be +.I exactly +the requested TTL; due to implementation details, it may be longer, which +is allowed by RFC 2589. +By default, tolerance is 0. + +.TP +.B dds\-max\-dynamicObjects <num> +Specifies the maximum number of dynamic objects that can simultaneously exist +within a naming context. +This allows one to limit the amount of resources (mostly in terms of +run-queue size) that are used by dynamic objects. +By default, no limit is set. + +.TP +.B dds\-state {TRUE|false} +Specifies if the Dynamic Directory Services feature is enabled or not. +By default it is; however, a proxy does not need to keep track of dynamic +objects itself, it only needs to inform the frontend that support for +dynamic objects is available. + +.SH ACCESS CONTROL +The +.B dds +overlay restricts the refresh operation by requiring +.B manage +access to the +.B entryTtl +attribute (see +.BR slapd.access (5) +for details about the +.B manage +access privilege). +Since the +.B entryTtl +is an operational, NO-USER-MODIFICATION attribute, no direct write access +to it is possible. +So the +.B dds +overlay turns refresh extended operation into an internal modification to +the value of the +.B entryTtl +attribute with the +.B relax +control set. + +RFC 2589 recommends that anonymous clients should not be allowed to refresh +a dynamic object. +This can be implemented by appropriately crafting access control to obtain +the desired effect. + +Example: restrict refresh to authenticated clients + +.RS +.nf +access to attrs=entryTtl + by users manage + by * read + +.fi +.RE +Example: restrict refresh to the creator of the dynamic object + +.RS +.nf +access to attrs=entryTtl + by dnattr=creatorsName manage + by * read + +.fi +.RE +Another suggested usage of dynamic objects is to implement dynamic meetings; +in this case, all the participants to the meeting are allowed to refresh +the meeting object, but only the creator can delete it (otherwise it will +be deleted when the TTL expires) + +Example: assuming \fIparticipant\fP is a valid DN-valued attribute, +allow users to start a meeting and to join it; restrict refresh +to the participants; restrict delete to the creator + +.RS +.nf +access to dn.base="cn=Meetings" + attrs=children + by users write + +access to dn.onelevel="cn=Meetings" + attrs=entry + by dnattr=creatorsName write + by * read + +access to dn.onelevel="cn=Meetings" + attrs=participant + by dnattr=creatorsName write + by users selfwrite + by * read + +access to dn.onelevel="cn=Meetings" + attrs=entryTtl + by dnattr=participant manage + by * read + +.fi +.RE + +.SH REPLICATION +This implementation of RFC 2589 provides a restricted interpretation of how +dynamic objects replicate. Only the provider takes care of handling dynamic +object expiration, while consumers simply see the dynamic object as a plain +object. + +When replicating these objects, one needs to explicitly exclude the +.B dynamicObject +class and the +.B entryTtl +attribute. +This implementation of RFC 2589 introduces a new operational attribute, +.BR entryExpireTimestamp , +that contains the expiration timestamp. This must be excluded from +replication as well. + +The quick and dirty solution is to set +.B schemacheck=off +in the syncrepl configuration +and, optionally, exclude the operational attributes from replication, using + +.RS +.nf +syncrepl ... + exattrs=entryTtl,entryExpireTimestamp +.fi +.RE + +In any case the overlay must be either statically built in or run-time loaded +by the consumer, so that it is aware of the +.B entryExpireTimestamp +operational attribute; however, it must not be configured in the shadow +database. +Currently, there is no means to remove the +.B dynamicObject +class from the entry; this may be seen as a feature, since it allows one to see +the dynamic properties of the object. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8). +.SH AUTHOR +Implemented by Pierangelo Masarati. diff --git a/doc/man/man5/slapo-deref.5 b/doc/man/man5/slapo-deref.5 new file mode 100644 index 0000000..abd2dfe --- /dev/null +++ b/doc/man/man5/slapo-deref.5 @@ -0,0 +1,80 @@ +.TH SLAPO-DEREF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2008-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-deref \- Dereference Control overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.TP +ETCDIR/slapd.d +.SH DESCRIPTION +This overlay implements the draft Dereference control. The overlay can be +used with any backend or globally for all backends. + +.SH EXAMPLES +.nf + database mdb + ... + overlay deref +.fi + +Given these entries: +.nf + dn: cn=Howard Chu,ou=people,dc=example,dc=org + objectClass: inetOrgPerson + cn: Howard Chu + sn: Chu + uid: hyc + + dn: cn=Pierangelo Masarati,ou=people,dc=example,dc=org + objectClass: inetOrgPerson + cn: Pierangelo Masarati + sn: Masarati + uid: ando + + dn: cn=Test Group,ou=groups,dc=example,dc=org + objectClass: groupOfNames + cn: Test Group + member: cn=Howard Chu,ou=people,dc=example,dc=org + member: cn=Pierangelo Masarati,ou=people,dc=example,dc=org +.fi + +A search could be performed with a Dereference request control value +specified as + +.nf + { member, uid } +.fi + +I.e., +.nf + ldapsearch -x -b dc=example,dc=org -E 'deref=member:uid' +.fi + +and the "cn=Test Group" entry would be returned with the response +control value +.nf + { { member, cn=Howard Chu,ou=people,dc=example,dc=org, + { { uid, [hyc] } } }, + { member, cn=Pierangelo Masarati,ou=people,dc=example,dc=org, + { { uid, [ando] } } } } +.fi + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +ETCDIR/slapd.d +default slapd configuration directory +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.LP +IETF LDAP Dereference Control proposal by P. Masarati, H. Chu, +in IETF document "draft-masarati-ldap-deref-00.txt". +.SH AUTHOR +Pierangelo Masarati diff --git a/doc/man/man5/slapo-dyngroup.5 b/doc/man/man5/slapo-dyngroup.5 new file mode 100644 index 0000000..bdb4dc5 --- /dev/null +++ b/doc/man/man5/slapo-dyngroup.5 @@ -0,0 +1,58 @@ +.TH SLAPO-DYNGROUP 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2005-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-dyngroup \- Dynamic Group overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Dynamic Group overlay allows clients to use LDAP Compare operations +to test the membership of a dynamic group the same way they would check +against a static group. Compare operations targeting a group's static +member attribute will be intercepted and tested against the configured +dynamic group's URL attribute. +.LP +Note that this intercept only happens if the actual +Compare operation does not return a LDAP_COMPARE_TRUE result. So if a +group has both static and dynamic members, the static member list will +be checked first. +.SH CONFIGURATION +This +.B slapd.conf +option applies to the Dynamic Group overlay. +It should appear after the +.B overlay +directive. +.TP +.B attrpair <memberAttr> <URLattr> +Specify the attributes to be compared. A compare operation on the +.I memberAttr +will cause the +.I URLattr +to be evaluated for the result. +.SH EXAMPLES +.nf + database mdb + ... + overlay dyngroup + attrpair member memberURL +.fi +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH BACKWARD COMPATIBILITY +The dyngroup overlay has been reworked with the 2.5 release to use +a consistent namespace as with other overlays. As a side-effect the +following cn=config parameters are deprecated and will be removed in +a future release: +.B olcDGAttrPair +is replaced with olcDynGroupAttrPair +.B olcDGConfig +is replaced with olcDynGroupConfig +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5). +.SH AUTHOR +Howard Chu diff --git a/doc/man/man5/slapo-dynlist.5 b/doc/man/man5/slapo-dynlist.5 new file mode 100644 index 0000000..db00312 --- /dev/null +++ b/doc/man/man5/slapo-dynlist.5 @@ -0,0 +1,275 @@ +.TH SLAPO-DYNLIST 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.SH NAME +slapo\-dynlist \- Dynamic List overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B dynlist +overlay to +.BR slapd (8) +allows expansion of dynamic groups and more. +Any time an entry with a specific objectClass (defined in the overlay configuration) is being returned, +the LDAP URI-valued occurrences of a specific attribute (also defined in the overlay configuration) are +expanded into the corresponding entries, and the values +of the attributes listed in the URI are added to the original +entry. +No recursion is allowed, to avoid potential infinite loops. + +The resulting entry must comply with the LDAP data model, so constraints +are enforced. +For example, if a \fISINGLE\-VALUE\fP attribute is listed, +only the first value found during the list expansion appears in the final entry. +All dynamic behavior is disabled when the \fImanageDSAit\fP +control (RFC 3296) is used. +In that case, the contents of the dynamic group entry is returned; +namely, the URLs are returned instead of being expanded. + +.SH CONFIGURATION +The config directives that are specific to the +.B dynlist +overlay must be prefixed by +.BR dynlist\- , +to avoid potential conflicts with directives specific to the underlying +database or to other stacked overlays. + +.TP +.B overlay dynlist +This directive adds the dynlist overlay to the current database, +or to the frontend, if used before any database instantiation; see +.BR slapd.conf (5) +for details. + +.LP +This +.B slapd.conf +configuration option is defined for the dynlist overlay. It may have multiple +occurrences, and it must appear after the +.B overlay +directive. +.TP +.B dynlist\-attrset <group-oc> [<URI>] <URL-ad> [[<mapped-ad>:]<member-ad>[+<memberOf-ad[@<static-oc>[*]] ...] +The value +.B group\-oc +is the name of the objectClass that triggers the dynamic expansion of the +data. + +The optional +.B URI +restricts expansion only to entries matching the \fIDN\fP, +the \fIscope\fP and the \fIfilter\fP portions of the URI. + +The value +.B URL-ad +is the name of the attributeDescription that contains the URI that is +expanded by the overlay; if none is present, no expansion occurs. +If the intersection of the attributes requested by the search operation +(or the asserted attribute for compares) and the attributes listed +in the URI is empty, no expansion occurs for that specific URI. +It must be a subtype of \fIlabeledURI\fP. + +The value +.B member-ad +is optional; if present, the overlay behaves as a dynamic group: this +attribute will list the DN of the entries resulting from the internal search. +In this case, the \fIattrs\fP portion of the URIs in the +.B URL-ad +attribute must be absent, and the \fIDN\fPs +of all the entries resulting from the expansion of the URIs are listed +as values of this attribute. +Compares that assert the value of the +.B member-ad +attribute of entries with +.B group-oc +objectClass apply as if the DN of the entries resulting from the expansion +of the URI were present in the +.B group-oc +entry as values of the +.B member-ad +attribute. +If the optional +.B memberOf-ad +attribute is also specified, then it will be populated with the DNs of the +dynamic groups that an entry is a member of. +If the optional +.B static-oc +objectClass is also specified, then the memberOf attribute will also be +populated with the DNs of the static groups that an entry is a member of. +If the optional +.B * +character is also specified, then the member and memberOf values will be +populated recursively, for nested groups. Note that currently nesting is +only supported for Search operations, not Compares. + +Alternatively, +.B mapped-ad +can be used to remap attributes obtained through expansion. +.B member-ad +attributes are not filled by expanded DN, but are remapped as +.B mapped-ad +attributes. Multiple mapping statements can be used. The +.B memberOf-ad +option is not used in this case. + +.LP +The dynlist overlay may be used with any backend, but it is mainly +intended for use with local storage backends. +In case the URI expansion is very resource-intensive and occurs frequently +with well-defined patterns, one should consider adding a proxycache +later on in the overlay stack. + +.SH AUTHORIZATION +By default the expansions are performed using the identity of the current +LDAP user. +This identity may be overridden by setting the +.B dgIdentity +attribute in the group's entry to the DN of another LDAP user. +In that case the dgIdentity will be used when expanding the URIs in the object. +Setting the dgIdentity to a zero-length string will cause the expansions +to be performed anonymously. +Note that the dgIdentity attribute is defined in the +.B dyngroup +schema, and this schema must be loaded before the dgIdentity +authorization feature may be used. +If the +.B dgAuthz +attribute is also present in the group's entry, its values are used +to determine what identities are authorized to use the +.B dgIdentity +to expand the group. +Values of the +.B dgAuthz +attribute must conform to the (experimental) \fIOpenLDAP authz\fP syntax. +When using dynamic memberOf in search filters, search access to the +.B entryDN +pseudo-attribute is required. + +.SH EXAMPLE +This example collects all the email addresses of a database into a single +entry; first of all, make sure that slapd.conf contains the directives: + +.LP +.nf + include /path/to/dyngroup.schema + # ... + + database <database> + # ... + + overlay dynlist + dynlist\-attrset groupOfURLs memberURL +.fi +.LP +and that slapd loads dynlist.la, if compiled as a run-time module; +then add to the database an entry like +.LP +.nf + dn: cn=Dynamic List,ou=Groups,dc=example,dc=com + objectClass: groupOfURLs + cn: Dynamic List + memberURL: ldap:///ou=People,dc=example,dc=com?mail?sub?(objectClass=person) +.fi + +If no <attrs> are provided in the URI, all (non-operational) attributes are +collected. + +This example implements the dynamic group feature on the +.B member +attribute: + +.LP +.nf + include /path/to/dyngroup.schema + # ... + + database <database> + # ... + + overlay dynlist + dynlist\-attrset groupOfURLs memberURL member +.fi +.LP + +A dynamic group with dgIdentity authorization could be created with an +entry like +.LP +.nf + dn: cn=Dynamic Group,ou=Groups,dc=example,dc=com + objectClass: groupOfURLs + objectClass: dgIdentityAux + cn: Dynamic Group + memberURL: ldap:///ou=People,dc=example,dc=com??sub?(objectClass=person) + dgIdentity: cn=Group Proxy,ou=Services,dc=example,dc=com +.fi + + +This example extends the dynamic group feature to add a dynamic +.B dgMemberOf +attribute to all the members of a dynamic group: +.LP +.nf + include /path/to/dyngroup.schema + # ... + + database <database> + # ... + + overlay dynlist + dynlist\-attrset groupOfURLs memberURL member+dgMemberOf +.fi +.LP + + +This example extends the dynamic memberOf feature to add the +.B memberOf +attribute to all the members of both static and dynamic groups: +.LP +.nf + include /path/to/dyngroup.schema + # ... + + database <database> + # ... + + overlay dynlist + dynlist\-attrset groupOfURLs memberURL member+memberOf@groupOfNames +.fi +.LP +This dynamic memberOf feature can fully replace the functionality of the +.BR slapo\-memberof (5) +overlay. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH BACKWARD COMPATIBILITY +The dynlist overlay has been reworked with the 2.5 release to use +a consistent namespace as with other overlays. As a side-effect the +following cn=config parameters are deprecated and will be removed in +a future release: +.B olcDlAttrSet +is replaced with olcDynListAttrSet +.B olcDynamicList +is replaced with olcDynListConfig +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8). +The +.BR slapo\-dynlist (5) +overlay supports dynamic configuration via +.BR back-config . + +.SH BUGS +Filtering on dynamic groups may return incomplete results if the +search operation uses the \fIpagedResults\fP control. + +.SH ACKNOWLEDGEMENTS +.P +This module was written in 2004 by Pierangelo Masarati for SysNet s.n.c. +.P +Attribute remapping was contributed in 2008 by Emmanuel Dreyfus. diff --git a/doc/man/man5/slapo-homedir.5 b/doc/man/man5/slapo-homedir.5 new file mode 100644 index 0000000..5cd4ee8 --- /dev/null +++ b/doc/man/man5/slapo-homedir.5 @@ -0,0 +1,130 @@ +.TH SLAPO-HOMEDIR 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.SH NAME +slapo\-homedir \- Home directory provisioning overlay +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B homedir +overlay causes +.BR slapd (8) +to notice changes involving RFC-2307bis style user-objects and make +appropriate changes to the local filesystem. This can be performed +on both master and replica systems, so it is possible to perform +remote home directory provisioning. +.SH CONFIGURATION +Both slapd.conf and back-config style configuration is supported. +.TP +.B overlay homedir +This directive adds the homedir overlay to the current database, +or to the frontend, if used before any database instantiation; see +.BR slapd.conf (5) +for details. +.TP +.B homedir\-skeleton\-path <pathname> +.TP +.B olcSkeletonPath: pathname +These options set the path to the skeleton account directory. +(Generally, /etc/skel) Files in this directory will be copied into +newly created home directories. Copying is recursive and handles +symlinks and fifos, but will skip most specials. +.TP +.B homedir\-min\-uidnumber <user id number> +.TP +.B olcMinimumUidNumber: number +These options configure the minimum userid to use in any home +directory attempt. This is a basic safety measure to prevent +accidentally using system accounts. See REPLICATION for more flexible +options for selecting accounts. +.TP +.B homedir\-regexp <regexp> <path> +.TP +.B olcHomedirRegexp: regexp path +These options configure a set of regular expressions to use for +matching and optionally remapping incoming +.B homeDirectory +attribute values to pathnames on the local filesystem. $number +expansion is supported to access values captured in parentheses. + +For example, to accept any directory starting with \/home and use it +verbatim on the local filesystem: + +.B homedir-regexp ^(/home/[\-_/a\-z0\-9]+)$ $1 + +To match the same set of directories, but create them instead under +\/export\/home, as is popular on Solaris NFS servers: + +.B homedir-regexp ^(/home/[\-_/a\-z0\-9]+)$ /export$1 +.TP +.B homedir\-delete\-style style +.TP +.B olcHomedirDeleteStyle: style +These options configure how deletes of posixAccount entries or their +attributes are handled; valid styles are +.B IGNORE, +which does nothing, and +.B DELETE, +which immediately performs a recursive delete on the home directory, +and +.B ARCHIVE, +which archives the home directory contents in a TAR file for later +examination. The default is IGNORE. Use with caution. ARCHIVE +requires homedir-archive-path to be set, or it functions similar to +IGNORE. +.TP +.B homedir\-archive\-path <pathname> +.TP +.B olcArchivePath: pathname +These options specify the destination path for TAR files created by +the ARCHIVE delete style. +.SH REPLICATION +The homedir overlay can operate on either master or replica systems +with no changes. See +.BR slapd.conf (5) +or +.BR slapd\-config (5) +for more information on configure syncrepl. + +Partial replication (e.g. with filters) is especially useful for +providing different provisioning options to different sets of users. +.SH BUGS +DELETE, MOD, and MODRDN operations that remove the unix attributes +when delete style is set to DELETE will recursively delete the (regex +modified) home directory from the disk. Please be careful when +deleting or changing values. + +MOD and MODRDN will correctly respond to homeDirectory changes and +perform a non-destructive rename() operation on the filesystem, but +this does not correctly retry with a recursive copy when moving +between filesystems. + +The recursive copy/delete/chown/tar functions are not aware of ACLs, +extended attributes, forks, sparse files, or hard links. Block and +character device archival is non-portable, but should not be an issue +in home directories, hopefully. + +Copying and archiving may not support files larger than 2GiB on some +architectures. Bare POSIX UStar archives cannot support internal +files larger than 8GiB. The current tar generator does not attempt to +resolve uid/gid into symbolic names. + +No attempt is made to try to mkdir() the parent directories needed for +a given home directory or archive path. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +/etc/skel (or similar) +source of new homedir files. +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8), +RFC-2307, RFC-2307bis. +.SH ACKNOWLEDGEMENTS +.P +This module was written in 2009 by Emily Backes for Symas Corporation. diff --git a/doc/man/man5/slapo-memberof.5 b/doc/man/man5/slapo-memberof.5 new file mode 100644 index 0000000..45bf1b1 --- /dev/null +++ b/doc/man/man5/slapo-memberof.5 @@ -0,0 +1,145 @@ +.TH SLAPO-MEMBEROF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.SH NAME +slapo\-memberof \- Reverse Group Membership overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B memberof +overlay to +.BR slapd (8) +allows automatic reverse group membership maintenance. +Any time a group entry is modified, its members are modified as appropriate +in order to keep a DN-valued "is member of" attribute updated with the DN +of the group. +.LP +Note that this overlay is deprecated and support will be dropped in future +OpenLDAP releases. Installations should use the \fBdynlist\fP +overlay instead. Using this overlay in a replicated environment is especially +discouraged. + +.SH CONFIGURATION +The config directives that are specific to the +.B memberof +overlay must be prefixed by +.BR memberof\- , +to avoid potential conflicts with directives specific to the underlying +database or to other stacked overlays. + +.TP +.B overlay memberof +This directive adds the memberof overlay to the current database; see +.BR slapd.conf (5) +for details. + +.LP +The following +.B slapd.conf +configuration options are defined for the memberof overlay. + +.TP +.BI memberof\-group\-oc \ <group-oc> +The value +.I <group-oc> +is the name of the objectClass that triggers the reverse group membership +update. +It defaults to \fIgroupOfNames\fP. + +.TP +.BI memberof\-member\-ad \ <member-ad> +The value +.I <member-ad> +is the name of the attribute that contains the names of the members +in the group objects; it must be DN-valued. +It defaults to \fImember\fP. + +.TP +.BI memberof\-memberof\-ad \ <memberof-ad> +The value +.I <memberof-ad> +is the name of the attribute that contains the names of the groups +an entry is member of; it must be DN-valued. Its contents are +automatically updated by the overlay. +It defaults to \fImemberOf\fP. + +.TP +.BI memberof\-dn \ <dn> +The value +.I <dn> +contains the DN that is used as \fImodifiersName\fP for internal +modifications performed to update the reverse group membership. +It defaults to the \fIrootdn\fP of the underlying database. + +.TP +.BI "memberof\-dangling {" ignore ", " drop ", " error "}" +This option determines the behavior of the overlay when, during +a modification, it encounters dangling references. +The default is +.IR ignore , +which may leave dangling references. +Other options are +.IR drop , +which discards those modifications that would result in dangling +references, and +.IR error , +which causes modifications that would result in dangling references +to fail. + +.TP +.BI memberof\-dangling\-error \ <error-code> +If +.BR memberof\-dangling +is set to +.IR error , +this configuration parameter can be used to modify the response code +returned in case of violation. It defaults to "constraint violation", +but other implementations are known to return "no such object" instead. + +.TP +.BI "memberof\-refint {" true "|" FALSE "}" +This option determines whether the overlay will try to preserve +referential integrity or not. +If set to +.IR TRUE , +when an entry containing values of the "is member of" attribute is modified, +the corresponding groups are modified as well. + +.LP +The memberof overlay may be used with any backend that provides full +read-write functionality, but it is mainly intended for use +with local storage backends. The maintenance operations it performs +are internal to the server on which the overlay is configured and +are never replicated. Consumer servers should be configured with their +own instances of the memberOf overlay if it is desired to maintain +these memberOf attributes on the consumers. Note that slapo-memberOf +is not compatible with syncrepl based replication, and should not be +used in a replicated environment. An alternative is to use slapo-dynlist +to emulate slapo-memberOf behavior. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH BACKWARD COMPATIBILITY +The memberof overlay has been reworked with the 2.5 release to use +a consistent namespace as with other overlays. As a side-effect the +following cn=config parameters are deprecated and will be removed in +a future release: +.B olcMemberOf +is replaced with olcMemberOfConfig +.SH SEE ALSO +.BR slapo-dynlist (5), +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8). +The +.BR slapo\-memberof (5) +overlay supports dynamic configuration via +.BR back-config . +.SH ACKNOWLEDGEMENTS +.P +This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c. + diff --git a/doc/man/man5/slapo-otp.5 b/doc/man/man5/slapo-otp.5 new file mode 100644 index 0000000..7ff89c3 --- /dev/null +++ b/doc/man/man5/slapo-otp.5 @@ -0,0 +1,138 @@ +.TH SLAPO_OTP 5 "2018/6/29" "SLAPO-OTP" +.\" Copyright 2015-2022 The OpenLDAP Foundation. +.\" Portions Copyright 2015 by Howard Chu, Symas Corp. All rights reserved. +.\" Portions Copyright 2018 by OndÅ™ej KuznÃk, Symas Corp. All rights reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +slapo-otp \- OATH One-Time Password module +.SH SYNOPSIS +.B moduleload +.I otp.la +.SH DESCRIPTION +The +.B otp +module allows time-based one-time password, AKA "authenticator-style", and +HMAC-based one-time password authentication to be used in conjunction with +a standard LDAP password for two-factor authentication. + +With this module, users would use their password, followed with the one-time +password in the password prompt to authenticate. + +The password needed for a user to authenticate is calculated based on a counter +(current time in case of TOTP) and a key that is referenced in the user's LDAP +entry. Since the password is based on the time or number of uses, it changes +periodically. Once used, it cannot be used again so keyloggers and +shoulder-surfers are thwarted. A mobile phone application, such as the Google +Authenticator or YubiKey (a +.BR prover ), +can be used to calculate the user's current one-time password, which is +expressed as a (usually six-digit) number. + +Alternatively, the value can be calculated by some other application with +access to the user's key and delivered to the user through SMS or some other +channel. When prompted to authenticate, the user merely appends the code +provided by the prover at the end of their password when authenticating. + +This implementation complies with +.B RFC 4226 HOTP HMAC-Based One Time Passwords +and +.B RFC 6238 TOTP Time-based One Time Passwords +and includes support for the SHA-1, SHA-256, and SHA-512 HMAC +algorithms. + +The HMAC key used in the OTP computation is stored in the oathOTPToken entry referenced in +the user's LDAP entry and the parameters are stored in the oathOTPParams LDAP +entry referenced in the token. + +.SH CONFIGURATION +Once the module is configured on the database, it will intercept LDAP simple +binds for users whose LDAP entry has any of the +.B oathOTPUser +derived objectlasses attached to it. The attributes linking the user and the +shared secret are: + +.RS +.TP +.B oathTOTPToken: <dn> +Mandatory for +.BR oathTOTPUser , +indicates that the named entry is designated to hold the time-based one-time +password shared secret and the last password used. +.TP +.B oathHOTPToken: <dn> +Mandatory for +.BR oathHOTPUser , +indicates that the named entry is designated to hold the one-time password +shared secret and the last password used. +.TP +.B oathTOTPParams: <dn> +Mandatory for +.BR oathTOTPToken , +indicates that the named entry is designated to hold the parameters to generate +time-based one-time password shared secret: its length and algorithm to use as +well as the length of each time step and the grace period. +.TP +.B oathHOTPParams: <dn> +Mandatory for +.BR oathHOTPToken , +indicates that the named entry is designated to hold the parameters to generate +one-time password shared secret: its length and algorithm to use as well as the +permitted number of passwords to skip. +.RE + +The following parts of the OATH-LDAP schema are implemented. + +General attributes: + +.RS +.TP +.B oathSecret: <data> +The shared secret is stored here as raw bytes. +.TP +.B oathOTPLength: <length> +The password length, usually 6. +.TP +.B oathHMACAlgorithm: <OID> +The OID of the hash algorithm to use as defined in RFC 8018. +Supported algorithms include SHA1, SHA224, SHA256, SHA384 and SHA512. +.RE + +The HOTP attributes: + +.RS +.TP +.B oathHOTPLookAhead: <number> +The number of successive HOTP tokens that can be skipped. +.TP +.B oathHOTPCounter: <number> +The order of the last HOTP token successfully redeemed by the user. +.RE + +The TOTP attributes: + +.RS +.TP +.B oathTOTPTimeStepPeriod: <seconds> +The length of the time-step period for TOTP calculation. +.TP +.B oathTOTPLastTimeStep: <number> +The order of the last TOTP token successfully redeemed by the user. +.TP +.B oathTOTPTimeStepWindow: <number> +The number of time periods around the current time to try when checking the +password provided by the user. +.TP +.B oathTOTPTimeStepDrift: <number> +If the client didn't provide the correct token but it still fit with +oathTOTPTimeStepWindow above, this attribute records the current offset to +provide for slow clock drift of the client device. +.RE + +.SH "SEE ALSO" +.BR slapd\-config (5). + +.SH ACKNOWLEDGEMENT +This work was developed by OndÅ™ej KuznÃk and Howard Chu of Symas Corporation +for inclusion in OpenLDAP Software. + +This work reuses the OATH-LDAP schema developed by Michael Ströder. diff --git a/doc/man/man5/slapo-pbind.5 b/doc/man/man5/slapo-pbind.5 new file mode 100644 index 0000000..4a3c58f --- /dev/null +++ b/doc/man/man5/slapo-pbind.5 @@ -0,0 +1,61 @@ +.TH SLAPO-PBIND 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2010-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.SH NAME +slapo\-pbind \- proxy bind overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B pbind +overlay to +.BR slapd (8) +forwards Simple Binds on a local database to a remote +LDAP server instead of processing them locally. The remote +connection is managed using an instance of the ldap backend. + +.LP +The +.B pbind +overlay uses a subset of the \fIldap\fP backend's config directives. They +are described in more detail in +.BR slapd\-ldap (5). + +Note: this overlay is built into the \fIldap\fP backend; it is not a +separate module. + +.TP +.B overlay pbind +This directive adds the proxy bind overlay to the current backend. +The proxy bind overlay may be used with any backend, but it is mainly +intended for use with local storage backends. + +.TP +.B uri <ldapurl> +LDAP server to use. + +.TP +.B tls <TLS parameters> +Specify the use of TLS. + +.TP +.B network\-timeout <time> +Set the network timeout. + +.TP +.B quarantine <quarantine parameters> +Turns on quarantine of URIs that returned +.IR LDAP_UNAVAILABLE . + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd\-ldap (5), +.BR slapd (8). +.SH AUTHOR +Howard Chu diff --git a/doc/man/man5/slapo-pcache.5 b/doc/man/man5/slapo-pcache.5 new file mode 100644 index 0000000..1425897 --- /dev/null +++ b/doc/man/man5/slapo-pcache.5 @@ -0,0 +1,327 @@ +.TH SLAPO-PCACHE 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it> +.\" $OpenLDAP$ +.SH NAME +slapo\-pcache \- proxy cache overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B pcache +overlay to +.BR slapd (8) +allows caching of LDAP search requests (queries) in a local database. +For an incoming query, the +proxy cache determines its corresponding \fBtemplate\fP. If the template +was specified as cacheable using the \fBpcacheTemplate\fP directive +and the request is contained in a cached request, it is answered from +the proxy cache. +Otherwise, the search is performed as usual and cacheable search results +are saved in the cache for use in future queries. +.LP + +A template is defined by a filter string and an index identifying a set of +attributes. The \fBtemplate string\fP for a query can be obtained by +removing assertion values from the RFC 4515 representation of its search +filter. A query belongs to a template if its template string and set of +projected attributes correspond to a cacheable template. +Examples of template strings are \fB(mail=)\fP, \fB(|(sn=)(cn=))\fP, +\fB(&(sn=)(givenName=))\fP. + +.LP +The config directives that are specific to the +.B pcache +overlay can be prefixed by +.BR pcache\- , +to avoid conflicts with directives specific to the underlying database +or to other stacked overlays. This may be particularly useful for those +directives that refer to the backend used for local storage. +The following cache specific directives can be used to configure the proxy +cache: +.TP +.B overlay pcache +This directive adds the proxy cache overlay to the current backend. The +proxy cache overlay may be used with any backend but is intended for use +with the +.BR ldap , +.BR meta , +and +.BR sql +backends. Please note that the underlying backend must have a configured +.BR rootdn. +.TP +.B pcache <database> <max_entries> <numattrsets> <entry_limit> <cc_period> +The directive enables proxy caching in the current backend and sets general +cache parameters. A <database> backend will be used internally to maintain +the cached entries. The chosen database will need to be configured as well, +as shown below. Cache replacement is invoked when the cache size grows to +<max_entries> entries and continues till the cache size drops below this size. +<numattrsets> should be equal to the number of following \fBpcacheAttrset\fP +directives. Queries are cached only if they correspond to a cacheable template +(specified by the \fBpcacheTemplate\fP directive) and the number of entries +returned is less than <entry_limit>. Consistency check is performed every +<cc_period> duration (specified in secs). In each cycle queries with expired +"time to live(\fBTTL\fP)" are removed. A sample cache configuration is: +.LP +.RS +pcache \fBmdb 10000 1 50 100\fP +.RE + +.TP +.B pcacheAttrset <index> <attrs...> +Used to associate a set of attributes <attrs..> with an <index>. Each attribute +set is associated with an integer from 0 to <numattrsets>\-1. These indices are +used by the \fBpcacheTemplate\fP directive to define cacheable templates. +A set of attributes cannot be empty. A set of attributes can contain the +special attributes "*" (all user attributes), "+" (all operational attributes) +or both; in the latter case, any other attribute is redundant and should +be avoided for clarity. A set of attributes can contain "1.1" as the only +attribute; in this case, only the presence of the entries is cached. +Attributes prefixed by "undef:" need not be present in the schema. + +.TP +.B pcacheMaxQueries <queries> +Specify the maximum number of queries to cache. The default is 10000. + +.TP +.B pcacheValidate { TRUE | FALSE } +Check whether the results of a query being cached can actually be returned +from the cache by the proxy DSA. When enabled, the entries being returned +while caching the results of a query are checked to ensure consistency +with the schema known to the proxy DSA. In case of failure, the query +is not cached. By default, the check is off. + +.TP +.B pcacheOffline { TRUE | FALSE } +Set the cache to offline mode. While offline, the consistency checker +will be stopped and no expirations will occur. This allows the cache +contents to be used indefinitely while the proxy is cut off from network +access to the remote DSA. The default is FALSE, i.e. consistency +checks and expirations will be performed. + +.TP +.B pcachePersist { TRUE | FALSE } +Specify whether the cached queries should be saved across restarts +of the caching proxy, to provide hot startup of the cache. Only non-expired +queries are reloaded. The default is FALSE. + +.BR CAVEAT : +of course, the configuration of the proxy cache must not change +across restarts; the pcache overlay does not perform any consistency +checks in this sense. +In detail, this option should be disabled unless the existing +.B pcacheAttrset +and +.B pcacheTemplate +directives are not changed neither in order nor in contents. +If new sets and templates are added, or if other details of the pcache +overlay configuration changed, this feature should not be affected. + +.TP +.B pcacheTemplate <template_string> <attrset_index> <ttl> [<negttl> [<limitttl> [<ttr>]]] +Specifies a cacheable template and "time to live" <ttl> of queries +belonging to the template. An optional <negttl> can be used to specify +that negative results (i.e., queries that returned zero entries) +should also be cached for the specified amount of time. Negative +results are not cached by default (<negttl> set to 0). +An optional <limitttl> can be used to specify that results +hitting a sizelimit should also be cached for the specified amount of time. +Results hitting a sizelimit are not cached by default (<limitttl> set to 0). +An optional <ttr> "time to refresh" can be used to specify that cached +entries should be automatically refreshed after a certain time. Entries +will only be refreshed while they have not expired, so the <ttl> should +be larger than the <ttr> for this option to be useful. Entries are not +refreshed by default (<ttr> set to 0). + +.TP +.B pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base> +Specifies a template for caching Simple Bind credentials based on an +already defined \fBpcacheTemplate\fP. The <filter_template> is similar +to a <template_string> except that it may have some values present. Its +purpose is to allow the overlay to generate filters similar to what other +applications do when they do a Search immediately before a Bind. E.g., +if a client like nss_ldap is configured to search for a user with the +filter "(&(objectClass=posixAccount)(uid=<username>))" then the corresponding +template "(&(objectClass=posixAccount)(uid=))" should be used here. When +converted to a regular template e.g. "(&(objectClass=)(uid=))" this +template and the <attrset_index> must match an already defined +\fBpcacheTemplate\fP clause. The "time to refresh" <ttr> determines the +time interval after which the cached credentials may be refreshed. The +first Bind request that occurs after that time will trigger the refresh +attempt. Refreshes are not performed when the overlay is Offline. There +is no "time to live" parameter for the Bind credentials; the credentials +will expire according to the \fBpcacheTemplate\fP ttl. The <scope> and +<base> should match the search scope and base used by the authentication +clients. The cached credentials are not stored in cleartext, they are +hashed using the default password hash. +By default Bind caching is not enabled. + +.TP +.B pcachePosition { head | tail } +Specifies whether the response callback should be placed at the +.B tail +(the default) or at the +.B head +(actually, wherever the stacking sequence would make it appear) +of the callback list. This affects how the overlay interacts with other +overlays, since the proxycache overlay should be executed as early +as possible (and thus configured as late as possible), to get +a chance to return the cached results; however, if executed early +at response, it would cache entries that may be later "massaged" +by other databases and thus returned \fIafter\fP massaging the first +time, and \fIbefore\fP massaging when cached. + +.TP +There are some constraints: + +all values must be positive; + +.B <entry_limit> +must be less than or equal to +.BR <max_entries> ; + +.B <numattrsets> +attribute sets SHOULD be defined by using the directive +.BR pcacheAttrset ; + +all attribute sets SHOULD be referenced by (at least) one +.B pcacheTemplate +directive; + +.LP +The following adds a template with filter string \fB(&(sn=)(givenName=))\fP +and attributes mail, postaladdress, telephonenumber and a TTL of 1 hour. +.LP +.RS +.nf +pcacheAttrset \fB0 mail postaladdress telephonenumber\fP +pcacheTemplate \fB(&(sn=)(givenName=)) 0 3600\fP +.fi +.RE + +.LP +Directives for configuring the underlying database must also be given, as +shown here: +.LP +.RS +.nf +directory /var/tmp/cache +cachesize 100 +.fi +.RE +.LP +Any valid directives for the chosen database type may be used. Indexing +should be used as appropriate for the queries being handled. In addition, +an equality index on the \fBpcacheQueryid\fP attribute should be configured, to +assist in the removal of expired query data. +.SH BACKWARD COMPATIBILITY +The configuration keywords have been renamed and the older form is +deprecated. These older keywords are still recognized but may disappear +in future releases. + +.TP +.B proxycache +use pcache + +.TP +.B proxyattrset +use pcacheAttrset + +.TP +.B proxycachequeries +use pcacheMaxQueries + +.TP +.B proxycheckcacheability +use pcacheValidate + +.TP +.B proxysavequeries +use pcachePersist + +.TP +.B proxytemplate +use pcacheTemplate + +.TP +.B response-callback +use pcachePosition + +.SH CAVEATS +Caching data is prone to inconsistencies because updates on the remote server +will not be reflected in the response of the cache at least (and at most) +for the duration of the +.B pcacheTemplate +.BR TTL . +These inconsistencies can be minimized by careful use of the TTR. + +The proxy cache overlay requires a full result set of data to properly +function. Therefore it will strip out the paged results control if it is +requested by the client. + +The remote server should expose the +.B objectClass +attribute because the underlying database that actually caches the entries +may need it for optimal local processing of the queries. + +The proxy server should contain all the schema information required for caching. +Significantly, it needs the schema of attributes used in the query templates. +If the objectClass attribute is used in a query template, it needs the definition +of the objectClasses of the entries it is supposed to cache. +It is the responsibility of the proxy administrator to keep the proxy schema +lined up with that of the proxied server. + +Another potential (and subtle) inconsistency may occur when data is retrieved +with different identities and specific per-identity access control +is enforced by the remote server. +If data was retrieved with an identity that collected only partial results +because of access rules enforcement on the remote server, other users +with different access privileges on the remote server will get different +results from the remote server and from the cache. +If those users have higher access privileges on the remote server, they will +get from the cache only a subset of the results they would get directly +from the remote server; but if they have lower access privileges, they will +get from the cache a superset of the results they would get directly +from the remote server. +Either occurrence may or may not be acceptable, based on the security policy +of the cache and of the remote server. +It is important to note that in this case the proxy is violating the security +of the remote server by disclosing to an identity data that was collected +by another identity. +For this reason, it is suggested that, when using +.BR back-ldap , +proxy caching be used in conjunction with the +.I identity assertion +feature of +.BR slapd\-ldap (5) +(see the +.B idassert\-bind +and the +.B idassert\-authz +statements), so that remote server interrogation occurs with a vanilla identity +that has some relatively high +.B search +and +.B read +access privileges, and the "real" access control is delegated to the proxy's ACLs. +Beware that since only the cached fraction of the real datum is available +to the cache, it may not be possible to enforce the same access rules that +are defined on the remote server. +When security is a concern, cached proxy access must be carefully tailored. +.SH FILES + +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd\-ldap (5), +.BR slapd\-meta (5), +.BR slapd\-sql (5), +.BR slapd (8). +.SH AUTHOR +Originally implemented by Apurva Kumar as an extension to back-meta; +turned into an overlay by Howard Chu. diff --git a/doc/man/man5/slapo-ppolicy.5 b/doc/man/man5/slapo-ppolicy.5 new file mode 100644 index 0000000..8d12ea2 --- /dev/null +++ b/doc/man/man5/slapo-ppolicy.5 @@ -0,0 +1,1060 @@ +.TH SLAPO_PPOLICY 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-ppolicy \- Password Policy overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +.LP +The +.B ppolicy +overlay +is an implementation of the most recent IETF Password +Policy proposal for LDAP. When instantiated, it intercepts, +decodes and applies specific password policy controls to overall +use of a backend database, changes to user password fields, etc. +.P +The overlay provides a variety of password control mechanisms. They +include password aging -- both minimum and maximum ages, password +reuse and duplication control, account time-outs, mandatory password +resets, acceptable password content, and even grace logins. +Different groups of users may be associated with different password +policies, and there is no limit to the number of password policies +that may be created. +.P +Note that some of the policies do not take effect when the operation +is performed with the +.B rootdn +identity; all the operations, when performed with any other identity, +may be subjected to constraints, like access control. This overlay +requires a rootdn to be configured on the database. +.P +During password update, an identity with +.B manage +access to the userPassword attribute is considered a password +administrator where relevant to the IETF Password Policy proposal. +.P +Note that the IETF Password Policy proposal for LDAP makes sense +when considering a single-valued password attribute, while +the userPassword attribute allows multiple values. This implementation +enforces a single value for the userPassword attribute, despite +its specification. +.P +In addition to supporting the IETF Password Policy, this module +supports the SunDS Account Usability control (1.3.6.1.4.1.42.2.27.9.5.8) +on search requests and can send the Netscape Password validity controls +when configured to do so. + +.SH CONFIGURATION +These +.B slapd.conf +configuration options apply to the ppolicy overlay. They should appear +after the +.B overlay +directive. +.TP +.B ppolicy_default <policyDN> +Specify the DN of the pwdPolicy object to use when no specific policy is +set on a given user's entry. If there is no specific policy for an entry +and no default is given, then no policies will be enforced. +.TP +.B ppolicy_forward_updates +Specify that policy state changes that result from Bind operations (such +as recording failures, lockout, etc.) on a consumer should be forwarded +to a provider instead of being written directly into the consumer's local +database. This setting is only useful on a replication consumer, and +also requires the +.B updateref +setting and +.B chain +overlay to be appropriately configured. +.TP +.B ppolicy_hash_cleartext +Specify that cleartext passwords present in Add and Modify requests should +be hashed before being stored in the database. This violates the X.500/LDAP +information model, but may be needed to compensate for LDAP clients that +don't use the Password Modify extended operation to manage passwords. It +is recommended that when this option is used that compare, search, and +read access be denied to all directory users. +.TP +.B ppolicy_use_lockout +A client will always receive an LDAP +.B InvalidCredentials +response when +Binding to a locked account. By default, when a Password Policy control +was provided on the Bind request, a Password Policy response will be +included with no special error code set. This option changes the +Password Policy response to include the +.B AccountLocked +error code. Note +that sending the +.B AccountLocked +error code provides useful information +to an attacker; sites that are sensitive to security issues should not +enable this option. +.TP +.B ppolicy_send_netscape_controls +If set, ppolicy will send the password policy expired (2.16.840.1.113730.3.4.4) +and password policy expiring (2.16.840.1.113730.3.4.5) controls when +appropriate. The controls are not sent for bind requests where the Password +policy control has already been requested. Default is not to send the controls. + +.SH OBJECT CLASS +The +.B ppolicy +overlay depends on the +.B pwdPolicy +object class. The definition of that class is as follows: +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.2.1 + NAME 'pwdPolicy' + AUXILIARY + SUP top + MUST ( pwdAttribute ) + MAY ( + pwdMinAge $ pwdMaxAge $ pwdInHistory $ + pwdCheckQuality $ pwdMinLength $ pwdMaxLength $ + pwdExpireWarning $ pwdGraceAuthnLimit $ + pwdGraceExpiry $ pwdLockout $ pwdLockoutDuration $ + pwdMaxFailure $ pwdFailureCountInterval $ + pwdMustChange $ pwdAllowUserChange $ + pwdSafeModify $ pwdMaxRecordedFailure $ + pwdMinDelay $ pwdMaxDelay $ pwdMaxIdle ) ) +.RE + +The +.B pwdPolicy +class is not structural, and so entries using it require another, +structural, object class. The +.B namedPolicy +object class is a good choice. +.B namedPolicy +requires a +.B cn +attribute, suitable as the policy entry's rDN. + +This implementation also provides an additional +.B pwdPolicyChecker +objectclass, used for password quality checking (see below). +.LP +.RS 4 +( 1.3.6.1.4.1.4754.2.99.1 + NAME 'pwdPolicyChecker' + AUXILIARY + SUP top + MAY ( pwdCheckModule $ pwdCheckModuleArg ) ) +.RE +.P +Every account that should be subject to password policy control should +have a +.B +pwdPolicySubentry +attribute containing the DN of a valid +.B pwdPolicy +entry, or they can simply use the configured default. +In this way different users may be managed according to +different policies. + +.SH OBJECT CLASS ATTRIBUTES +.P +Each one of the sections below details the meaning and use of a particular +attribute of this +.B pwdPolicy +object class. +.P + +.B pwdAttribute +.P +This attribute contains the name of the attribute to which the password +policy is applied. For example, the password policy may be applied +to the +.B userPassword +attribute. +.P +Note: in this implementation, the only +value accepted for +.B pwdAttribute +is +.IR " userPassword ". +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.1 + NAME 'pwdAttribute' + EQUALITY objectIdentifierMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) +.RE + +.B pwdMinAge +.P +This attribute contains the number of seconds that must elapse +between modifications allowed to the password. If this attribute +is not present, zero seconds is assumed (i.e. the password may be +modified whenever and however often is desired). +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.2 + NAME 'pwdMinAge' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdMaxAge +.P +This attribute contains the number of seconds after which a modified +password will expire. If this attribute is not present, or if its +value is zero (0), then passwords will not expire. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.3 + NAME 'pwdMaxAge' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdInHistory +.P +This attribute is used to specify the maximum number of used +passwords that will be stored in the +.B pwdHistory +attribute. If the +.B pwdInHistory +attribute is not present, or if its value is +zero (0), used passwords will not be stored in +.B pwdHistory +and thus any previously-used password may be reused. +No history checking occurs if the password is being modified by the +.BR rootdn , +although the password is saved in the history. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.4 + NAME 'pwdInHistory' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdCheckQuality +.P +This attribute indicates if and how password syntax will be checked +while a password is being modified or added. If this attribute is +not present, or its value is zero (0), no syntax checking will be +done. If its value is one (1), the server will check the syntax, +and if the server is unable to check the syntax, +whether due to a client-side hashed password or some other reason, +it will be +accepted. If its value is two (2), the server will check the syntax, +and if the server is unable to check the syntax it will return an +error refusing the password. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.5 + NAME 'pwdCheckQuality' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdMinLength +.P +When syntax checking is enabled +(see also the +.B pwdCheckQuality +attribute), this attribute contains the minimum +length in bytes that will be accepted in a password. If this +attribute is not present, minimum password length is not +enforced. If the server is unable to check the length of the password, +whether due to a client-side hashed password or some other reason, +the server will, depending on the +value of +.BR pwdCheckQuality , +either accept the password +without checking it (if +.B pwdCheckQuality +is zero (0) or one (1)) or refuse it (if +.B pwdCheckQuality +is two (2)). If the number of characters should be enforced with regards +to a particular encoding, the use of an appropriate pwdCheckModule is +required. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.6 + NAME 'pwdMinLength' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdMaxLength +.P +When syntax checking is enabled +(see also the +.B pwdCheckQuality +attribute), this attribute contains the maximum +length in bytes that will be accepted in a password. If this +attribute is not present, maximum password length is not +enforced. If the server is unable to check the length of the password, +whether due to a client-side hashed password or some other reason, +the server will, depending on the +value of +.BR pwdCheckQuality , +either accept the password +without checking it (if +.B pwdCheckQuality +is zero (0) or one (1)) or refuse it (if +.B pwdCheckQuality +is two (2)). If the number of characters should be enforced with regards +to a particular encoding, the use of an appropriate pwdCheckModule is +required. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.31 + NAME 'pwdMaxLength' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdExpireWarning +.P +This attribute contains the maximum number of seconds before a +password is due to expire that expiration warning messages will be +returned to a user who is authenticating to the directory. +If this attribute is not +present, or if the value is zero (0), no warnings will be sent. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.7 + NAME 'pwdExpireWarning' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdGraceAuthnLimit +.P +This attribute contains the number of times that an expired password +may be used to authenticate a user to the directory. If this +attribute is not present or if its value is zero (0), users with +expired passwords will not be allowed to authenticate to the +directory. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.8 + NAME 'pwdGraceAuthnLimit' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdGraceExpiry +.P +This attribute specifies the number of seconds the grace +authentications are valid. If this attribute is not present or if +the value is zero (0), there is no time limit on the grace +authentications. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.30 + NAME 'pwdGraceExpiry' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdLockout +.P +This attribute specifies the action that should be taken +by the directory when a user has made a number of failed attempts +to authenticate to the directory. If +.B pwdLockout +is set (its value is "TRUE"), the user will not be allowed to +attempt to authenticate to the directory after there have been a +specified number of consecutive failed bind attempts. The maximum +number of consecutive failed bind attempts allowed is specified by +the +.B pwdMaxFailure +attribute. If +.B pwdLockout +is not present, or if its value is "FALSE", the password may be +used to authenticate no matter how many consecutive failed bind +attempts have been made. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.9 + NAME 'pwdLockout' + EQUALITY booleanMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 + SINGLE\-VALUE ) +.RE + +.B pwdLockoutDuration +.P +This attribute contains the number of seconds during +which the password cannot be used to authenticate the +user to the directory due to too many consecutive failed +bind attempts. +(See also +.B pwdLockout +and +.BR pwdMaxFailure .) +If +.B pwdLockoutDuration +is not present, or if its value is zero (0), the password +cannot be used to authenticate the user to the directory +again until it is reset by an administrator. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.10 + NAME 'pwdLockoutDuration' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdMaxFailure +.P +This attribute contains the number of consecutive failed bind +attempts after which the password may not be used to authenticate +a user to the directory. +If +.B pwdMaxFailure +is not present, or its value is zero (0), then a user will +be allowed to continue to attempt to authenticate to +the directory, no matter how many consecutive failed +bind attempts have occurred with that user's DN. +(See also +.B pwdLockout +and +.BR pwdLockoutDuration .) +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.11 + NAME 'pwdMaxFailure' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdMaxRecordedFailure +.P +This attribute contains the maximum number of failed bind +attempts to store in a user's entry. +If +.B pwdMaxRecordedFailure +is not present, or its value is zero (0), then it defaults +to the value of +.BR pwdMaxFailure . +If that value is also 0, the default is 5. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.32 + NAME 'pwdMaxRecordedFailure' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdFailureCountInterval +.P +This attribute contains the number of seconds after which old +consecutive failed bind attempts are purged from the failure counter, +even though no successful authentication has occurred. +If +.B pwdFailureCountInterval +is not present, or its value is zero (0), the failure +counter will only be reset by a successful authentication. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.12 + NAME 'pwdFailureCountInterval' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdMustChange +.P +This attribute specifies whether users must change their passwords +when they first bind to the directory after a password is set or +reset by the administrator, or not. If +.B pwdMustChange +has a value of "TRUE", users must change their passwords when they +first bind to the directory after a password is set or reset by +the administrator. If +.B pwdMustChange +is not present, or its value is "FALSE", +users are not required to change their password upon binding after +the administrator sets or resets the password. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.13 + NAME 'pwdMustChange' + EQUALITY booleanMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 + SINGLE\-VALUE ) +.RE + +.B pwdAllowUserChange +.P +This attribute specifies whether users are allowed to change their own +passwords or not. If +.B pwdAllowUserChange +is set to "TRUE", or if the attribute is not present, users will be +allowed to change their own passwords. If its value is "FALSE", +users will not be allowed to change their own passwords. +.LP +Note: this implies that when +.B pwdAllowUserChange +is set to "TRUE", +users will still be able to change the password of another user, +subjected to access control. +This restriction only applies to modifications of ones's own password. +It should also be noted that +.B pwdAllowUserChange +was defined in the specification to provide rough access control +to the password attribute in implementations that do not allow fine-grain +access control. +Since OpenLDAP provides fine-grain access control, the use of this attribute +is discouraged; ACLs should be used instead +(see +.BR slapd.access (5) +for details). +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.14 + NAME 'pwdAllowUserChange' + EQUALITY booleanMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 + SINGLE\-VALUE ) +.RE + +.B pwdSafeModify +.P +This attribute denotes whether the user's existing password must be sent +along with their new password when changing a password. If +.B pwdSafeModify +is set to "TRUE", the existing password must be sent +along with the new password. If the attribute is not present, or +its value is "FALSE", the existing password need not be sent +along with the new password. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.15 + NAME 'pwdSafeModify' + EQUALITY booleanMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 + SINGLE\-VALUE ) +.RE + +.B pwdMinDelay +.P +This attribute specifies the number of seconds to delay responding to +the first failed authentication attempt. If this attribute is not +set or is zero (0), no delays will be used. +.B pwdMaxDelay +must also be specified if +.B pwdMinDelay +is set. + +Note that this implementation uses a variable lockout instead of +delaying the bind response. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.24 + NAME 'pwdMinDelay' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdMaxDelay +.P +This attribute specifies the maximum number of seconds to delay when +responding to a failed authentication attempt. The time specified in +.B pwdMinDelay +is used as the starting time and is then doubled on each failure until +the delay time is greater than or equal to +.B pwdMaxDelay +(or a successful authentication occurs, which resets the failure +counter). +.B pwdMinDelay +must also be specified if +.B pwdMaxDelay +is set. + +Note that this implementation uses a variable lockout instead of +delaying the bind response. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.25 + NAME 'pwdMaxDelay' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.B pwdMaxIdle +.P +This attribute specifies the number of seconds an account may remain +unused before it becomes locked. If this attribute is not set or is +zero (0), no check is performed. For this to be enforced, +.B lastbind +functionality needs to be enabled on the database, that is +.B olcLastBind +is set to +.BR TRUE . +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.26 + NAME 'pwdMaxIdle' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE + +.BR pwdCheckModule / pwdCheckModuleArg +.P +This attribute names a user-defined loadable module that must +instantiate the check_password() function. This function +will be called to further check a new password if +.B pwdCheckQuality +is set to one (1) or two (2), +after all of the built-in password compliance checks have +been passed. This function will be called according to this +function prototype: +.RS 4 +int +.I check_password +(char *pPasswd, char **ppErrStr, Entry *pEntry, struct berval *pArg); +.RE +The +.B pPasswd +parameter contains the clear-text user password, the +.B ppErrStr +parameter contains a double pointer that allows the function +to return human-readable details about any error it encounters. + +The +.B pEntry +parameter is optional, if non-NULL, carries a pointer to the +entry whose password is being checked. + +The optional +.B pArg +parameter points to a +.B struct berval +containing the value of +.B pwdCheckModuleArg +in the effective password policy, if set, otherwise NULL. + +If +.B ppErrStr +is NULL, then +.I funcName +must NOT attempt to use it/them. +A return value of LDAP_SUCCESS from the called +function indicates that the password is ok, any other value +indicates that the password is unacceptable. If the password is +unacceptable, the server will return an error to the client, and +.B ppErrStr +may be used to return a human-readable textual explanation of the +error. The error string must be dynamically allocated as it will +be free()'d by slapd. +.LP +.RS 4 +( 1.3.6.1.4.1.4754.1.99.1 + NAME 'pwdCheckModule' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 + SINGLE\-VALUE ) + +( 1.3.6.1.4.1.4754.1.99.2 + NAME 'pwdCheckModuleArg' + EQUALITY octetStringMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 + DESC 'Argument to pass to check_password() function' + SINGLE\-VALUE ) +.RE +.P +Note: +The user-defined loadable module named by +.B pwdCheckModule +must be in +.B slapd's +standard executable search PATH. +.P +Note: +.B pwdCheckModule +is a non-standard extension to the LDAP password +policy proposal. + +.SH OPERATIONAL ATTRIBUTES +.P +The operational attributes used by the +.B ppolicy +module are stored in the user's entry. Most of these attributes +are not intended to be changed directly by users; they are there +to track user activity. They have been detailed here so that +administrators and users can both understand the workings of +the +.B ppolicy +module. + +.P +Note that the current IETF Password Policy proposal does not define +how these operational attributes are expected to behave in a +replication environment. In general, authentication attempts on +a replica server only affect the copy of the operational attributes +on that replica and will not affect any attributes for +a user's entry on the provider. Operational attribute changes +resulting from authentication attempts on a provider +will usually replicate to the replicas (and also overwrite +any changes that originated on the replica). +These behaviors are not guaranteed and are subject to change +when a formal specification emerges. + +.B userPassword +.P +The +.B userPassword +attribute is not strictly part of the +.B ppolicy +module. It is, however, the attribute that is tracked and controlled +by the module. Please refer to the standard OpenLDAP schema for +its definition. + +.B pwdPolicySubentry +.P +This attribute refers directly to the +.B pwdPolicy +subentry that is to be used for this particular directory user. +If +.B pwdPolicySubentry +exists, it must contain the DN of a valid +.B pwdPolicy +object. If it does not exist, the +.B ppolicy +module will enforce the default password policy rules on the +user associated with this authenticating DN. If there is no +default, or the referenced subentry does not exist, then no +policy rules will be enforced. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.23 + NAME 'pwdPolicySubentry' + DESC 'The pwdPolicy subentry in effect for + this object' + EQUALITY distinguishedNameMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 + SINGLE\-VALUE + USAGE directoryOperation) +.RE + +.B pwdChangedTime +.P +This attribute denotes the last time that the entry's password was +changed. This value is used by the password expiration policy to +determine whether the password is too old to be allowed to be used +for user authentication. If +.B pwdChangedTime +does not exist, the user's password will not expire. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.16 + NAME 'pwdChangedTime' + DESC 'The time the password was last changed' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SINGLE\-VALUE + NO\-USER\-MODIFICATION + USAGE directoryOperation) +.RE + +.B pwdAccountLockedTime +.P +This attribute contains the time that the user's account was locked. +If the account has been locked, the password may no longer be used to +authenticate the user to the directory. If +.B pwdAccountLockedTime +is set to 000001010000Z, the user's account has been permanently locked +and may only be unlocked by an administrator. Note that account locking +only takes effect when the +.B pwdLockout +password policy attribute is set to "TRUE". +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.17 + NAME 'pwdAccountLockedTime' + DESC 'The time an user account was locked' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SINGLE\-VALUE + USAGE directoryOperation) +.RE + +.B pwdFailureTime +.P +This attribute contains the timestamps of each of the consecutive +authentication failures made upon attempted authentication to this +DN (i.e. account). If too many timestamps accumulate here (refer to +the +.B pwdMaxFailure +password policy attribute for details), +and the +.B pwdLockout +password policy attribute is set to "TRUE", the +account may be locked. +(Please also refer to the +.B pwdLockout +password policy attribute.) +Excess timestamps beyond those allowed by +.B pwdMaxFailure +or +.B pwdMaxRecordedFailure +may also be purged. If a successful authentication is made to this +DN (i.e. to this user account), then +.B pwdFailureTime +will be cleansed of entries. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.19 + NAME 'pwdFailureTime' + DESC 'The timestamps of the last consecutive + authentication failures' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + NO\-USER\-MODIFICATION + USAGE directoryOperation ) +.RE + +.B pwdHistory +.P +This attribute contains the history of previously used passwords +for this DN (i.e. for this user account). +The values of this attribute are stored in string format as follows: + +.RS 4 + +pwdHistory= +.RS 4 +time "#" syntaxOID "#" length "#" data +.RE + +time= +.RS 4 +GeneralizedTime as specified in section 3.3.13 of [RFC4517] +.RE + +.P +syntaxOID = numericoid +.RS 4 +This is the string representation of the dotted-decimal OID that +defines the syntax used to store the password. numericoid is +described in section 1.4 of [RFC4512]. +.RE + +length = NumericString +.RS 4 +The number of octets in the data. NumericString is described in +section 3.3.23 of [RFC4517]. +.RE + +data = +.RS 4 +Octets representing the password in the format specified by syntaxOID. +.RE + +.RE + +This format allows the server to store and transmit a history of +passwords that have been used. In order for equality matching +on the values in this attribute to function properly, the time +field is in GMT format. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.20 + NAME 'pwdHistory' + DESC 'The history of user passwords' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 + EQUALITY octetStringMatch + NO\-USER\-MODIFICATION + USAGE directoryOperation) +.RE + +.B pwdGraceUseTime + +This attribute contains the list of timestamps of logins made after +the user password in the DN has expired. These post-expiration +logins are known as "\fIgrace logins\fP". +If too many +.I grace logins +have been used (please refer to the +.B pwdGraceAuthnLimit +password policy attribute), then the DN will no longer be allowed +to be used to authenticate the user to the directory until the +administrator changes the DN's +.B userPassword +attribute. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.21 + NAME 'pwdGraceUseTime' + DESC 'The timestamps of the grace login once the password has expired' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + EQUALITY generalizedTimeMatch + NO\-USER\-MODIFICATION + USAGE directoryOperation) +.RE + +.B pwdReset +.P +This attribute indicates whether the user's password has been reset +by the administrator and thus must be changed upon first use of this +DN for authentication to the directory. If +.B pwdReset +is set to "TRUE", then the password was reset and the user must change +it upon first authentication. If the attribute does not exist, or +is set to "FALSE", the user need not change their password due to +administrative reset. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.22 + NAME 'pwdReset' + DESC 'The indication that the password has + been reset' + EQUALITY booleanMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 + SINGLE\-VALUE + USAGE directoryOperation) +.RE + +.B pwdStartTime + +This attribute specifies the time the entry's password becomes valid +for authentication. Authentication attempts made before this time +will fail. If this attribute does not exist, then no restriction +applies. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.27 + NAME 'pwdStartTime' + DESC 'The time the password becomes enabled' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + SINGLE\-VALUE + USAGE directoryOperation ) +.RE + +.B pwdEndTime + +This attribute specifies the time the entry's password becomes +invalid for authentication. Authentication attempts made after this +time will fail, regardless of expiration or grace settings. If this +attribute does not exist, then this restriction does not apply. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.28 + NAME 'pwdEndTime' + DESC 'The time the password becomes disabled' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + SINGLE\-VALUE + USAGE directoryOperation ) +.RE + +Note that pwdStartTime may be set to a time greater than or equal to +pwdEndTime; this simply disables the account. + +.B pwdAccountTmpLockoutEnd +.P +This attribute that the user's password has been locked out temporarily +according to the +.B pwdMinDelay +policy option and when the lockout ends. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.33 + NAME 'pwdAccountTmpLockoutEnd' + DESC 'Temporary lockout end' + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + SINGLE\-VALUE + NO\-USER\-MODIFICATION + USAGE directoryOperation ) +.RE + +.SH SUNDS ACCOUNT USABILITY CONTROL +.LP +If the SunDS Account Usability control is used with a search request, the +overlay will attach validity information to each entry provided all of the +following are met: +.IP \[bu] 2 +There is a password policy that applies to the entry +.IP \[bu] +The user has +.B compare +access to the entry's password attribute. +.IP \[bu] +The configured password attribute is present in the entry + +.SH EXAMPLES +.LP +.RS +.nf +database mdb +suffix dc=example,dc=com +\|... +overlay ppolicy +ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com" +.fi +.RE + +.SH SEE ALSO +.BR ldap (3), +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapo\-chain (5). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.LP +IETF LDAP password policy proposal by P. Behera, L. Poitou and J. +Sermersheim: documented in IETF document +"draft-behera-ldap-password-policy-10.txt". + +.SH BUGS +The LDAP Password Policy specification is not yet an approved standard, +and it is still evolving. This code will continue to be in flux until the +specification is finalized. + +.SH ACKNOWLEDGEMENTS +.P +This module was written in 2004 by Howard Chu of Symas Corporation +with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard. +.P +This manual page borrows heavily and shamelessly from the specification +upon which the password policy module it describes is based. This +source is the +IETF LDAP password policy proposal by P. Behera, L. +Poitou and J. Sermersheim. +The proposal is fully documented in +the +IETF document named draft-behera-ldap-password-policy-10.txt, +written in August of 2009. +.P +.so ../Project diff --git a/doc/man/man5/slapo-refint.5 b/doc/man/man5/slapo-refint.5 new file mode 100644 index 0000000..98c24e7 --- /dev/null +++ b/doc/man/man5/slapo-refint.5 @@ -0,0 +1,78 @@ +.TH SLAPO-REFINT 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-refint \- Referential Integrity overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Referential Integrity overlay can be used with a backend database such as +.BR slapd\-mdb (5) +to maintain the cohesiveness of a schema which utilizes reference attributes. +.LP +Integrity is maintained by updating database records which contain the named +attributes to match the results of a +.B modrdn +or +.B delete +operation. For example, if the integrity attribute were configured as +.BR manager , +deletion of the record "uid=robert,ou=people,dc=example,dc=com" would trigger a +search for all other records which have a +.B manager +attribute containing that DN. Entries matching that search would have their +.B manager +attribute removed. +Or, renaming the same record into "uid=george,ou=people,dc=example,dc=com" +would trigger a search for all other records which have a +.B manager +attribute containing that DN. +Entries matching that search would have their +.B manager +attribute deleted and replaced by the new DN. +.LP +.B rootdn +must be set for the database. refint runs as the rootdn +to gain access to make its updates. +.B rootpw +is not needed. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the Referential Integrity overlay. +They should appear after the +.B overlay +directive. +.TP +.B refint_attributes <attribute> [...] +Specify one or more attributes for which integrity will be maintained +as described above. +.TP +.B refint_nothing <string> +Specify an arbitrary value to be used as a placeholder when the last value +would otherwise be deleted from an attribute. This can be useful in cases +where the schema requires the existence of an attribute for which referential +integrity is enforced. The attempted deletion of a required attribute will +otherwise result in an Object Class Violation, causing the request to fail. +The string must be a valid DN. +.TP +.B refint_modifiersname <DN> +Specify the DN to be used as the modifiersName of the internal modifications +performed by the overlay. +It defaults to "\fIcn=Referential Integrity Overlay\fP". +.LP +Modifications performed by this overlay are not propagated during +replication. This overlay must be configured identically on +replication consumers in order to maintain full synchronization +with the provider. + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5). +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapo-remoteauth.5 b/doc/man/man5/slapo-remoteauth.5 new file mode 100644 index 0000000..4d12587 --- /dev/null +++ b/doc/man/man5/slapo-remoteauth.5 @@ -0,0 +1,160 @@ +.TH SLAPO-REMOTEAUTH 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.SH NAME +slapo-remoteauth \- Delegate authentication requests to remote directories, e.g. Active Directory +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B remoteauth +overlay to +.BR slapd (8) +provides passthrough authentication to remote directory servers, e.g. +Active Directory, for LDAP simple bind operations. The local LDAP entry +referenced in the bind operation is mapped to its counterpart in the remote +directory. An LDAP bind operation is performed against the remote directory +and results are returned based on those of the remote operation. +.LP +A slapd server configured with the +.B remoteauth +overlay handles an authentication request based on the presence of +.B userPassword +in the local entry. If the +.B userPassword +is present, authentication is performed locally, otherwise the +.B remoteauth +overlay performs the authentication request to the configured remote directory +server. +.LP + +.SH CONFIGURATION + +The following options can be applied to the +.B remoteauth +overlay within the slapd.conf file. All options should follow the +.B overlay remoteauth +directive. + +.TP +.B overlay remoteauth +This directive adds the +.B remoteauth +overlay to the current database, see +.BR slapd.conf (5) +for details. + +.TP +.B remoteauth_dn_attribute <dnattr> +Attribute in the local entry that is used to store the bind DN to a remote +directory server. + +.TP +.B remoteauth_mapping <domain> <hostname|LDAP URI|file:///path/to/list_of_hostnames> +For a non-Windows deployment, a domain can be considered as a collection of +one or more hosts to which slapd server authentcates against on behalf of +authenticating users. +For a given domain name, the mapping specifies the target server(s), +e.g., Active Directory domain controller(s), to connect to via LDAP. +The second argument can be given either as a hostname, an LDAP URI, or a file +containing a list of hostnames/URIs, one per line. The hostnames are tried in +sequence until the connection succeeds. + +This option can be provided more than once to provide mapping information for +different domains. For example: + +.nf + remoteauth_mapping americas file:///path/to/americas.domain.hosts + remoteauth_mapping asiapacific file:///path/to/asiapacific.domain.hosts + remoteauth_mapping emea emeadc1.emea.example.com +.fi + +.TP +.B remoteauth_domain_attribute <attr> +Attribute in the local entry that specifies the domain name, any text after +"\\" or ":" is ignored. + +.TP +.B remoteauth_default_domain <default domain> +Default domain. + + +.TP +.B remoteauth_default_realm <server> +Fallback server to connect to for domains not specified in +.BR remoteauth_mapping . + +.TP +.B remoteauth_retry_count <num> +Number of connection retries attempted. Default is 3. + +.TP +.B remoteauth_store <on|off> +Whether to store the password in the local entry on successful bind. Default is +off. + +.HP +.hy 0 +.B remoteauth_tls +.B [starttls=yes] +.B [tls_cert=<file>] +.B [tls_key=<file>] +.B [tls_cacert=<file>] +.B [tls_cacertdir=<path>] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=<ciphers>] +.B [tls_ecname=<names>] +.B [tls_crlcheck=none|peer|all] +.RS +Remoteauth specific TLS configuration, see +.BR slapd.conf (5) +for more details on each of the parameters and defaults. +.RE + +.TP +.B remoteauth_tls_peerkey_hash <hostname> <hashname>:<base64 of public key hash> +Mapping between remote server hostnames and their public key hashes. Only one +mapping per hostname is supported and if any pins are specified, all hosts +need to be pinned. If set, pinning is in effect regardless of whether or not +certificate name validation is enabled by +.BR tls_reqcert . + +.SH EXAMPLE +A typical example configuration of +.B remoteauth +overlay for AD is shown below (as a +.BR slapd.conf (5) +snippet): + +.LP +.nf + database <database> + #... + + overlay remoteauth + remoteauth_dn_attribute seeAlso + remoteauth_domain_attribute associatedDomain + remoteauth_default_realm americas.example.com + + remoteauth_mapping americas file:///home/ldap/etc/remoteauth.americas + remoteauth_mapping emea emeadc1.emea.example.com + + remoteauth_tls starttls=yes tls_reqcert=demand tls_cacert=/home/ldap/etc/example-ca.pem + remoteauth_tls_peerkey_hash ldap.americas.tld sha256:Bxv3MkLoDm6gt/iDfeGNdNNqa5TTpPDdIwvZM/cIgeo= +.fi + +Where seeAlso contains the AD bind DN for the user, associatedDomain contains the +Windows Domain Id in the form of <NT-domain-name>:<NT-username> in which +anything following, including ":", is ignored. + +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd (8). + +.SH Copyrights +Copyright 2004-2022 The OpenLDAP Foundation. +Portions Copyright 2004-2017 Howard Chu, Symas Corporation. +Portions Copyright 2017-2021 OndÅ™ej KuznÃk, Symas Corporation. +Portions Copyright 2004 Hewlett-Packard Company diff --git a/doc/man/man5/slapo-retcode.5 b/doc/man/man5/slapo-retcode.5 new file mode 100644 index 0000000..ab63801 --- /dev/null +++ b/doc/man/man5/slapo-retcode.5 @@ -0,0 +1,257 @@ +.TH SLAPO-RETCODE 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it> +.\" $OpenLDAP$ +.SH NAME +slapo\-retcode \- return code overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B retcode +overlay to +.BR slapd (8) +is useful to test the behavior of clients when server-generated erroneous +and/or unusual responses occur, e.g. error codes, referrals, +excessive response times and so on. + +The error responses are generated according to different strategies. +.LP +In the first case, all operations targeted at a specific configurable +subtree cause the object related to the request DN to be looked up +and checked for return code data: a response code, plus an optional +textual message, an optional configurable delay, an optional matched DN +field, and, when the response code is "referral", a (list of) referral(s). +.LP +Well-known response codes from standard track documents are provided +in \fBretcode.conf\fP, which can be included after instantiating +the overlay. +.LP +In the second case, objects of classes inherited from +the \fBerrAbsObject\fP, like \fBerrObject\fP or \fBerrAuxObject\fP, +when returned as intermediate responses of a search request, are changed +into the response dictated by their content. +.LP +A third mode causes objects to be looked up from the underlying database +to discover if their class inherits from \fBerrABsObject\fP; +in that case, their content is used to compute the corresponding response. +.LP +The behavior is disabled by using the \fBmanageDSAit\fP control (RFC 3296); +in that case, the resulting object, either present in the directory +or dynamically generated by the overlay, or contained in the request, +is handled as usual. +.LP +The config directives that are specific to the +.B retcode +overlay must be prefixed by +.BR retcode\- , +to avoid conflicts with directives specific to the underlying database +or to other stacked overlays. The following specific directives +can be used to configure the retcode overlay: +.TP +.B retcode\-parent <DN> +This directive defines the parent DN where dynamically generated +entries reside. +If not defined, the suffix of the database is used. +.HP +.hy 0 +.B retcode\-item <RDN> <errCode> [op=<oplist>] [text=<message>] +.B [ref=<referral>] [sleeptime=<sec>] [matched=<DN>] +.B [unsolicited=<OID>[:<data>]] [flags=[\{pre|post\}\-]disconnect[,...]] +.RS +A dynamically generated entry, located below \fBretcode\-parent\fP. +The \fBerrCode\fP is the number of the response code; +it can be in any format supported by +.BR strtol (3). +The optional \fBoplist\fP is a list of operations that cause +response code generation; if absent, all operations are affected. +The \fBmatched\fP field is the matched DN that is returned +along with the error, while the \fBtext\fP field is an optional +diagnostics message. +The \fBref\fP field is only allowed for the \fBreferral\fP +response code. +The \fBsleeptime\fP field causes +.BR slapd (8) +to sleep the specified number of seconds before proceeding +with the operation. +The \fBunsolicited\fP field can be used to cause the return +of an RFC 4511 unsolicited response message; if \fBOID\fP +is not "0", an extended response is generated, with the optional +\fBdata\fP appended. +If \fBflags\fP contains \fBdisconnect\fP, or \fBpre\-disconnect\fP, +.BR slapd (8) +disconnects abruptly, without notice; \fBpost\-disconnect\fP +causes disconnection right after sending response as appropriate. +.RE +.TP +.B retcode\-indir +Enables exploitation of in-directory stored errAbsObject. +May result in a lot of unnecessary overhead. +.TP +.B retcode\-sleep [\-]<n> +Defines a sleep time in seconds that is spent before actually handling +any operation. +If negative, a random time between 0 and the absolute value of the argument +is used. + +.SH SCHEMA +The +.B retcode +overlay utilizes the "return code" schema described herein. +This schema is specifically designed for use with this +overlay and is not intended to be used otherwise. +It is also noted that the schema described here is +.I a work in +.IR progress , +and hence subject to change without notice. +The schema is loaded automatically by the overlay. + +The schema includes a number of object classes and associated +attribute types as described below. + +.LP +The error code: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.1.1 + NAME ( 'errCode' ) + DESC 'LDAP error code' + EQUALITY integerMatch + ORDERING integerOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE +.LP +The operations that trigger the response code: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.1.2 + NAME ( 'errOp' ) + DESC 'Operations the errObject applies to' + EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) +.RE +.LP +The text message: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.1.3 + NAME ( 'errText' ) + DESC 'LDAP error textual description' + EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + SINGLE\-VALUE ) +.RE +.LP +The sleep time before the response is actually returned to the client: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.1.4 + NAME ( 'errSleepTime' ) + DESC 'Time to wait before returning the error' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE\-VALUE ) +.RE +.LP +The matched DN returned to the client: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.1.5 + NAME ( 'errMatchedDN' ) + DESC 'Value to be returned as matched DN' + EQUALITY distinguishedNameMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 + SINGLE\-VALUE ) +.RE +.LP +The OID to be returned as extended response OID +in RFC 4511 unsolicited responses +("0" generates a regular response with msgid set to 0): +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.1.6 + NAME ( 'errUnsolicitedOID' ) + DESC 'OID to be returned within unsolicited response' + EQUALITY objectIdentifierMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 + SINGLE\-VALUE ) +.RE +.LP +The octet string to be returned as extended response data +in RFC 4511 unsolicited response: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.1.7 + NAME ( 'errUnsolicitedData' ) + DESC 'Data to be returned within unsolicited response' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 + SINGLE\-VALUE ) +.RE +.LP +If TRUE, +.BR slapd (8) +disconnects abruptly without notice; if FALSE, it disconnects +after sending response as appropriate: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.1.8 + NAME ( 'errDisconnect' ) + DESC 'Disconnect without notice' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 + SINGLE\-VALUE ) +.RE +.LP +The abstract class that triggers the overlay: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.3.0 + NAME ( 'errAbsObject' ) + SUP top ABSTRACT + MUST ( errCode ) + MAY ( cn $ description $ errOp $ errText $ errSleepTime + $ errMatchedDN ) ) +.RE +.LP +The standalone structural objectclass for specifically created data: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.3.1 + NAME ( 'errObject' ) + SUP errAbsObject STRUCTURAL ) +.RE +.LP +The auxiliary objectclass to alter the behavior of existing objects: +.RS 4 +( 1.3.6.1.4.1.4203.666.11.4.3.2 + NAME ( 'errAuxObject' ) + SUP errAbsObject AUXILIARY ) +.RE + +.SH EXAMPLE +.LP +.RS +.nf +overlay retcode +retcode\-parent "ou=RetCodes,dc=example,dc=com" + +# retcode.conf is found in tests/data/ of the source tree +include ./retcode.conf + +# Wait 10 seconds, then return success (0x00) +retcode\-item "cn=Success after 10 seconds" 0x00 sleeptime=10 +# Wait 10 seconds, then return timelimitExceeded (0x03) +retcode\-item "cn=Timelimit after 10 seconds" 0x03 sleeptime=10 +.fi +.RE +.LP +.LP + +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8). +The +.BR slapo\-retcode (5) +overlay supports dynamic configuration via +.BR back-config . +.SH ACKNOWLEDGEMENTS +.P +This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c. diff --git a/doc/man/man5/slapo-rwm.5 b/doc/man/man5/slapo-rwm.5 new file mode 100644 index 0000000..69912d6 --- /dev/null +++ b/doc/man/man5/slapo-rwm.5 @@ -0,0 +1,669 @@ +.TH SLAPO-RWM 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" Copyright 2004, Pierangelo Masarati, All rights reserved. <ando@sys-net.it> +.\" $OpenLDAP$ +.\" +.\" Portions of this document should probably be moved to slapd-ldap(5) +.\" and maybe manual pages for librewrite. +.\" +.SH NAME +slapo\-rwm \- rewrite/remap overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B rwm +overlay to +.BR slapd (8) +performs basic DN/data rewrite and objectClass/attributeType mapping. +Its usage is mostly intended to provide virtual views of existing data +either remotely, in conjunction with the proxy backend described in +.BR slapd\-ldap (5), +or locally, in conjunction with the relay backend described in +.BR slapd\-relay (5). +.LP +This overlay is experimental. +.SH MAPPING +An important feature of the +.B rwm +overlay is the capability to map objectClasses and attributeTypes +from the local set (or a subset of it) to a foreign set, and vice versa. +This is accomplished by means of the +.B rwm\-map +directive. +.TP +.B rwm\-map "{attribute | objectclass} [<local name> | *] {<foreign name> | *}" +Map attributeTypes and objectClasses from the foreign server to +different values on the local slapd. +The reason is that some attributes might not be part of the local +slapd's schema, some attribute names might be different but serve the +same purpose, etc. +If local or foreign name is `*', the name is preserved. +If local name is omitted, the foreign name is removed. +Unmapped names are preserved if both local and foreign name are `*', +and removed if local name is omitted and foreign name is `*'. +.LP +The local +.I objectClasses +and +.I attributeTypes +must be defined in the local schema; the foreign ones do not have to, +but users are encouraged to explicitly define the remote attributeTypes +and the objectClasses they intend to map. All in all, when remapping +a remote server via back-ldap (\fBslapd\-ldap\fP(5)) +or back-meta (\fBslapd\-meta\fP(5)) +their definition can be easily obtained by querying the \fIsubschemaSubentry\fP +of the remote server; the problem should not exist when remapping a local +database. +Note, however, that the decision whether to rewrite or not attributeTypes +with +.IR "distinguishedName syntax" , +requires the knowledge of the attributeType syntax. +See the REWRITING section for details. +.LP +Note that when mapping DN-valued attributes from local to remote, +first the DN is rewritten, and then the attributeType is mapped; +while mapping from remote to local, first the attributeType is mapped, +and then the DN is rewritten. +As such, it is important that the local attributeType is appropriately +defined as using the distinguishedName syntax. +Also, note that there are DN-related syntaxes (i.e. compound types with +a portion that is DN-valued), like nameAndOptionalUID, +whose values are currently not rewritten. +.LP +If the foreign type of an attribute mapping is not defined on the local +server, it might be desirable to have the attribute values normalized after +the mapping process. Not normalizing the values can lead to wrong results, +when the +.B rwm +overlay is used together with e.g. the +.B pcache +overlay. This normalization can be enabled by means of the +.B rwm\-normalize\-mapped\-attrs +directive. +.TP +.B rwm\-normalize\-mapped\-attrs {yes|no} +Set this to "yes", if the +.B rwm +overlay should try to normalize the values of attributes that are mapped from +an attribute type that is unknown to the local server. The default value of +this setting is "no". +.TP +.B rwm-drop-unrequested-attrs {yes|no} +Set this to "yes", if the +.B rwm +overlay should drop attributes that are not explicitly requested +by a search operation. +When this is set to "no", the +.B rwm +overlay will leave all attributes in place, so that subsequent modules +can further manipulate them. +In any case, unrequested attributes will be omitted from search results +by the frontend, when the search entry response package is encoded. +The default value of this setting is "yes". +.SH SUFFIX MASSAGING +A basic feature of the +.B rwm +overlay is the capability to perform suffix massaging between a virtual +and a real naming context by means of the +.B rwm\-suffixmassage +directive. +This, in conjunction with proxy backends, +.BR slapd\-ldap (5) +and +.BR slapd\-meta (5), +or with the relay backend, +.BR slapd\-relay (5), +allows one to create virtual views of databases. +A distinguishing feature of this overlay is that, when instantiated +before any database, it can modify the DN of requests +.I before +database selection. +For this reason, rules that rewrite the empty DN ("") +or the subschemaSubentry DN (usually "cn=subschema"), +would prevent clients from reading the root DSE or the DSA's schema. +.TP +.B rwm\-suffixmassage "[<virtual naming context>]" "<real naming context>" +Shortcut to implement naming context rewriting; the trailing part +of the DN is rewritten from the virtual to the real naming context +in the bindDN, searchDN, searchFilterAttrDN, compareDN, compareAttrDN, +addDN, addAttrDN, modifyDN, modifyAttrDN, modrDN, newSuperiorDN, +deleteDN, exopPasswdDN, and from the real to the virtual naming context +in the searchEntryDN, searchAttrDN and matchedDN rewrite contexts. +By default no rewriting occurs for the searchFilter +and for the referralAttrDN and referralDN rewrite contexts. +If no \fI<virtual naming context>\fP is given, the first suffix of the +database is used; this requires the +.B rwm\-suffixmassage +directive be defined \fIafter\fP the database +.B suffix +directive. +The +.B rwm\-suffixmassage +directive automatically sets the +.B rwm\-rewriteEngine +to +.BR ON . +.LP +See the REWRITING section for details. +.SH REWRITING +A string is rewritten according to a set of rules, called a `rewrite +context'. +The rules are based on POSIX (''extended'') regular expressions with +substring matching; basic variable substitution and map resolution +of substrings is allowed by specific mechanisms detailed in the following. +The behavior of pattern matching/substitution can be altered by a set +of flags. +.LP +.RS +.nf +<rewrite context> ::= <rewrite rule> [...] +<rewrite rule> ::= <pattern> <action> [<flags>] +.fi +.RE +.LP +The underlying concept is to build a lightweight rewrite module +for the slapd server (initially dedicated to the LDAP backend): +.LP +.SH Passes +An incoming string is matched against a set of +.IR rewriteRules . +Rules are made of a +.IR "regex match pattern" , +a +.I "substitution pattern" +and a set of actions, described by a set of +.IR "optional flags" . +In case of match, string rewriting is performed according to the +substitution pattern that allows one to refer to substrings matched in the +incoming string. +The actions, if any, are finally performed. +Each rule is executed recursively, unless altered by specific action +flags; see "Action Flags" for details. +A default limit on the recursion level is set, and can be altered +by the +.B rwm\-rewriteMaxPasses +directive, as detailed in the "Additional Configuration Syntax" section. +The substitution pattern allows map resolution of substrings. +A map is a generic object that maps a substitution pattern to a value. +The flags are divided in "Pattern Matching Flags" and "Action Flags"; +the former alter the regex match pattern behavior, while the latter +alter the actions that are taken after substitution. +.SH "Pattern Matching Flags" +.TP +.B `C' +honors case in matching (default is case insensitive) +.TP +.B `R' +use POSIX ''basic'' regular expressions (default is ''extended'') +.TP +.B `M{n}' +allow no more than +.B n +recursive passes for a specific rule; does not alter the max total count +of passes, so it can only enforce a stricter limit for a specific rule. +.SH "Action Flags" +.TP +.B `:' +apply the rule once only (default is recursive) +.TP +.B `@' +stop applying rules in case of match; the current rule is still applied +recursively; combine with `:' to apply the current rule only once +and then stop. +.TP +.B `#' +stop current operation if the rule matches, and issue an `unwilling to +perform' error. +.TP +.B `G{n}' +jump +.B n +rules back and forth (watch for loops!). +Note that `G{1}' is implicit in every rule. +.TP +.B `I' +ignores errors in rule; this means, in case of error, e.g. issued by a +map, the error is treated as a missed match. +The `unwilling to perform' is not overridden. +.TP +.B `U{n}' +uses +.B +n +as return code if the rule matches; the flag does not alter the recursive +behavior of the rule, so, to have it performed only once, it must be used +in combination with `:', e.g. +.B `:U{32}' +returns the value `32' (indicating noSuchObject) after exactly +one execution of the rule, if the pattern matches. +As a consequence, its behavior is equivalent to `@', with the return +code set to +.BR n ; +or, in other words, `@' is equivalent to `U{0}'. +Positive errors are allowed, indicating the related LDAP error codes +as specified in \fIdraft-ietf-ldapbis-protocol\fP. +.LP +The ordering of the flags can be significant. +For instance: `IG{2}' means ignore errors and jump two lines ahead +both in case of match and in case of error, while `G{2}I' means ignore +errors, but jump two lines ahead only in case of match. +.LP +More flags (mainly Action Flags) will be added as needed. +.SH "Pattern Matching" +See +.BR regex (7) +and/or +.BR re_format (7). +.SH "Substitution Pattern Syntax" +Everything starting with `$' requires substitution; +.LP +the only obvious exception is `$$', which is turned into a single `$'; +.LP +the basic substitution is `$<d>', where `<d>' is a digit; +0 means the whole string, while 1-9 is a submatch, as discussed in +.BR regex (7) +and/or +.BR re_format (7). +.LP +a `$' followed by a `{' invokes an advanced substitution. +The pattern is: +.LP +.RS +`$' `{' [ <operator> ] <name> `(' <substitution> `)' `}' +.RE +.LP +where <name> must be a legal name for the map, i.e. +.LP +.RS +.nf +<name> ::= [a-z][a-z0-9]* (case insensitive) +<operator> ::= `>' `|' `&' `&&' `*' `**' `$' +.fi +.RE +.LP +and <substitution> must be a legal substitution +pattern, with no limits on the nesting level. +.LP +The operators are: +.TP +.B > +sub-context invocation; <name> must be a legal, already defined +rewrite context name +.TP +.B | +external command invocation; <name> must refer to a legal, already +defined command name (NOT IMPLEMENTED YET) +.TP +.B & +variable assignment; <name> defines a variable in the running +operation structure which can be dereferenced later; operator +.B & +assigns a variable in the rewrite context scope; operator +.B && +assigns a variable that scopes the entire session, e.g. its value +can be dereferenced later by other rewrite contexts +.TP +.B * +variable dereferencing; <name> must refer to a variable that is +defined and assigned for the running operation; operator +.B * +dereferences a variable scoping the rewrite context; operator +.B ** +dereferences a variable scoping the whole session, e.g. the value +is passed across rewrite contexts +.TP +.B $ +parameter dereferencing; <name> must refer to an existing parameter; +the idea is to make some run-time parameters set by the system +available to the rewrite engine, as the client host name, the bind DN +if any, constant parameters initialized at config time, and so on; +no parameter is currently set by either +.B back\-ldap +or +.BR back\-meta , +but constant parameters can be defined in the configuration file +by using the +.B rewriteParam +directive. +.LP +Substitution escaping has been delegated to the `$' symbol, +which is used instead of `\e' in string substitution patterns +because `\e' is already escaped by slapd's low level parsing routines; +as a consequence, regex escaping requires +two `\e' symbols, e.g. `\fB.*\e.foo\e.bar\fP' must +be written as `\fB.*\e\e.foo\e\e.bar\fP'. +.\" +.\" The symbol can be altered at will by redefining the related macro in +.\" "rewrite-int.h". +.\" +.SH "Rewrite Context" +A rewrite context is a set of rules which are applied in sequence. +The basic idea is to have an application initialize a rewrite +engine (think of Apache's mod_rewrite ...) with a set of rewrite +contexts; when string rewriting is required, one invokes the +appropriate rewrite context with the input string and obtains the +newly rewritten one if no errors occur. +.LP +Each basic server operation is associated to a rewrite context; +they are divided in two main groups: client \-> server and +server \-> client rewriting. +.LP +client \-> server: +.LP +.RS +.nf +(default) if defined and no specific context + is available +bindDN bind +searchDN search +searchFilter search +searchFilterAttrDN search +compareDN compare +compareAttrDN compare AVA +addDN add +addAttrDN add AVA (DN portion of "ref" excluded) +modifyDN modify +modifyAttrDN modify AVA (DN portion of "ref" excluded) +referralAttrDN add/modify DN portion of referrals + (default to none) +renameDN modrdn (the old DN) +newSuperiorDN modrdn (the new parent DN, if any) +newRDN modrdn (the new relative DN) +deleteDN delete +exopPasswdDN password modify extended operation DN +.fi +.RE +.LP +server \-> client: +.LP +.RS +.nf +searchEntryDN search (only if defined; no default; + acts on DN of search entries) +searchAttrDN search AVA (only if defined; defaults + to searchEntryDN; acts on DN-syntax + attributes of search results) +matchedDN all ops (only if applicable; defaults + to searchEntryDN) +referralDN all ops (only if applicable; defaults + to none) +.fi +.RE +.LP +.SH "Basic Configuration Syntax" +All rewrite/remap directives start with the prefix +.BR rwm\- +.TP +.B rwm\-rewriteEngine { on | off } +If `on', the requested rewriting is performed; if `off', no +rewriting takes place (an easy way to stop rewriting without +altering too much the configuration file). +.TP +.B rwm\-rewriteContext <context name> "[ alias <aliased context name> ]" +<Context name> is the name that identifies the context, i.e. the name +used by the application to refer to the set of rules it contains. +It is used also to reference sub contexts in string rewriting. +A context may alias another one. +In this case the alias context contains no rule, and any reference to +it will result in accessing the aliased one. +.TP +.B rwm\-rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]" +Determines how a string can be rewritten if a pattern is matched. +Examples are reported below. +.SH "Additional Configuration Syntax" +.TP +.B rwm\-rewriteMap "<map type>" "<map name>" "[ <map attrs> ]" +Allows one to define a map that transforms substring rewriting into +something else. +The map is referenced inside the substitution pattern of a rule. +.TP +.B rwm\-rewriteParam <param name> <param value> +Sets a value with global scope, that can be dereferenced by the +command `${$paramName}'. +.TP +.B rwm\-rewriteMaxPasses <number of passes> [<number of passes per rule>] +Sets the maximum number of total rewriting passes that can be +performed in a single rewrite operation (to avoid loops). +A safe default is set to 100; note that reaching this limit is still +treated as a success; recursive invocation of rules is simply +interrupted. +The count applies to the rewriting operation as a whole, not +to any single rule; an optional per-rule limit can be set. +This limit is overridden by setting specific per-rule limits +with the `M{n}' flag. + +.SH "MAPS" +Currently, few maps are builtin but additional map types may be +registered at runtime. + +Supported maps are: +.TP +.B LDAP <URI> [bindwhen=<when>] [version=<version>] [binddn=<DN>] [credentials=<cred>] +The +.B LDAP +map expands a value by performing a simple LDAP search. +Its configuration is based on a mandatory URI, whose +.B attrs +portion must contain exactly one attribute +(use +.B entryDN +to fetch the DN of an entry). +If a multi-valued attribute is used, only the first value is considered. + +The parameter +.B bindwhen +determines when the connection is established. +It can take the values +.BR now , +.BR later , +and +.BR everytime , +respectively indicating that the connection should be created at startup, +when required, or any time it is used. +In the former two cases, the connection is cached, while in the latter +a fresh new one is used all times. This is the default. + +The parameters +.B binddn +and +.B credentials +represent the DN and the password that is used to perform an authenticated +simple bind before performing the search operation; if not given, +an anonymous connection is used. + +The parameter +.B version +can be 2 or 3 to indicate the protocol version that must be used. +The default is 3. + +.TP +.B slapd <URI> +The +.B slapd +map expands a value by performing an internal LDAP search. +Its configuration is based on a mandatory URI, which must begin with +.B "ldap:///" +(i.e., it must be an LDAP URI and it must not specify a host). +As with the +LDAP map, the +.B attrs +portion must contain exactly one attribute, and if +a multi-valued attribute is used, only the first value is considered. + +.SH "REWRITE CONFIGURATION EXAMPLES" +.nf +# set to `off' to disable rewriting +rwm\-rewriteEngine on + +# the rules the "suffixmassage" directive implies +rwm\-rewriteEngine on +# all dataflow from client to server referring to DNs +rwm\-rewriteContext default +rwm\-rewriteRule "(.+,)?<virtualnamingcontext>$" "$1<realnamingcontext>" ":" +# empty filter rule +rwm\-rewriteContext searchFilter +# all dataflow from server to client +rwm\-rewriteContext searchEntryDN +rwm\-rewriteRule "(.+,)?<realnamingcontext>$" "$1<virtualnamingcontext>" ":" +rwm\-rewriteContext searchAttrDN alias searchEntryDN +rwm\-rewriteContext matchedDN alias searchEntryDN +# misc empty rules +rwm\-rewriteContext referralAttrDN +rwm\-rewriteContext referralDN + +# Everything defined here goes into the `default' context. +# This rule changes the naming context of anything sent +# to `dc=home,dc=net' to `dc=OpenLDAP, dc=org' + +rwm\-rewriteRule "(.+,)?dc=home,[ ]?dc=net$" + "$1dc=OpenLDAP, dc=org" ":" + +# since a pretty/normalized DN does not include spaces +# after rdn separators, e.g. `,', this rule suffices: + +rwm\-rewriteRule "(.+,)?dc=home,dc=net$" + "$1dc=OpenLDAP,dc=org" ":" + +# Start a new context (ends input of the previous one). +# This rule adds blanks between DN parts if not present. +rwm\-rewriteContext addBlanks +rwm\-rewriteRule "(.*),([^ ].*)" "$1, $2" + +# This one eats blanks +rwm\-rewriteContext eatBlanks +rwm\-rewriteRule "(.*), (.*)" "$1,$2" + +# Here control goes back to the default rewrite +# context; rules are appended to the existing ones. +# anything that gets here is piped into rule `addBlanks' +rwm\-rewriteContext default +rwm\-rewriteRule ".*" "${>addBlanks($0)}" ":" + +.\" # Anything with `uid=username' is looked up in +.\" # /etc/passwd for gecos (I know it's nearly useless, +.\" # but it is there just as a guideline to implementing +.\" # custom maps). +.\" # Note the `I' flag that leaves `uid=username' in place +.\" # if `username' does not have a valid account, and the +.\" # `:' that forces the rule to be processed exactly once. +.\" rwm\-rewriteContext uid2Gecos +.\" rwm\-rewriteRule "(.*)uid=([a\-z0\-9]+),(.+)" +.\" "$1cn=$2{xpasswd},$3" "I:" +.\" +.\" # Finally, in a bind, if one uses a `uid=username' DN, +.\" # it is rewritten in `cn=name surname' if possible. +.\" rwm\-rewriteContext bindDN +.\" rwm\-rewriteRule ".*" "${>addBlanks(${>uid2Gecos($0)})}" ":" +.\" +# Rewrite the search base according to `default' rules. +rwm\-rewriteContext searchDN alias default + +# Search results with OpenLDAP DN are rewritten back with +# `dc=home,dc=net' naming context, with spaces eaten. +rwm\-rewriteContext searchEntryDN +rwm\-rewriteRule "(.*[^ ],)?[ ]?dc=OpenLDAP,[ ]?dc=org$" + "${>eatBlanks($1)}dc=home,dc=net" ":" + +# Bind with email instead of full DN: we first need +# an ldap map that turns attributes into a DN (the +# argument used when invoking the map is appended to +# the URI and acts as the filter portion) +rwm\-rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub" + +# Then we need to detect DN made up of a single email, +# e.g. `mail=someone@example.com'; note that the rule +# in case of match stops rewriting; in case of error, +# it is ignored. In case we are mapping virtual +# to real naming contexts, we also need to rewrite +# regular DNs, because the definition of a bindDN +# rewrite context overrides the default definition. +rwm\-rewriteContext bindDN +rwm\-rewriteRule "^mail=[^,]+@[^,]+$" "${attr2dn($0)}" ":@I" + +# This is a rather sophisticated example. It massages a +# search filter in case who performs the search has +# administrative privileges. First we need to keep +# track of the bind DN of the incoming request, which is +# stored in a variable called `binddn' with session scope, +# and left in place to allow regular binding: +rwm\-rewriteContext bindDN +rwm\-rewriteRule ".+" "${&&binddn($0)}$0" ":" + +# A search filter containing `uid=' is rewritten only +# if an appropriate DN is bound. +# To do this, in the first rule the bound DN is +# dereferenced, while the filter is decomposed in a +# prefix, in the value of the `uid=<arg>' AVA, and +# in a suffix. A tag `<>' is appended to the DN. +# If the DN refers to an entry in the `ou=admin' subtree, +# the filter is rewritten OR-ing the `uid=<arg>' with +# `cn=<arg>'; otherwise it is left as is. This could be +# useful, for instance, to allow apache's auth_ldap-1.4 +# module to authenticate users with both `uid' and +# `cn', but only if the request comes from a possible +# `cn=Web auth,ou=admin,dc=home,dc=net' user. +rwm\-rewriteContext searchFilter +rwm\-rewriteRule "(.*\e\e()uid=([a\-z0\-9_]+)(\e\e).*)" + "${**binddn}<>${&prefix($1)}${&arg($2)}${&suffix($3)}" + ":I" +rwm\-rewriteRule "^[^,]+,ou=admin,dc=home,dc=net$" + "${*prefix}|(uid=${*arg})(cn=${*arg})${*suffix}" ":@I" +rwm\-rewriteRule ".*<>$" "${*prefix}uid=${*arg}${*suffix}" ":" + +# This example shows how to strip unwanted DN-valued +# attribute values from a search result; the first rule +# matches DN values below "ou=People,dc=example,dc=com"; +# in case of match the rewriting exits successfully. +# The second rule matches everything else and causes +# the value to be rejected. +rwm\-rewriteContext searchEntryDN +rwm\-rewriteRule ".+,ou=People,dc=example,dc=com$" "$0" ":@" +rwm\-rewriteRule ".*" "" "#" +.fi +.SH "MAPPING EXAMPLES" +The following directives map the object class `groupOfNames' to +the object class `groupOfUniqueNames' and the attribute type +`member' to the attribute type `uniqueMember': +.LP +.RS +.nf +map objectclass groupOfNames groupOfUniqueNames +map attribute uniqueMember member +.fi +.RE +.LP +This presents a limited attribute set from the foreign +server: +.LP +.RS +.nf +map attribute cn * +map attribute sn * +map attribute manager * +map attribute description * +map attribute * +.fi +.RE +.LP +These lines map cn, sn, manager, and description to themselves, and +any other attribute gets "removed" from the object before it is sent +to the client (or sent up to the LDAP server). This is obviously a +simplistic example, but you get the point. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd\-ldap (5), +.BR slapd\-meta (5), +.BR slapd\-relay (5), +.BR slapd (8), +.BR regex (7), +.BR re_format (7). +.SH AUTHOR +Pierangelo Masarati; based on back-ldap rewrite/remap features +by Howard Chu, Pierangelo Masarati. diff --git a/doc/man/man5/slapo-sssvlv.5 b/doc/man/man5/slapo-sssvlv.5 new file mode 100644 index 0000000..42a39a7 --- /dev/null +++ b/doc/man/man5/slapo-sssvlv.5 @@ -0,0 +1,57 @@ +.TH SLAPO-SSSVLV 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2009-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copyright 2009 Symas Corporation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-sssvlv \- Server Side Sorting and Virtual List View overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +This overlay implements the LDAP Server Side Sorting (RFC2891) control +as well as the Virtual List View control. It also replaces the default +implementation of the LDAP PagedResults (RFC2696) control, to ensure +that it works with Sorting. The overlay can be used with any backend +or globally for all backends. + +Since a complete result set must be generated in memory before sorting can +be performed, processing sort requests can have a large impact on the +server's memory use. As such, any connection is limited to having only +a limited number of sort requests active at a time. Additional limits may +be configured as described below. + +.SH CONFIGURATION +These +.B slapd.conf +options apply to the SSSVLV overlay. +They should appear after the +.B overlay +directive. +.TP +.B sssvlv\-max <num> +Set the maximum number of concurrent sort requests allowed across all +connections. The default is one half of the number of server threads. +.TP +.B sssvlv\-maxkeys <num> +Set the maximum number of keys allowed in a sort request. The default is 5. +.TP +.B sssvlv\-maxperconn <num> +Set the maximum number of concurrent paged search requests per connection. The default is 5. The number of concurrent requests remains limited by +.B sssvlv-max. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.TP +ETCDIR/slapd.d +default slapd configuration directory +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.LP +IETF LDAP Virtual List View proposal by D. Boreham, J. Sermersheim, +and A. Kashi in IETF document "draft-ietf-ldapext-ldapv3-vlv-09.txt". +.SH AUTHOR +Howard Chu diff --git a/doc/man/man5/slapo-syncprov.5 b/doc/man/man5/slapo-syncprov.5 new file mode 100644 index 0000000..3c6e6b8 --- /dev/null +++ b/doc/man/man5/slapo-syncprov.5 @@ -0,0 +1,81 @@ +.TH SLAPO-SYNCPROV 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-syncprov \- Sync Provider overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Sync Provider overlay implements the provider-side support for the +LDAP Content Synchronization (RFC4533) as well as syncrepl replication +support. The overlay +can be used with any backend that maintains entryCSN and entryUUID +attributes for its entries. It also creates a contextCSN attribute in +the root entry of the database. + +The contextCSN is updated for every write operation performed against the +database. To reduce database contention, the contextCSN is only updated in +memory. The value is written to the database on server shutdown and read into +memory on startup, and maintained in memory thereafter. Checkpoints may be +configured to write the contextCSN into the underlying database to minimize +recovery time after an unclean shutdown. + +On databases that support inequality indexing, it is highly recommended to set an +eq index on the entryCSN attribute when using this overlay. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the Sync Provider overlay. +They should appear after the +.B overlay +directive. +.TP +.B syncprov\-checkpoint <ops> <minutes> +After a write operation has succeeded, write the contextCSN to the underlying +database if +.B <ops> +write operations or more than +.B <minutes> +time have passed +since the last checkpoint. Checkpointing is disabled by default. +.TP +.B syncprov\-sessionlog <ops> +Configures an in-memory session log for recording information about write +operations made on the database. The +.B <ops> +specifies the number of operations that are recorded in the log. All write +operations (except Adds) are recorded in the log. +When using the session log, it is helpful to set an eq index on the +entryUUID attribute in the underlying database. +.TP +.B syncprov\-sessionlog\-source <dn> +Should not be set when syncprov-sessionlog is set and vice versa. + +When accesslog for this database is configured and is logging at this suffix, +it can be used as the session log source instead of the in-memory session log +mentioned above. This log has the advantage of not starting afresh every time +the server is restarted. +.TP +.B syncprov\-nopresent TRUE | FALSE +Specify that the Present phase of refreshing should be skipped. This value +should only be set TRUE for a syncprov instance on top of a log database +(such as one managed by the accesslog overlay). +The default is FALSE. +.TP +.B syncprov\-reloadhint TRUE | FALSE +Specify that the overlay should honor the reloadHint flag in the Sync +Control. It must be set TRUE when using the accesslog overlay for +delta-based syncrepl replication support. +The default is FALSE. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapo\-accesslog (5). +OpenLDAP Administrator's Guide. +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapo-translucent.5 b/doc/man/man5/slapo-translucent.5 new file mode 100644 index 0000000..f7dadf2 --- /dev/null +++ b/doc/man/man5/slapo-translucent.5 @@ -0,0 +1,133 @@ +.TH SLAPO-TRANSLUCENT 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-translucent \- Translucent Proxy overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Translucent Proxy overlay can be used with a backend database such as +.BR slapd\-mdb (5) +to create a "translucent proxy". Entries retrieved from a remote LDAP +server may have some or all attributes overridden, or new attributes +added, by entries in the local database before being presented to the +client. +.LP +A +.BR search +operation is first populated with entries from the remote LDAP server, the +attributes of which are then overridden with any attributes defined in the +local database. Local overrides may be populated with the +.BR add , +.B modify , +and +.B modrdn +operations, the use of which is restricted to the root user. +.LP +A +.BR compare +operation will perform a comparison with attributes defined in the local +database record (if any) before any comparison is made with data in the +remote database. +.SH CONFIGURATION +The Translucent Proxy overlay uses a proxied database, +typically a (set of) remote LDAP server(s), which is configured with the options shown in +.BR slapd\-ldap (5), +.BR slapd\-meta (5) +or similar. +These +.B slapd.conf +options are specific to the Translucent Proxy overlay; they must appear +after the +.B overlay +directive that instantiates the +.B translucent +overlay. +.TP +.B translucent_strict +By default, attempts to delete attributes in either the local or remote +databases will be silently ignored. The +.B translucent_strict +directive causes these modifications to fail with a Constraint Violation. +.TP +.B translucent_no_glue +This configuration option disables the automatic creation of "glue" records +for an +.B add +or +.B modrdn +operation, such that all parents of an entry added to the local database +must be created by hand. Glue records are always created for a +.B modify +operation. +.TP +.B translucent_local <attr[,attr...]> +Specify a list of attributes that should be searched for in the local database +when used in a search filter. By default, search filters are only handled by +the remote database. With this directive, search filters will be split into a +local and remote portion, and local attributes will be searched locally. +.TP +.B translucent_remote <attr[,attr...]> +Specify a list of attributes that should be searched for in the remote database +when used in a search filter. This directive complements the +.B translucent_local +directive. Attributes may be specified as both local and remote if desired. +.LP +If neither +.B translucent_local +nor +.B translucent_remote +are specified, the default behavior is to search the remote database with the +complete search filter. If only +.B translucent_local +is specified, searches will only be run on the local database. Likewise, if only +.B translucent_remote +is specified, searches will only be run on the remote database. In any case, both +the local and remote entries corresponding to a search result will be merged +before being returned to the client. + +.TP +.B translucent_bind_local +Enable looking for locally stored credentials for simple bind when binding +to the remote database fails. Disabled by default. + +.TP +.B translucent_pwmod_local +Enable RFC 3062 Password Modification extended operation on locally stored +credentials. The operation only applies to entries that exist in the remote +database. Disabled by default. + +.SH ACCESS CONTROL +Access control is delegated to either the remote DSA(s) or to the local database +backend for +.B auth +and +.B write +operations. +It is delegated to the remote DSA(s) and to the frontend for +.B read +operations. +Local access rules involving data returned by the remote DSA(s) should be designed +with care. In fact, entries are returned by the remote DSA(s) only based on the +remote fraction of the data, based on the identity the operation is performed as. +As a consequence, local rules might only be allowed to see a portion +of the remote data. + +.SH CAVEATS +.LP +The Translucent Proxy overlay will disable schema checking in the local database, +so that an entry consisting of overlay attributes need not adhere to the +complete schema. +.LP +Because the translucent overlay does not perform any DN rewrites, the local +and remote database instances must have the same suffix. Other configurations +will probably fail with No Such Object and other errors. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd\-ldap (5). diff --git a/doc/man/man5/slapo-unique.5 b/doc/man/man5/slapo-unique.5 new file mode 100644 index 0000000..720c35a --- /dev/null +++ b/doc/man/man5/slapo-unique.5 @@ -0,0 +1,187 @@ +.TH SLAPO-UNIQUE 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-unique \- Attribute Uniqueness overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Attribute Uniqueness overlay can be used with a backend database such as +.BR slapd\-mdb (5) +to enforce the uniqueness of some or all attributes within a +scope. This subtree defaults to all objects within the subtree of the +database for which the Uniqueness overlay is configured. +.LP +Uniqueness is enforced by searching the subtree to ensure that the values of +all attributes presented with an +.BR add , +.B modify +or +.B modrdn +operation are unique within the scope. +For example, if uniqueness were enforced for the +.B uid +attribute, the subtree would be searched for any other records which also +have a +.B uid +attribute containing the same value. If any are found, the request is +rejected. +.LP +The search is performed using the rootdn of the database, to avoid issues +with ACLs preventing the overlay from seeing all of the relevant data. As +such, the database must have a rootdn configured. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the Attribute Uniqueness overlay. +They should appear after the +.B overlay +directive. +.TP +.B unique_uri <[strict ][ignore ][serialize ]URI[[ URI...]...]> +Configure the base, attributes, scope, and filter for uniqueness +checking. Multiple URIs may be specified within a domain, +allowing complex selections of objects. Multiple +.B unique_uri +statements or +.B olcUniqueURI +attribute values will create independent domains, each with their own +independent lists of URIs and ignore/strict settings. + +Keywords +.BR strict , +.BR ignore , +and +.B serialize +have to be enclosed in quotes (") together with the URI. + +The LDAP URI syntax is a subset of +.B RFC-4516, +and takes the form: + +ldap:///[base dn]?[attributes...]?scope[?filter] + +The +.B base dn +defaults to that of the back-end database. +Specified base dns must be within the subtree of the back-end database. + +If no +.B attributes +are specified, the URI applies to all non-operational attributes. + +The +.B scope +component is effectively mandatory, because LDAP URIs default to +.B base +scope, which is not valid for uniqueness, because groups of one object +are always unique. Scopes of +.B sub +(for subtree) and +.B one +for one-level are valid. + +The +.B filter +component causes the domain to apply uniqueness constraints only to +matching objects. e.g. +.B ldap:///?cn?sub?(sn=e*) +would require unique +.B cn +attributes for all objects in the subtree of the back-end database whose +.B sn +starts with an e. + +It is possible to assert uniqueness upon all non-operational +attributes except those listed by prepending the keyword +.B ignore +If not configured, all non-operational (e.g., system) attributes must be +unique. Note that the +.B attributes +list of an +.B ignore +URI should generally contain the +.BR objectClass , +.BR dc , +.B ou +and +.B o +attributes, as these will generally not be unique, nor are they operational +attributes. + +It is possible to set strict checking for the uniqueness domain by +prepending the keyword +.B strict. +By default, uniqueness is not enforced +for null values. Enabling +.B strict +mode extends the concept of uniqueness to include null values, such +that only one attribute within a subtree will be allowed to have a +null value. Strictness applies to all URIs within a uniqueness +domain, but some domains may be strict while others are not. + +It is possible to enforce strict serialization of modifications by +prepending the keyword +.B serialize. +By default, no serialization is performed, so multiple modifications +occurring nearly simultaneously may see incomplete uniqueness results. +Using +.B serialize +will force individual write operations to fully complete before allowing +any others to proceed, to ensure that each operation's uniqueness checks +are consistent. +.LP +It is not possible to set both URIs and legacy slapo\-unique configuration +parameters simultaneously. In general, the legacy configuration options +control pieces of a single unfiltered subtree domain. +.TP +.B unique_base <basedn> +This legacy configuration parameter should be converted to the +.B base dn +component of the above +.B unique_uri +style of parameter. +.TP +.B unique_ignore <attribute...> +This legacy configuration parameter should be converted to a +.B unique_uri +parameter with +.B ignore +keyword as described above. +.TP +.B unique_attributes <attribute...> +This legacy configuration parameter should be converted to a +.B unique_uri +parameter, as described above. +.TP +.B unique_strict <attribute...> +This legacy configuration parameter should be converted to a +.B strict +keyword prepended to a +.B unique_uri +parameter, as described above. +.SH CAVEATS +.LP +.B unique_uri +cannot be used with the old-style of configuration, and vice versa. +.B unique_uri +can implement everything the older system can do, however. +.LP +Typical attributes for the +.B ignore ldap:///... +URIs are intentionally not hardcoded into the overlay to allow for +maximum flexibility in meeting site-specific requirements. +.LP +Replication and operations with the +.B relax +control are allowed to bypass this enforcement. It is therefore important that +all servers accepting writes have this overlay configured in order to maintain +uniqueness in a replicated DIT. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5). diff --git a/doc/man/man5/slapo-valsort.5 b/doc/man/man5/slapo-valsort.5 new file mode 100644 index 0000000..97f8db4 --- /dev/null +++ b/doc/man/man5/slapo-valsort.5 @@ -0,0 +1,97 @@ +.TH SLAPO-VALSORT 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2005-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapo\-valsort \- Value Sorting overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Value Sorting overlay can be used with a backend database to sort the +values of specific multi-valued attributes within a subtree. The sorting +occurs whenever the attributes are returned in a search response. +.LP +Sorting can be specified in ascending or descending order, using either +numeric or alphanumeric sort methods. Additionally, a "weighted" sort can +be specified, which uses a numeric weight prepended to the attribute values. +The weighted sort is always performed in ascending order, but may be combined +with the other methods for values that all have equal weights. The weight +is specified by prepending an integer weight {<\fIweight\fP>} +in front of each value of the attribute for which weighted sorting is +desired. This weighting factor is stripped off and not returned in search +results unless the valsort control is specified (1.3.6.1.4.1.4203.666.5.14). + +The valsort control requires a value consisting of a Sequence that contains +a boolean flag. The weighting factor is only returned if the boolean value is TRUE. In +.BR lber-encode (3) +format, the required value must conform to "{b}" syntax. + +.SH CONFIGURATION +These +.I slapd.conf +options apply to the Value Sorting overlay. +They should appear after the +.B overlay +directive. +.TP +valsort\-attr <\fIattribute\fP> <\fIbaseDN\fP> (<\fIsort-method\fP> | weighted [<\fIsort-method\fP>]) +Configure a sorting method for the specified +.I attribute +in the subtree rooted at +.IR baseDN . +The +.I sort-method +may be one of +.BR alpha\-ascend , +.BR alpha\-descend , +.BR numeric\-ascend , +or +.BR numeric\-descend . +If the special +.B weighted +method is specified, a secondary +.I sort-method +may also be specified. It is an +error to specify an alphanumeric +.I sort-method +for an attribute with Integer +or NumericString syntax, and it is an error to specify a numeric +.I sort-method +for an attribute with a syntax other than Integer or NumericString. +.SH EXAMPLES +.LP +.nf + database mdb + suffix dc=example,dc=com + ... + overlay valsort + valsort\-attr member ou=groups,dc=example,dc=com alpha\-ascend +.fi + +To invoke +.BR ldapsearch (1) +with the valsort control, the control value must be set appropriately. +The following octets represent the desired "{b}" encoding: +.LP +.nf + 0x30 0x03 0x01 0x01 0xff +.fi + +The control can be sent from the command-line using the base64 +encoding of the value: +.LP +.nf + ldapsearch \-E 1.3.6.1.4.1.4203.666.5.14=::MAMBAf8= +.fi + +.SH FILES +.TP +\fIETCDIR/slapd.conf\fP +default \fBslapd\fP configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5). +.SH ACKNOWLEDGEMENTS +.P +This module was written in 2005 by Howard Chu of Symas Corporation. The +work was sponsored by Stanford University. diff --git a/doc/man/man5/slappw-argon2.5 b/doc/man/man5/slappw-argon2.5 new file mode 100644 index 0000000..eaeab2b --- /dev/null +++ b/doc/man/man5/slappw-argon2.5 @@ -0,0 +1,131 @@ +.TH SLAPPW-ARGON2 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2020-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slappw\-argon2 \- Argon2 password module to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.RS +.LP +.B moduleload argon2 +.RI [ <parameters> ] +.RE +.SH DESCRIPTION +.LP +The +.B argon2 +module to +.BR slapd (8) +provides support for the use of the key derivation function Argon2, +that was selected as the winner of the Password Hashing Competition in July 2015, +in hashed passwords in OpenLDAP. +.LP +It does so by providing the additional password scheme +.B {ARGON2} +for use in slapd. + +.SH CONFIGURATION +The +.B argon2 +module does not need any configuration, +but it can be configured by giving the following parameters: +.TP +.BI m= <memory> +Set memory usage to +.I <memory> +kiB. +.TP +.BI p= <parallelism> +Set parallelism to +.I <parallelism> +threads. Currently supported only when linked with +.BR libargon2 . +.TP +.BI t= <iterations> +Set the number of iterations to +.IR <iterations> . +.LP +These replace defaults when preparing hashes for new passwords where possible. +.LP +After loading the module, the password scheme +.B {ARGON2} +will be recognised in values of the +.I userPassword +attribute. +.LP +You can then instruct OpenLDAP to use this scheme when processing +the LDAPv3 Password Modify (RFC 3062) extended operations by using the +.BR password-hash +option in +.BR slapd.conf (5): +.RS +.LP +.B password\-hash {ARGON2} +.RE +.LP + +.SS NOTES +If you want to use the scheme described here with +.BR slappasswd (8), +remember to load the module using its command line options. +The relevant option/value is: +.RS +.LP +.B \-o +.BR module\-load = argon2 +.LP +.RE +Or if non-default parameters are required: +.RS +.LP +.B \-o +.BR module\-load =" argon2 +.RB [ <param> ...]" +.LP +.RE +Depending on +.BR argon2 's +location, you may also need: +.RS +.LP +.B \-o +.BR module\-path = \fIpathspec\fP +.RE + +.SH EXAMPLES +Both userPassword LDAP attributes below encode the password +.RI ' secret ' +using different salts: +.EX +.LP +userPassword: {ARGON2}$argon2i$v=19$m=4096,t=3,p=1$c2FsdHNhbHQ$DKlexoEJUoZTmkAAC3SaMWk30El9/RvVhlqGo6afIng +.LP +userPassword: {ARGON2}$argon2i$v=19$m=4096,t=3,p=1$c2FsdHNhbHRzYWx0$qOCkx9nMeFlaGOO4DUmPDgrlUbgMMuO9T1+vQCFuyzw +.EE + +.SH SEE ALSO +.BR slapd.conf (5), +.BR ldappasswd (1), +.BR slappasswd (8), +.BR ldap (3), +.LP +.UR http://www.OpenLDAP.org/doc/ +"OpenLDAP Administrator's Guide" +.UE +.LP + +.SH ACKNOWLEDGEMENTS +This manual page has been written by Peter Marschall based on the +module's README file written by +.MT simon@levermann.de +Simon Levermann +.ME . +.LP +.B OpenLDAP +is developed and maintained by +.UR http://www.openldap.org/ +The OpenLDAP Project +.UE . +.B OpenLDAP +is derived from University of Michigan LDAP 3.3 Release. |