diff options
Diffstat (limited to 'doc/man')
149 files changed, 29843 insertions, 0 deletions
diff --git a/doc/man/Makefile.in b/doc/man/Makefile.in new file mode 100644 index 0000000..f6024b3 --- /dev/null +++ b/doc/man/Makefile.in @@ -0,0 +1,16 @@ +# man 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>. + +SUBDIRS= man1 man3 man5 man8 diff --git a/doc/man/Project b/doc/man/Project new file mode 100644 index 0000000..ed7cd85 --- /dev/null +++ b/doc/man/Project @@ -0,0 +1,5 @@ +.\" Shared Project Acknowledgement Text +.B "OpenLDAP Software" +is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. +.B "OpenLDAP Software" +is derived from the University of Michigan LDAP 3.3 Release. diff --git a/doc/man/man1/Makefile.in b/doc/man/man1/Makefile.in new file mode 100644 index 0000000..c051765 --- /dev/null +++ b/doc/man/man1/Makefile.in @@ -0,0 +1,16 @@ +# man1 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=1 diff --git a/doc/man/man1/ldapcompare.1 b/doc/man/man1/ldapcompare.1 new file mode 100644 index 0000000..b15b0c4 --- /dev/null +++ b/doc/man/man1/ldapcompare.1 @@ -0,0 +1,241 @@ +.TH LDAPCOMPARE 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldapcompare \- LDAP compare tool +.SH SYNOPSIS +.B ldapcompare +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-z ] +[\c +.BR \-M [ M ]] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-P \ { 2 \||\| 3 }] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +.IR DN +{\c +.BI attr: value +| +.BI attr:: b64value\fR} +.SH DESCRIPTION +.I ldapcompare +is a shell-accessible interface to the +.BR ldap_compare_ext (3) +library call. +.LP +.B ldapcompare +opens a connection to an LDAP server, binds, and performs a compare +using specified parameters. The \fIDN\fP should be a distinguished +name in the directory. \fIAttr\fP should be a known attribute. If +followed by one colon, the assertion \fIvalue\fP should be provided +as a string. If followed by two colons, the base64 encoding of the +value is provided. The result code of the compare is provided as +the exit code and, unless ran with \fB\-z\fP, the program prints +TRUE, FALSE, or UNDEFINED on standard output. +.LP +.SH OPTIONS +.TP +.BR \-V [ V ] +Print version info. +If \fB\-VV\fP is given, only the version information is printed. +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.B ldapcompare +must be compiled with LDAP_DEBUG defined for this option to have any effect. +.TP +.B \-n +Show what would be done, but don't actually perform the compare. Useful for +debugging in conjunction with \fB\-v\fP. +.TP +.B \-v +Run in verbose mode, with many diagnostics written to standard output. +.TP +.B \-z +Run in quiet mode, no output is written. You must check the return +status. Useful in shell scripts. +.TP +.BR \-M [ M ] +Enable manage DSA IT control. +.B \-MM +makes control critical. +.TP +.B \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. +.TP +.B \-W +Prompt for simple authentication. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +Note that \fIcomplete\fP means that any leading or trailing whitespaces, +including newlines, will be considered part of the password and, +unlike other software, they will not be stripped. +As a consequence, passwords stored in files by commands like +.BR echo (1) +will not behave as expected, since +.BR echo (1) +by default appends a trailing newline to the echoed string. +The recommended portable way to store a cleartext password in a file +for use with this option is to use +.BR slappasswd (8) +with \fI{CLEARTEXT}\fP as hash and the option \fB\-n\fP. +.TP +.BI \-H \ ldapuri +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. +.TP +.BR \-P \ { 2 \||\| 3 } +Specify the LDAP protocol version to use. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and compare extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +Compare extensions: +.nf + !dontUseCopy +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.B \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.B \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username> +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. If it's not +specified, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. If you use +\fB\-ZZ\fP, the command will require the operation to be successful. +.SH EXAMPLES +.nf + ldapcompare "uid=babs,dc=example,dc=com" sn:Jensen + ldapcompare "uid=babs,dc=example,dc=com" sn::SmVuc2Vu +.fi +are all equivalent. +.SH LIMITATIONS +Requiring the value be passed on the command line is limiting +and introduces some security concerns. The command should support +a mechanism to specify the location (file name or URL) to read +the value from. +.SH "SEE ALSO" +.BR ldap.conf (5), +.BR ldif (5), +.BR ldap (3), +.BR ldap_compare_ext (3) +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldapdelete.1 b/doc/man/man1/ldapdelete.1 new file mode 100644 index 0000000..e12cc56 --- /dev/null +++ b/doc/man/man1/ldapdelete.1 @@ -0,0 +1,252 @@ +.TH LDAPDELETE 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldapdelete \- LDAP delete entry tool +.SH SYNOPSIS +.B ldapdelete +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-c ] +[\c +.BI \-f \ file\fR] +[\c +.BR \-r ] +[\c +.BI \-z \ sizelimit\fR] +[\c +.BR \-M [ M ]] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-P \ { 2 \||\| 3 }] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +[\c +.IR DN \ [ ... ]] +.SH DESCRIPTION +.I ldapdelete +is a shell-accessible interface to the +.BR ldap_delete_ext (3) +library call. +.LP +.B ldapdelete +opens a connection to an LDAP server, binds, and deletes one or more +entries. If one or more \fIDN\fP arguments are provided, entries with +those Distinguished Names are deleted. Each \fIDN\fP should be provided +using the LDAPv3 string representation as defined in RFC 4514. +If no \fIDN\fP arguments +are provided, a list of DNs is read from standard input (or from +\fIfile\fP if the \fB\-f\fP flag is used). +.SH OPTIONS +.TP +.BR \-V [ V ] +Print version info. +If \fB\-VV\fP is given, only the version information is printed. +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.B ldapdelete +must be compiled with LDAP_DEBUG defined for this option to have any effect. +.TP +.B \-n +Show what would be done, but don't actually delete entries. Useful for +debugging in conjunction with \fB\-v\fP. +.TP +.B \-v +Use verbose mode, with many diagnostics written to standard output. +.TP +.B \-c +Continuous operation mode. Errors are reported, but +.B ldapdelete +will continue with deletions. The default is to exit after +reporting an error. +.TP +.BI \-f \ file +Read a series of DNs from \fIfile\fP, one per line, performing an +LDAP delete for each. +.TP +.B \-r +Do a recursive delete. If the DN specified isn't a leaf, its +children, and all their children are deleted down the tree. No +verification is done, so if you add this switch, ldapdelete will +happily delete large portions of your tree. Use with care. +.TP +.BI \-z \ sizelimit +Use \fIsizelimit\fP when searching for children DN to delete, +to circumvent any server-side size limit. Only useful in conjunction +with \fB\-r\fP. +.TP +.BR \-M [ M ] +Enable manage DSA IT control. +.B \-MM +makes control critical. +.TP +.B \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. +.TP +.B \-W +Prompt for simple authentication. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +.TP +.BI \-H \ ldapuri +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. +.TP +.BR \-P \ { 2 \||\| 3 } +Specify the LDAP protocol version to use. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and delete extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +Delete extensions: +.nf + (none) +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.B \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.B \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the identity depends on the +actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username> +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. If it's not +specified, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. If you use +\fB\-ZZ\fP, the command will require the operation to be successful. +.SH EXAMPLE +The following command: +.LP +.nf + ldapdelete "cn=Delete Me,dc=example,dc=com" +.fi +.LP +will attempt to delete the entry named "cn=Delete Me,dc=example,dc=com". +Of course it would probably be necessary to supply authentication +credentials. +.SH DIAGNOSTICS +Exit status is 0 if no errors occur. Errors result in a non-zero exit +status and a diagnostic message being written to standard error. +.SH "SEE ALSO" +.BR ldap.conf (5), +.BR ldapadd (1), +.BR ldapmodify (1), +.BR ldapmodrdn (1), +.BR ldapsearch (1), +.BR ldap (3), +.BR ldap_delete_ext (3) +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldapexop.1 b/doc/man/man1/ldapexop.1 new file mode 100644 index 0000000..2040c3e --- /dev/null +++ b/doc/man/man1/ldapexop.1 @@ -0,0 +1,242 @@ +.\" $OpenLDAP$ +.\" This contribution is derived from OpenLDAP Software. +.\" All of the modifications to OpenLDAP Software represented in this +.\" contribution were developed by Peter Marschall <peter@adpm.de>. +.\" I have not assigned rights and/or interest in this work to any party. +.\" +.\" Copyright 2009 Peter Marschall +.\" 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 file LICENSE in the +.\" top-level directory of the distribution or, alternatively, at +.\" http://www.OpenLDAP.org/license.html. + +.TH LDAPEXOP 1 + +.SH NAME +ldapexop \- issue LDAP extended operations + +.SH SYNOPSIS +ldapexop +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BI \-f \ file\fR] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ URI\fR] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +{\c +.I oid +| +.BI oid: data +| +.BI oid:: b64data +| +.B whoami +| +.BI cancel \ cancel-id +| +.BI refresh \ DN \ \fR[\fIttl\fR]} + +.SH DESCRIPTION +ldapexop issues the LDAP extended operation specified by \fBoid\fP +or one of the special keywords \fBwhoami\fP, \fBcancel\fP, or \fBrefresh\fP. + +Additional data for the extended operation can be passed to the server using +\fIdata\fP or base-64 encoded as \fIb64data\fP in the case of \fBoid\fP, +or using the additional parameters in the case of the specially named extended +operations above. + +Please note that ldapexop behaves differently for the same extended operation +when it was given as an OID or as a specially named operation: + +Calling ldapexop with the OID of the \fBwhoami\fP (RFC 4532) extended operation +.nf + + ldapexop [<options>] 1.3.6.1.4.1.4203.1.11.3 + +.fi +yields +.nf + + # extended operation response + data:: <base64 encoded response data> + +.fi +while calling it with the keyword \fBwhoami\fP +.nf + + ldapexop [<options>] whoami + +.fi +results in +.nf + + dn:<client's identity> + +.fi + + +.SH OPTIONS +.TP +.BI \-V [ V ] +Print version info. +If\fB\-VV\fP is given, only the version information is printed. +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.TP +.BI \-n +Show what would be done but don't actually do it. +Useful for debugging in conjunction with \fB\-v\fP. +.TP +.BI \-v +Run in verbose mode, with many diagnostics written to standard output. +.TP +.BI \-f \ file +Read operations from \fIfile\fP. +.TP +.BI \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +.TP +.BI \-W +Prompt for simple authentication. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +.TP +.BI \-H \ URI +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +Specify general extensions. \'!\' indicates criticality. +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.BI \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.BI \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username> +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. +Without this option, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. +Giving it twice (\fB\-ZZ\fP) will require the operation to be successful. + +.SH DIAGNOSTICS +Exit status is zero if no errors occur. +Errors result in a non-zero exit status and +a diagnostic message being written to standard error. + +.SH "SEE ALSO" +.BR ldap_extended_operation_s (3) + +.SH AUTHOR +This manual page was written by Peter Marschall +based on \fBldapexop\fP's usage message and a few tests +with \fBldapexop\fP. +Do not expect it to be complete or absolutely correct. + +.SH ACKNOWLEDGEMENTS +.so ../Project + diff --git a/doc/man/man1/ldapmodify.1 b/doc/man/man1/ldapmodify.1 new file mode 100644 index 0000000..1104e9f --- /dev/null +++ b/doc/man/man1/ldapmodify.1 @@ -0,0 +1,390 @@ +.TH LDAPMODIFY 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldapmodify, ldapadd \- LDAP modify entry and LDAP add entry tools +.SH SYNOPSIS +.B ldapmodify +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-a ] +[\c +.BR \-c ] +[\c +.BI \-f \ file\fR] +[\c +.BI \-S \ file\fR] +[\c +.BR \-M [ M ]] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-P \ { 2 \||\| 3 }] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +.LP +.B ldapadd +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-c ] +[\c +.BI \-f \ file\fR] +[\c +.BI \-S \ file\fR] +[\c +.BR \-M [ M ]] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-P \ { 2 \||\| 3 }] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +.SH DESCRIPTION +.B ldapmodify +is a shell-accessible interface to the +.BR ldap_add_ext (3), +.BR ldap_modify_ext (3), +.BR ldap_delete_ext (3) +and +.BR ldap_rename (3). +library calls. +.B ldapadd +is implemented as a hard link to the ldapmodify tool. When invoked as +.B ldapadd +the \fB\-a\fP (add new entry) flag is turned on automatically. +.LP +.B ldapmodify +opens a connection to an LDAP server, binds, and modifies or adds entries. +The entry information is read from standard input or from \fIfile\fP through +the use of the \fB\-f\fP option. +.SH OPTIONS +.TP +.BR \-V [ V ] +Print version info. +If \fB\-VV\fP is given, only the version information is printed. +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.B ldapmodify +must be compiled with LDAP_DEBUG defined for this option to have any effect. +.TP +.B \-n +Show what would be done, but don't actually modify entries. Useful for +debugging in conjunction with \fB\-v\fP. +.TP +.B \-v +Use verbose mode, with many diagnostics written to standard output. +.TP +.B \-a +Add new entries. The default for +.B ldapmodify +is to modify existing entries. If invoked as +.BR ldapadd , +this flag is always set. +.TP +.B \-c +Continuous operation mode. Errors are reported, but +.B ldapmodify +will continue with modifications. The default is to exit after +reporting an error. +.TP +.BI \-f \ file +Read the entry modification information from \fIfile\fP instead of from +standard input. +.TP +.BI \-S \ file +Add or change records which were skipped due to an error are written to \fIfile\fP +and the error message returned by the server is added as a comment. Most useful in +conjunction with \fB\-c\fP. +.TP +.BR \-M [ M ] +Enable manage DSA IT control. +.B \-MM +makes control critical. +.TP +.B \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. +.TP +.B \-W +Prompt for simple authentication. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +.TP +.BI \-H \ ldapuri +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. +.TP +.BR \-P \ { 2 \||\| 3 } +Specify the LDAP protocol version to use. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and modify extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +Modify extensions: +.nf + [!]txn[=abort|commit] +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR]] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.B \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.B \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username> +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. If it's not +specified, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. If you use +.B \-ZZ\c +, the command will require the operation to be successful. +.SH INPUT FORMAT +The contents of \fIfile\fP (or standard input if no \fB\-f\fP flag is given on +the command line) must conform to the format defined in +.BR ldif (5) +(LDIF as defined in RFC 2849). +.SH EXAMPLES +Assuming that the file +.B /tmp/entrymods +exists and has the contents: +.LP +.nf + dn: cn=Modify Me,dc=example,dc=com + changetype: modify + replace: mail + mail: modme@example.com + \- + add: title + title: Grand Poobah + \- + add: jpegPhoto + jpegPhoto:< file:///tmp/modme.jpeg + \- + delete: description + \- +.fi +.LP +the command: +.LP +.nf + ldapmodify \-f /tmp/entrymods +.fi +.LP +will replace the contents of the "Modify Me" entry's +.I mail +attribute with the value "modme@example.com", add a +.I title +of "Grand Poobah", and the contents of the file "/tmp/modme.jpeg" +as a +.IR jpegPhoto , +and completely remove the +.I description +attribute. +.LP +Assuming that the file +.B /tmp/newentry +exists and has the contents: +.LP +.nf + dn: cn=Barbara Jensen,dc=example,dc=com + objectClass: person + cn: Barbara Jensen + cn: Babs Jensen + sn: Jensen + title: the world's most famous mythical manager + mail: bjensen@example.com + uid: bjensen +.fi +.LP +the command: +.LP +.nf + ldapadd \-f /tmp/newentry +.fi +.LP +will add a new entry for Babs Jensen, using the values from the +file +.B /tmp/newentry. +.LP +Assuming that the file +.B /tmp/entrymods +exists and has the contents: +.LP +.nf + dn: cn=Barbara Jensen,dc=example,dc=com + changetype: delete +.fi +.LP +the command: +.LP +.nf + ldapmodify \-f /tmp/entrymods +.fi +.LP +will remove Babs Jensen's entry. +.SH DIAGNOSTICS +Exit status is zero if no errors occur. Errors result in a non-zero +exit status and a diagnostic message being written to standard error. +.SH "SEE ALSO" +.BR ldapadd (1), +.BR ldapdelete (1), +.BR ldapmodrdn (1), +.BR ldapsearch (1), +.BR ldap.conf (5), +.BR ldap (3), +.BR ldap_add_ext (3), +.BR ldap_delete_ext (3), +.BR ldap_modify_ext (3), +.BR ldap_modrdn_ext (3), +.BR ldif (5). +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldapmodify.1.links b/doc/man/man1/ldapmodify.1.links new file mode 100644 index 0000000..eb4fb76 --- /dev/null +++ b/doc/man/man1/ldapmodify.1.links @@ -0,0 +1 @@ +ldapadd.1 diff --git a/doc/man/man1/ldapmodrdn.1 b/doc/man/man1/ldapmodrdn.1 new file mode 100644 index 0000000..777c539 --- /dev/null +++ b/doc/man/man1/ldapmodrdn.1 @@ -0,0 +1,268 @@ +.TH LDAPMODRDN 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldapmodrdn \- LDAP rename entry tool +.SH SYNOPSIS +.B ldapmodrdn +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-r ] +[\c +.BI \-s \ newsup\fR] +[\c +.BR \-c ] +[\c +.BI \-f \ file\fR] +[\c +.BR \-M [ M ]] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-P \ { 2 \||\| 3 }] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +[\c +.I dn rdn\fR] +.SH DESCRIPTION +.B ldapmodrdn +is a shell-accessible interface to the +.BR ldap_rename (3) +library call. +.LP +.B ldapmodrdn +opens a connection to an LDAP server, binds, and modifies the RDN of entries. +The entry information is read from standard input, from \fIfile\fP through +the use of the +.RI \- f +option, or from the command-line pair \fIdn\fP and +\fIrdn\fP. +.SH OPTIONS +.TP +.BR \-V [ V ] +Print version info. +If \fB\-VV\fP is given, only the version information is printed. +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.B ldapmodrdn +must be compiled with LDAP_DEBUG defined for this option to have any effect. +.TP +.B \-n +Show what would be done, but don't actually change entries. Useful for +debugging in conjunction with \fB\-v\fP. +.TP +.B \-v +Use verbose mode, with many diagnostics written to standard output. +.TP +.B \-r +Remove old RDN values from the entry. Default is to keep old values. +.TP +.BI \-s \ newsup +Specify a new superior entry. (I.e., move the target entry and make it a +child of the new superior.) This option is not supported in LDAPv2. +.TP +.B \-c +Continuous operation mode. Errors are reported, but ldapmodrdn +will continue with modifications. The default is to exit after +reporting an error. +.TP +.BI \-f \ file +Read the entry modification information from \fIfile\fP instead of from +standard input or the command-line. +.TP +.BR \-M [ M ] +Enable manage DSA IT control. +.B \-MM +makes control critical. +.TP +.B \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. +.TP +.B \-W +Prompt for simple authentication. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +.TP +.BI \-H \ ldapuri +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. +.TP +.BR \-P \ { 2 \||\| 3 } +Specify the LDAP protocol version to use. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and modrdn extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +Modrdn extensions: +.nf + (none) +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.B \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.B \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username> +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. If it's not +specified, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. If you use +\fB\-ZZ\fP, the command will require the operation to be successful. +.SH INPUT FORMAT +If the command-line arguments \fIdn\fP and \fIrdn\fP are given, \fIrdn\fP +will replace the RDN of the entry specified by the DN, \fIdn\fP. +.LP +Otherwise, the contents of \fIfile\fP (or standard input if +no \fB\-f\fP flag is given) should consist of one or more entries. +.LP +.nf + Distinguished Name (DN) + Relative Distinguished Name (RDN) +.fi +.LP +One or more blank lines may be used to separate each DN/RDN pair. +.SH EXAMPLE +Assuming that the file +.B /tmp/entrymods +exists and has the contents: +.LP +.nf + cn=Modify Me,dc=example,dc=com + cn=The New Me +.fi +.LP +the command: +.LP +.nf + ldapmodrdn \-r \-f /tmp/entrymods +.fi +.LP +will change the RDN of the "Modify Me" entry from "Modify Me" to +"The New Me" and the old cn, "Modify Me" will be removed. +.LP +.SH DIAGNOSTICS +Exit status is 0 if no errors occur. Errors result in a non-zero exit +status and a diagnostic message being written to standard error. +.SH "SEE ALSO" +.BR ldapadd (1), +.BR ldapdelete (1), +.BR ldapmodify (1), +.BR ldapsearch (1), +.BR ldap.conf (5), +.BR ldap (3), +.BR ldap_rename (3) +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldappasswd.1 b/doc/man/man1/ldappasswd.1 new file mode 100644 index 0000000..d1aea0c --- /dev/null +++ b/doc/man/man1/ldappasswd.1 @@ -0,0 +1,231 @@ +.TH LDAPPASSWD 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldappasswd \- change the password of an LDAP entry +.SH SYNOPSIS +.B ldappasswd +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-A ] +[\c +.BI \-a \ oldPasswd\fR] +[\c +.BI \-t \ oldpasswdfile\fR] +[\c +.BR \-S ] +[\c +.BI \-s \ newPasswd\fR] +[\c +.BI \-T \ newpasswdfile\fR] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +[\c +.IR user ] +.SH DESCRIPTION +.B ldappasswd +is a tool to set the password of an LDAP user. +.B ldappasswd +uses the LDAPv3 Password Modify (RFC 3062) extended operation. +.LP +.B ldappasswd +sets the password of associated with the user [or an optionally +specified +.IR user ]. +If the new +password is not specified on the command line and the user +doesn't enable prompting, the server will be asked to generate +a password for the user. +.LP +.B ldappasswd +is neither designed nor intended to be a replacement for +.BR passwd (1) +and should not be installed as such. +.SH OPTIONS +.TP +.BR \-V [ V ] +Print version info. +If \fB\-VV\fP is given, only the version information is printed. +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.B ldappasswd +must be compiled with LDAP_DEBUG defined for this option to have any effect. +.TP +.B \-n +Do not set password. (Can be useful when used in conjunction with +\fB\-v\fP or \fB\-d\fP) +.TP +.B \-v +Increase the verbosity of output. Can be specified multiple times. +.TP +.BI \-A +Prompt for old password. +This is used instead of specifying the password on the command line. +.TP +.BI \-a \ oldPasswd +Set the old password to \fIoldPasswd\fP. +.TP +.BI \-t \ oldPasswdFile +Set the old password to the contents of \fIoldPasswdFile\fP. +.TP +.BI \-S +Prompt for new password. +This is used instead of specifying the password on the command line. +.TP +.BI \-s \ newPasswd +Set the new password to \fInewPasswd\fP. +.TP +.BI \-T \ newPasswdFile +Set the new password to the contents of \fInewPasswdFile\fP. +.TP +.B \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. +.TP +.BI \-W +Prompt for bind password. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password to bind with. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +.TP +.BI \-H \ ldapuri +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and passwd modify extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +Passwd Modify extensions: +.nf + (none) +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR]] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.B \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.B \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username>\fP. +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. If it's not +specified, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. If you use +\fB\-ZZ\fP, the command will require the operation to be successful +.SH SEE ALSO +.BR ldap_sasl_bind (3), +.BR ldap_extended_operation (3), +.BR ldap_start_tls_s (3) +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldapsearch.1 b/doc/man/man1/ldapsearch.1 new file mode 100644 index 0000000..7f3ec40 --- /dev/null +++ b/doc/man/man1/ldapsearch.1 @@ -0,0 +1,497 @@ +.TH LDAPSEARCH 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldapsearch \- LDAP search tool +.SH SYNOPSIS +.B ldapsearch +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-c ] +[\c +.BR \-u ] +[\c +.BR \-t [ t ]] +[\c +.BI \-T \ path\fR] +[\c +.BI \-F \ prefix\fR] +[\c +.BR \-A ] +[\c +.BR \-L [ L [ L ]]] +[\c +.BI \-S \ attribute\fR] +[\c +.BI \-b \ searchbase\fR] +[\c +.BR \-s \ { base \||\| one \||\| sub \||\| children }] +[\c +.BR \-a \ { never \||\| always \||\| search \||\| find }] +[\c +.BI \-l \ timelimit\fR] +[\c +.BI \-z \ sizelimit\fR] +[\c +.BI \-f \ file\fR] +[\c +.BR \-M [ M ]] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-P \ { 2 \||\| 3 }] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +.I filter +[\c +.IR attrs... ] +.SH DESCRIPTION +.I ldapsearch +is a shell-accessible interface to the +.BR ldap_search_ext (3) +library call. +.LP +.B ldapsearch +opens a connection to an LDAP server, binds, and performs a search +using specified parameters. The \fIfilter\fP should conform to +the string representation for search filters as defined in RFC 4515. +If not provided, the default filter, \fB(objectClass=*)\fP, is used. +.LP +If +.B ldapsearch +finds one or more entries, the attributes specified by +\fIattrs\fP are returned. If \fB*\fP is listed, all user attributes are +returned. If \fB+\fP is listed, all operational attributes are returned. +If no \fIattrs\fP are listed, all user attributes are returned. If only +1.1 is listed, no attributes will be returned. +.LP +The search results are displayed using an extended version of LDIF. +Option \fI\-L\fP controls the format of the output. +.SH OPTIONS +.TP +.BR \-V [ V ] +Print version info. +If \fB\-VV\fP is given, exit after providing version info. Otherwise proceed +with the specified search +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.B ldapsearch +must be compiled with LDAP_DEBUG defined for this option to have any effect. +.TP +.B \-n +Show what would be done, but don't actually perform the search. Useful for +debugging in conjunction with \fB\-v\fP. +.TP +.B \-v +Run in verbose mode, with many diagnostics written to standard output. +.TP +.B \-c +Continuous operation mode. Errors are reported, but ldapsearch will continue +with searches. The default is to exit after reporting an error. Only useful +in conjunction with \fB\-f\fP. +.TP +.B \-u +Include the User Friendly Name form of the Distinguished Name (DN) +in the output. +.TP +.BR \-t [ t ] +A single \fB\-t\fP writes retrieved non-printable values to a set of temporary +files. This is useful for dealing with values containing non-character +data such as jpegPhoto or audio. A second \fB\-t\fP writes all retrieved values to +files. +.TP +.BI \-T \ path +Write temporary files to directory specified by \fIpath\fP (default: +\fBsystem default tmp directory\fP). The environment variables \fBTMPDIR\fP, +\fBTMP\fP, or \fBTEMP\fP will override the default path. +.TP +.BI \-F \ prefix +URL prefix for temporary files. Default is \fBfile://\fIpath\fP where +\fIpath\fP is the \fBsystem default tmp directory\fP or the value specified +with \fB\-T\fP. +.TP +.B \-A +Retrieve attributes only (no values). This is useful when you just want to +see if an attribute is present in an entry and are not interested in the +specific values. +.TP +.B \-L +Search results are display in LDAP Data Interchange Format detailed in +.BR ldif (5). +A single \fB\-L\fP restricts the output to LDIFv1. + A second \fB\-L\fP disables comments. +A third \fB\-L\fP disables printing of the LDIF version. +The default is to use an extended version of LDIF. +.TP +.BI \-S \ attribute +Sort the entries returned based on \fIattribute\fP. The default is not +to sort entries returned. If \fIattribute\fP is a zero-length string (""), +the entries are sorted by the components of their Distinguished Name. See +.BR ldap_sort (3) +for more details. Note that +.B ldapsearch +normally prints out entries as it receives them. The use of the \fB\-S\fP +option defeats this behavior, causing all entries to be retrieved, +then sorted, then printed. +.TP +.BI \-b \ searchbase +Use \fIsearchbase\fP as the starting point for the search instead of +the default. +.TP +.BR \-s \ { base \||\| one \||\| sub \||\| children } +Specify the scope of the search to be one of +.BR base , +.BR one , +.BR sub , +or +.B children +to specify a base object, one-level, subtree, or children search. +The default is +.BR sub . +Note: +.I children +scope requires LDAPv3 subordinate feature extension. +.TP +.BR \-a \ { never \||\| always \||\| search \||\| find } +Specify how aliases dereferencing is done. Should be one of +.BR never , +.BR always , +.BR search , +or +.B find +to specify that aliases are never dereferenced, always dereferenced, +dereferenced when searching, or dereferenced only when locating the +base object for the search. The default is to never dereference aliases. +.TP +.BI \-l \ timelimit +wait at most \fItimelimit\fP seconds for a search to complete. +A timelimit of +.I 0 +(zero) or +.I none +means no limit. +A timelimit of +.I max +means the maximum integer allowable by the protocol. +A server may impose a maximal timelimit which only +the root user may override. +.TP +.BI \-z \ sizelimit +retrieve at most \fIsizelimit\fP entries for a search. +A sizelimit of +.I 0 +(zero) or +.I none +means no limit. +A sizelimit of +.I max +means the maximum integer allowable by the protocol. +A server may impose a maximal sizelimit which only +the root user may override. +.TP +.BI \-f \ file +Read a series of lines from \fIfile\fP, performing one LDAP search for +each line. In this case, the \fIfilter\fP given on the command line +is treated as a pattern where the first and only occurrence of \fB%s\fP +is replaced with a line from \fIfile\fP. Any other occurrence of the +the \fB%\fP character in the pattern will be regarded as an error. +Where it is desired that the search filter include a \fB%\fP character, +the character should be encoded as \fB\\25\fP (see RFC 4515). +If \fIfile\fP is a single +\fB\-\fP character, then the lines are read from standard input. +.B ldapsearch +will exit when the first non-successful search result is returned, +unless \fB\-c\fP is used. +.TP +.BR \-M [ M ] +Enable manage DSA IT control. +.B \-MM +makes control critical. +.TP +.B \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. +.TP +.B \-W +Prompt for simple authentication. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +.TP +.BI \-H \ ldapuri +Specify URI(s) referring to the ldap server(s); +a list of URI, separated by whitespace or commas is expected; +only the protocol/host/port fields are allowed. +As an exception, if no host/port is specified, but a DN is, +the DN is used to look up the corresponding host(s) using the +DNS SRV records, according to RFC 2782. The DN must be a non-empty +sequence of AVAs whose attribute type is "dc" (domain component), +and must be escaped according to RFC 2396. +.TP +.BR \-P \ { 2 \||\| 3 } +Specify the LDAP protocol version to use. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and search extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +Search extensions: +.nf + !dontUseCopy + [!]domainScope (domain scope) + [!]mv=<filter> (matched values filter) + [!]pr=<size>[/prompt|noprompt] (paged results/prompt) + [!]sss=[\-]<attr[:OID]>[/[\-]<attr[:OID]>...] (server side sorting) + [!]subentries[=true|false] (subentries) + [!]sync=ro[/<cookie>] (LDAP Sync refreshOnly) + rp[/<cookie>][/<slimit>] (LDAP Sync refreshAndPersist) + [!]vlv=<before>/<after>(/<offset>/<count>|:<value>) (virtual list view) + [!]deref=derefAttr:attr[,attr[...]][;derefAttr:attr[,attr[...]]] + [!]<oid>[=:<value>|::<b64value>] +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.B \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.B \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username> +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. If it's not +specified, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. If you use +\fB\-ZZ\fP, the command will require the operation to be successful. +.SH OUTPUT FORMAT +If one or more entries are found, each entry is written to standard +output in LDAP Data Interchange Format or +.BR ldif (5): +.LP +.nf + version: 1 + + # bjensen, example, net + dn: uid=bjensen,dc=example,dc=net + objectClass: person + objectClass: dcObject + uid: bjensen + cn: Barbara Jensen + sn: Jensen + ... +.fi +.LP +If the \fB\-t\fP option is used, the URI of a temporary file +is used in place of the actual value. If the \fB\-A\fP option +is given, only the "attributename" part is written. +.SH EXAMPLE +The following command: +.LP +.nf + ldapsearch \-LLL "(sn=smith)" cn sn telephoneNumber +.fi +.LP +will perform a subtree search (using the default search base and +other parameters defined in +.BR ldap.conf (5)) +for entries with a surname (sn) of smith. The common name (cn), surname +(sn) and telephoneNumber values will be retrieved and printed to +standard output. +The output might look something like this if two entries are found: +.LP +.nf + dn: uid=jts,dc=example,dc=com + cn: John Smith + cn: John T. Smith + sn: Smith + sn;lang\-en: Smith + sn;lang\-de: Schmidt + telephoneNumber: 1 555 123\-4567 + + dn: uid=sss,dc=example,dc=com + cn: Steve Smith + cn: Steve S. Smith + sn: Smith + sn;lang\-en: Smith + sn;lang\-de: Schmidt + telephoneNumber: 1 555 765\-4321 +.fi +.LP +The command: +.LP +.nf + ldapsearch \-LLL \-u \-t "(uid=xyz)" jpegPhoto audio +.fi +.LP +will perform a subtree search using the default search base for entries +with user id of "xyz". The user friendly form of the entry's DN will be +output after the line that contains the DN itself, and the jpegPhoto +and audio values will be retrieved and written to temporary files. The +output might look like this if one entry with one value for each of the +requested attributes is found: +.LP +.nf + dn: uid=xyz,dc=example,dc=com + ufn: xyz, example, com + audio:< file:///tmp/ldapsearch\-audio\-a19924 + jpegPhoto:< file:///tmp/ldapsearch\-jpegPhoto\-a19924 +.fi +.LP +This command: +.LP +.nf + ldapsearch \-LLL \-s one \-b "c=US" "(o=University*)" o description +.fi +.LP +will perform a one-level search at the c=US level for all entries +whose organization name (o) begins with \fBUniversity\fP. +The organization name and description attribute values will be retrieved +and printed to standard output, resulting in output similar to this: +.LP +.nf + dn: o=University of Alaska Fairbanks,c=US + o: University of Alaska Fairbanks + description: Naturally Inspiring + description: leaf node only + + dn: o=University of Colorado at Boulder,c=US + o: University of Colorado at Boulder + description: No personnel information + description: Institution of education and research + + dn: o=University of Colorado at Denver,c=US + o: University of Colorado at Denver + o: UCD + o: CU/Denver + o: CU\-Denver + description: Institute for Higher Learning and Research + + dn: o=University of Florida,c=US + o: University of Florida + o: UFl + description: Warper of young minds + + ... +.fi +.SH DIAGNOSTICS +Exit status is zero if no errors occur. +Errors result in a non-zero exit status and +a diagnostic message being written to standard error. +.SH "SEE ALSO" +.BR ldapadd (1), +.BR ldapdelete (1), +.BR ldapmodify (1), +.BR ldapmodrdn (1), +.BR ldap.conf (5), +.BR ldif (5), +.BR ldap (3), +.BR ldap_search_ext (3), +.BR ldap_sort (3) +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldapurl.1 b/doc/man/man1/ldapurl.1 new file mode 100644 index 0000000..7e38270 --- /dev/null +++ b/doc/man/man1/ldapurl.1 @@ -0,0 +1,168 @@ +.TH LDAPURL 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 2008-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldapurl \- LDAP URL formatting tool +.SH SYNOPSIS +.B ldapurl +[\c +.BR \-a \ attrs\fR] +[\c +.BI \-b \ searchbase\fR] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-f \ filter\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BI \-h \ ldaphost\fR] +[\c +.BI \-p \ ldapport\fR] +[\c +.BR \-s \ { base \||\| one \||\| sub \||\| children }] +[\c +.BI \-S \ scheme\fR] +.SH DESCRIPTION +.I ldapurl +is a command that allows one to either compose or decompose LDAP URIs. +.LP +When invoked with the \fB\-H\fP option, +.B ldapurl +extracts the components of the \fIldapuri\fP option argument, +unescaping hex-escaped chars as required. +It basically acts as a frontend to the +.BR ldap_url_parse (3) +call. +Otherwise, it builds an LDAP URI based on the components +passed with the appropriate options, performing the inverse operation. +Option \fB\-H\fP is incompatible with options +.BR \-a , +.BR \-b , +.BR \-E , +.BR \-f , +.BR \-H , +.BR \-h , +.BR \-p , +.BR \-S , +and +.BR \-s . +.SH OPTIONS +.TP +.TP +.BI \-a \ attrs +Set a comma-separated list of attribute selectors. +.TP +.BI \-b \ searchbase +Set the \fIsearchbase\fP. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +Set URL extensions; incompatible with +.BR \-H . +.TP +.BI \-f \ filter +Set the URL filter. No particular check on conformity with RFC 4515 +LDAP filters is performed, but the value is hex-escaped as required. +.TP +.BI \-H \ ldapuri +Specify URI to be exploded. +.TP +.BI \-h \ ldaphost +Set the host. +.TP +.BI \-p \ ldapport +Set the TCP port. +.TP +.BI \-S \ scheme +Set the URL scheme. Defaults for other fields, like \fIldapport\fP, +may depend on the value of \fIscheme\fP. +.TP +.BR \-s \ { base \||\| one \||\| sub \||\| children } +Specify the scope of the search to be one of +.BR base , +.BR one , +.BR sub , +or +.B children +to specify a base object, one-level, subtree, or children search. +The default is +.BR sub . +Note: +.B children +scope requires LDAPv3 subordinate feature extension. + +.SH OUTPUT FORMAT +If the \fB\-H\fP option is used, the \fIldapuri\fP supplied +is exploded in its components, which are printed to standard output +in an LDIF-like form. +.LP +Otherwise, the URI built using the values passed with the other options +is printed to standard output. +.SH EXAMPLE +The following command: +.LP +.nf + ldapurl \-h ldap.example.com \-b dc=example,dc=com \-s sub \-f "(cn=Some One)" +.fi +.LP +returns +.LP +.nf + ldap://ldap.example.com:389/dc=example,dc=com??sub?(cn=Some%20One) +.fi +.LP +The command: +.LP +.nf + ldapurl \-H ldap://ldap.example.com:389/dc=example,dc=com??sub?(cn=Some%20One) +.fi +.LP +returns +.LP +.nf + scheme: ldap + host: ldap.example.com + port: 389 + dn: dc=example,dc=com + scope: sub + filter: (cn=Some One) +.fi +.LP +.SH DIAGNOSTICS +Exit status is zero if no errors occur. +Errors result in a non-zero exit status and +a diagnostic message being written to standard error. +.SH "SEE ALSO" +.BR ldap (3), +.BR ldap_url_parse (3), +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldapvc.1 b/doc/man/man1/ldapvc.1 new file mode 100644 index 0000000..4733080 --- /dev/null +++ b/doc/man/man1/ldapvc.1 @@ -0,0 +1,213 @@ +.TH LDAPVC 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldapvc \- LDAP verify credentials tool +.SH SYNOPSIS +.B ldapvc +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-a ] +[\c +.BR \-b ] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +\c +.I Distinguished Name \ +\c +.I [Credentials] +.SH DESCRIPTION +.I ldapvc +implements the LDAP "Verify Credentials" extended operation. +.LP +.B Verify Credentials +operation behaves like LDAP Bind but has no impact upon the underlying LDAP session. +.SH OPTIONS +.TP +.BR \-V [ V ] +Print version info. +If \fB\-VV\fP is given, only the version information is printed. +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.B ldapvc +must be compiled with LDAP_DEBUG defined for this option to have any effect. +.TP +.B \-a +Print the authzID resulting from a successful verification of credentials. +.TP +.B \-b +Print the results from the ppolicy control after verification of credentials. +.TP +.B \-n +Show what would be done, but don't actually perform the operation. +Useful for +debugging in conjunction with \fB\-v\fP. +.TP +.B \-v +Run in verbose mode, with many diagnostics written to standard output. +.TP +.B \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. +.TP +.B \-W +Prompt for simple authentication. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +.TP +.BI \-H \ ldapuri +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and Verify Credentials extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi +.sp +Verify Credentials extensions: +.sp +The following options set SASL params on the Verify Credentials request: +.nf + authcid=<authcid> (SASL Authentication Identity "dn:<dn>" or "u:<user>") + authzid=<authzid> (SASL Authorization Identity "dn:<dn>" or "u:<user>") + mech=<mech> (SASL mechanism default e.g. Simple) + realm=<realm> (SASL Realm, defaults to none) + sasl=a[utomatic]|i[nteractive]|q[uiet] (SASL mode defaults to automatic if any other -E option provided, otherwise none) + secprops=<secprops> (SASL Security Properties) +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.B -o +option that can be passed here, check +.BR ldap.conf (5) +for details. +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.B \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.B \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username> +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. If it's not +specified, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. If you use +\fB\-ZZ\fP, the command will require the operation to be successful. +.SH EXAMPLE +.nf + ldapvc \-x "uid=Alice,ou=People,dc=example,dc=com" +.fi +.SH "SEE ALSO" +.BR ldap.conf (5), +.BR ldap (3), +.BR ldap_extended_operation (3) +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldapwhoami.1 b/doc/man/man1/ldapwhoami.1 new file mode 100644 index 0000000..49b1187 --- /dev/null +++ b/doc/man/man1/ldapwhoami.1 @@ -0,0 +1,194 @@ +.TH LDAPWHOAMI 1 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldapwhoami \- LDAP who am i? tool +.SH SYNOPSIS +.B ldapwhoami +[\c +.BR \-V [ V ]] +[\c +.BI \-d \ debuglevel\fR] +[\c +.BR \-n ] +[\c +.BR \-v ] +[\c +.BR \-x ] +[\c +.BI \-D \ binddn\fR] +[\c +.BR \-W ] +[\c +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] +[\c +.BI \-H \ ldapuri\fR] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BI \-o \ opt \fR[= optparam \fR]] +[\c +.BI \-O \ security-properties\fR] +[\c +.BR \-I ] +[\c +.BR \-Q ] +[\c +.BR \-N ] +[\c +.BI \-U \ authcid\fR] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-X \ authzid\fR] +[\c +.BI \-Y \ mech\fR] +[\c +.BR \-Z [ Z ]] +.SH DESCRIPTION +.I ldapwhoami +implements the LDAP "Who Am I?" extended operation. +.LP +.B ldapwhoami +opens a connection to an LDAP server, binds, and performs a whoami +operation. +.SH OPTIONS +.TP +.BR \-V [ V ] +Print version info. +If \fB\-VV\fP is given, only the version information is printed. +.TP +.BI \-d \ debuglevel +Set the LDAP debugging level to \fIdebuglevel\fP. +.B ldapwhoami +must be compiled with LDAP_DEBUG defined for this option to have any effect. +.TP +.B \-n +Show what would be done, but don't actually perform the whoami operation. +Useful for +debugging in conjunction with \fB\-v\fP. +.TP +.B \-v +Run in verbose mode, with many diagnostics written to standard output. +.TP +.B \-x +Use simple authentication instead of SASL. +.TP +.BI \-D \ binddn +Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. +.TP +.B \-W +Prompt for simple authentication. +This is used instead of specifying the password on the command line. +.TP +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. +.TP +.BI \-H \ ldapuri +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. +.TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and whoami extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert=<filter> (an RFC 4515 Filter) + !authzid=<authzid> ("dn:<dn>" or "u:<user>") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=<resolve>[/<cont>]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=<attrs>] (a comma-separated attribute list) + [!]preread[=<attrs>] (a comma-separated attribute list) + [!]relax + sessiontracking[=<username>] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +WhoAmI extensions: +.nf + (none) +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout=<timeout> (in seconds, or "none" or "max") + ldif_wrap=<width> (in columns, or "no" for no wrapping) +.fi + +.B -o +option that can be passed here, check +.BR ldap.conf (5) +for details. +.TP +.BI \-O \ security-properties +Specify SASL security properties. +.TP +.B \-I +Enable SASL Interactive mode. Always prompt. Default is to prompt +only as needed. +.TP +.B \-Q +Enable SASL Quiet mode. Never prompt. +.TP +.B \-N +Do not use reverse DNS to canonicalize SASL host name. +.TP +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. +.TP +.BI \-X \ authzid +Specify the requested authorization ID for SASL bind. +.I authzid +must be one of the following formats: +.BI dn: "<distinguished name>" +or +.BI u: <username> +.TP +.BI \-Y \ mech +Specify the SASL mechanism to be used for authentication. If it's not +specified, the program will choose the best mechanism the server knows. +.TP +.BR \-Z [ Z ] +Issue StartTLS (Transport Layer Security) extended operation. If you use +\fB\-ZZ\fP, the command will require the operation to be successful. +.SH EXAMPLE +.nf + ldapwhoami \-x \-D "cn=Manager,dc=example,dc=com" \-W +.fi +.SH "SEE ALSO" +.BR ldap.conf (5), +.BR ldap (3), +.BR ldap_extended_operation (3) +.SH AUTHOR +The OpenLDAP Project <http://www.openldap.org/> +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/Deprecated b/doc/man/man3/Deprecated new file mode 100644 index 0000000..3b7f696 --- /dev/null +++ b/doc/man/man3/Deprecated @@ -0,0 +1,7 @@ +Deprecated interfaces generally remain in the library. The macro +LDAP_DEPRECATED can be defined to a non-zero value +(e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use +deprecated interfaces. It is recommended that developers writing new +programs, or updating old programs, avoid use of deprecated interfaces. +Over time, it is expected that documentation (and, eventually, support) for +deprecated interfaces to be eliminated. diff --git a/doc/man/man3/Makefile.in b/doc/man/man3/Makefile.in new file mode 100644 index 0000000..0a43c6e --- /dev/null +++ b/doc/man/man3/Makefile.in @@ -0,0 +1,16 @@ +# man3 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=3 diff --git a/doc/man/man3/lber-decode.3 b/doc/man/man3/lber-decode.3 new file mode 100644 index 0000000..97d4932 --- /dev/null +++ b/doc/man/man3/lber-decode.3 @@ -0,0 +1,357 @@ +.TH LBER_DECODE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include <lber.h> +.LP +.BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" +.LP +.BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" +.LP +.BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" +.LP +.BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" +.LP +.BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" +.LP +.BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" +.LP +.BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" +.LP +.BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" +.LP +.BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" +.LP +.BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" +.LP +.BI "ber_tag_t ber_get_null(BerElement *" ber ");" +.LP +.BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" +.LP +.BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" +.LP +.BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" +.LP +.BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" +.SH DESCRIPTION +.LP +These routines provide a subroutine interface to a simplified +implementation of the Basic Encoding Rules of ASN.1. The version +of BER these routines support is the one defined for the LDAP +protocol. The encoding rules are the same as BER, except that +only definite form lengths are used, and bitstrings and octet strings +are always encoded in primitive form. This man page +describes the decoding routines in the lber library. See +.BR lber-encode (3) +for details on the corresponding encoding routines. +Consult +.BR lber-types (3) +for information about types, allocators, and deallocators. +.LP +Normally, the only routines that need to be called by an application +are +.BR ber_get_next () +to get the next BER element and +.BR ber_scanf () +to do the actual decoding. In some cases, +.BR ber_peek_tag () +may also need to be called in normal usage. The other routines are +provided for those applications that need more control than +.BR ber_scanf () +provides. In +general, these routines return the tag of the element decoded, or +LBER_ERROR if an error occurred. +.LP +The +.BR ber_get_next () +routine is used to read the next BER element from the given Sockbuf, +\fIsb\fP. It strips off and returns the leading tag, strips off and +returns the length of the entire element in \fIlen\fP, and sets up +\fIber\fP for subsequent calls to +.BR ber_scanf () +et al to decode the element. See +.BR lber-sockbuf (3) +for details of the Sockbuf implementation of the \fIsb\fP parameter. +.LP +The +.BR ber_scanf () +routine is used to decode a BER element in much the same way that +.BR scanf (3) +works. It reads from \fIber\fP, a pointer to a BerElement +such as returned by +.BR ber_get_next (), +interprets the bytes according to the format string \fIfmt\fP, and stores the +results in its additional arguments. The format string contains +conversion specifications which are used to direct the interpretation +of the BER element. The format string can contain the following +characters. +.RS +.LP +.TP 3 +.B a +Octet string. A char ** should be supplied. Memory is allocated, +filled with the contents of the octet string, null-terminated, and +returned in the parameter. The caller should free the returned +string using +.BR ber_memfree (). +.TP +.B A +Octet string. A variant of "\fBa\fP". A char ** should be supplied. +Memory is allocated, filled with the contents of the octet string, +null-terminated, and returned in the parameter, unless a zero-length +string would result; in that case, the arg is set to NULL. +The caller should free the returned string using +.BR ber_memfree (). +.TP +.B s +Octet string. A char * buffer should be supplied, followed by a pointer to a +ber_len_t initialized to the size of the buffer. Upon return, the +null-terminated octet string is put into the buffer, and the +ber_len_t is set to the actual size of the octet string. +.TP +.B O +Octet string. A struct ber_val ** should be supplied, which upon +return points to a dynamically allocated struct berval +containing the octet string and its length. +The caller should free the returned structure using +.BR ber_bvfree (). +.TP +.B o +Octet string. A struct ber_val * should be supplied, which upon +return contains the dynamically allocated +octet string and its length. The caller should free the returned octet +string using +.BR ber_memfree (). +.TP +.B m +Octet string. A struct ber_val * should be supplied, which upon return +contains the octet string and its length. The string resides in memory +assigned to the BerElement, and must not be freed by the caller. +.TP +.B b +Boolean. A pointer to a ber_int_t should be supplied. +.TP +.B e +Enumeration. A pointer to a ber_int_t should be supplied. +.TP +.B i +Integer. A pointer to a ber_int_t should be supplied. +.TP +.B B +Bitstring. A char ** should be supplied which will point to the +dynamically allocated +bits, followed by a ber_len_t *, which will point to the length +(in bits) of the bitstring returned. +.TP +.B n +Null. No parameter is required. The element is simply skipped if +it is recognized. +.TP +.B v +Sequence of octet strings. A char *** should be supplied, which upon +return points to a dynamically allocated null-terminated array of char *'s +containing the octet strings. NULL is returned if the sequence is empty. +The caller should free the returned array and octet strings using +.BR ber_memvfree (). +.TP +.B V +Sequence of octet strings with lengths. +A struct berval *** should be supplied, which upon +return points to a dynamically allocated null-terminated array of +struct berval *'s +containing the octet strings and their lengths. +NULL is returned if the sequence is empty. +The caller should free the returned structures using +.BR ber_bvecfree (). +.TP +.B W +Sequence of octet strings with lengths. +A BerVarray * should be supplied, which upon +return points to a dynamically allocated array of +struct berval's +containing the octet strings and their lengths. The array is terminated +by a struct berval with a NULL bv_val string pointer. +NULL is returned if the sequence is empty. +The caller should free the returned structures using +.BR ber_bvarray_free (). +.TP +.B M +Sequence of octet strings with lengths. This is a generalized form +of the previous three formats. +A void ** (ptr) should be supplied, followed by a ber_len_t * (len) +and a ber_len_t (off). +Upon return (ptr) will point to a dynamically allocated array +whose elements are all of size (*len). A struct berval will be filled +starting at offset (off) in each element. The strings in each struct +berval reside in memory assigned to the BerElement and must not be +freed by the caller. The array is terminated by a struct berval +with a NULL bv_val string pointer. NULL is returned if the sequence +is empty. The number of elements in the array is also stored +in (*len) on return. The caller should free the returned array using +.BR ber_memfree (). +.TP +.B l +Length of the next element. A pointer to a ber_len_t should be supplied. +.TP +.B t +Tag of the next element. A pointer to a ber_tag_t should be supplied. +.TP +.B T +Skip element and return its tag. A pointer to a ber_tag_t should be supplied. +.TP +.B x +Skip element. The next element is skipped. +.TP +.B { +Begin sequence. No parameter is required. The initial sequence tag +and length are skipped. +.TP +.B } +End sequence. No parameter is required and no action is taken. +.TP +.B [ +Begin set. No parameter is required. The initial set tag +and length are skipped. +.TP +.B ] +End set. No parameter is required and no action is taken. +.RE +.LP +The +.BR ber_get_int () +routine tries to interpret the next element as an integer, +returning the result in \fInum\fP. The tag of whatever it finds is returned +on success, LBER_ERROR (\-1) on failure. +.LP +The +.BR ber_get_stringb () +routine is used to read an octet string into a +preallocated buffer. The \fIlen\fP parameter should be initialized to +the size of the buffer, and will contain the length of the octet string +read upon return. The buffer should be big enough to take the octet +string value plus a terminating NULL byte. +.LP +The +.BR ber_get_stringa () +routine is used to dynamically allocate space into +which an octet string is read. +The caller should free the returned string using +.BR ber_memfree(). +.LP +The +.BR ber_get_stringal () +routine is used to dynamically allocate space +into which an octet string and its length are read. It takes a +struct berval **, and returns the result in this parameter. +The caller should free the returned structure using +.BR ber_bvfree(). +.LP +The +.BR ber_get_stringbv () +routine is used to read an octet string and its length into the +provided struct berval *. If the \fIalloc\fP parameter is zero, the string +will reside in memory assigned to the BerElement, and must not be freed +by the caller. If the \fIalloc\fP parameter is non-zero, the string will be +copied into dynamically allocated space which should be returned using +.BR ber_memfree (). +.LP +The +.BR ber_get_null () +routine is used to read a NULL element. It returns +the tag of the element it skips over. +.LP +The +.BR ber_get_boolean () +routine is used to read a boolean value. It is called the same way that +.BR ber_get_int () +is called. +.LP +The +.BR ber_get_enum () +routine is used to read a enumeration value. It is called the same way that +.BR ber_get_int () +is called. +.LP +The +.BR ber_get_bitstringa () +routine is used to read a bitstring value. It +takes a char ** which will hold the dynamically allocated bits, followed by an +ber_len_t *, which will point to the length (in bits) of the bitstring returned. +The caller should free the returned string using +.BR ber_memfree (). +.LP +The +.BR ber_first_element () +routine is used to return the tag and length +of the first element in a set or sequence. It also returns in \fIcookie\fP +a magic cookie parameter that should be passed to subsequent calls to +ber_next_element(), which returns similar information. +.SH EXAMPLES +Assume the variable \fIber\fP contains a lightweight BER encoding of +the following ASN.1 object: +.LP +.nf + AlmostASearchRequest := SEQUENCE { + baseObject DistinguishedName, + scope ENUMERATED { + baseObject (0), + singleLevel (1), + wholeSubtree (2) + }, + derefAliases ENUMERATED { + neverDerefaliases (0), + derefInSearching (1), + derefFindingBaseObj (2), + alwaysDerefAliases (3) + }, + sizelimit INTEGER (0 .. 65535), + timelimit INTEGER (0 .. 65535), + attrsOnly BOOLEAN, + attributes SEQUENCE OF AttributeType + } +.fi +.LP +The element can be decoded using +.BR ber_scanf () +as follows. +.LP +.nf + ber_int_t scope, deref, size, time, attrsonly; + char *dn, **attrs; + ber_tag_t tag; + + tag = ber_scanf( ber, "{aeeiib{v}}", + &dn, &scope, &deref, + &size, &time, &attrsonly, &attrs ); + + if( tag == LBER_ERROR ) { + /* error */ + } else { + /* success */ + } + + ber_memfree( dn ); + ber_memvfree( attrs ); +.fi +.SH ERRORS +If an error occurs during decoding, generally these routines return +LBER_ERROR ((ber_tag_t)\-1). +.LP +.SH NOTES +.LP +The return values for all of these functions are declared in the +.B <lber.h> +header file. Some routines may dynamically allocate memory +which must be freed by the caller using supplied deallocation routines. +.SH SEE ALSO +.BR lber-encode (3), +.BR lber-memory (3), +.BR lber-sockbuf (3), +.BR lber-types (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/lber-decode.3.links b/doc/man/man3/lber-decode.3.links new file mode 100644 index 0000000..3ec9328 --- /dev/null +++ b/doc/man/man3/lber-decode.3.links @@ -0,0 +1,13 @@ +ber_get_next.3 +ber_skip_tag.3 +ber_peek_tag.3 +ber_scanf.3 +ber_get_int.3 +ber_get_stringa.3 +ber_get_stringb.3 +ber_get_null.3 +ber_get_enum.3 +ber_get_boolean.3 +ber_get_bitstring.3 +ber_first_element.3 +ber_next_element.3 diff --git a/doc/man/man3/lber-encode.3 b/doc/man/man3/lber-encode.3 new file mode 100644 index 0000000..0d2e44d --- /dev/null +++ b/doc/man/man3/lber-encode.3 @@ -0,0 +1,288 @@ +.TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include <lber.h> +.LP +.BI "BerElement *ber_alloc_t(int " options ");" +.LP +.BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" +.LP +.BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" +.LP +.BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" +.LP +.BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" +.LP +.BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" +.LP +.BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_seq(BerElement *" ber ");" +.LP +.BI "int ber_put_set(BerElement *" ber ");" +.SH DESCRIPTION +.LP +These routines provide a subroutine interface to a simplified +implementation of the Basic Encoding Rules of ASN.1. The version +of BER these routines support is the one defined for the LDAP +protocol. The encoding rules are the same as BER, except that +only definite form lengths are used, and bitstrings and octet strings +are always encoded in primitive form. This +man page describes the encoding routines in the lber library. See +.BR lber-decode (3) +for details on the corresponding decoding routines. Consult +.BR lber-types (3) +for information about types, allocators, and deallocators. +.LP +Normally, the only routines that need to be called by an application +are +.BR ber_alloc_t () +to allocate a BER element for encoding, +.BR ber_printf () +to do the actual encoding, and +.BR ber_flush2 () +to actually write the element. The other routines are provided for those +applications that need more control than +.BR ber_printf () +provides. In +general, these routines return the length of the element encoded, or +\-1 if an error occurred. +.LP +The +.BR ber_alloc_t () +routine is used to allocate a new BER element. It +should be called with an argument of LBER_USE_DER. +.LP +The +.BR ber_flush2 () +routine is used to actually write the element to a socket +(or file) descriptor, once it has been fully encoded (using +.BR ber_printf () +and friends). See +.BR lber-sockbuf (3) +for more details on the Sockbuf implementation of the \fIsb\fP parameter. +If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will +be freed. +If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed +when successfully flushed, otherwise it is left intact; +if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed +when an error occurs, otherwise it is left intact; +if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. +This function differs from the original +.BR ber_flush (3) +function, whose behavior corresponds to that indicated +for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. +Note that in the future, the behavior of +.BR ber_flush (3) +with \fIfreeit\fP non-zero might change into that of +.BR ber_flush2 (3) +with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. +.LP +The +.BR ber_printf () +routine is used to encode a BER element in much the same way that +.BR sprintf (3) +works. One important difference, though, is +that some state information is kept with the \fIber\fP parameter so +that multiple calls can be made to +.BR ber_printf () +to append things to the end of the BER element. +.BR Ber_printf () +writes to \fIber\fP, a pointer to a BerElement such as returned by +.BR ber_alloc_t (). +It interprets and +formats its arguments according to the format string \fIfmt\fP. +The format string can contain the following characters: +.RS +.LP +.TP 3 +.B b +Boolean. An ber_int_t parameter should be supplied. A boolean element +is output. +.TP +.B e +Enumeration. An ber_int_t parameter should be supplied. An +enumeration element is output. +.TP +.B i +Integer. An ber_int_t parameter should be supplied. An integer element +is output. +.TP +.B B +Bitstring. A char * pointer to the start of the bitstring is supplied, +followed by the number of bits in the bitstring. A bitstring element +is output. +.TP +.B n +Null. No parameter is required. A null element is output. +.TP +.B o +Octet string. A char * is supplied, followed by the length of the +string pointed to. An octet string element is output. +.TP +.B O +Octet string. A struct berval * is supplied. +An octet string element is output. +.TP +.B s +Octet string. A null-terminated string is supplied. An octet string +element is output, not including the trailing NULL octet. +.TP +.B t +Tag. A ber_tag_t specifying the tag to give the next element +is provided. This works across calls. +.TP +.B v +Several octet strings. A null-terminated array of char *'s is +supplied. Note that a construct like '{v}' is required to get +an actual SEQUENCE OF octet strings. +.TP +.B V +Several octet strings. A null-terminated array of struct berval *'s +is supplied. Note that a construct like '{V}' is required to get +an actual SEQUENCE OF octet strings. +.TP +.B W +Several octet strings. An array of struct berval's is supplied. The +array is terminated by a struct berval with a NULL bv_val. +Note that a construct like '{W}' is required to get +an actual SEQUENCE OF octet strings. +.TP +.B { +Begin sequence. No parameter is required. +.TP +.B } +End sequence. No parameter is required. +.TP +.B [ +Begin set. No parameter is required. +.TP +.B ] +End set. No parameter is required. +.RE +.LP +The +.BR ber_put_int () +routine writes the integer element \fInum\fP to the BER element \fIber\fP. +.LP +The +.BR ber_put_enum () +routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. +.LP +The +.BR ber_put_boolean () +routine writes the boolean value given by \fIbool\fP to the BER element. +.LP +The +.BR ber_put_bitstring () +routine writes \fIblen\fP bits starting +at \fIstr\fP as a bitstring value to the given BER element. Note +that \fIblen\fP is the length \fIin bits\fP of the bitstring. +.LP +The +.BR ber_put_ostring () +routine writes \fIlen\fP bytes starting at +\fIstr\fP to the BER element as an octet string. +.LP +The +.BR ber_put_string () +routine writes the null-terminated string (minus +the terminating '\0') to the BER element as an octet string. +.LP +The +.BR ber_put_null () +routine writes a NULL element to the BER element. +.LP +The +.BR ber_start_seq () +routine is used to start a sequence in the BER element. The +.BR ber_start_set () +routine works similarly. +The end of the sequence or set is marked by the nearest matching call to +.BR ber_put_seq () +or +.BR ber_put_set (), +respectively. +.SH EXAMPLES +Assuming the following variable declarations, and that the variables +have been assigned appropriately, an lber encoding of +the following ASN.1 object: +.LP +.nf + AlmostASearchRequest := SEQUENCE { + baseObject DistinguishedName, + scope ENUMERATED { + baseObject (0), + singleLevel (1), + wholeSubtree (2) + }, + derefAliases ENUMERATED { + neverDerefaliases (0), + derefInSearching (1), + derefFindingBaseObj (2), + alwaysDerefAliases (3) + }, + sizelimit INTEGER (0 .. 65535), + timelimit INTEGER (0 .. 65535), + attrsOnly BOOLEAN, + attributes SEQUENCE OF AttributeType + } +.fi +.LP +can be achieved like so: +.LP +.nf + int rc; + ber_int_t scope, ali, size, time, attrsonly; + char *dn, **attrs; + BerElement *ber; + + /* ... fill in values ... */ + + ber = ber_alloc_t( LBER_USE_DER ); + + if ( ber == NULL ) { + /* error */ + } + + rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, + size, time, attrsonly, attrs ); + + if( rc == \-1 ) { + /* error */ + } else { + /* success */ + } +.fi +.SH ERRORS +If an error occurs during encoding, generally these routines return \-1. +.LP +.SH NOTES +.LP +The return values for all of these functions are declared in the +<lber.h> header file. +.SH SEE ALSO +.BR lber-decode (3), +.BR lber-memory (3), +.BR lber-sockbuf (3), +.BR lber-types (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/lber-encode.3.links b/doc/man/man3/lber-encode.3.links new file mode 100644 index 0000000..54cd0e9 --- /dev/null +++ b/doc/man/man3/lber-encode.3.links @@ -0,0 +1,11 @@ +ber_alloc_t.3 +ber_flush.3 +ber_printf.3 +ber_put_int.3 +ber_put_ostring.3 +ber_put_string.3 +ber_put_null.3 +ber_put_enum.3 +ber_start_set.3 +ber_put_seq.3 +ber_put_set.3 diff --git a/doc/man/man3/lber-memory.3 b/doc/man/man3/lber-memory.3 new file mode 100644 index 0000000..70679b5 --- /dev/null +++ b/doc/man/man3/lber-memory.3 @@ -0,0 +1,49 @@ +.TH LBER_MEMORY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_memalloc, ber_memcalloc, ber_memrealloc, ber_memfree, ber_memvfree \- OpenLDAP LBER memory allocators +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include <lber.h> +.LP +.BI "void *ber_memalloc(ber_len_t " bytes ");" +.LP +.BI "void *ber_memcalloc(ber_len_t " nelems ", ber_len_t " bytes ");" +.LP +.BI "void *ber_memrealloc(void *" ptr ", ber_len_t " bytes ");" +.LP +.BI "void ber_memfree(void *" ptr ");" +.LP +.BI "void ber_memvfree(void **" vec ");" +.SH DESCRIPTION +.LP +These routines are used to allocate/deallocate memory used/returned +by the Lightweight BER library as required by +.BR lber-encode (3) +and +.BR lber-decode (3). +.BR ber_memalloc (), +.BR ber_memcalloc (), +.BR ber_memrealloc (), +and +.BR ber_memfree () +are used exactly like the standard +.BR malloc (3), +.BR calloc (3), +.BR realloc (3), +and +.BR free (3) +routines, respectively. The +.BR ber_memvfree () +routine is used to free a dynamically allocated array of pointers to +arbitrary dynamically allocated objects. +.SH SEE ALSO +.BR lber-decode (3), +.BR lber-encode (3), +.BR lber-types (3) +.LP +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/lber-sockbuf.3 b/doc/man/man3/lber-sockbuf.3 new file mode 100644 index 0000000..383ccda --- /dev/null +++ b/doc/man/man3/lber-sockbuf.3 @@ -0,0 +1,199 @@ +.TH LBER_SOCKBUF 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_sockbuf_alloc, ber_sockbuf_free, ber_sockbuf_ctrl, ber_sockbuf_add_io, ber_sockbuf_remove_io, Sockbuf_IO \- OpenLDAP LBER I/O infrastructure +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include <lber.h> +.LP +.B Sockbuf *ber_sockbuf_alloc( void ); +.LP +.BI "void ber_sockbuf_free(Sockbuf *" sb ");" +.LP +.BI "int ber_sockbuf_ctrl(Sockbuf *" sb ", int " opt ", void *" arg ");" +.LP +.BI "int ber_sockbuf_add_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ", void *" arg ");" +.LP +.BI "int ber_sockbuf_remove_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ");" +.LP +.nf +.B typedef struct sockbuf_io_desc { +.BI "int " sbiod_level ";" +.BI "Sockbuf *" sbiod_sb ";" +.BI "Sockbuf_IO *" sbiod_io ";" +.BI "void *" sbiod_pvt ";" +.BI "struct sockbuf_io_desc *" sbiod_next ";" +.B } Sockbuf_IO_Desc; +.LP +.B typedef struct sockbuf_io { +.BI "int (*" sbi_setup ")(Sockbuf_IO_Desc *" sbiod ", void *" arg ");" +.BI "int (*" sbi_remove ")(Sockbuf_IO_Desc *" sbiod ");" +.BI "int (*" sbi_ctrl ")(Sockbuf_IO_Desc *" sbiod ", int " opt ", void *" arg ");" +.BI "ber_slen_t (*" sbi_read ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");" +.BI "ber_slen_t (*" sbi_write ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");" +.BI "int (*" sbi_close ")(Sockbuf_IO_Desc *" sbiod ");" +.B } Sockbuf_IO; + +.SH DESCRIPTION +.LP +These routines are used to manage the low level I/O operations performed +by the Lightweight BER library. They are called implicitly by the other +libraries and usually do not need to be called directly from applications. +The I/O framework is modularized and new transport layers can be supported +by appropriately defining a +.B Sockbuf_IO +structure and installing it onto an existing +.BR Sockbuf . +.B Sockbuf +structures are allocated and freed by +.BR ber_sockbuf_alloc () +and +.BR ber_sockbuf_free (), +respectively. The +.BR ber_sockbuf_ctrl () +function is used to get and set options related to a +.B Sockbuf +or to a specific I/O layer of the +.BR Sockbuf . +The +.BR ber_sockbuf_add_io () +and +.BR ber_sockbuf_remove_io () +functions are used to add and remove specific I/O layers on a +.BR Sockbuf . + +Options for +.BR ber_sockbuf_ctrl () +include: +.TP +.B LBER_SB_OPT_HAS_IO +Takes a +.B Sockbuf_IO * +argument and returns 1 if the given handler is installed +on the +.BR Sockbuf , +otherwise returns 0. +.TP +.B LBER_SB_OPT_GET_FD +Retrieves the file descriptor associated to the +.BR Sockbuf ; +.B arg +must be a +.BR "ber_socket_t *" . +The return value will be 1 if a valid descriptor was present, \-1 otherwise. +.TP +.B LBER_SB_OPT_SET_FD +Sets the file descriptor of the +.B Sockbuf +to the descriptor pointed to by +.BR arg ; +.B arg +must be a +.BR "ber_socket_t *" . +The return value will always be 1. +.TP +.B LBER_SB_OPT_SET_NONBLOCK +Toggles the non-blocking state of the file descriptor associated to +the +.BR Sockbuf . +.B arg +should be NULL to disable and non-NULL to enable the non-blocking state. +The return value will be 1 for success, \-1 otherwise. +.TP +.B LBER_SB_OPT_DRAIN +Flush (read and discard) all available input on the +.BR Sockbuf . +The return value will be 1. +.TP +.B LBER_SB_OPT_NEEDS_READ +Returns non-zero if input is waiting to be read. +.TP +.B LBER_SB_OPT_NEEDS_WRITE +Returns non-zero if the +.B Sockbuf +is ready to be written. +.TP +.B LBER_SB_OPT_GET_MAX_INCOMING +Returns the maximum allowed size of an incoming message; +.B arg +must be a +.BR "ber_len_t *" . +The return value will be 1. +.TP +.B LBER_SB_OPT_SET_MAX_INCOMING +Sets the maximum allowed size of an incoming message; +.B arg +must be a +.BR "ber_len_t *" . +The return value will be 1. + +.LP +Options not in this list will be passed down to each +.B Sockbuf_IO +handler in turn until one of them processes it. If the option is not handled +.BR ber_sockbuf_ctrl () +will return 0. + +.LP +Multiple +.B Sockbuf_IO +handlers can be stacked in multiple layers to provide various functionality. +Currently defined layers include +.TP +.B LBER_SBIOD_LEVEL_PROVIDER +the lowest layer, talking directly to a network +.TP +.B LBER_SBIOD_LEVEL_TRANSPORT +an intermediate layer +.TP +.B LBER_SBIOD_LEVEL_APPLICATION +a higher layer +.LP +Currently defined +.B Sockbuf_IO +handlers in liblber include +.TP +.B ber_sockbuf_io_tcp +The default stream-oriented provider +.TP +.B ber_sockbuf_io_fd +A stream-oriented provider for local IPC sockets +.TP +.B ber_sockbuf_io_dgram +A datagram-oriented provider. This handler is only present if the liblber +library was built with LDAP_CONNECTIONLESS defined. +.TP +.B ber_sockbuf_io_readahead +A buffering layer, usually used with a datagram provider to hide the +datagram semantics from upper layers. +.TP +.B ber_sockbuf_io_debug +A generic handler that outputs hex dumps of all traffic. This handler +may be inserted multiple times at arbitrary layers to show the flow +of data between other handlers. +.LP +Additional handlers may be present in libldap if support for them was +enabled: +.TP +.B ldap_pvt_sockbuf_io_sasl +An application layer handler for SASL encoding/decoding. +.TP +.B sb_tls_sbio +A transport layer handler for SSL/TLS encoding/decoding. Note that this +handler is private to the library and is not exposed in the API. +.LP +The provided handlers are all instantiated implicitly by libldap, and +applications generally will not need to directly manipulate them. + +.SH SEE ALSO +.BR lber-decode (3), +.BR lber-encode (3), +.BR lber-types (3), +.BR ldap_get_option (3) + +.LP +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/lber-types.3 b/doc/man/man3/lber-types.3 new file mode 100644 index 0000000..29cfc2c --- /dev/null +++ b/doc/man/man3/lber-types.3 @@ -0,0 +1,188 @@ +.TH LBER_TYPES 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include <lber.h> +.LP +.nf +.ft B +typedef impl_tag_t ber_tag_t; +typedef impl_int_t ber_int_t; +typedef impl_uint_t ber_uint_t; +typedef impl_len_t ber_len_t; +typedef impl_slen_t ber_slen_t; + +typedef struct berval { + ber_len_t bv_len; + char *bv_val; +} BerValue, *BerVarray; + +typedef struct berelement BerElement; +.ft +.fi +.LP +.BI "void ber_bvfree(struct berval *" bv ");" +.LP +.BI "void ber_bvecfree(struct berval **" bvec ");" +.LP +.BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" +.LP +.BI "void ber_bvarray_free(struct berval *" bvarray ");" +.LP +.BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" +.LP +.BI "struct berval *ber_bvdup(const struct berval *" bv ");" +.LP +.BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" +.LP +.BI "struct berval *ber_bvstr(const char *" str ");" +.LP +.BI "struct berval *ber_bvstrdup(const char *" str ");" +.LP +.BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" +.LP +.BI "BerElement *ber_alloc_t(int " options ");" +.LP +.BI "BerElement *ber_init(struct berval *" bv ");" +.LP +.BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" +.LP +.BI "void ber_free(BerElement *" ber ", int " freebuf ");" +.SH DESCRIPTION +.LP +The following are the basic types and structures defined for use +with the Lightweight BER library. +.LP +.B ber_int_t +is a signed integer of at least 32 bits. It is commonly equivalent to +.BR int . +.B ber_uint_t +is the unsigned variant of +.BR ber_int_t . +.LP +.B ber_len_t +is an unsigned integer of at least 32 bits used to represent a length. +It is commonly equivalent to a +.BR size_t . +.B ber_slen_t +is the signed variant to +.BR ber_len_t . +.LP +.B ber_tag_t +is an unsigned integer of at least 32 bits used to represent a +BER tag. It is commonly equivalent to a +.BR unsigned\ long . +.LP +The actual definitions of the integral impl_TYPE_t types are platform +specific. +.LP +.BR BerValue , +commonly used as +.BR struct\ berval , +is used to hold an arbitrary sequence of octets. +.B bv_val +points to +.B bv_len +octets. +.B bv_val +is not necessarily terminated by a NULL (zero) octet. +.BR ber_bvfree () +frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP +is NULL, the routine does nothing. +.LP +.BR ber_bvecfree () +frees an array of BerValues (and the array), pointed to by \fIbvec\fP, +returned from this API. If \fIbvec\fP is NULL, the routine does nothing. +.BR ber_bvecadd () +appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array +is allocated as needed. The end of the array is marked by a NULL pointer. +.LP +.BR ber_bvarray_free () +frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, +returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. +.BR ber_bvarray_add () +appends the contents of the BerValue pointed to by \fIbv\fP to the +\fIbvarray\fP array. Space for the new element is allocated as needed. +The end of the array is marked by a BerValue with a NULL bv_val field. +.LP +.BR ber_bvdup () +returns a copy of a BerValue. The routine returns NULL upon error +(e.g. out of memory). The caller should use +.BR ber_bvfree () +to deallocate the resulting BerValue. +.BR ber_dupbv () +copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a +new BerValue will be allocated to hold the copy. The routine returns NULL +upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is +NULL the caller should use +.BR ber_bvfree () +to deallocate the resulting BerValue, otherwise +.BR ber_memfree () +should be used to deallocate the \fIdst->bv_val\fP. (The +.BR ber_bvdup () +function is internally implemented as ber_dupbv(NULL, bv). +.BR ber_bvdup () +is provided only for compatibility with an expired draft of the LDAP C API; +.BR ber_dupbv () +is the preferred interface.) +.LP +.BR ber_bvstr () +returns a BerValue containing the string pointed to by \fIstr\fP. +.BR ber_bvstrdup () +returns a BerValue containing a copy of the string pointed to by \fIstr\fP. +.BR ber_str2bv () +returns a BerValue containing the string pointed to by \fIstr\fP, whose +length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, +the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the +number of bytes to copy will be determined by +.BR strlen (3), +otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result +will be stored in the given BerValue, otherwise a new BerValue will be +allocated to store the result. NOTE: Both +.BR ber_bvstr () +and +.BR ber_bvstrdup () +are implemented as macros using +.BR ber_str2bv () +in this version of the library. +.LP +.B BerElement +is an opaque structure used to maintain state information used in +encoding and decoding. +.BR ber_alloc_t () +is used to create an empty BerElement structure. If +.B LBER_USE_DER +is specified for the +.I options +parameter then data lengths for data written to the BerElement will be +encoded in the minimal number of octets required, otherwise they will +always be written as four byte values. +.BR ber_init () +creates a BerElement structure that is initialized with a copy of the +data in its +.I bv +parameter. +.BR ber_init2 () +initializes an existing BerElement +.I ber +using the data in the +.I bv +parameter. The data is referenced directly, not copied. The +.I options +parameter is the same as for +.BR ber_alloc_t (). +.BR ber_free () +frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine +does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. +.SH SEE ALSO +.BR lber-encode (3), +.BR lber-decode (3), +.BR lber-memory (3) +.LP +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/lber-types.3.links b/doc/man/man3/lber-types.3.links new file mode 100644 index 0000000..89f90fb --- /dev/null +++ b/doc/man/man3/lber-types.3.links @@ -0,0 +1,11 @@ +ber_bvarray_add.3 +ber_bvarray_free.3 +ber_bvdup.3 +ber_bvecadd.3 +ber_bvecfree.3 +ber_bvfree.3 +ber_bvstr.3 +ber_bvstrdup.3 +ber_dupbv.3 +ber_free.3 +ber_str2bv.3 diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3 new file mode 100644 index 0000000..25fa0f0 --- /dev/null +++ b/doc/man/man3/ldap.3 @@ -0,0 +1,278 @@ +.TH LDAP 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap \- OpenLDAP Lightweight Directory Access Protocol API +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.ft +.fi +.SH DESCRIPTION +.LP +The Lightweight Directory Access Protocol (LDAP) (RFC 4510) provides +access to X.500 directory services. These services may be stand\-alone +or part of a distributed directory service. This client API supports +LDAP over TCP (RFC 4511), LDAP over TLS/SSL, and LDAP over IPC (UNIX +domain sockets). This API supports SASL (RFC 4513) and Start TLS +(RFC 4513) as well as a number of protocol extensions. This API is +loosely based upon IETF/LDAPEXT C LDAP API draft specification, a (orphaned) +work in progress. +.LP +The OpenLDAP Software package includes a stand\-alone server in +.BR slapd (8), +various LDAP clients, and an LDAP client library used to provide +programmatic access to the LDAP protocol. This man page gives an +overview of the LDAP library routines. +.LP +Both synchronous and asynchronous APIs are provided. Also included are +various routines to parse the results returned from these routines. +These routines are found in the \-lldap library. +.LP +The basic interaction is as follows. A session handle is +created using +.BR ldap_initialize (3) +and set the protocol version to 3 by calling +.BR ldap_set_option (3). +The underlying session is established first operation is +issued. This would generally be a Start TLS or Bind operation, +or a Search operation to read attributes of the Root DSE. +A Start TLS operation is performed by calling +.BR ldap_start_tls_s (3). +A LDAP bind operation is performed by calling +.BR ldap_sasl_bind (3) +or one of its friends. +A Search operation is performed by calling ldap_search_ext_s(3) +or one of its friends. + +Subsequently, additional operations are performed +by calling one of the synchronous or asynchronous routines (e.g., +.BR ldap_compare_ext_s (3) +or +.BR ldap_compare_ext (3) +followed by +.BR ldap_result (3)). +Results returned from these routines are interpreted by calling the +LDAP parsing routines such as +.BR ldap_parse_result (3). +The LDAP association and underlying connection is terminated by calling +.BR ldap_unbind_ext (3). +Errors can be interpreted by calling +.BR ldap_err2string (3). +.SH LDAP versions +This library supports version 3 of the Lightweight Directory Access +Protocol (LDAPv3) as defined in RFC 4510. It also supports a variant +of version 2 of LDAP as defined by U-Mich LDAP and, to some degree, +RFC 1777. Version 2 (all variants) are considered obsolete. +Version 3 should be used instead. +.LP +For backwards compatibility reasons, the library defaults to version 2. +Hence, all new applications (and all actively maintained applications) +should use +.BR ldap_set_option (3) +to select version 3. The library manual pages assume version 3 +has been selected. +.SH INPUT and OUTPUT PARAMETERS +All character string input/output is expected to be/is UTF-8 +encoded Unicode (version 3.2). +.LP +Distinguished names (DN) (and relative distinguished names (RDN) to +be passed to the LDAP routines should conform to RFC 4514 UTF-8 +string representation. +.LP +Search filters to be passed to the search routines are to be +constructed by hand and should conform to RFC 4515 UTF-8 +string representation. +.LP +LDAP URLs to be passed to routines are expected to conform +to RFC 4516 format. The +.BR ldap_url (3) +routines can be used to work with LDAP URLs. +.LP +LDAP controls to be passed to routines can be manipulated using the +.BR ldap_controls (3) +routines. +.SH DISPLAYING RESULTS +Results obtained from the search routines can be output by hand, +by calling +.BR ldap_first_entry (3) +and +.BR ldap_next_entry (3) +to step through +the entries returned, +.BR ldap_first_attribute (3) +and +.BR ldap_next_attribute (3) +to step through an entry's attributes, and +.BR ldap_get_values (3) +to retrieve a given attribute's values. Attribute values +may or may not be displayable. +.SH UTILITY ROUTINES +Also provided are various utility routines. The +.BR ldap_sort (3) +routines are used to sort the entries and values returned via +the ldap search routines. +.SH DEPRECATED INTERFACES +A number of interfaces are now considered deprecated. For instance, +ldap_add(3) is deprecated in favor of ldap_add_ext(3). +.so Deprecated +.SH BER LIBRARY +Also included in the distribution is a set of lightweight Basic +Encoding Rules routines. These routines are used by the LDAP library +routines to encode and decode LDAP protocol elements using the +(slightly simplified) Basic Encoding Rules defined by LDAP. They are +not normally used directly by an LDAP application program except +in the handling of controls and extended operations. The +routines provide a printf and scanf\-like interface, as well as +lower\-level access. These routines are discussed in +.BR lber\-decode (3), +.BR lber\-encode (3), +.BR lber\-memory (3), +and +.BR lber\-types (3). +.SH INDEX +.TP 20 +.SM ldap_initialize(3) +initialize the LDAP library without opening a connection to a server +.TP +.SM ldap_result(3) +wait for the result from an asynchronous operation +.TP +.SM ldap_abandon_ext(3) +abandon (abort) an asynchronous operation +.TP +.SM ldap_add_ext(3) +asynchronously add an entry +.TP +.SM ldap_add_ext_s(3) +synchronously add an entry +.TP +.SM ldap_sasl_bind(3) +asynchronously bind to the directory +.TP +.SM ldap_sasl_bind_s(3) +synchronously bind to the directory +.TP +.SM ldap_unbind_ext(3) +synchronously unbind from the LDAP server and close the connection +.TP +.SM ldap_unbind(3) and ldap_unbind_s(3) are +equivalent to +.BR ldap_unbind_ext (3) +.TP +.SM ldap_memfree(3) +dispose of memory allocated by LDAP routines. +.TP +.SM ldap_compare_ext(3) +asynchronously compare to a directory entry +.TP +.SM ldap_compare_ext_s(3) +synchronously compare to a directory entry +.TP +.SM ldap_delete_ext(3) +asynchronously delete an entry +.TP +.SM ldap_delete_ext_s(3) +synchronously delete an entry +.TP +.SM ld_errno(3) +LDAP error indication +.TP +.SM ldap_errlist(3) +list of LDAP errors and their meanings +.TP +.SM ldap_err2string(3) +convert LDAP error indication to a string +.TP +.SM ldap_extended_operation(3) +asynchronously perform an arbitrary extended operation +.TP +.SM ldap_extended_operation_s(3) +synchronously perform an arbitrary extended operation +.TP +.SM ldap_first_attribute(3) +return first attribute name in an entry +.TP +.SM ldap_next_attribute(3) +return next attribute name in an entry +.TP +.SM ldap_first_entry(3) +return first entry in a chain of search results +.TP +.SM ldap_next_entry(3) +return next entry in a chain of search results +.TP +.SM ldap_count_entries(3) +return number of entries in a search result +.TP +.SM ldap_get_dn(3) +extract the DN from an entry +.TP +.SM ldap_get_values_len(3) +return an attribute's values with lengths +.TP +.SM ldap_value_free_len(3) +free memory allocated by ldap_get_values_len(3) +.TP +.SM ldap_count_values_len(3) +return number of values +.TP +.SM ldap_modify_ext(3) +asynchronously modify an entry +.TP +.SM ldap_modify_ext_s(3) +synchronously modify an entry +.TP +.SM ldap_mods_free(3) +free array of pointers to mod structures used by ldap_modify_ext(3) +.TP +.SM ldap_rename(3) +asynchronously rename an entry +.TP +.SM ldap_rename_s(3) +synchronously rename an entry +.TP +.SM ldap_msgfree(3) +free results allocated by ldap_result(3) +.TP +.SM ldap_msgtype(3) +return the message type of a message from ldap_result(3) +.TP +.SM ldap_msgid(3) +return the message id of a message from ldap_result(3) +.TP +.SM ldap_search_ext(3) +asynchronously search the directory +.TP +.SM ldap_search_ext_s(3) +synchronously search the directory +.TP +.SM ldap_is_ldap_url(3) +check a URL string to see if it is an LDAP URL +.TP +.SM ldap_url_parse(3) +break up an LDAP URL string into its components +.TP +.SM ldap_sort_entries(3) +sort a list of search results +.TP +.SM ldap_sort_values(3) +sort a list of attribute values +.TP +.SM ldap_sort_strcasecmp(3) +case insensitive string comparison +.SH SEE ALSO +.BR ldap.conf (5), +.BR slapd (8), +.BR draft-ietf-ldapext-ldap-c-api-xx.txt \ <http://www.ietf.org> +.SH ACKNOWLEDGEMENTS +.so ../Project +.LP +These API manual pages are loosely based upon descriptions provided +in the IETF/LDAPEXT C LDAP API Internet Draft, a (orphaned) work +in progress. + diff --git a/doc/man/man3/ldap_abandon.3 b/doc/man/man3/ldap_abandon.3 new file mode 100644 index 0000000..7beb37a --- /dev/null +++ b/doc/man/man3/ldap_abandon.3 @@ -0,0 +1,69 @@ +.TH LDAP_ABANDON 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_abandon_ext \- Abandon an LDAP operation in progress +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.B +#include <ldap.h> +.LP +.ft B +int ldap_abandon_ext( +.RS +.ft B +LDAP *\fIld\fB, +Bint \fImsgid\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB ); +.RE +.fi +.SH DESCRIPTION +The +.B ldap_abandon_ext() +routine is used to send a LDAP Abandon request for an +operation in progress. The \fImsgid\fP passed should be the +message id of an outstanding LDAP operation, such as returned by +.BR ldap_search_ext (3). +.LP +.BR ldap_abandon_ext () +checks to see if the result of the operation has already come in. If it +has, it deletes it from the queue of pending messages. If not, +it sends an LDAP abandon request to the LDAP server. +.LP +The caller can expect that the result of an abandoned operation +will not be returned from a future call to +.BR ldap_result (3). +.LP +.B ldap_abandon_ext() +allows server and client controls to be passed in via the +.I sctrls +and +.I cctrls +parameters, respectively. +.LP +.B ldap_abandon_ext() +returns a code indicating success or, in the case of failure, the +nature of the failure. See +.BR ldap_error (3) +for details. +.SH DEPRECATED INTERFACES +The +.B ldap_abandon() +routine is deprecated in favor of the +.B ldap_abandon_ext() +routine. +.LP +.so Deprecated + +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_result (3), +.BR ldap_search_ext (3) +.SH ACKNOWLEDGEMENTS +.so ../Project + diff --git a/doc/man/man3/ldap_abandon.3.links b/doc/man/man3/ldap_abandon.3.links new file mode 100644 index 0000000..3b7bc3f --- /dev/null +++ b/doc/man/man3/ldap_abandon.3.links @@ -0,0 +1 @@ +ldap_abandon_ext.3 diff --git a/doc/man/man3/ldap_add.3 b/doc/man/man3/ldap_add.3 new file mode 100644 index 0000000..9fdc695 --- /dev/null +++ b/doc/man/man3/ldap_add.3 @@ -0,0 +1,81 @@ +.TH LDAP_ADD 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.ft B +#include <ldap.h> +.LP +.ft B +.nf +int ldap_add_ext( +.RS +.ft B +LDAP *\fIld, +const char *\fIdn\fB, +LDAPMod **\fIattrs\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB, +int *\fImsgidp\fB ); +.RE +.LP +.ft B +.nf +int ldap_add_ext_s( +.RS +LDAP *\fIld\fB, +const char *\fIdn\fB, +LDAPMod **\fIattrs\fB, +LDAPControl *\fIsctrls\fB, +LDAPControl *\fIcctrls\fB ); +.RE +.fi +.SH DESCRIPTION +The +.B ldap_add_ext_s() +routine is used to perform an LDAP add operation. +It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a +null-terminated array of the entry's attributes. The LDAPMod structure +is used to represent attributes, with the \fImod_type\fP and +\fImod_values\fP fields being used as described under +.BR ldap_modify_ext (3), +and the \fIldap_op\fP field being used only if you need to specify +the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. +.LP +Note that all entries except that +specified by the last component in the given DN must already exist. +.B ldap_add_ext_s() +returns an code indicating success or, in the case of failure, +indicating the nature of failure of the operation. See +.BR ldap_error (3) +for more details. +.LP +The +.B ldap_add_ext() +routine works just like +.BR ldap_add_ext_s() , +but it is asynchronous. It returns the message id of the request it +initiated. The result of this operation can be obtained by calling +.BR ldap_result (3). +.SH DEPRECATED INTERFACES +The +.BR ldap_add () +and +.BR ldap_add_s () +routines are deprecated in favor of the +.BR ldap_add_ext () +and +.BR ldap_add_ext_s () +routines, respectively. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_modify (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_add.3.links b/doc/man/man3/ldap_add.3.links new file mode 100644 index 0000000..8114ef1 --- /dev/null +++ b/doc/man/man3/ldap_add.3.links @@ -0,0 +1,3 @@ +ldap_add_s.3 +ldap_add_ext.3 +ldap_add_ext_s.3 diff --git a/doc/man/man3/ldap_bind.3 b/doc/man/man3/ldap_bind.3 new file mode 100644 index 0000000..f70182e --- /dev/null +++ b/doc/man/man3/ldap_bind.3 @@ -0,0 +1,337 @@ +.TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.B #include <ldap.h> +.LP +.BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," +.RS +.BI "int " method ");" +.RE +.LP +.BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," +.RS +.BI "int " method ");" +.RE +.LP +.BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" +.LP +.BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" +.LP +.BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," +.RS +.BI "struct berval *" cred ", LDAPControl *" sctrls "[]," +.BI "LDAPControl *" cctrls "[], int *" msgidp ");" +.RE +.LP +.BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," +.RS +.BI "struct berval *" cred ", LDAPControl *" sctrls "[]," +.BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" +.RE +.LP +.BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," +.RS +.BI "struct berval **" servercredp ", int " freeit ");" +.RE +.LP +.BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," +.RS +.BI "const char *" mechs "," +.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," +.BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," +.BI "void *" defaults ");" +.RE +.LP +.BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," +.RS +.BI "const char *" mechs "," +.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," +.BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," +.BI "void *" defaults ", LDAPMessage *" result "," +.BI "const char **" rmechp ", int *" msgidp ");" +.RE +.LP +.BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" +.LP +.BI "int ldap_unbind(LDAP *" ld ");" +.LP +.BI "int ldap_unbind_s(LDAP *" ld ");" +.LP +.BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," +.RS +.BI "LDAPControl *" cctrls "[]);" +.RE +.LP +.BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," +.RS +.BI "LDAPControl *" cctrls "[]);" +.RE +.LP +.BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" +.LP +.BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" +.SH DESCRIPTION +.LP +These routines provide various interfaces to the LDAP bind operation. +After an association with an LDAP server is made using +.BR ldap_init (3), +an LDAP bind operation should be performed before other operations are +attempted over the connection. An LDAP bind is required when using +Version 2 of the LDAP protocol; it is optional for Version 3 but is +usually needed due to security considerations. +.LP +There are three types of bind calls, ones providing simple authentication, +ones providing SASL authentication, and general routines capable of doing +either simple or SASL authentication. +.LP +.B SASL +(Simple Authentication and Security Layer) +can negotiate one of many different kinds of authentication. +Both synchronous and asynchronous versions of each variant of the bind +call are provided. All routines +take \fIld\fP as their first parameter, as returned from +.BR ldap_init (3). +.SH SIMPLE AUTHENTICATION +The simplest form of the bind call is +.BR ldap_simple_bind_s() . +It takes the DN to bind as in \fIwho\fP, and the userPassword associated +with the entry in \fIpasswd\fP. It returns an LDAP error indication +(see +.BR ldap_error (3)). +The +.B ldap_simple_bind() +call is asynchronous, +taking the same parameters but only initiating the bind operation and +returning the message id of the request it sent. The result of the +operation can be obtained by a subsequent call to +.BR ldap_result (3). +The +.B ldap_sasl_bind_s() +and asynchronous +.B ldap_sasl_bind() +functions can also be used to make a simple bind by using +LDAP_SASL_SIMPLE as the SASL mechanism. +.SH GENERAL AUTHENTICATION +The +.B ldap_bind() +and +.B ldap_bind_s() +routines can be used when the +authentication method to use needs to be selected at runtime. They +both take an extra \fImethod\fP parameter selecting the authentication +method to use. It should be set to LDAP_AUTH_SIMPLE +to select simple authentication. +.B ldap_bind() +returns the message id of the request it initiates. +.B ldap_bind_s() +returns an LDAP error indication. +.SH SASL AUTHENTICATION +For SASL binds the server always ignores any provided DN, so the +.I dn +parameter should always be NULL. +.BR ldap_sasl_bind_s () +sends a single SASL bind request with the given SASL +.I mechanism +and credentials in the +.I cred +parameter. The format of the credentials depends on the particular +SASL mechanism in use. For mechanisms that provide mutual authentication +the server's credentials will be returned in the +.I servercredp +parameter. +The routine returns an LDAP error indication (see +.BR ldap_error (3)). +The +.BR ldap_sasl_bind () +call is asynchronous, taking the same parameters but only sending the +request and returning the message id of the request it sent. The result of +the operation can be obtained by a subsequent +call to +.BR ldap_result (3). +The result must be additionally parsed by +.BR ldap_parse_sasl_bind_result () +to obtain any server credentials sent from the server. + +Any returned server credentials should be freed using +.BR ber_bvfree (). +.LP +Many SASL mechanisms require multiple message exchanges to perform a +complete authentication. Applications should generally use +.BR ldap_sasl_interactive_bind_s () +rather than calling the basic +.BR ldap_sasl_bind () +functions directly. The +.I mechs +parameter should contain a space-separated list of candidate mechanisms +to use. If this parameter is NULL or empty the library will query +the supportedSASLMechanisms attribute from the server's rootDSE +for the list of SASL mechanisms the server supports. The +.I flags +parameter controls the interaction used to retrieve any necessary +SASL authentication parameters and should be one of: +.TP +LDAP_SASL_AUTOMATIC +use defaults if available, prompt otherwise +.TP +LDAP_SASL_INTERACTIVE +always prompt +.TP +LDAP_SASL_QUIET +never prompt +.LP +The +.I interact +function uses the provided +.I defaults +to handle requests from the SASL library for particular authentication +parameters. There is no defined format for the +.I defaults +information; +it is up to the caller to use whatever format is appropriate for the +supplied +.I interact +function. +The +.I sasl_interact +parameter comes from the underlying SASL library. When used with Cyrus SASL +this is an array of +.B sasl_interact_t +structures. The Cyrus SASL library will prompt for a variety of inputs, +including: +.TP +SASL_CB_GETREALM +the realm for the authentication attempt +.TP +SASL_CB_AUTHNAME +the username to authenticate +.TP +SASL_CB_PASS +the password for the provided username +.TP +SASL_CB_USER +the username to use for proxy authorization +.TP +SASL_CB_NOECHOPROMPT +generic prompt for input with input echoing disabled +.TP +SASL_CB_ECHOPROMPT +generic prompt for input with input echoing enabled +.TP +SASL_CB_LIST_END +indicates the end of the array of prompts +.LP +See the Cyrus SASL documentation for more details. +.LP +Applications which need to manage connections asynchronously may use +.BR ldap_sasl_interactive_bind () +instead of the synchronous version. +A valid mechs parameter must be supplied, otherwise the library will +be forced to query the server for a list of supported mechanisms, +and this query will be performed synchronously. +The other parameters are the same as +for the synchronous function, with three additional parameters. +The actual SASL mechanism that was used, and the message ID for use +with +.BR ldap_result () +will be returned in rmechp and msgidp, respectively. +The value in rmechp must not be modified by the caller and must be +passed back on each subsequent call. The message obtained from +.BR ldap_result () +must be passed in the result parameter. +This parameter must be NULL when initiating a new Bind. The caller +must free the result message after each call using +.BR ldap_msgfree (). +The +.BR ldap_sasl_interactive_bind () +function returns an LDAP result code. If the code is +LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and +this function must be called again with the next result from the server. +.SH REBINDING +.LP +The +.B ldap_set_rebind_proc +function() sets the process to use for binding when an operation returns a +referral. This function is used when an application needs to bind to another server +in order to follow a referral or search continuation reference. +.LP +The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, +the arbitrary data like state information which the client might need to properly rebind. +The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries +to use the rebind function. Use the +.BR ldap_set_option +function to set the value. +.LP +The rebind function parameters are as follows: +.LP +The \fIld\fP parameter must be used by the application when binding to the +referred server if the application wants the libraries to follow the referral. +.LP +The \fIurl\fP parameter points to the URL referral string received from the LDAP server. +The LDAP application can use the +.BR ldap_url_parse (3) +function to parse the string into its components. +.LP +The \fIrequest\fP parameter specifies the type of request that generated the referral. +.LP +The \fImsgid\fP parameter specifies the message ID of the request generating the referral. +.LP +The \fIparams\fP parameter is the same value as passed originally to the +.BR ldap_set_rebind_proc () +function. +.LP +The LDAP libraries set all the parameters when they call the rebind function. The application +should not attempt to free either the ld or the url structures in the rebind function. +.LP +The application must supply to the rebind function the required authentication information such as, +user name, password, and certificates. The rebind function must use a synchronous bind method. +.SH UNBINDING +The +.B ldap_unbind() +call is used to unbind from the directory, +terminate the current association, and free the resources contained +in the \fIld\fP structure. Once it is called, the connection to +the LDAP server is closed, and the \fIld\fP structure is invalid. +The +.B ldap_unbind_s() +call is just another name for +.BR ldap_unbind() ; +both of these calls are synchronous in nature. +.LP +The +.B ldap_unbind_ext() +and +.B ldap_unbind_ext_s() +allows the operations to specify controls. +.SH ERRORS +Asynchronous routines will return \-1 in case of error, setting the +\fIld_errno\fP parameter of the \fIld\fP structure. Synchronous +routines return whatever \fIld_errno\fP is set to. See +.BR ldap_error (3) +for more information. +.SH NOTES +If an anonymous bind is sufficient for the application, the rebind process +need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option +set to ON (default value) will automatically follow referrals using an anonymous bind. +.LP +If the application needs stronger authentication than an anonymous bind, +you need to provide a rebind process for that authentication method. +The bind method must be synchronous. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_open (3), +.BR ldap_set_option (3), +.BR ldap_url_parse (3) +.B RFC 4422 +(http://www.rfc-editor.org), +.B Cyrus SASL +(http://asg.web.cmu.edu/sasl/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_bind.3.links b/doc/man/man3/ldap_bind.3.links new file mode 100644 index 0000000..ffaedd5 --- /dev/null +++ b/doc/man/man3/ldap_bind.3.links @@ -0,0 +1,10 @@ +ldap_bind_s.3 +ldap_simple_bind.3 +ldap_simple_bind_s.3 +ldap_sasl_bind.3 +ldap_sasl_bind_s.3 +ldap_unbind.3 +ldap_unbind_ext.3 +ldap_unbind_s.3 +ldap_unbind_ext_s.3 +ldap_set_rebind_proc.3 diff --git a/doc/man/man3/ldap_compare.3 b/doc/man/man3/ldap_compare.3 new file mode 100644 index 0000000..86b3bdd --- /dev/null +++ b/doc/man/man3/ldap_compare.3 @@ -0,0 +1,79 @@ +.TH LDAP_COMPARE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_compare_ext( +.RS +.ft B +LDAP *\fIld\fB, +char *\fIdn\fB, +char *\fIattr\fB, +const struct berval *\fIbvalue\fB, +LDAPControl **\fIserverctrls\fB, +LDAPControl **\fIclientctrls\fB, +int *\fImsgidp\fB ); +.RE +.LP +.ft B +int ldap_compare_ext_s( +.RS +.ft B +LDAP *\fIld\fB, +char *\fIdn\fB, +char *\fIattr\fB, +const struct berval *\fIbvalue\fB, +LDAPControl **\fIserverctrls\fB, +LDAPControl **\fIclientctrls\fB ); +.RE +.SH DESCRIPTION +The +.B ldap_compare_ext_s() +routine is used to perform an LDAP compare operation synchronously. +It takes \fIdn\fP, the DN of the entry upon which to perform the +compare, and \fIattr\fP and \fIvalue\fP, the attribute description and +value to compare to those found in the entry. It returns a code, which +will be LDAP_COMPARE_TRUE if the entry contains the attribute value and +LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is +returned that indicates the nature of the problem. See +.BR ldap (3) +for details. +.LP +The +.B ldap_compare_ext() +routine is used to perform an LDAP compare operation +asynchronously. It takes the same parameters as +.BR ldap_compare_ext_s() , +but provides the message id of the request it initiated in the +integer pointed to \fImsgidp\fP. The result of +the compare can be obtained by a subsequent call to +.BR ldap_result (3). +.LP +Both routines allow server and client controls to be specified to +extend the compare request. +.SH DEPRECATED INTERFACES +The routines +.BR ldap_compare () +and +.BR ldap_compare_s () +are deprecated in favor of +.BR ldap_compare_ext () +and +.BR ldap_compare_ext_s (), +respectively. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_compare.3.links b/doc/man/man3/ldap_compare.3.links new file mode 100644 index 0000000..66821cc --- /dev/null +++ b/doc/man/man3/ldap_compare.3.links @@ -0,0 +1,3 @@ +ldap_compare_s.3 +ldap_compare_ext.3 +ldap_compare_ext_s.3 diff --git a/doc/man/man3/ldap_controls.3 b/doc/man/man3/ldap_controls.3 new file mode 100644 index 0000000..292bb0e --- /dev/null +++ b/doc/man/man3/ldap_controls.3 @@ -0,0 +1,84 @@ +.TH LDAP_CONTROLS 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_control_create, ldap_control_find, ldap_control_dup, +ldap_controls_dup, ldap_control_free, ldap_controls_free +\- LDAP control manipulation routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.B #include <ldap.h> +.LP +.BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" +.LP +.BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" +.LP +.BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" +.LP +.BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" +.LP +.BI "void ldap_control_free(LDAPControl *" ctrl ");" +.LP +.BI "void ldap_controls_free(LDAPControl **" ctrls ");" +.SH DESCRIPTION +These routines are used to manipulate structures used for LDAP controls. + +.BR ldap_control_create () +creates a control with the specified +.I OID +using the contents of the +.I value +parameter for the control value, if any. The content of +.I value +is duplicated if +.I dupval +is non-zero. The +.I iscritical +parameter must be non-zero for a critical control. The created control +is returned in the +.I ctrlp +parameter. The routine returns +.B LDAP_SUCCESS +on success or some other error code on failure. +The content of +.IR value , +for supported control types, can be prepared using helpers provided +by this implementation of libldap, usually in the form +.BR "ldap_create_<control name>_control_value" (). +Otherwise, it can be BER-encoded using the functionalities of liblber. + +.BR ldap_control_find () +searches the NULL-terminated +.I ctrls +array for a control whose OID matches the +.I oid +parameter. The routine returns a pointer to the control if found, +NULL otherwise. +If the parameter +.I nextctrlp +is not NULL, on return it will point to the next control +in the array, and can be passed to the +.BR ldap_control_find () +routine for subsequent calls, to find further occurrences of the same +control type. +The use of this function is discouraged; the recommended way of handling +controls in responses consists in going through the array of controls, +dealing with each of them in the returned order, since it could matter. + +.BR ldap_control_dup () +duplicates an individual control structure, and +.BR ldap_controls_dup () +duplicates a NULL-terminated array of controls. + +.BR ldap_control_free () +frees an individual control structure, and +.BR ldap_controls_free () +frees a NULL-terminated array of controls. + +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_controls.3.links b/doc/man/man3/ldap_controls.3.links new file mode 100644 index 0000000..6c5248f --- /dev/null +++ b/doc/man/man3/ldap_controls.3.links @@ -0,0 +1,6 @@ +ldap_control_create.3 +ldap_control_find.3 +ldap_control_dup.3 +ldap_controls_dup.3 +ldap_control_free.3 +ldap_controls_free.3 diff --git a/doc/man/man3/ldap_delete.3 b/doc/man/man3/ldap_delete.3 new file mode 100644 index 0000000..5086a6d --- /dev/null +++ b/doc/man/man3/ldap_delete.3 @@ -0,0 +1,89 @@ +.TH LDAP_DELETE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_delete_s(ld, dn) +.ft +LDAP *ld; +char *dn; +.LP +.ft B +int ldap_delete(ld, dn) +.ft +LDAP *ld; +char *dn; +.LP +.ft B +int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) +.ft +LDAP *ld; +char *dn; +LDAPControl **serverctrls, **clientctrls; +int *msgidp; +.LP +.ft B +int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) +.ft +LDAP *ld; +char *dn; +LDAPControl **serverctrls, **clientctrls; +.SH DESCRIPTION +The +.B ldap_delete_s() +routine is used to perform an LDAP delete operation +synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. +It returns an LDAP error code, indicating the success or failure of the +operation. +.LP +The +.B ldap_delete() +routine is used to perform an LDAP delete operation +asynchronously. It takes the same parameters as +.BR ldap_delete_s(), +but returns the message id of the request it initiated. The result of +the delete can be obtained by a subsequent call to +.BR ldap_result (3). +.LP +The +.B ldap_delete_ext() +routine allows server and client controls to be +specified to extend the delete request. This routine is asynchronous like +ldap_delete(), but its return value is an LDAP error code. It stores the +message id of the request in the integer pointed to by msgidp. +.LP +The +.B ldap_delete_ext_s() +routine is the synchronous version of +.BR ldap_delete_ext(). +It also returns an LDAP error code indicating success +or failure of the operation. +.SH ERRORS +.B ldap_delete_s() +returns an LDAP error code which can be interpreted +by calling one of +.BR ldap_perror (3) +and friends. +.B ldap_delete() +returns \-1 if something went wrong initiating the request. It returns the +non-negative message id of the request if things went ok. +.LP +.B ldap_delete_ext() +and +.B ldap_delete_ext_s() +return some Non-zero value if +something went wrong initiating the request, else return 0. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_delete.3.links b/doc/man/man3/ldap_delete.3.links new file mode 100644 index 0000000..d4eac2f --- /dev/null +++ b/doc/man/man3/ldap_delete.3.links @@ -0,0 +1,3 @@ +ldap_delete_s.3 +ldap_delete_ext.3 +ldap_delete_ext_s.3 diff --git a/doc/man/man3/ldap_dup.3 b/doc/man/man3/ldap_dup.3 new file mode 100644 index 0000000..945ca54 --- /dev/null +++ b/doc/man/man3/ldap_dup.3 @@ -0,0 +1,125 @@ +.TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +LDAP *ldap_dup( +.RS +.ft B +LDAP *\fIold\fB ); +.RE +.LP +.ft B +int ldap_destroy( +.RS +.ft B +LDAP *\fIold\fB ); +.RE +.SH DESCRIPTION +.LP +.B ldap_dup() +duplicates an existing LDAP +.RB ( "LDAP *" ) +session handle. +The new session handle may be used concurrently with the +original session handle. +In a threaded environment, different threads may execute concurrent +requests on the same connection/session without fear of contamination. +Each session handle manages its own private error results. +.LP +.B ldap_destroy() +destroys an existing session handle. +.LP +The +.B ldap_dup() +and +.B ldap_destroy() +functions are used in conjunction with a "thread safe" version +of +.B libldap +to enable operation thread safe API calls, so that a single session +may be simultaneously used across multiple threads with consistent +error handling. +.LP +When a session is created through the use of one of the session creation +functions including +.BR ldap_open (3), +.BR ldap_init (3), +.BR ldap_initialize (3) +or +.BR ldap_init_fd (3) +an +.B "LDAP *" +session handle is returned to the application. +The session handle may be shared amongst threads, however the +error codes are unique to a session handle. +Multiple threads performing different operations using the same +session handle will result in inconsistent error codes and +return values. +.LP +To prevent this confusion, +.B ldap_dup() +is used duplicate an existing session handle so that multiple threads +can share the session, and maintain consistent error information +and results. +.LP +The message queues for a session are shared between sibling session handles. +Results of operations on a sibling session handles are accessible +to all the sibling session handles. +Applications desiring results associated with a specific operation +should provide the appropriate msgid to +.BR ldap_result() . +Applications should avoid calling +.B ldap_result() +with +.B LDAP_RES_ANY +as that may "steal" and return results in the calling thread +that another operation in a different thread, using a +different session handle, may require to complete. +.LP +When +.B ldap_unbind() +is called on a session handle with siblings, all the +siblings become invalid. +.LP +Siblings must be destroyed using +.BR ldap_destroy() . +Session handle resources associated with the original +.RB ( "LDAP *" ) +will be freed when the last session handle is destroyed or when +.B ldap_unbind() +is called, if no other session handles currently exist. +.SH ERRORS +If an error occurs, +.B ldap_dup() +will return NULL and +.I errno +should be set appropriately. +.B ldap_destroy() +will directly return the LDAP code associated to the error (or +.I LDAP_SUCCESS +in case of success); +.I errno +should be set as well whenever appropriate. +.SH SEE ALSO +.BR ldap_open (3), +.BR ldap_init (3), +.BR ldap_initialize (3), +.BR ldap_init_fd (3), +.BR errno (3) +.SH ACKNOWLEDGEMENTS +This work is based on the previously proposed +.B LDAP C API Concurrency Extensions +draft +.BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt ) +effort. +.so ../Project diff --git a/doc/man/man3/ldap_dup.3.links b/doc/man/man3/ldap_dup.3.links new file mode 100644 index 0000000..1d77f93 --- /dev/null +++ b/doc/man/man3/ldap_dup.3.links @@ -0,0 +1 @@ +ldap_destroy.3 diff --git a/doc/man/man3/ldap_error.3 b/doc/man/man3/ldap_error.3 new file mode 100644 index 0000000..bbe0b5d --- /dev/null +++ b/doc/man/man3/ldap_error.3 @@ -0,0 +1,224 @@ +.TH LDAP_ERROR 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +char *ldap_err2string( int \fIerr\fB ); +.SH DESCRIPTION +The +.B ldap_err2string() +routine provides short description of the various codes returned by +routines in this library. The returned string is a pointer to a +static area that should not be modified. + +These codes are either negative, +indicating an API error code; positive, indicating an LDAP resultCode +other than \'success' (0), or - zero, indicating both successful use +of the API and the LDAP resultCode \'success' (0). + +The code associated with an LDAP session is accessible using +.BR ldap_get_option (3) +and +.BR ldap_set_option (3) +with the +.B LDAP_OPT_RESULT_CODE +option (previously called +.BR LDAP_OPT_ERROR_NUMBER ). + +.SH PROTOCOL RESULT CODES + +This section provides a partial list of protocol codes recognized +by the library. As LDAP is extensible, additional values may be +returned. A complete listing of \fIregistered\fP LDAP result codes +can be obtained from the \fIInternet Assigned Numbers Authority\fP +<http://www.iana.org>. + +.LP +.TP 20 +.SM LDAP_SUCCESS +The request was successful. +.TP +.SM LDAP_OPERATIONS_ERROR +An operations error occurred. +.TP +.SM LDAP_PROTOCOL_ERROR +A protocol violation was detected. +.TP +.SM LDAP_TIMELIMIT_EXCEEDED +An LDAP time limit was exceeded. +.TP +.SM LDAP_SIZELIMIT_EXCEEDED +An LDAP size limit was exceeded. +.TP +.SM LDAP_COMPARE_FALSE +A compare operation returned false. +.TP +.SM LDAP_COMPARE_TRUE +A compare operation returned true. +.TP +.SM LDAP_STRONG_AUTH_NOT_SUPPORTED +The LDAP server does not support strong authentication. +.TP +.SM LDAP_STRONG_AUTH_REQUIRED +Strong authentication is required for the operation. +.TP +.SM LDAP_PARTIAL_RESULTS +Partial results only returned. +.TP +.SM LDAP_NO_SUCH_ATTRIBUTE +The attribute type specified does not exist in the entry. +.TP +.SM LDAP_UNDEFINED_TYPE +The attribute type specified is invalid. +.TP +.SM LDAP_INAPPROPRIATE_MATCHING +Filter type not supported for the specified attribute. +.TP +.SM LDAP_CONSTRAINT_VIOLATION +An attribute value specified violates some constraint (e.g., a postalAddress +has too many lines, or a line that is too long). +.TP +.SM LDAP_TYPE_OR_VALUE_EXISTS +An attribute type or attribute value specified already exists in the entry. +.TP +.SM LDAP_INVALID_SYNTAX +An invalid attribute value was specified. +.TP +.SM LDAP_NO_SUCH_OBJECT +The specified object does not exist in The Directory. +.TP +.SM LDAP_ALIAS_PROBLEM +An alias in The Directory points to a nonexistent entry. +.TP +.SM LDAP_INVALID_DN_SYNTAX +A syntactically invalid DN was specified. +.TP +.SM LDAP_IS_LEAF +The object specified is a leaf. +.TP +.SM LDAP_ALIAS_DEREF_PROBLEM +A problem was encountered when dereferencing an alias. +.TP +.SM LDAP_INAPPROPRIATE_AUTH +Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was +specified and the entry does not have a userPassword attribute). +.TP +.SM LDAP_INVALID_CREDENTIALS +Invalid credentials were presented (e.g., the wrong password). +.TP +.SM LDAP_INSUFFICIENT_ACCESS +The user has insufficient access to perform the operation. +.TP +.SM LDAP_BUSY +The DSA is busy. +.TP +.SM LDAP_UNAVAILABLE +The DSA is unavailable. +.TP +.SM LDAP_UNWILLING_TO_PERFORM +The DSA is unwilling to perform the operation. +.TP +.SM LDAP_LOOP_DETECT +A loop was detected. +.TP +.SM LDAP_NAMING_VIOLATION +A naming violation occurred. +.TP +.SM LDAP_OBJECT_CLASS_VIOLATION +An object class violation occurred (e.g., a "must" attribute was missing +from the entry). +.TP +.SM LDAP_NOT_ALLOWED_ON_NONLEAF +The operation is not allowed on a nonleaf object. +.TP +.SM LDAP_NOT_ALLOWED_ON_RDN +The operation is not allowed on an RDN. +.TP +.SM LDAP_ALREADY_EXISTS +The entry already exists. +.TP +.SM LDAP_NO_OBJECT_CLASS_MODS +Object class modifications are not allowed. +.TP +.SM LDAP_OTHER +An unknown error occurred. + +.SH API ERROR CODES + +This section provides a complete list of API error codes recognized +by the library. Note that LDAP_SUCCESS indicates success of an +API call in addition to representing the return of the LDAP +\'success' resultCode. + + +.LP +.TP 20 +.SM LDAP_SERVER_DOWN +The LDAP library can't contact the LDAP server. +.TP +.SM LDAP_LOCAL_ERROR +Some local error occurred. This is usually a failed dynamic memory allocation. +.TP +.SM LDAP_ENCODING_ERROR +An error was encountered encoding parameters to send to the LDAP server. +.TP +.SM LDAP_DECODING_ERROR +An error was encountered decoding a result from the LDAP server. +.TP +.SM LDAP_TIMEOUT +A timelimit was exceeded while waiting for a result. +.TP +.SM LDAP_AUTH_UNKNOWN +The authentication method specified to ldap_bind() is not known. +.TP +.SM LDAP_FILTER_ERROR +An invalid filter was supplied to ldap_search() (e.g., unbalanced +parentheses). +.TP +.SM LDAP_PARAM_ERROR +An ldap routine was called with a bad parameter. +.TP +.SM LDAP_NO_MEMORY +An memory allocation (e.g., malloc(3) or other dynamic memory +allocator) call failed in an ldap library routine. +.TP +.SM LDAP_USER_CANCELED +Indicates the user cancelled the operation. +.TP +.SM LDAP_CONNECT_ERROR +Indicates a connection problem. +.TP +.SM LDAP_NOT_SUPPORTED +Indicates the routine was called in a manner not supported by the library. +.TP +.SM LDAP_CONTROL_NOT_FOUND +Indicates the control provided is unknown to the client library. +.TP +.SM LDAP_NO_RESULTS_RETURNED +Indicates no results returned. +.TP +.SM LDAP_MORE_RESULTS_TO_RETURN +Indicates more results could be returned. +.TP +.SM LDAP_CLIENT_LOOP +Indicates the library has detected a loop in its processing. +.TP +.SM LDAP_REFERRAL_LIMIT_EXCEEDED +Indicates the referral limit has been exceeded. + +.SH DEPRECATED +.so Deprecated + +.SH SEE ALSO +.BR ldap (3), +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_error.3.links b/doc/man/man3/ldap_error.3.links new file mode 100644 index 0000000..841370d --- /dev/null +++ b/doc/man/man3/ldap_error.3.links @@ -0,0 +1,5 @@ +ldap_perror.3 +ld_errno.3 +ldap_result2error.3 +ldap_errlist.3 +ldap_err2string.3 diff --git a/doc/man/man3/ldap_extended_operation.3 b/doc/man/man3/ldap_extended_operation.3 new file mode 100644 index 0000000..02ec882 --- /dev/null +++ b/doc/man/man3/ldap_extended_operation.3 @@ -0,0 +1,75 @@ +.TH LDAP_EXTENDED_OPERATION 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_extended_operation, ldap_extended_operation_s \- Extends the LDAP operations to the LDAP server. +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_extended_operation( +.RS +.ft B +LDAP *\fIld\fB, +const char *\fIrequestoid\fB, +const struct berval *\fIrequestdata\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB, +int *\fImsgidp\fB ); +.RE +.LP +.ft B +int ldap_extended_operation_s( +.RS +.ft B +LDAP *\fIld\fB, +const char *\fIrequestoid\fB, +const struct berval *\fIrequestdata\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB, +char **\fIretoidp\fB, +struct berval **\fIretdatap\fB ); +.RE +.SH DESCRIPTION +The +.B ldap_extended_operation_s() +routine is used to synchronously perform an LDAP extended operation. +It takes \fIrequestoid\fP, which points to a dotted-decimal OID string +identifying the extended operation to perform. \fIrequestdata\fP is the +data required for the request, \fIsctrls\fP is an array of LDAPControl +structures to use with this extended operation, \fIcctrls\fP is an array +of LDAPControl structures that list the client controls to use with +this extended operation. +.LP +The output parameter \fIretoidp\fP points to a dotted-decimal OID +string returned by the LDAP server. The memory used by the string +should be freed with the +.BR ldap_memfree (3) +function. +The output parameter \fIretdatap\fP points to a pointer to a berval +structure that contains the returned data. If no data is returned +by the server, the pointer is set this to NULL. The memory used by +this structure should be freed with the +.BR ber_bvfree (3) +function. +.LP +The +.B ldap_extended_operation() +works just like +.BR ldap_extended_operation_s() , +but the operation is asynchronous. It provides the message id of +the request it initiated in the integer pointed to be \fImsgidp\fP. +The result of this operation can be obtained by calling +.BR ldap_result(3). +.SH SEE ALSO +.BR ber_bvfree (3), +.BR ldap_memfree (3), +.BR ldap_parse_extended_result (3), +.BR ldap_result (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_extended_operation.3.links b/doc/man/man3/ldap_extended_operation.3.links new file mode 100644 index 0000000..1c5dc67 --- /dev/null +++ b/doc/man/man3/ldap_extended_operation.3.links @@ -0,0 +1,2 @@ +ldap_extended_operation_s.3 + diff --git a/doc/man/man3/ldap_first_attribute.3 b/doc/man/man3/ldap_first_attribute.3 new file mode 100644 index 0000000..47e8b0c --- /dev/null +++ b/doc/man/man3/ldap_first_attribute.3 @@ -0,0 +1,97 @@ +.TH LDAP_FIRST_ATTRIBUTE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +char *ldap_first_attribute( + LDAP *ld, LDAPMessage *entry, BerElement **berptr ) +.LP +.ft B +char *ldap_next_attribute( + LDAP *ld, LDAPMessage *entry, BerElement *ber ) +.LP +.ft B +int ldap_get_attribute_ber( + LDAP *ld, LDAPMessage *entry, BerElement *ber, + BerValue *attr, BerVarray *vals ) +.SH DESCRIPTION +The +.BR ldap_first_attribute() , +.B ldap_next_attribute() +and +.B ldap_get_attribute_ber() +routines are used +to step through the attributes in an LDAP entry. +.B ldap_first_attribute() +takes an \fIentry\fP as returned by +.BR ldap_first_entry (3) +or +.BR ldap_next_entry (3) +and returns a pointer to character string +containing the first attribute description in the entry. +.B ldap_next_attribute() +returns the next attribute description in the entry. +.LP +It also returns, in \fIberptr\fP, a pointer to a BerElement it has +allocated to keep track of its current position. This pointer should +be passed to subsequent calls to +.B ldap_next_attribute() +and is used +to effectively step through the entry's attributes. The caller is +solely responsible for freeing the BerElement pointed to by \fIberptr\fP +when it is no longer needed by calling +.BR ber_free (3). +When calling +.BR ber_free (3) +in this instance, be sure the second argument is 0. +.LP +The attribute names returned are suitable for inclusion in a call +to +.BR ldap_get_values (3) +to retrieve the attribute's values. +.LP +The +.B ldap_get_attribute_ber() +routine allows one to iterate over all attributes in-place, without +allocating memory to hold text for the attribute name or its values, +if requested. The use case is similar to +.B ldap_next_attribute() +except that the attribute name is returned into \fIattr\fP and, if +\fIvals\fP is non-NULL, the list of values is stored there. Both point +into the LDAP message and remain valid only while the entry is valid. +The caller is still responsible for freeing \fIvals\fP with +.BR ldap_memfree (3), +if used. +.SH ERRORS +If an error occurs, NULL is returned and the ld_errno field in the +\fIld\fP parameter is set to indicate the error. See +.BR ldap_error (3) +for a description of possible error codes. +.SH NOTES +The +.B ldap_first_attribute() +and +.B ldap_next_attribute() +return dynamically allocated memory that must be freed by the caller via +.BR ldap_memfree (3). +For +.BR ldap_get_attribute_ber() , +only the actual \fIvals\fP pointer needs to be freed with +.BR ldap_memfree (3), +other data is accounted for as part of \fIber\fP. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_entry (3), +.BR ldap_get_values (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_first_attribute.3.links b/doc/man/man3/ldap_first_attribute.3.links new file mode 100644 index 0000000..ce3981c --- /dev/null +++ b/doc/man/man3/ldap_first_attribute.3.links @@ -0,0 +1,2 @@ +ldap_next_attribute.3 +ldap_get_attribute_ber.3 diff --git a/doc/man/man3/ldap_first_entry.3 b/doc/man/man3/ldap_first_entry.3 new file mode 100644 index 0000000..b0eadd0 --- /dev/null +++ b/doc/man/man3/ldap_first_entry.3 @@ -0,0 +1,80 @@ +.TH LDAP_FIRST_ENTRY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_count_entries( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ) +.SH DESCRIPTION +.LP +These routines are used to parse results received from +.BR ldap_result (3) +or the synchronous LDAP search operation routines +.BR ldap_search_s (3) +and +.BR ldap_search_st (3). +.LP +The +.B ldap_first_entry() +routine is used to retrieve the first entry in a chain +of search results. It takes the \fIresult\fP as returned by a call to +.BR ldap_result (3) +or +.BR ldap_search_s (3) +or +.BR ldap_search_st (3) +and returns a pointer to the first entry in the result. +.LP +This pointer should be supplied on a subsequent call to +.B ldap_next_entry() +to get the next entry, the result of which should be +supplied to the next call to +.BR ldap_next_entry() , +etc. +.B ldap_next_entry() +will return NULL when there are no more entries. The entries returned +from these calls are used in calls to the routines described in +.BR ldap_get_dn (3), +.BR ldap_first_attribute (3), +.BR ldap_get_values (3), +etc. +.LP +A count of the number of entries in the search result can be obtained +by calling +.BR ldap_count_entries() . +.SH ERRORS +If an error occurs in +.B ldap_first_entry() +or +.BR ldap_next_entry() , +NULL is returned and the ld_errno field in the \fIld\fP parameter +is set to indicate the error. If an error occurs in +.BR ldap_count_entries() , +-1 is returned, and +.B ld_errno +is set appropriately. See +.BR ldap_error (3) +for a description of possible error codes. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_search (3), +.BR ldap_first_attribute (3), +.BR ldap_get_values (3), +.BR ldap_get_dn (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_first_entry.3.links b/doc/man/man3/ldap_first_entry.3.links new file mode 100644 index 0000000..781590b --- /dev/null +++ b/doc/man/man3/ldap_first_entry.3.links @@ -0,0 +1,2 @@ +ldap_next_entry.3 +ldap_count_entries.3 diff --git a/doc/man/man3/ldap_first_message.3 b/doc/man/man3/ldap_first_message.3 new file mode 100644 index 0000000..4d62359 --- /dev/null +++ b/doc/man/man3/ldap_first_message.3 @@ -0,0 +1,82 @@ +.TH LDAP_FIRST_MESSAGE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_count_messages( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message ) +.SH DESCRIPTION +.LP +These routines are used to step through the messages in a result chain +received from +.BR ldap_result (3) . +For search operations, the result chain can contain referral, entry +and result messages. The +.BR ldap_msgtype (3) +function can be used to distinguish between the different message types. +.LP +The +.B ldap_first_message() +routine is used to retrieve the first message in a result chain. +It takes the \fIresult\fP as returned by a call to +.BR ldap_result (3) , +.BR ldap_search_s (3) +or +.BR ldap_search_st (3) +and returns a pointer to the first message in the result chain. +.LP +This pointer should be supplied on a subsequent call to +.B ldap_next_message() +to get the next message, the result of which should be +supplied to the next call to +.BR ldap_next_message() , +etc. +.B ldap_next_message() +will return NULL when there are no more messages. +.LP +These functions are useful when using routines like +.BR ldap_parse_result (3) +that only operate on the first result in the chain. +.LP +A count of the number of messages in the result chain can be obtained +by calling +.BR ldap_count_messages() . +It can also be used to count the number of remaining messages in a chain +if called with a message, entry or reference returned by +.B ldap_first_message() , +.B ldap_next_message() , +.BR ldap_first_entry (3) , +.BR ldap_next_entry (3) , +.BR ldap_first_reference (3) , +.BR ldap_next_reference (3) . +.SH ERRORS +If an error occurs in +.B ldap_first_message() +or +.BR ldap_next_message() , +NULL is returned. If an error occurs in +.BR ldap_count_messages() , +-1 is returned. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_search (3), +.BR ldap_result (3), +.BR ldap_parse_result (3), +.BR ldap_first_entry (3), +.BR ldap_first_reference (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_first_message.3.links b/doc/man/man3/ldap_first_message.3.links new file mode 100644 index 0000000..420c04f --- /dev/null +++ b/doc/man/man3/ldap_first_message.3.links @@ -0,0 +1,2 @@ +ldap_next_message.3 +ldap_count_messages.3 diff --git a/doc/man/man3/ldap_first_reference.3 b/doc/man/man3/ldap_first_reference.3 new file mode 100644 index 0000000..2bcba1a --- /dev/null +++ b/doc/man/man3/ldap_first_reference.3 @@ -0,0 +1,71 @@ +.TH LDAP_FIRST_REFERENCE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_count_references( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference ) +.SH DESCRIPTION +.LP +These routines are used to step through the continuation references in a +result chain received from +.BR ldap_result (3) +or the synchronous LDAP search operation routines. +.LP +The +.B ldap_first_reference() +routine is used to retrieve the first reference message in a +result chain. It takes the \fIresult\fP as returned by a call to +.BR ldap_result (3) , +.BR ldap_search_s (3) +or +.BR ldap_search_st (3) +and returns a pointer to the first reference message in the +result chain. +.LP +This pointer should be supplied on a subsequent call to +.B ldap_next_reference() +to get the next reference message, the result of which should be +supplied to the next call to +.BR ldap_next_reference() , +etc. +.B ldap_next_reference() +will return NULL when there are no more reference messages. +The reference messages returned from these calls are used by +.BR ldap_parse_reference (3) +to extract referrals and controls. +.LP +A count of the number of reference messages in the search result can be +obtained by calling +.BR ldap_count_references() . +It can also be used to count the number of reference messages remaining +in a result chain. +.SH ERRORS +If an error occurs in +.B ldap_first_reference() +or +.BR ldap_next_reference() , +NULL is returned. If an error occurs in +.BR ldap_count_references() , +-1 is returned. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_search (3), +.BR ldap_parse_reference (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_first_reference.3.links b/doc/man/man3/ldap_first_reference.3.links new file mode 100644 index 0000000..a747bbb --- /dev/null +++ b/doc/man/man3/ldap_first_reference.3.links @@ -0,0 +1,2 @@ +ldap_next_reference.3 +ldap_count_references.3 diff --git a/doc/man/man3/ldap_get_dn.3 b/doc/man/man3/ldap_get_dn.3 new file mode 100644 index 0000000..6e052a3 --- /dev/null +++ b/doc/man/man3/ldap_get_dn.3 @@ -0,0 +1,246 @@ +.TH LDAP_GET_DN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) +.LP +.ft B +int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) +.LP +.ft B +void ldap_dnfree( LDAPDN dn ) +.LP +.ft B +int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) +.LP +.ft B +char **ldap_explode_dn( const char *dn, int notypes ) +.LP +.ft B +char **ldap_explode_rdn( const char *rdn, int notypes ) +.LP +.ft B +char *ldap_dn2ufn( const char * dn ) +.LP +.ft B +char *ldap_dn2dcedn( const char * dn ) +.LP +.ft B +char *ldap_dcedn2dn( const char * dn ) +.LP +.ft B +char *ldap_dn2ad_canonical( const char * dn ) +.SH DESCRIPTION +These routines allow LDAP entry names (Distinguished Names, or DNs) +to be obtained, parsed, converted to a user-friendly form, and tested. +A DN has the form described in +RFC 4414 "Lightweight Directory Access Protocol (LDAP): +String Representation of Distinguished Names". +.LP +The +.B ldap_get_dn() +routine takes an \fIentry\fP as returned by +.BR ldap_first_entry (3) +or +.BR ldap_next_entry (3) +and returns a copy of +the entry's DN. Space for the DN will be obtained dynamically +and should be freed by the caller using +.BR ldap_memfree (3). +.LP +.B ldap_str2dn() +parses a string representation of a distinguished name contained in +.B str +into its components, +which are stored in +.B dn +as +.B ldap_ava +structures, arranged in +.B LDAPAVA, +.B LDAPRDN, +and +.B LDAPDN +terms. Space for +.B dn +will be obtained dynamically and should be freed by the caller using +.BR ldap_dnfree (3). +The +.B LDAPDN +is defined as: +.nf +.ft B + +typedef struct ldap_ava { + struct berval la_attr; + struct berval la_value; + unsigned la_flags; +} LDAPAVA; + +typedef LDAPAVA** LDAPRDN; +typedef LDAPRDN* LDAPDN; + +.ft +.fi +The attribute types and the attribute values are not normalized. +The +.B la_flags +can be either +.B LDAP_AVA_STRING +or +.B LDAP_AVA_BINARY, +the latter meaning that the value is BER/DER encoded and thus must +be represented as, quoting from RFC 4514, " ... an +octothorpe character ('#' ASCII 35) followed by the hexadecimal +representation of each of the bytes of the BER encoding of the X.500 +AttributeValue." +The +.B flags +parameter to +.B ldap_str2dn() +can be +.LP +.nf + LDAP_DN_FORMAT_LDAPV3 + LDAP_DN_FORMAT_LDAPV2 + LDAP_DN_FORMAT_DCE + +.fi +which defines what DN syntax is expected (according to RFC 4514, +RFC 1779 and DCE, respectively). +The format can be \fIOR\fPed to the flags +.LP +.nf + LDAP_DN_P_NO_SPACES + LDAP_DN_P_NO_SPACE_AFTER_RDN + ... + LDAP_DN_PEDANTIC + +.fi +The latter is a shortcut for all the previous limitations. +.LP +.B LDAP_DN_P_NO_SPACES +does not allow extra spaces in the dn; the default is to silently +eliminate spaces around AVA separators ('='), RDN component separators +('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators +(',' LDAPv3/LDAPv2 or '/' for DCE). +.LP +.B LDAP_DN_P_NO_SPACE_AFTER_RDN +does not allow a single space after RDN separators. +.LP +.B ldap_dn2str() +performs the inverse operation, yielding in +.B str +a string representation of +.B dn. +It allows the same values for +.B flags +as +.B ldap_str2dn(), +plus +.LP +.nf + LDAP_DN_FORMAT_UFN + LDAP_DN_FORMAT_AD_CANONICAL + +.fi +for user-friendly naming (RFC 1781) and AD canonical. +.LP +The following routines are viewed as deprecated in favor of +.B ldap_str2dn() +and +.BR ldap_dn2str(). +They are provided to support legacy applications. +.LP +The +.B ldap_explode_dn() +routine takes a DN as returned by +.B ldap_get_dn() +and breaks it up into its component parts. Each part is known as a +Relative Distinguished Name, or RDN. +.B ldap_explode_dn() +returns a +NULL-terminated array, each component of which contains an RDN from the +DN. The \fInotypes\fP parameter is used to request that only the RDN +values be returned, not their types. For example, the DN "cn=Bob, +c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", +"US", NULL }, depending on whether notypes was 0 or 1, respectively. +Assertion values in RDN strings may included escaped characters. +The result can be freed by calling +.BR ldap_value_free (3). +.LP +Similarly, the +.B ldap_explode_rdn() +routine takes an RDN as returned by +.B ldap_explode_dn(dn,0) +and breaks it up into its "type=value" component parts (or just "value", +if the \fInotypes\fP parameter is set). Note the value is not +unescaped. The result can be freed by calling +.BR ldap_value_free (3). +.LP +.B ldap_dn2ufn() +is used to turn a DN as returned by +.BR ldap_get_dn (3) +into a more user-friendly form, stripping off all type names. See +"Using the Directory to Achieve User Friendly Naming" (RFC 1781) +for more details on the UFN format. Due to the ambiguous nature +of the format, it is generally only used for display purposes. +The space for the UFN returned is obtained dynamically and the user +is responsible for freeing it via a call to +.BR ldap_memfree (3). +.LP +.B ldap_dn2dcedn() +is used to turn a DN as returned by +.BR ldap_get_dn (3) +into a DCE-style DN, e.g. a string with most-significant to least +significant rdns separated by slashes ('/'); rdn components +are separated by commas (','). +Only printable chars (e.g. LDAPv2 printable string) are allowed, +at least in this implementation. +.B ldap_dcedn2dn() +performs the opposite operation. +.B ldap_dn2ad_canonical() +turns a DN into a AD canonical name, which is basically a DCE dn +with attribute types omitted. +The trailing domain, if present, is turned in a DNS-like domain. +The space for the returned value is obtained dynamically and the user +is responsible for freeing it via a call to +.BR ldap_memfree (3). +.SH ERRORS +If an error occurs in +.BR ldap_get_dn() , +NULL is returned and the +.B ld_errno +field in the \fIld\fP parameter is set to indicate the error. See +.BR ldap_error (3) +for a description of possible error codes. +.BR ldap_explode_dn() , +.BR ldap_explode_rdn() , +.B ldap_dn2ufn(), +.B ldap_dn2dcedn(), +.B ldap_dcedn2dn(), +and +.B ldap_dn2ad_canonical() +will return NULL with +.BR errno (3) +set appropriately in case of trouble. +.SH NOTES +These routines dynamically allocate memory that the caller must free. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_first_entry (3), +.BR ldap_memfree (3), +.BR ldap_value_free (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_get_dn.3.links b/doc/man/man3/ldap_get_dn.3.links new file mode 100644 index 0000000..4c71aa5 --- /dev/null +++ b/doc/man/man3/ldap_get_dn.3.links @@ -0,0 +1,9 @@ +ldap_explode_dn.3 +ldap_explode_rdn.3 +ldap_dn2ufn.3 +ldap_str2dn.3 +ldap_dnfree.3 +ldap_dn2str.3 +ldap_dn2dcedn.3 +ldap_dcedn2dn.3 +ldap_dn2ad_canonical.3 diff --git a/doc/man/man3/ldap_get_option.3 b/doc/man/man3/ldap_get_option.3 new file mode 100644 index 0000000..e6b0580 --- /dev/null +++ b/doc/man/man3/ldap_get_option.3 @@ -0,0 +1,933 @@ +.TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_get_option, ldap_set_option \- LDAP option handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.B #include <ldap.h> +.LP +.BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");" +.LP +.BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");" +.SH DESCRIPTION +.LP +These routines provide access to options stored either in a LDAP handle +or as global options, where applicable. +They make use of a neutral interface, where the type of the value +either retrieved by +.BR ldap_get_option (3) +or set by +.BR ldap_set_option (3) +is cast to +.BR "void *" . +The actual type is determined based on the value of the +.B option +argument. +Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles +inherit their default settings from the global options in effect at the time +the handle is created. +.TP +.B LDAP_OPT_API_FEATURE_INFO +Fills-in a +.BR "LDAPAPIFeatureInfo" ; +.BR outvalue +must be a +.BR "LDAPAPIFeatureInfo *" , +pointing to an already allocated struct. +The +.B ldapaif_info_version +field of the struct must be initialized to +.B LDAP_FEATURE_INFO_VERSION +before making the call. The +.B ldapaif_name +field must be set to the name of a feature to query. +This is a read-only option. +.TP +.B LDAP_OPT_API_INFO +Fills-in a +.BR "LDAPAPIInfo" ; +.BR outvalue +must be a +.BR "LDAPAPIInfo *" , +pointing to an already allocated struct. The +.B ldapai_info_version +field of the struct must be initialized to +.B LDAP_API_INFO_VERSION +before making the call. +If the version passed in does not match the current library +version, the expected version number will be stored in the +struct and the call will fail. +The caller is responsible for freeing the elements of the +.B ldapai_extensions +array and the array itself using +.BR ldap_memfree (3). +The caller must also free the +.BR ldapi_vendor_name . +This is a read-only option. +.TP +.B LDAP_OPT_CLIENT_CONTROLS +Sets/gets the client-side controls to be used for all operations. +This is now deprecated as modern LDAP C API provides replacements +for all main operations which accepts client-side controls as +explicit arguments; see for example +.BR ldap_search_ext (3), +.BR ldap_add_ext (3), +.BR ldap_modify_ext (3) +and so on. +.BR outvalue +must be +.BR "LDAPControl ***" , +and the caller is responsible of freeing the returned controls, if any, +by calling +.BR ldap_controls_free (3), +while +.BR invalue +must be +.BR "LDAPControl *const *" ; +the library duplicates the controls passed via +.BR invalue . +.TP +.B LDAP_OPT_CONNECT_ASYNC +Sets/gets the status of the asynchronous connect flag. +.BR invalue +should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON ; +.BR outvalue +must be +.BR "int *" . +When set, the library will call +.BR connect (2) +and return, without waiting for response. +This leaves the handle in a connecting state. +Subsequent calls to library routines will poll for completion +of the connect before performing further operations. +As a consequence, library calls that need to establish a connection +with a DSA do not block even for the network timeout +(option +.BR LDAP_OPT_NETWORK_TIMEOUT ). +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_CONNECT_CB +This option allows to set a connect callback. +.B invalue +must be a +.BR "const struct ldap_conncb *" . +Callbacks are executed in last in-first served order. +Handle-specific callbacks are executed first, followed by global ones. +Right before freeing the callback structure, the +.B lc_del +callback handler is passed a +.B NULL +.BR Sockbuf . +Calling +.BR ldap_get_option (3) +for this option removes the callback whose pointer matches +.BR outvalue . +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEBUG_LEVEL +Sets/gets the debug level of the client library. +.BR invalue +must be a +.BR "const int *" ; +.BR outvalue +must be a +.BR "int *" . +Valid debug levels are +.BR LDAP_DEBUG_ANY , +.BR LDAP_DEBUG_ARGS , +.BR LDAP_DEBUG_BER , +.BR LDAP_DEBUG_CONNS , +.BR LDAP_DEBUG_NONE , +.BR LDAP_DEBUG_PACKETS , +.BR LDAP_DEBUG_PARSE , +and +.BR LDAP_DEBUG_TRACE . +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEFBASE +Sets/gets a string containing the DN to be used as default base +for search operations. +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library duplicates the corresponding string. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEREF +Sets/gets the value that defines when alias dereferencing must occur. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +They cannot be NULL. +The value of +.BR *invalue +should be one of +.BR LDAP_DEREF_NEVER +(the default), +.BR LDAP_DEREF_SEARCHING , +.BR LDAP_DEREF_FINDING , +or +.BR LDAP_DEREF_ALWAYS . +Note that this has ever been the only means to determine alias dereferencing +within search operations. +.TP +.B LDAP_OPT_DESC +Returns the file descriptor associated to the socket buffer +of the LDAP handle passed in as +.BR ld ; +.BR outvalue +must be a +.BR "int *" . +This is a read-only, handle-specific option. +.TP +.B LDAP_OPT_DIAGNOSTIC_MESSAGE +Sets/gets a string containing the error string associated to the LDAP handle. +This option was formerly known as +.BR LDAP_OPT_ERROR_STRING . +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_HOST_NAME +Sets/gets a space-separated list of hosts to be contacted by the library +when trying to establish a connection. +This is now deprecated in favor of +.BR LDAP_OPT_URI . +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the resulting string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_MATCHED_DN +Sets/gets a string containing the matched DN associated to the LDAP handle. +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_NETWORK_TIMEOUT +Sets/gets the network timeout value after which +.BR poll (2)/ select (2) +following a +.BR connect (2) +returns in case of no activity. +.B outvalue +must be a +.BR "struct timeval **" +(the caller has to free +.BR *outvalue +using +.BR ldap_memfree (3)), +and +.B invalue +must be a +.BR "const struct timeval *" . +They cannot be NULL. Using a struct with seconds set to \-1 results +in an infinite timeout, which is the default. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_PROTOCOL_VERSION +Sets/gets the protocol version. +.BR outvalue +and +.BR invalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_REFERRAL_URLS +Sets/gets an array containing the referral URIs associated to the LDAP handle. +.BR outvalue +must be a +.BR "char ***" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memvfree (3), +while +.BR invalue +must be a NULL-terminated +.BR "char *const *" ; +the library duplicates the corresponding string. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_REFERRALS +Determines whether the library should implicitly chase referrals or not. +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.\".TP +.\".B LDAP_OPT_REFHOPLIMIT +.\"This option is OpenLDAP specific. +.\"It is not currently implemented. +.TP +.B LDAP_OPT_RESTART +Determines whether the library should implicitly restart connections (FIXME). +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_RESULT_CODE +Sets/gets the LDAP result code associated to the handle. +This option was formerly known as +.BR LDAP_OPT_ERROR_NUMBER . +.BR invalue +must be a +.BR "const int *" . +.BR outvalue +must be a +.BR "int *" . +.TP +.B LDAP_OPT_SERVER_CONTROLS +Sets/gets the server-side controls to be used for all operations. +This is now deprecated as modern LDAP C API provides replacements +for all main operations which accepts server-side controls as +explicit arguments; see for example +.BR ldap_search_ext (3), +.BR ldap_add_ext (3), +.BR ldap_modify_ext (3) +and so on. +.BR outvalue +must be +.BR "LDAPControl ***" , +and the caller is responsible of freeing the returned controls, if any, +by calling +.BR ldap_controls_free (3), +while +.BR invalue +must be +.BR "LDAPControl *const *" ; +the library duplicates the controls passed via +.BR invalue . +.TP +.B LDAP_OPT_SESSION_REFCNT +Returns the reference count associated with the LDAP handle passed in as +.BR ld ; +.BR outvalue +must be a +.BR "int *" . +This is a read-only, handle-specific option. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_SIZELIMIT +Sets/gets the value that defines the maximum number of entries +to be returned by a search operation. +.BR invalue +must be +.BR "const int *" , +while +.BR outvalue +must be +.BR "int *" ; +They cannot be NULL. +.TP +.B LDAP_OPT_SOCKBUF +Returns a pointer to the socket buffer of the LDAP handle passed in as +.BR ld ; +.BR outvalue +must be a +.BR "Sockbuf **" . +This is a read-only, handle-specific option. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_SOCKET_BIND_ADDRESSES +Sets/gets a space-separated list of IP Addresses used as binding interface +to remote server when trying to establish a connection. Only one valid IPv4 +address and/or one valid IPv6 address are allowed in the list. +.BR outvalue +must be a +.BR "char **", +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_TIMELIMIT +Sets/gets the value that defines the time limit after which +a search operation should be terminated by the server. +.BR invalue +must be +.BR "const int *" , +while +.BR outvalue +must be +.BR "int *" , +and they cannot be NULL. +.TP +.B LDAP_OPT_TIMEOUT +Sets/gets a timeout value for the synchronous API calls. +.B outvalue +must be a +.BR "struct timeval **" +(the caller has to free +.BR *outvalue +using +.BR ldap_memfree (3)), +and +.B invalue +must be a +.BR "struct timeval *" , +and they cannot be NULL. Using a struct with seconds set to \-1 results +in an infinite timeout, which is the default. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_URI +Sets/gets a comma- or space-separated list of URIs to be contacted by the library +when trying to establish a connection. +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the resulting string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library parses the string into a list of +.BR LDAPURLDesc +structures, so the invocation of +.BR ldap_set_option (3) +may fail if URL parsing fails. +URIs may only contain the +.BR schema , +the +.BR host , +and the +.BR port +fields. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_KEEPCONN +Instructs +.BR ldap_result (3) +to keep the connection open on read error or if Notice of Disconnection is received. In these cases, the connection should be closed by the caller. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_TCP_USER_TIMEOUT +Allows to configure TCP_USER_TIMEOUT in milliseconds on the connection, overriding the operating system setting. +This option is OpenLDAP specific and supported only on Linux 2.6.37 or higher. +.B invalue +must be a +.BR "const unsigned int *" ; +.BR outvalue +must be an +.BR "unsigned int *" . + +.SH SASL OPTIONS +The SASL options are OpenLDAP specific and unless otherwise noted, require an LDAP handle to be passed. +.TP +.B LDAP_OPT_X_SASL_AUTHCID +Gets the SASL authentication identity; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_AUTHZID +Gets the SASL authorization identity; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_MAXBUFSIZE +Gets/sets SASL maximum buffer size; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_MECH +Gets the SASL mechanism; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_MECHLIST +Gets the list of the available mechanisms, +in form of a NULL-terminated array of strings; +.BR outvalue +must be +.BR "char ***" . +The caller must not free or otherwise muck with it. This option can be used globally. +.TP +.B LDAP_OPT_X_SASL_NOCANON +Sets/gets the NOCANON flag. +When unset, the hostname is canonicalized. +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_SASL_REALM +Gets the SASL realm; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_SECPROPS +Sets the SASL secprops; +.BR invalue +must be a +.BR "char *" , +containing a comma-separated list of properties. +Legal values are: +.BR none , +.BR nodict , +.BR noplain , +.BR noactive , +.BR passcred , +.BR forwardsec , +.BR noanonymous , +.BR minssf=<minssf> , +.BR maxssf=<maxssf> , +.BR maxbufsize=<maxbufsize> . +.TP +.B LDAP_OPT_X_SASL_SSF +Gets the SASL SSF; +.BR outvalue +must be a +.BR "ber_len_t *" . +.TP +.B LDAP_OPT_X_SASL_SSF_EXTERNAL +Sets the SASL SSF value related to an authentication +performed using an EXTERNAL mechanism; +.BR invalue +must be a +.BR "const ber_len_t *" . +.TP +.B LDAP_OPT_X_SASL_SSF_MAX +Gets/sets SASL maximum SSF; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_SSF_MIN +Gets/sets SASL minimum SSF; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_USERNAME +Gets the SASL username; +.BR outvalue +must be a +.BR "char **" . +Its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_CBINDING +Sets/gets the channel-binding type to use in SASL, +one of +.BR LDAP_OPT_X_SASL_CBINDING_NONE +(the default), +.BR LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE +the "tls-unique" type from RFC 5929. +.BR LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT +the "tls-server-end-point" from RFC 5929, compatible with Windows. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.SH TCP OPTIONS +The TCP options are OpenLDAP specific. +Mainly intended for use with Linux, they may not be portable. +.TP +.B LDAP_OPT_X_KEEPALIVE_IDLE +Sets/gets the number of seconds a connection needs to remain idle +before TCP starts sending keepalive probes. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_KEEPALIVE_PROBES +Sets/gets the maximum number of keepalive probes TCP should send +before dropping the connection. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_KEEPALIVE_INTERVAL +Sets/gets the interval in seconds between individual keepalive probes. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.SH TLS OPTIONS +The TLS options are OpenLDAP specific. +.\".TP +.\".B LDAP_OPT_X_TLS +.\"Sets/gets the TLS mode. +.TP +.B LDAP_OPT_X_TLS_CACERTDIR +Sets/gets the path of the directories containing CA certificates. +Multiple directories may be specified, separated by a semi-colon. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CACERTFILE +Sets/gets the full-path of the CA certificate file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CERTFILE +Sets/gets the full-path of the certificate file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CIPHER +Gets the cipher being used on an established TLS session. +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CIPHER_SUITE +Sets/gets the allowed cipher suite. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CONNECT_ARG +Sets/gets the connection callback argument. +.BR invalue +must be +.BR "const void *" ; +.BR outvalue +must be +.BR "void **" . +.TP +.B LDAP_OPT_X_TLS_CONNECT_CB +Sets/gets the connection callback handle. +.BR invalue +must be +.BR "const LDAP_TLS_CONNECT_CB *" ; +.BR outvalue +must be +.BR "LDAP_TLS_CONNECT_CB **" . +.TP +.B LDAP_OPT_X_TLS_CRLCHECK +Sets/gets the CRL evaluation strategy, one of +.BR LDAP_OPT_X_TLS_CRL_NONE , +.BR LDAP_OPT_X_TLS_CRL_PEER , +or +.BR LDAP_OPT_X_TLS_CRL_ALL . +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +Requires OpenSSL. +.TP +.B LDAP_OPT_X_TLS_CRLFILE +Sets/gets the full-path of the CRL file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +This option is only valid for GnuTLS. +.TP +.B LDAP_OPT_X_TLS_CTX +Sets/gets the TLS library context. New TLS sessions will inherit their +default settings from this library context. +.BR invalue +must be +.BR "const void *" ; +.BR outvalue +must be +.BR "void **" . +When using the OpenSSL library this is an SSL_CTX*. When using other +crypto libraries this is a pointer to an OpenLDAP private structure. +Applications generally should not use this option or attempt to +manipulate this structure. +.TP +.B LDAP_OPT_X_TLS_DHFILE +Gets/sets the full-path of the file containing the parameters +for Diffie-Hellman ephemeral key exchange. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_ECNAME +Gets/sets the name of the curve(s) used for +elliptic curve key exchanges. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +Ignored by GnuTLS. In GnuTLS a curve may be selected +in the cipher suite specification. +.TP +.B LDAP_OPT_X_TLS_KEYFILE +Sets/gets the full-path of the certificate key file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_NEWCTX +Instructs the library to create a new TLS library context. +.BR invalue +must be +.BR "const int *" . +A non-zero value pointed to by +.BR invalue +tells the library to create a context for a server. +.TP +.B LDAP_OPT_X_TLS_PEERCERT +Gets the peer's certificate in DER format from an established TLS session. +.BR outvalue +must be +.BR "struct berval *" , +and the data it returns needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_PROTOCOL_MAX +Sets/gets the maximum protocol version. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_TLS_PROTOCOL_MIN +Sets/gets the minimum protocol version. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_TLS_RANDOM_FILE +Sets/gets the random file when +.B /dev/random +and +.B /dev/urandom +are not available. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +Ignored by GnuTLS older than version 2.2. +.TP +.B LDAP_OPT_X_TLS_REQUIRE_CERT +Sets/gets the peer certificate checking strategy, +one of +.BR LDAP_OPT_X_TLS_NEVER , +.BR LDAP_OPT_X_TLS_HARD , +.BR LDAP_OPT_X_TLS_DEMAND , +.BR LDAP_OPT_X_TLS_ALLOW , +.BR LDAP_OPT_X_TLS_TRY . +.TP +.B LDAP_OPT_X_TLS_REQUIRE_SAN +Sets/gets the peer certificate subjectAlternativeName checking strategy, +one of +.BR LDAP_OPT_X_TLS_NEVER , +.BR LDAP_OPT_X_TLS_HARD , +.BR LDAP_OPT_X_TLS_DEMAND , +.BR LDAP_OPT_X_TLS_ALLOW , +.BR LDAP_OPT_X_TLS_TRY . +.TP +.B LDAP_OPT_X_TLS_SSL_CTX +Gets the TLS session context associated with this handle. +.BR outvalue +must be +.BR "void **" . +When using the OpenSSL library this is an SSL*. When using other +crypto libraries this is a pointer to an OpenLDAP private structure. +Applications generally should not use this option. +.TP +.B LDAP_OPT_X_TLS_VERSION +Gets the TLS version being used on an established TLS session. +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_PEERKEY_HASH +Sets the (public) key that the application expects the peer to be using. +.B invalue +must be +.BR "const char *" +containing the base64 encoding of the expected peer's key or in the format +.B "<hashalg>:<peerkey hash base64 encoded>" +where as a TLS session is established, the library will hash the peer's key +with the provided hash algorithm and compare it with value provided and will +only allow the session to continue if they match. This happens regardless of +certificate checking strategy. The list of supported +.B hashalg +values depends on the crypto library used, check its documentation to get +a list. +.SH ERRORS +On success, the functions return +.BR LDAP_OPT_SUCCESS , +while they may return +.B LDAP_OPT_ERROR +to indicate a generic option handling error. +Occasionally, more specific errors can be returned, like +.B LDAP_NO_MEMORY +to indicate a failure in memory allocation. +.SH NOTES +The LDAP libraries with the +.B LDAP_OPT_REFERRALS +option set to +.B LDAP_OPT_ON +(default value) automatically follow referrals using an anonymous bind. +Application developers are encouraged to either implement consistent +referral chasing features, or explicitly disable referral chasing +by setting that option to +.BR LDAP_OPT_OFF . +.P +The protocol version used by the library defaults to LDAPv2 (now historic), +which corresponds to the +.B LDAP_VERSION2 +macro. +Application developers are encouraged to explicitly set +.B LDAP_OPT_PROTOCOL_VERSION +to LDAPv3, using the +.B LDAP_VERSION3 +macro, or to allow users to select the protocol version. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.B RFC 4422 +(http://www.rfc-editor.org), +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_get_option.3.links b/doc/man/man3/ldap_get_option.3.links new file mode 100644 index 0000000..9105ef0 --- /dev/null +++ b/doc/man/man3/ldap_get_option.3.links @@ -0,0 +1 @@ +ldap_set_option.3 diff --git a/doc/man/man3/ldap_get_values.3 b/doc/man/man3/ldap_get_values.3 new file mode 100644 index 0000000..a557c53 --- /dev/null +++ b/doc/man/man3/ldap_get_values.3 @@ -0,0 +1,102 @@ +.TH LDAP_GET_VALUES 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> + +.LP +.ft B +char **ldap_get_values(ld, entry, attr) +.ft +LDAP *ld; +LDAPMessage *entry; +char *attr; +.LP +.ft B +struct berval **ldap_get_values_len(ld, entry, attr) +.ft +LDAP *ld; +LDAPMessage *entry; +char *attr; +.LP +.ft B +int ldap_count_values(vals) +.ft +char **vals; +.LP +.ft B +int ldap_count_values_len(vals) +.ft +struct berval **vals; +.LP +.ft B +void ldap_value_free(vals) +.ft +char **vals; +.LP +.ft B +void ldap_value_free_len(vals) +.ft +struct berval **vals; +.SH DESCRIPTION +These routines are used to retrieve and manipulate attribute values +from an LDAP entry as returned by +.BR ldap_first_entry (3) +or +.BR ldap_next_entry (3). +.B ldap_get_values() +takes the \fIentry\fP and the attribute \fIattr\fP +whose values are desired and returns a NULL-terminated array of the +attribute's values. \fIattr\fP may be an attribute type as returned +from +.BR ldap_first_attribute (3) +or +.BR ldap_next_attribute (3), +or if the attribute type is known it can simply be given. +.LP +The number of values in the array can be counted by calling +.BR ldap_count_values() . +The array of values returned can be freed by calling +.BR ldap_value_free() . +.LP +If the attribute values are binary in nature, and thus not suitable +to be returned as an array of char *'s, the +.B ldap_get_values_len() +routine can be used instead. It takes the same parameters as +.BR ldap_get_values() , +but returns a NULL-terminated array of pointers +to berval structures, each containing the length of and a pointer +to a value. +.LP +The number of values in the array can be counted by calling +.BR ldap_count_values_len() . +The array of values returned can be freed by calling +.BR ldap_value_free_len() . +.SH ERRORS +If an error occurs in +.B ldap_get_values() +or +.BR ldap_get_values_len() , +NULL is returned and the +.B ld_errno +field in the \fIld\fP parameter is set to +indicate the error. See +.BR ldap_error (3) +for a description of possible error codes. +.SH NOTES +These routines dynamically allocate memory which the caller must free +using the supplied routines. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_entry (3), +.BR ldap_first_attribute (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_get_values.3.links b/doc/man/man3/ldap_get_values.3.links new file mode 100644 index 0000000..ac2b454 --- /dev/null +++ b/doc/man/man3/ldap_get_values.3.links @@ -0,0 +1,5 @@ +ldap_get_values_len.3 +ldap_value_free.3 +ldap_value_free_len.3 +ldap_count_values.3 +ldap_count_values_len.3 diff --git a/doc/man/man3/ldap_memory.3 b/doc/man/man3/ldap_memory.3 new file mode 100644 index 0000000..b3b6bb0 --- /dev/null +++ b/doc/man/man3/ldap_memory.3 @@ -0,0 +1,50 @@ +.TH LDAP_MEMORY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.B #include <ldap.h> +.LP +.BI "void ldap_memfree(void *" p ");" +.LP +.BI "void ldap_memvfree(void **" v ");" +.LP +.BI "void *ldap_memalloc(ber_len_t " s ");" +.LP +.BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" +.LP +.BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" +.LP +.BI "char *ldap_strdup(LDAP_CONST char *" p ");" +.SH DESCRIPTION +These routines are used to allocate/deallocate memory used/returned +by the LDAP library. +.BR ldap_memalloc (), +.BR ldap_memcalloc (), +.BR ldap_memrealloc (), +and +.BR ldap_memfree () +are used exactly like the standard +.BR malloc (3), +.BR calloc (3), +.BR realloc (3), +and +.BR free (3) +routines, respectively. +The +.BR ldap_memvfree () +routine is used to free a dynamically allocated array of pointers to +arbitrary dynamically allocated objects. +The +.BR ldap_strdup () +routine is used exactly like the standard +.BR strdup (3) +routine. +.SH SEE ALSO +.BR ldap (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_memory.3.links b/doc/man/man3/ldap_memory.3.links new file mode 100644 index 0000000..9351ff1 --- /dev/null +++ b/doc/man/man3/ldap_memory.3.links @@ -0,0 +1,6 @@ +ldap_memfree.3 +ldap_memvfree.3 +ldap_memalloc.3 +ldap_memcalloc.3 +ldap_memrealloc.3 +ldap_strdup.3 diff --git a/doc/man/man3/ldap_modify.3 b/doc/man/man3/ldap_modify.3 new file mode 100644 index 0000000..9ce3d74 --- /dev/null +++ b/doc/man/man3/ldap_modify.3 @@ -0,0 +1,134 @@ +.TH LDAP_MODIFY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_modify_ext( +.RS +.ft B +LDAP *\fIld\fB, +char *\fIdn\fB, +LDAPMod *\fImods[]\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB, +int *\fImsgidp\fB ); +.RE +.LP +.nf +.ft B +int ldap_modify_ext_s( +.RS +.ft B +LDAP *\fIld\fB, +char *\fIdn\fB, +LDAPMod *\fImods[]\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB ); +.RE +.LP +.nf +.ft B +void ldap_mods_free( +.RS +.ft B +LDAPMod **\fImods\fB, +int \fIfreemods\fB ); +.RE +.SH DESCRIPTION +The routine +.B ldap_modify_ext_s() +is used to perform an LDAP modify operation. +\fIdn\fP is the DN of the entry to modify, and \fImods\fP is a +null-terminated array of modifications to make to the entry. Each element +of the \fImods\fP array is a pointer to an LDAPMod structure, which is +defined below. +.LP +.nf + typedef struct ldapmod { + int mod_op; + char *mod_type; + union { + char **modv_strvals; + struct berval **modv_bvals; + } mod_vals; + } LDAPMod; + #define mod_values mod_vals.modv_strvals + #define mod_bvalues mod_vals.modv_bvals +.ft +.fi +.LP +The \fImod_op\fP field is used to specify the type of modification to +perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or +LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields +specify the attribute type to modify and a null-terminated array of +values to add, delete, or replace respectively. +.LP +If you need to specify a non-string value (e.g., to add a +photo or audio attribute value), you should set \fImod_op\fP to the +logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) +and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP +should be used instead of \fImod_values\fP, and it should point to +a null-terminated array of struct bervals, as defined in <lber.h>. +.LP +For LDAP_MOD_ADD modifications, the given values are added to the +entry, creating the attribute if necessary. For LDAP_MOD_DELETE +modifications, the given values are deleted from the entry, removing +the attribute if no values remain. If the entire attribute is to be deleted, +the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE +modifications, the attribute will have the listed values after the +modification, having been created if necessary. All modifications are +performed in the order in which they are listed. +.LP +.B ldap_mods_free() +can be used to free each element of a NULL-terminated +array of mod structures. If \fIfreemods\fP is non-zero, the +\fImods\fP pointer itself is freed as well. +.LP +.B ldap_modify_ext_s() +returns a code indicating success or, in the case of failure, +indicating the nature of the failure. See +.BR ldap_error (3) +for details +.LP +The +.B ldap_modify_ext() +operation works the same way as +.BR ldap_modify_ext_s() , +except that it is asynchronous. The integer that \fImsgidp\fP points +to is set to the message id of the modify request. The result of +the operation can be obtained by calling +.BR ldap_result (3). +.LP +Both +.B ldap_modify_ext() +and +.B ldap_modify_ext_s() +allows server and client controls to be passed in +via the sctrls and cctrls parameters, respectively. +.SH DEPRECATED INTERFACES +The +.B ldap_modify() +and +.B ldap_modify_s() +routines are deprecated in favor of the +.B ldap_modify_ext() +and +.B ldap_modify_ext_s() +routines, respectively. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.SH ACKNOWLEDGEMENTS +.so ../Project + diff --git a/doc/man/man3/ldap_modify.3.links b/doc/man/man3/ldap_modify.3.links new file mode 100644 index 0000000..81c6f2a --- /dev/null +++ b/doc/man/man3/ldap_modify.3.links @@ -0,0 +1,4 @@ +ldap_modify_s.3 +ldap_modify_ext.3 +ldap_modify_ext_s.3 +ldap_mods_free.3 diff --git a/doc/man/man3/ldap_modrdn.3 b/doc/man/man3/ldap_modrdn.3 new file mode 100644 index 0000000..3b2e77a --- /dev/null +++ b/doc/man/man3/ldap_modrdn.3 @@ -0,0 +1,81 @@ +.TH LDAP_MODRDN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_modrdn(ld, dn, newrdn) +.ft +LDAP \(**ld; +char \(**dn, \(**newrdn; +.LP +.ft B +.LP +.ft B +int ldap_modrdn_s(ld, dn, newrdn) +.ft +LDAP \(**ld; +char \(**dn, \(**newrdn; +.LP +.ft B +int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) +.ft +LDAP \(**ld; +char \(**dn, \(**newrdn; +int deleteoldrdn; +.LP +.ft B +int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) +.ft +LDAP \(**ld; +char \(**dn, \(**newrdn; +int deleteoldrdn; +.SH DESCRIPTION +The +.B ldap_modrdn() +and +.B ldap_modrdn_s() +routines perform an LDAP modify +RDN operation. They both take \fIdn\fP, the DN of the entry whose +RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. +The old RDN of the entry is never kept as an attribute of the entry. +.B ldap_modrdn() +is asynchronous, returning the message id of the operation +it initiates. +.B ldap_modrdn_s() +is synchronous, returning the LDAP error +code indicating the success or failure of the operation. Use of +these routines is deprecated. Use the versions described below +instead. +.LP +The +.B ldap_modrdn2() +and +.B ldap_modrdn2_s() +routines also perform an LDAP +modify RDN operation, taking the same parameters as above. In addition, +they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean +value to indicate whether the old RDN values should be deleted from +the entry or not. +.SH ERRORS +The synchronous (_s) versions of these routines return an LDAP error +code, either LDAP_SUCCESS or an error if there was trouble. +The asynchronous versions return \-1 in case +of trouble, setting the +.B ld_errno +field of \fIld\fP. See +.BR ldap_error (3) +for more details. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_modrdn.3.links b/doc/man/man3/ldap_modrdn.3.links new file mode 100644 index 0000000..86063e2 --- /dev/null +++ b/doc/man/man3/ldap_modrdn.3.links @@ -0,0 +1,3 @@ +ldap_modrdn_s.3 +ldap_modrdn2.3 +ldap_modrdn2_s.3 diff --git a/doc/man/man3/ldap_open.3 b/doc/man/man3/ldap_open.3 new file mode 100644 index 0000000..994032c --- /dev/null +++ b/doc/man/man3/ldap_open.3 @@ -0,0 +1,236 @@ +.TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +LDAP *ldap_open(host, port) +.ft +char *host; +int port; +.LP +.ft B +LDAP *ldap_init(host, port) +.ft +char *host; +int port; +.LP +.ft B +int ldap_initialize(ldp, uri) +.ft +LDAP **ldp; +char *uri; +.LP +.ft B +int ldap_connect(ldp) +.ft +LDAP *ldp; +.LP +.ft B +int ldap_set_urllist_proc(ld, proc, params) +.ft +LDAP *ld; +LDAP_URLLIST_PROC *proc; +void *params; +.LP +.ft B +int (LDAP_URLLIST_PROC)(ld, urllist, url, params); +.ft +LDAP *ld; +LDAPURLDesc **urllist; +LDAPURLDesc **url; +void *params; +.LP +.ft B +#include <openldap.h> +.LP +.ft B +int ldap_init_fd(fd, proto, uri, ldp) +.ft +ber_socket_t fd; +int proto; +char *uri; +LDAP **ldp; +.SH DESCRIPTION +.LP +.B ldap_open() +opens a connection to an LDAP server and allocates an LDAP +structure which is used to identify +the connection and to maintain per-connection information. +.B ldap_init() +allocates an LDAP structure but does not open an initial connection. +.B ldap_initialize() +allocates an LDAP structure but does not open an initial connection. +.B ldap_init_fd() +allocates an LDAP structure using an existing connection on the +provided socket. +One +of these routines must be called before any operations are attempted. +.LP +.B ldap_open() +takes \fIhost\fP, the hostname on which the LDAP server is +running, and \fIport\fP, the port number to which to connect. If the default +IANA-assigned port of 389 is desired, LDAP_PORT should be specified for +\fIport\fP. The \fIhost\fP parameter may contain a blank-separated list +of hosts to try to connect to, and each host may optionally by of the form +\fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP +parameter to +.BR ldap_open() . +Upon successfully making a connection to an +LDAP server, +.B ldap_open() +returns a pointer to an opaque LDAP structure, which should be passed +to subsequent calls to +.BR ldap_bind() , +.BR ldap_search() , +etc. Certain fields in the LDAP structure can be set to indicate size limit, +time limit, and how aliases are handled during operations; read and write access +to those fields must occur by calling +.BR ldap_get_option (3) +and +.BR ldap_set_option (3) +respectively, whenever possible. +.LP +.B +ldap_init() +acts just like +.BR ldap_open() , +but does not open a connection +to the LDAP server. The actual connection open will occur when the +first operation is attempted. +.LP +.B ldap_initialize() +acts like +.BR ldap_init() , +but it returns an integer indicating either success or the failure reason, +and it allows to specify details for the connection in the schema portion +of the URI. +The +.I uri +parameter may be a comma- or whitespace-separated list of URIs +containing only the +.IR schema , +the +.IR host , +and the +.I port +fields. +Apart from +.BR ldap , +other (non-standard) recognized values of the +.I schema +field are +.B ldaps +(LDAP over TLS), +.B ldapi +(LDAP over IPC), +and +.B cldap +(connectionless LDAP). +If other fields are present, the behavior is undefined. +.LP +At this time, +.B ldap_open() +and +.B ldap_init() +are deprecated in favor of +.BR ldap_initialize() , +essentially because the latter allows to specify a schema in the URI +and it explicitly returns an error code. +.LP +.B ldap_connect() +causes a handle created by +.B ldap_initialize() +to connect to the server. This is useful in situations where a file +descriptor is required before a request is performed. +.LP +.B ldap_init_fd() +allows an LDAP structure to be initialized using an already-opened +connection. The +.I proto +parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, +or LDAP_PROTO_IPC +for a connection using TCP, UDP, or IPC, respectively. The value +LDAP_PROTO_EXT +may also be specified if user-supplied sockbuf handlers are going to +be used. Note that support for UDP is not implemented unless libldap +was built with LDAP_CONNECTIONLESS defined. +The +.I uri +parameter may optionally be provided for informational purposes. +.LP +.B ldap_set_urllist_proc() +allows to set a function +.I proc +of type +.I LDAP_URLLIST_PROC +that is called when a successful connection can be established. +This function receives the list of URIs parsed from the +.I uri +string originally passed to +.BR ldap_initialize() , +and the one that successfully connected. +The function may manipulate the URI list; the typical use consists +in moving the successful URI to the head of the list, +so that subsequent attempts to connect to one of the URIs using the same LDAP handle +will try it first. +If +.I ld +is null, +.I proc +is set as a global parameter that is inherited by all handlers +within the process that are created after the call to +.BR ldap_set_urllist_proc() . +By default, no +.I LDAP_URLLIST_PROC +is set. +In a multithreaded environment, +.B ldap_set_urllist_proc() +must be called before any concurrent operation using the LDAP handle is started. + +Note: the first call into the LDAP library also initializes the global +options for the library. As such the first call should be single-threaded +or otherwise protected to insure that only one call is active. It is +recommended that +.BR ldap_get_option () +or +.BR ldap_set_option () +be used in the program's main thread before any additional threads are created. +See +.BR ldap_get_option (3). + +.SH ERRORS +If an error occurs, +.B ldap_open() +and +.B ldap_init() +will return NULL and +.I errno +should be set appropriately. +.B ldap_initialize() +and +.B ldap_init_fd() +will directly return the LDAP code associated to the error (or +.I LDAP_SUCCESS +in case of success); +.I errno +should be set as well whenever appropriate. +.B ldap_set_urllist_proc() +returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_bind (3), +.BR ldap_get_option (3), +.BR ldap_set_option (3), +.BR lber-sockbuf (3), +.BR errno (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_open.3.links b/doc/man/man3/ldap_open.3.links new file mode 100644 index 0000000..aa34ab7 --- /dev/null +++ b/doc/man/man3/ldap_open.3.links @@ -0,0 +1,4 @@ +ldap_init.3 +ldap_initialize.3 +ldap_set_urllist_proc.3 +ldap_init_fd.3 diff --git a/doc/man/man3/ldap_parse_reference.3 b/doc/man/man3/ldap_parse_reference.3 new file mode 100644 index 0000000..21fd733 --- /dev/null +++ b/doc/man/man3/ldap_parse_reference.3 @@ -0,0 +1,61 @@ +.TH LDAP_PARSE_REFERENCE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_parse_reference \- Extract referrals and controls from a reference message +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_parse_reference( LDAP *ld, LDAPMessage *reference, + char ***referralsp, LDAPControl ***serverctrlsp, + int freeit ) +.SH DESCRIPTION +.LP +The +.B ldap_parse_reference() +routine is used to extract referrals and controls from a reference message. +The \fIreference\fP parameter is a reference message as returned by a +call to +.BR ldap_first_reference (3) , +.BR ldap_next_reference (3) , +.BR ldap_first_message (3) , +.BR ldap_next_message (3) , +or +.BR ldap_result (3) . +.LP +The \fIreferralsp\fP parameter will be filled in with an allocated array of +character strings. The strings are copies of the referrals contained in +the parsed message. The array should be freed by calling +.BR ldap_value_free (3) . +If \fIreferralsp\fP is NULL, no referrals are returned. +If no referrals were returned, \fI*referralsp\fP is set to NULL. +.LP +The \fIserverctrlsp\fP parameter will be filled in with an allocated array of +controls copied from the parsed message. The array should be freed by calling +.BR ldap_controls_free (3). +If \fIserverctrlsp\fP is NULL, no controls are returned. +If no controls were returned, \fI*serverctrlsp\fP is set to NULL. +.LP +The \fIfreeit\fP parameter determines whether the parsed message is +freed or not after the extraction. Any non-zero value will make it +free the message. The +.BR ldap_msgfree (3) +routine can also be used to free the message later. +.SH ERRORS +Upon success LDAP_SUCCESS is returned. Otherwise the values of the +\fIreferralsp\fP and \fIserverctrlsp\fP parameters are undefined. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_reference (3), +.BR ldap_first_message (3), +.BR ldap_result (3), +.BR ldap_get_values (3), +.BR ldap_controls_free (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_parse_result.3 b/doc/man/man3/ldap_parse_result.3 new file mode 100644 index 0000000..82c7710 --- /dev/null +++ b/doc/man/man3/ldap_parse_result.3 @@ -0,0 +1,114 @@ +.TH LDAP_PARSE_RESULT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_parse_result \- Parsing results +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_parse_result( LDAP *ld, LDAPMessage *result, + int *errcodep, char **matcheddnp, char **errmsgp, + char ***referralsp, LDAPControl ***serverctrlsp, + int freeit ) +.LP +.ft B +int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, + struct berval **servercredp, int freeit ) +.LP +.ft B +int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, + char **retoidp, struct berval **retdatap, int freeit ) +.LP +.ft B +int ldap_parse_intermediate( LDAP *ld, LDAPMessage *result, + char **retoidp, struct berval **retdatap, + LDAPControl ***serverctrlsp, int freeit ) +.SH DESCRIPTION +.LP +These routines are used to extract information from a result message. +They will operate on the first result message in a chain of search +results (skipping past other message types). They take the \fIresult\fP +as returned by a call to +.BR ldap_result (3), +.BR ldap_search_s (3) +or +.BR ldap_search_st (3). +In addition to +.BR ldap_parse_result() , +the routines +.B ldap_parse_sasl_bind_result() +and +.B ldap_parse_extended_result() +are used to get all the result information from SASL bind and extended +operations. To extract information from intermediate responses, +.B ldap_parse_intermediate() +can be used. +.LP +The \fIerrcodep\fP parameter will be filled in with the result code from +the result message. +.LP +The server might supply a matched DN string in the message indicating +how much of a name in a request was recognized. The \fImatcheddnp\fP +parameter will be filled in with this string if supplied, else it will +be NULL. If a string is returned, it should be freed using +.BR ldap_memfree (3). +.LP +The \fIerrmsgp\fP parameter will be filled in with the error message +field from the parsed message. This string should be freed using +.BR ldap_memfree (3). +.LP +The \fIreferralsp\fP parameter will be filled in with an allocated array of +referral strings from the parsed message. This array should be freed using +.BR ldap_memvfree (3). +If no referrals were returned, \fI*referralsp\fP is set to NULL. +.LP +The \fIserverctrlsp\fP parameter will be filled in with an allocated array of +controls copied from the parsed message. The array should be freed using +.BR ldap_controls_free (3). +If no controls were returned, \fI*serverctrlsp\fP is set to NULL. +.LP +The \fIfreeit\fP parameter determines whether the parsed message is +freed or not after the extraction. Any non-zero value will make it +free the message. The +.BR ldap_msgfree (3) +routine can also be used to free the message later. +.LP +For SASL bind results, the \fIservercredp\fP parameter will be filled in +with an allocated berval structure containing the credentials from the +server if present. The structure should be freed using +.BR ber_bvfree (3). +.LP +For extended results and intermediate responses, the \fIretoidp\fP parameter will be filled in +with the dotted-OID text representation of the name of the extended +operation response. The string should be freed using +.BR ldap_memfree (3). +If no OID was returned, \fI*retoidp\fP is set to NULL. +.LP +For extended results and intermediate responses, the \fIretdatap\fP parameter will be filled in +with a pointer to a berval structure containing the data from the +extended operation response. The structure should be freed using +.BR ber_bvfree (3). +If no data were returned, \fI*retdatap\fP is set to NULL. +.LP +For all the above result parameters, NULL values can be used in calls +in order to ignore certain fields. +.SH ERRORS +Upon success LDAP_SUCCESS is returned. Otherwise the values of the +result parameters are undefined. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_search (3), +.BR ldap_memfree (3), +.BR ldap_memvfree (3), +.BR ldap_get_values (3), +.BR ldap_controls_free (3), +.BR lber-types (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_parse_result.3.links b/doc/man/man3/ldap_parse_result.3.links new file mode 100644 index 0000000..e2f4755 --- /dev/null +++ b/doc/man/man3/ldap_parse_result.3.links @@ -0,0 +1,3 @@ +ldap_parse_sasl_bind_result.3 +ldap_parse_extended_result.3 +ldap_parse_intermediate.3 diff --git a/doc/man/man3/ldap_parse_sort_control.3 b/doc/man/man3/ldap_parse_sort_control.3 new file mode 100644 index 0000000..56bf021 --- /dev/null +++ b/doc/man/man3/ldap_parse_sort_control.3 @@ -0,0 +1,40 @@ +.TH LDAP_PARSE_SORT-CONTROL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_parse_sort_control \- Decode the information returned from a search operation that used a server-side sort control +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_parse_sort_control(ld, ctrls, returnCode, attribute) +.ft +LDAP *ld; +LDAPControl **ctrls; +unsigned long *returnCode; +char **attribute; +.SH DESCRIPTION +This function is used to parse the results returned in a search operation +that uses a server-side sort control. +.LP +It takes a null terminated array of LDAPControl structures usually obtained +by a call to the +.BR ldap_parse_result +function. A returncode which points to the sort control result code,and an array +of LDAPControl structures that list the client controls to use with the search. +The function also takes an out parameter \fIattribute\fP and if the sort operation +fails, the server may return a string that indicates the first attribute in the +sortKey list that caused the failure. If this parameter is NULL, no string is +returned. If a string is returned, the memory should be freed by calling the +ldap_memfree function. +.SH NOTES +.SH SEE ALSO +.BR ldap_result (3), +.BR ldap_controls_free (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_parse_vlv_control.3 b/doc/man/man3/ldap_parse_vlv_control.3 new file mode 100644 index 0000000..be9efae --- /dev/null +++ b/doc/man/man3/ldap_parse_vlv_control.3 @@ -0,0 +1,49 @@ +.TH LDAP_PARSE_VLV_CONTROL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_parse_vlv_control \- Decode the information returned from a search operation that used a VLV (virtual list view) control +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_parse_vlv_control( ld, ctrlp, target_posp, list_countp, contextp, errcodep ) +.ft +LDAP *ld; +LDAPControl **ctrlp; +unsigned long *target_posp, *list_countp; +struct berval **contextp; +int *errcodep; +.SH DESCRIPTION +The +.B ldap_parse_vlv_control +is used to decode the information returned from a search operation that used a +VLV (virtual list view)control. It takes a null terminated array of LDAPControl +structures, usually obtained by a call to the +.BR ldap_parse_result function, +a \fItarget_pos\fP which points to the list index of the target entry. If +this parameter is NULL, the target position is not returned. The index returned +is an approximation of the position of the target entry. It is +not guaranteed to be exact. The parameter \fIlist_countp\fP points to +the server's estimate of the size of the list. If this parameter is NULL, the +size is not returned. \fIcontextp\fP is a pointer to the address of a berval +structure that contains a server-generated context identifier if server returns +one. If server does not return a context identifier, the server returns a NULL +in this parameter. If this parameter is set to NULL, the context identifier is +not returned. You should use this returned context in the next call to +create a VLV control. When the berval structure is no longer needed, you should +free the memory by calling the \fIber_bvfree function.e\fP +\fIerrcodep\fP is an output parameter, which points to the result code returned +by the server. If this parameter is NULL, the result code is not returned. +.LP +See +ldap.h for a list of possible return codes. +.SH SEE ALSO +.BR ldap_search (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_rename.3 b/doc/man/man3/ldap_rename.3 new file mode 100644 index 0000000..497be46 --- /dev/null +++ b/doc/man/man3/ldap_rename.3 @@ -0,0 +1,66 @@ +.TH LDAP_RENAME 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_rename, ldap_rename_s \- Renames the specified entry. +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_rename( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[], msgidp ); +.ft +LDAP *ld; +const char *dn, *newrdn, *newparent; +int deleteoldrdn; +LDAPControl *sctrls[], *cctrls[]; +int *msgidp); +.LP +.ft B +int ldap_rename_s( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[] ); +.ft +LDAP *ld; +const char *dn, *newrdn, *newparent; +int deleteoldrdn; +LDAPControl *sctrls[], *cctrls[]; +.SH DESCRIPTION +These routines are used to perform a LDAP rename operation. +The function changes the leaf component of an entry's distinguished +name and optionally moves the entry to a new parent container. The +.B ldap_rename_s +performs a rename operation synchronously. +The method takes \fIdn\fP, which points to the distinguished name of +the entry whose attribute is being compared, \fInewparent\fP,the distinguished +name of the entry's new parent. If this parameter is NULL, only the RDN is changed. +The root DN is specified by passing a zero length string, "". +\fIdeleteoldrdn\fP specifies whether the old RDN should be retained or deleted. +Zero indicates that the old RDN should be retained. If you choose this option, +the attribute will contain both names (the old and the new). +Non-zero indicates that the old RDN should be deleted. +\fIserverctrls\fP points to an array of LDAPControl structures that list the +client controls to use with this extended operation. Use NULL to specify +no client controls. \fIclientctrls\fP points to an array of LDAPControl +structures that list the client controls to use with the search. +.LP +.B ldap_rename +works just like +.B ldap_rename_s, +but the operation is asynchronous. It returns the message id of the request +it initiated. The result of this operation can be obtained by calling +.BR ldap_result(3). +.SH ERRORS +.B ldap_rename() +returns \-1 in case of error initiating the request, and +will set the \fIld_errno\fP field in the \fIld\fP parameter to +indicate the error. +.BR ldap_rename_s() +returns the LDAP error code resulting from the rename operation. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_modify (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_rename.3.links b/doc/man/man3/ldap_rename.3.links new file mode 100644 index 0000000..3281906 --- /dev/null +++ b/doc/man/man3/ldap_rename.3.links @@ -0,0 +1 @@ +ldap_rename_s.3 diff --git a/doc/man/man3/ldap_result.3 b/doc/man/man3/ldap_result.3 new file mode 100644 index 0000000..27f0805 --- /dev/null +++ b/doc/man/man3/ldap_result.3 @@ -0,0 +1,136 @@ +.TH LDAP_RESULT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_result \- Wait for the result of an LDAP operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_result( LDAP *ld, int msgid, int all, + struct timeval *timeout, LDAPMessage **result ); + +int ldap_msgfree( LDAPMessage *msg ); + +int ldap_msgtype( LDAPMessage *msg ); + +int ldap_msgid( LDAPMessage *msg ); +.ft +.SH DESCRIPTION +The +.B ldap_result() +routine is used to wait for and return the result of +an operation previously initiated by one of the LDAP asynchronous +operation routines (e.g., +.BR ldap_search_ext (3), +.BR ldap_modify_ext (3), +etc.). Those routines all return \-1 in case of error, and an +invocation identifier upon successful initiation of the operation. The +invocation identifier is picked by the library and is guaranteed to be +unique across the LDAP session. It can be used to request the result +of a specific operation from +.B ldap_result() +through the \fImsgid\fP parameter. +.LP +The +.B ldap_result() +routine will block or not, depending upon the setting +of the \fItimeout\fP parameter. +If timeout is not a NULL pointer, it specifies a maximum +interval to wait for the selection to complete. If timeout +is a NULL pointer, the LDAP_OPT_TIMEOUT value set by +.BR ldap_set_option (3) +is used. With the default setting, +the select blocks indefinitely. To +effect a poll, the timeout argument should be a non-NULL +pointer, pointing to a zero-valued timeval structure. +To obtain the behavior of the default setting, bypassing any value set by +.BR ldap_set_option (3), +set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. +See +.BR select (2) +for further details. +.LP +If the result of a specific operation is required, \fImsgid\fP should +be set to the invocation identifier returned when the operation was +initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be +supplied to wait for any or unsolicited response. +.LP +The \fIall\fP parameter, if non-zero, causes +.B ldap_result() +to return all responses with msgid, otherwise only the +next response is returned. This is commonly used to obtain all +the responses of a search operation. +.LP +A search response is made up of zero or +more search entries, zero or more search references, and zero or +more extended partial responses followed by a search result. If +\fIall\fP is set to 0, search entries will be returned one at a +time as they come in, via separate calls to +.BR ldap_result() . +If it's set to 1, the search +response will only be returned in its entirety, i.e., after all entries, +all references, all extended partial responses, and the final search +result have been received. +.SH RETURN VALUE +Upon success, the type of the result received is returned and the +\fIresult\fP parameter will contain the result of the operation; +otherwise, the \fIresult\fP parameter is undefined. This +result should be passed to the LDAP parsing routines, +.BR ldap_first_message (3) +and friends, for interpretation. +.LP +The possible result types returned are: +.LP +.nf + LDAP_RES_BIND (0x61) + LDAP_RES_SEARCH_ENTRY (0x64) + LDAP_RES_SEARCH_REFERENCE (0x73) + LDAP_RES_SEARCH_RESULT (0x65) + LDAP_RES_MODIFY (0x67) + LDAP_RES_ADD (0x69) + LDAP_RES_DELETE (0x6b) + LDAP_RES_MODDN (0x6d) + LDAP_RES_COMPARE (0x6f) + LDAP_RES_EXTENDED (0x78) + LDAP_RES_INTERMEDIATE (0x79) +.fi +.LP +The +.B ldap_msgfree() +routine is used to free the memory allocated for +result(s) by +.B ldap_result() +or +.BR ldap_search_ext_s (3) +and friends. +It takes a pointer to the result or result chain to be freed and returns +the type of the last message in the chain. +If the parameter is NULL, the function does nothing and returns zero. +.LP +The +.B ldap_msgtype() +routine returns the type of a message. +.LP +The +.B ldap_msgid() +routine returns the message id of a message. +.SH ERRORS +.B ldap_result() +returns \-1 if something bad happens, and zero if the +timeout specified was exceeded. +.B ldap_msgtype() +and +.B ldap_msgid() +return \-1 on error. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_message (3), +.BR select (2) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_result.3.links b/doc/man/man3/ldap_result.3.links new file mode 100644 index 0000000..1394c6c --- /dev/null +++ b/doc/man/man3/ldap_result.3.links @@ -0,0 +1,3 @@ +ldap_msgfree.3 +ldap_msgtype.3 +ldap_msgid.3 diff --git a/doc/man/man3/ldap_schema.3 b/doc/man/man3/ldap_schema.3 new file mode 100644 index 0000000..1cae152 --- /dev/null +++ b/doc/man/man3/ldap_schema.3 @@ -0,0 +1,320 @@ +.TH LDAP_SCHEMA 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 2000-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +#include <ldap_schema.h> +.LP +.ft B +LDAPSyntax * ldap_str2syntax(s, code, errp, flags) +.ft +const char * s; +int * code; +const char ** errp; +const int flags; +.LP +.ft B +char * ldap_syntax2str(syn) +.ft +const LDAPSyntax * syn; +.LP +.ft B +const char * ldap_syntax2name(syn) +.ft +LDAPSyntax * syn; +.LP +.ft B +ldap_syntax_free(syn) +.ft +LDAPSyntax * syn; +.LP +.ft B +LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) +.ft +const char * s; +int * code; +const char ** errp; +const int flags; +.LP +.ft B +char * ldap_matchingrule2str(mr); +.ft +const LDAPMatchingRule * mr; +.LP +.ft B +const char * ldap_matchingrule2name(mr) +.ft +LDAPMatchingRule * mr; +.LP +.ft B +ldap_matchingrule_free(mr) +.ft +LDAPMatchingRule * mr; +.LP +.ft B +LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) +.ft +const char * s; +int * code; +const char ** errp; +const int flags; +.LP +.ft B +char * ldap_attributetype2str(at) +.ft +const LDAPAttributeType * at; +.LP +.ft B +const char * ldap_attributetype2name(at) +.ft +LDAPAttributeType * at; +.LP +.ft B +ldap_attributetype_free(at) +.ft +LDAPAttributeType * at; +.LP +.ft B +LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) +.ft +const char * s; +int * code; +const char ** errp; +const int flags; +.LP +.ft B +char * ldap_objectclass2str(oc) +.ft +const LDAPObjectClass * oc; +.LP +.ft B +const char * ldap_objectclass2name(oc) +.ft +LDAPObjectClass * oc; +.LP +.ft B +ldap_objectclass_free(oc) +.ft +LDAPObjectClass * oc; +.LP +.ft B +char * ldap_scherr2str(code) +.ft +int code; +.SH DESCRIPTION +These routines are used to parse schema definitions in the syntax +defined in RFC 4512 into structs and handle these structs. These +routines handle four kinds of definitions: syntaxes, matching rules, +attribute types and object classes. For each definition kind, four +routines are provided. +.LP +.B ldap_str2xxx() +takes a definition in RFC 4512 format in argument +.IR s +as a NUL-terminated string and returns, if possible, a pointer to a +newly allocated struct of the appropriate kind. The caller is +responsible for freeing the struct by calling +.B ldap_xxx_free() +when not needed any longer. The routine returns NULL if some problem +happened. In this case, the integer pointed at by argument +.IR code +will receive an error code (see below the description of +.B ldap_scherr2str() +for an explanation of the values) and a pointer to a NUL-terminated +string will be placed where requested by argument +.IR errp +, indicating where in argument +.IR s +the error happened, so it must not be freed by the caller. Argument +.IR flags +is a bit mask of parsing options controlling the relaxation of the +syntax recognized. The following values are defined: +.TP +.B LDAP_SCHEMA_ALLOW_NONE +strict parsing according to RFC 4512. +.TP +.B LDAP_SCHEMA_ALLOW_NO_OID +permit definitions that do not contain an initial OID. +.TP +.B LDAP_SCHEMA_ALLOW_QUOTED +permit quotes around some items that should not have them. +.TP +.B LDAP_SCHEMA_ALLOW_DESCR +permit a +.B descr +instead of a numeric OID in places where the syntax expect the latter. +.TP +.B LDAP_SCHEMA_ALLOW_DESCR_PREFIX +permit that the initial numeric OID contains a prefix in +.B descr +format. +.TP +.B LDAP_SCHEMA_ALLOW_ALL +be very liberal, include all options. +.LP +The structures returned are as follows: +.sp +.RS +.nf +.ne 7 +.ta 8n 16n 32n +typedef struct ldap_schema_extension_item { + char *lsei_name; /* Extension name */ + char **lsei_values; /* Extension values */ +} LDAPSchemaExtensionItem; + +typedef struct ldap_syntax { + char *syn_oid; /* OID */ + char **syn_names; /* Names */ + char *syn_desc; /* Description */ + LDAPSchemaExtensionItem **syn_extensions; /* Extension */ +} LDAPSyntax; + +typedef struct ldap_matchingrule { + char *mr_oid; /* OID */ + char **mr_names; /* Names */ + char *mr_desc; /* Description */ + int mr_obsolete; /* Is obsolete? */ + char *mr_syntax_oid; /* Syntax of asserted values */ + LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ +} LDAPMatchingRule; + +typedef struct ldap_attributetype { + char *at_oid; /* OID */ + char **at_names; /* Names */ + char *at_desc; /* Description */ + int at_obsolete; /* Is obsolete? */ + char *at_sup_oid; /* OID of superior type */ + char *at_equality_oid; /* OID of equality matching rule */ + char *at_ordering_oid; /* OID of ordering matching rule */ + char *at_substr_oid; /* OID of substrings matching rule */ + char *at_syntax_oid; /* OID of syntax of values */ + int at_syntax_len; /* Suggested minimum maximum length */ + int at_single_value; /* Is single-valued? */ + int at_collective; /* Is collective? */ + int at_no_user_mod; /* Are changes forbidden through LDAP? */ + int at_usage; /* Usage, see below */ + LDAPSchemaExtensionItem **at_extensions; /* Extensions */ +} LDAPAttributeType; + +typedef struct ldap_objectclass { + char *oc_oid; /* OID */ + char **oc_names; /* Names */ + char *oc_desc; /* Description */ + int oc_obsolete; /* Is obsolete? */ + char **oc_sup_oids; /* OIDs of superior classes */ + int oc_kind; /* Kind, see below */ + char **oc_at_oids_must; /* OIDs of required attribute types */ + char **oc_at_oids_may; /* OIDs of optional attribute types */ + LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ +} LDAPObjectClass; +.ta +.fi +.RE +.PP +Some integer fields (those described with a question mark) have a +truth value, for these fields the possible values are: +.TP +.B LDAP_SCHEMA_NO +The answer to the question is no. +.TP +.B LDAP_SCHEMA_YES +The answer to the question is yes. +.LP +For attribute types, the following usages are possible: +.TP +.B LDAP_SCHEMA_USER_APPLICATIONS +the attribute type is non-operational. +.TP +.B LDAP_SCHEMA_DIRECTORY_OPERATION +the attribute type is operational and is pertinent to the directory +itself, i.e. it has the same value on all servers that provide the +entry containing this attribute type. +.TP +.B LDAP_SCHEMA_DISTRIBUTED_OPERATION +the attribute type is operational and is pertinent to replication, +shadowing or other distributed directory aspect. TBC. +.TP +.B LDAP_SCHEMA_DSA_OPERATION +the attribute type is operational and is pertinent to the directory +server itself, i.e. it may have different values for the same entry +when retrieved from different servers that provide the entry. +.LP +Object classes can be of three kinds: +.TP +.B LDAP_SCHEMA_ABSTRACT +the object class is abstract, i.e. there cannot be entries of this +class alone. +.TP +.B LDAP_SCHEMA_STRUCTURAL +the object class is structural, i.e. it describes the main role of the +entry. On some servers, once the entry is created the set of +structural object classes assigned cannot be changed: none of those +present can be removed and none other can be added. +.TP +.B LDAP_SCHEMA_AUXILIARY +the object class is auxiliary, i.e. it is intended to go with other, +structural, object classes. These can be added or removed at any time +if attribute types are added or removed at the same time as needed by +the set of object classes resulting from the operation. +.LP +Routines +.B ldap_xxx2name() +return a canonical name for the definition. +.LP +Routines +.B ldap_xxx2str() +return a string representation in the format described by RFC 4512 of +the struct passed in the argument. The string is a newly allocated +string that must be freed by the caller. These routines may return +NULL if no memory can be allocated for the string. +.LP +.B ldap_scherr2str() +returns a NUL-terminated string with a text description of the error +found. This is a pointer to a static area, so it must not be freed by +the caller. The argument +.IR code +comes from one of the parsing routines and can adopt the following +values: +.TP +.B LDAP_SCHERR_OUTOFMEM +Out of memory. +.TP +.B LDAP_SCHERR_UNEXPTOKEN +Unexpected token. +.TP +.B LDAP_SCHERR_NOLEFTPAREN +Missing opening parenthesis. +.TP +.B LDAP_SCHERR_NORIGHTPAREN +Missing closing parenthesis. +.TP +.B LDAP_SCHERR_NODIGIT +Expecting digit. +.TP +.B LDAP_SCHERR_BADNAME +Expecting a name. +.TP +.B LDAP_SCHERR_BADDESC +Bad description. +.TP +.B LDAP_SCHERR_BADSUP +Bad superiors. +.TP +.B LDAP_SCHERR_DUPOPT +Duplicate option. +.TP +.B LDAP_SCHERR_EMPTY +Unexpected end of data. + +.SH SEE ALSO +.BR ldap (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_schema.3.links b/doc/man/man3/ldap_schema.3.links new file mode 100644 index 0000000..05e1675 --- /dev/null +++ b/doc/man/man3/ldap_schema.3.links @@ -0,0 +1,17 @@ +ldap_str2syntax.3 +ldap_syntax2str.3 +ldap_syntax2name.3 +ldap_syntax_free.3 +ldap_str2matchingrule.3 +ldap_matchingrule2str.3 +ldap_matchingrule2name.3 +ldap_matchingrule_free.3 +ldap_str2attributetype.3 +ldap_attributetype2str.3 +ldap_attributetype2name.3 +ldap_attributetype_free.3 +ldap_str2objectclass.3 +ldap_objectclass2str.3 +ldap_objectclass2name.3 +ldap_objectclass_free.3 +ldap_scherr2str.3 diff --git a/doc/man/man3/ldap_search.3 b/doc/man/man3/ldap_search.3 new file mode 100644 index 0000000..dc58b6d --- /dev/null +++ b/doc/man/man3/ldap_search.3 @@ -0,0 +1,144 @@ +.TH LDAP_SEARCH 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <sys/types.h> +#include <ldap.h> +.LP +.ft B +int ldap_search_ext( +.RS +LDAP *\fIld\fB, +char *\fIbase\fB, +int \fIscope\fB, +char *\fIfilter\fB, +char *\fIattrs\fB[], +int \fIattrsonly\fB, +LDAPControl **\fIserverctrls\fB, +LDAPControl **\fIclientctrls\fB, +struct timeval *\fItimeout\fB, +int \fIsizelimit\fB, +int *\fImsgidp\fB ); +.RE +.LP +.ft B +int ldap_search_ext_s( +.RS +LDAP *\fIld\fB, +char *\fIbase\fB, +int \fIscope\fB, +char *\fIfilter\fB, +char *\fIattrs\fB[], +int \fIattrsonly\fB, +LDAPControl **\fIserverctrls\fB, +LDAPControl **\fIclientctrls\fB, +struct timeval *\fItimeout\fB, +int \fIsizelimit\fB, +LDAPMessage **\fIres\fB ); +.RE +.SH DESCRIPTION +These routines are used to perform LDAP search operations. +The +.B ldap_search_ext_s() +routine +does the search synchronously (i.e., not +returning until the operation completes), providing a pointer +to the resulting LDAP messages at the location pointed to by +the \fIres\fP parameter. +.LP +The +.B ldap_search_ext() +routine is the asynchronous version, initiating the search and returning +the message id of the operation it initiated in the integer +pointed to by the \fImsgidp\fP parameter. +.LP +The \fIbase\fP parameter is the DN of the entry at which to start the search. +.LP +The \fIscope\fP parameter is the scope of the search and should be one +of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, +to search the object's immediate children, LDAP_SCOPE_SUBTREE, to +search the object and all its descendants, or LDAP_SCOPE_CHILDREN, +to search all of the descendants. Note that the latter requires +the server support the LDAP Subordinates Search Scope extension. +.LP +The \fIfilter\fP is a string representation of the filter to +apply in the search. The string should conform to the format +specified in RFC 4515 as extended by RFC 4526. For instance, +"(cn=Jane Doe)". Note that use of the extension requires the +server to support the LDAP Absolute True/False Filter extension. +NULL may be specified to indicate the library should send the +filter (objectClass=*). +.LP +The \fIattrs\fP parameter is a null-terminated array of attribute +descriptions to return from matching entries. +If NULL is specified, the return of all user attributes is requested. +The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request +all user attributes to be returned. +The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to +request all operational attributes to be returned. Note that this +requires the server to support the LDAP All Operational Attribute +extension. +To request no attributes, the description "1.1" (LDAP_NO_ATTRS) +should be listed by itself. +.LP +The \fIattrsonly\fP parameter should be set to a non-zero value +if only attribute descriptions are wanted. It should be set to zero (0) +if both attributes descriptions and attribute values are wanted. +.LP +The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used +to specify server and client controls, respectively. +.LP +The +.B ldap_search_ext_s() +routine is the synchronous version of +.BR ldap_search_ext(). +.LP +It also returns a code indicating success or, in the +case of failure, indicating the nature of the failure +of the operation. See +.BR ldap_error (3) +for details. +.SH NOTES +Note that both read +and list functionality are subsumed by these routines, +by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to +emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). +.LP +These routines may dynamically allocate memory. The caller is +responsible for freeing such memory using supplied deallocation +routines. Return values are contained in <ldap.h>. +.LP +Note that \fIres\fR parameter of +.B ldap_search_ext_s() +and +.B ldap_search_s() +should be freed with +.B ldap_msgfree() +regardless of return value of these functions. +.SH DEPRECATED INTERFACES +The +.B ldap_search() +routine is deprecated in favor of the +.B ldap_search_ext() +routine. The +.B ldap_search_s() +and +.B ldap_search_st() +routines are deprecated in favor of the +.B ldap_search_ext_s() +routine. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_search.3.links b/doc/man/man3/ldap_search.3.links new file mode 100644 index 0000000..d85bf81 --- /dev/null +++ b/doc/man/man3/ldap_search.3.links @@ -0,0 +1,4 @@ +ldap_search_s.3 +ldap_search_st.3 +ldap_search_ext.3 +ldap_search_ext_s.3 diff --git a/doc/man/man3/ldap_sort.3 b/doc/man/man3/ldap_sort.3 new file mode 100644 index 0000000..75fe54c --- /dev/null +++ b/doc/man/man3/ldap_sort.3 @@ -0,0 +1,21 @@ +.TH LDAP_SORT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH DESCRIPTION +The +.BR ldap_sort_entries (), +.BR ldap_sort_values (), +and +.BR ldap_sort_strcasecmp () +are deprecated. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_sort.3.links b/doc/man/man3/ldap_sort.3.links new file mode 100644 index 0000000..7a4be53 --- /dev/null +++ b/doc/man/man3/ldap_sort.3.links @@ -0,0 +1,3 @@ +ldap_sort_entries.3 +ldap_sort_values.3 +ldap_sort_strcasecmp.3 diff --git a/doc/man/man3/ldap_sync.3 b/doc/man/man3/ldap_sync.3 new file mode 100644 index 0000000..8fb77f5 --- /dev/null +++ b/doc/man/man3/ldap_sync.3 @@ -0,0 +1,326 @@ +.TH LDAP_SYNC 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 2006-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist, ldap_sync_poll \- LDAP sync routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.B #include <ldap.h> +.LP +.BI "int ldap_sync_init(ldap_sync_t *" ls ", int " mode ");" +.LP +.BI "int ldap_sync_init_refresh_only(ldap_sync_t *" ls ");" +.LP +.BI "int ldap_sync_init_refresh_and_persist(ldap_sync_t *" ls ");" +.LP +.BI "int ldap_sync_poll(ldap_sync_t *" ls ");" +.LP +.BI "ldap_sync_t * ldap_sync_initialize(ldap_sync_t *" ls ");" +.LP +.BI "void ldap_sync_destroy(ldap_sync_t *" ls ", int " freeit ");" +.LP +.BI "typedef int (*" ldap_sync_search_entry_f ")(ldap_sync_t *" ls "," +.RS +.BI "LDAPMessage *" msg ", struct berval *" entryUUID "," +.BI "ldap_sync_refresh_t " phase ");" +.RE +.LP +.BI "typedef int (*" ldap_sync_search_reference_f ")(ldap_sync_t *" ls "," +.RS +.BI "LDAPMessage *" msg ");" +.RE +.LP +.BI "typedef int (*" ldap_sync_intermediate_f ")(ldap_sync_t *" ls "," +.RS +.BI "LDAPMessage *" msg ", BerVarray " syncUUIDs "," +.BI "ldap_sync_refresh_t " phase ");" +.RE +.LP +.BI "typedef int (*" ldap_sync_search_result_f ")(ldap_sync_t *" ls "," +.RS +.BI "LDAPMessage *" msg ", int " refreshDeletes ");" +.RE +.SH DESCRIPTION +.LP +These routines provide an interface to the LDAP Content Synchronization +operation (RFC 4533). +They require an +.BR ldap_sync_t +structure to be set up with parameters required for various phases +of the operation; this includes setting some handlers for special events. +All handlers take a pointer to the \fBldap_sync_t\fP structure as the first +argument, and a pointer to the \fBLDAPMessage\fP structure as received +from the server by the client library, plus, occasionally, other specific +arguments. + +The members of the \fBldap_sync_t\fP structure are: +.TP +.BI "char *" ls_base +The search base; by default, the +.B BASE +option in +.BR ldap.conf (5). +.TP +.BI "int " ls_scope +The search scope (one of +.BR LDAP_SCOPE_BASE , +.BR LDAP_SCOPE_ONELEVEL , +.BR LDAP_SCOPE_SUBORDINATE +or +.BR LDAP_SCOPE_SUBTREE ; +see +.B ldap.h +for details). +.TP +.BI "char *" ls_filter +The filter (RFC 4515); by default, +.BR (objectClass=*) . +.TP +.BI "char **" ls_attrs +The requested attributes; by default +.BR NULL , +indicating all user attributes. +.TP +.BI "int " ls_timelimit +The requested time limit (in seconds); by default +.BR 0 , +to indicate no limit. +.TP +.BI "int " ls_sizelimit +The requested size limit (in entries); by default +.BR 0 , +to indicate no limit. +.TP +.BI "int " ls_timeout +The desired timeout during polling with +.BR ldap_sync_poll (3). +A value of +.BR \-1 +means that polling is blocking, so +.BR ldap_sync_poll (3) +will not return until a message is received; a value of +.BR 0 +means that polling returns immediately, no matter if any response +is available or not; a positive value represents the timeout the +.BR ldap_sync_poll (3) +function will wait for response before returning, unless a message +is received; in that case, +.BR ldap_sync_poll (3) +returns as soon as the message is available. +.TP +.BI "ldap_sync_search_entry_f " ls_search_entry +A function that is called whenever an entry is returned. +The +.BR msg +argument is the +.BR LDAPMessage +that contains the searchResultEntry; it can be parsed using the regular +client API routines, like +.BR ldap_get_dn (3), +.BR ldap_first_attribute (3), +and so on. +The +.BR entryUUID +argument contains the entryUUID of the entry. +The +.BR phase +argument indicates the type of operation: one of +.BR LDAP_SYNC_CAPI_PRESENT , +.BR LDAP_SYNC_CAPI_ADD , +.BR LDAP_SYNC_CAPI_MODIFY , +.BR LDAP_SYNC_CAPI_DELETE ; +in case of +.BR LDAP_SYNC_CAPI_PRESENT +or +.BR LDAP_SYNC_CAPI_DELETE , +only the DN is contained in the +.IR LDAPMessage ; +in case of +.BR LDAP_SYNC_CAPI_MODIFY , +the whole entry is contained in the +.IR LDAPMessage , +and the application is responsible of determining the differences +between the new view of the entry provided by the caller and the data +already known. +.TP +.BI "ldap_sync_search_reference_f " ls_search_reference +A function that is called whenever a search reference is returned. +The +.BR msg +argument is the +.BR LDAPMessage +that contains the searchResultReference; it can be parsed using +the regular client API routines, like +.BR ldap_parse_reference (3). +.TP +.BI "ldap_sync_intermediate_f " ls_intermediate +A function that is called whenever something relevant occurs during +the refresh phase of the search, which is marked by +an \fIintermediateResponse\fP message type. +The +.BR msg +argument is the +.BR LDAPMessage +that contains the intermediate response; it can be parsed using +the regular client API routines, like +.BR ldap_parse_intermediate (3). +The +.BR syncUUIDs +argument contains an array of UUIDs of the entries that depends +on the value of the +.BR phase +argument. +In case of +.BR LDAP_SYNC_CAPI_PRESENTS , +the "present" phase is being entered; +this means that the following sequence of results will consist +in entries in "present" sync state. +In case of +.BR LDAP_SYNC_CAPI_DELETES , +the "deletes" phase is being entered; +this means that the following sequence of results will consist +in entries in "delete" sync state. +In case of +.BR LDAP_SYNC_CAPI_PRESENTS_IDSET , +the message contains a set of UUIDs of entries that are present; +it replaces a "presents" phase. +In case of +.BR LDAP_SYNC_CAPI_DELETES_IDSET , +the message contains a set of UUIDs of entries that have been deleted; +it replaces a "deletes" phase. +In case of +.BR LDAP_SYNC_CAPI_DONE, +a "presents" phase with "refreshDone" set to "TRUE" has been returned +to indicate that the refresh phase of refreshAndPersist is over, and +the client should start polling. +Except for the +.BR LDAP_SYNC_CAPI_PRESENTS_IDSET +and +.BR LDAP_SYNC_CAPI_DELETES_IDSET +cases, +.BR syncUUIDs +is NULL. +.BR +.TP +.BI "ldap_sync_search_result_f " ls_search_result +A function that is called whenever a searchResultDone is returned. +In refreshAndPersist this can only occur when the server decides +that the search must be interrupted. +The +.BR msg +argument is the +.BR LDAPMessage +that contains the response; it can be parsed using +the regular client API routines, like +.BR ldap_parse_result (3). +The +.BR refreshDeletes +argument is not relevant in this case; it should always be \-1. +.TP +.BI "void *" ls_private +A pointer to private data. The client may register here +a pointer to data the handlers above may need. +.TP +.BI "LDAP *" ls_ld +A pointer to a LDAP structure that is used to connect to the server. +It is the responsibility of the client to initialize the structure +and to provide appropriate authentication and security in place. + +.SH "GENERAL USE" +A +.B ldap_sync_t +structure is initialized by calling +.BR ldap_sync_initialize(3). +This simply clears out the contents of an already existing +.B ldap_sync_t +structure, and sets appropriate values for some members. +After that, the caller is responsible for setting up the +connection (member +.BR ls_ld ), +eventually setting up transport security (TLS), +for binding and any other initialization. +The caller must also fill all the documented search-related fields +of the +.B ldap_sync_t +structure. + +At the end of a session, the structure can be cleaned up by calling +.BR ldap_sync_destroy (3), +which takes care of freeing all data assuming it was allocated by +.BR ldap_mem* (3) +routines. +Otherwise, the caller should take care of destroying and zeroing out +the documented search-related fields, and call +.BR ldap_sync_destroy (3) +to free undocumented members set by the API. + +.SH "REFRESH ONLY" +The +.BR refreshOnly +functionality is obtained by periodically calling +.BR ldap_sync_init (3) +with mode set to +.BR LDAP_SYNC_REFRESH_ONLY , +or, which is equivalent, by directly calling +.BR ldap_sync_init_refresh_only (3). +The state of the search, and the consistency of the search parameters, +is preserved across calls by passing the +.B ldap_sync_t +structure as left by the previous call. + +.SH "REFRESH AND PERSIST" +The +.BR refreshAndPersist +functionality is obtained by calling +.BR ldap_sync_init (3) +with mode set to +.BR LDAP_SYNC_REFRESH_AND_PERSIST , +or, which is equivalent, by directly calling +.BR ldap_sync_init_refresh_and_persist (3) +and, after a successful return, by repeatedly polling with +.BR ldap_sync_poll (3) +according to the desired pattern. + +A client may insert a call to +.BR ldap_sync_poll (3) +into an external loop to check if any modification was returned; +in this case, it might be appropriate to set +.BR ls_timeout +to 0, or to set it to a finite, small value. +Otherwise, if the client's main purpose consists in waiting for +responses, a timeout of \-1 is most suitable, so that the function +only returns after some data has been received and handled. + +.SH ERRORS +All routines return any LDAP error resulting from a lower-level error +in the API calls they are based on, or LDAP_SUCCESS in case of success. +.BR ldap_sync_poll (3) +may return +.BR LDAP_SYNC_REFRESH_REQUIRED +if a full refresh is requested by the server. +In this case, it is appropriate to call +.BR ldap_sync_init (3) +again, passing the same +.B ldap_sync_t +structure as resulted from any previous call. +.SH NOTES +.SH SEE ALSO +.BR ldap (3), +.BR ldap_search_ext (3), +.BR ldap_result (3) ; +.B RFC 4533 +(http://www.rfc-editor.org), +.SH AUTHOR +Designed and implemented by Pierangelo Masarati, based on RFC 4533 +and loosely inspired by syncrepl code in +.BR slapd (8). +.SH ACKNOWLEDGEMENTS +Initially developed by +.BR "SysNet s.n.c." +.B OpenLDAP +is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). +.B OpenLDAP +is derived from University of Michigan LDAP 3.3 Release. diff --git a/doc/man/man3/ldap_tls.3 b/doc/man/man3/ldap_tls.3 new file mode 100644 index 0000000..4170d42 --- /dev/null +++ b/doc/man/man3/ldap_tls.3 @@ -0,0 +1,41 @@ +.TH LDAP_TLS 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.B #include <ldap.h> +.LP +.BI "int ldap_start_tls(LDAP *" ld ");" +.LP +.BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" +.LP +.BI "int ldap_tls_inplace(LDAP *" ld ");" +.LP +.BI "int ldap_install_tls(LDAP *" ld ");" +.SH DESCRIPTION +These routines are used to initiate TLS processing on an LDAP session. +.BR ldap_start_tls_s () +sends a StartTLS request to a server, waits for the reply, and then installs +TLS handlers on the session if the request succeeded. The routine returns +.B LDAP_SUCCESS +if everything succeeded, otherwise it returns an LDAP error code. +.BR ldap_start_tls () +sends a StartTLS request to a server and does nothing else. It returns +.B LDAP_SUCCESS +if the request was sent successfully. +.BR ldap_tls_inplace () +returns 1 if TLS handlers have been installed on the specified session, 0 +otherwise. +.BR ldap_install_tls () +installs the TLS handlers on the given session. It returns +.B LDAP_LOCAL_ERROR +if TLS is already installed. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man3/ldap_tls.3.links b/doc/man/man3/ldap_tls.3.links new file mode 100644 index 0000000..d03e2bf --- /dev/null +++ b/doc/man/man3/ldap_tls.3.links @@ -0,0 +1,4 @@ +ldap_start_tls.3 +ldap_start_tls_s.3 +ldap_tls_inplace.3 +ldap_install_tls.3 diff --git a/doc/man/man3/ldap_url.3 b/doc/man/man3/ldap_url.3 new file mode 100644 index 0000000..ec7f343 --- /dev/null +++ b/doc/man/man3/ldap_url.3 @@ -0,0 +1,83 @@ +.TH LDAP_URL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include <ldap.h> +.LP +.ft B +int ldap_is_ldap_url( const char *url ) +.LP +.ft B +int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) +.LP +typedef struct ldap_url_desc { + char * lud_scheme; /* URI scheme */ + char * lud_host; /* LDAP host to contact */ + int lud_port; /* port on host */ + char * lud_dn; /* base for search */ + char ** lud_attrs; /* list of attributes */ + int lud_scope; /* a LDAP_SCOPE_... value */ + char * lud_filter; /* LDAP search filter */ + char ** lud_exts; /* LDAP extensions */ + int lud_crit_exts; /* true if any extension is critical */ + /* may contain additional fields for internal use */ +} LDAPURLDesc; +.LP +.ft B +void ldap_free_urldesc( LDAPURLDesc *ludp ); +.SH DESCRIPTION +These routines support the use of LDAP URLs (Uniform Resource Locators) +as detailed in RFC 4516. LDAP URLs look like this: +.nf + + \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] + +where: + \fIhostport\fP is a host name with an optional ":portnumber" + \fIdn\fP is the search base + \fIattrs\fP is a comma separated list of attributes to request + \fIscope\fP is one of these three strings: + base one sub (default=base) + \fIfilter\fP is filter + \fIexts\fP are recognized set of LDAP and/or API extensions. + +Example: + ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) + +.fi +.LP +URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also +tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be +parsed using the below routines as well. +.LP +.B ldap_is_ldap_url() +returns a non-zero value if \fIurl\fP looks like an LDAP URL (as +opposed to some other kind of URL). It can be used as a quick check +for an LDAP URL; the +.B ldap_url_parse() +routine should be used if a more thorough check is needed. +.LP +.B ldap_url_parse() +breaks down an LDAP URL passed in \fIurl\fP into its component pieces. +If successful, zero is returned, an LDAP URL description is +allocated, filled in, and \fIludpp\fP is set to point to it. If an +error occurs, a non-zero URL error code is returned. +.LP +.B ldap_free_urldesc() +should be called to free an LDAP URL description that was obtained from +a call to +.B ldap_url_parse(). +.SH SEE ALSO +.nf +.BR ldap (3) +.BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" +.SH ACKNOWLEDGEMENTS +.fi +.so ../Project diff --git a/doc/man/man3/ldap_url.3.links b/doc/man/man3/ldap_url.3.links new file mode 100644 index 0000000..90fe023 --- /dev/null +++ b/doc/man/man3/ldap_url.3.links @@ -0,0 +1,3 @@ +ldap_is_ldap_url.3 +ldap_url_parse.3 +ldap_free_urldesc.3 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..aea3577 --- /dev/null +++ b/doc/man/man5/ldap.conf.5 @@ -0,0 +1,530 @@ +.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 directories that contain Certificate Authority +certificates in separate individual files. Multiple directories may +be specified, separated by a semi-colon. 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..c2170ed --- /dev/null +++ b/doc/man/man5/lloadd.conf.5 @@ -0,0 +1,1001 @@ +.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 +.TP +.B logfile-format debug | syslog-utc | syslog-localtime +Specify the prefix format for messages written to the logfile. The debug +format is the normal format used for slapd debug messages, with a timestamp +in hexadecimal, followed by a thread ID. The other options are to +use syslog(3) style prefixes, with timestamps either in UTC or in the +local timezone. The default is debug format. +.B loglevel +configuration parameter. Specifying a logfile copies messages to both stderr +and the logfile. +.TP +.B logfile-only on | off +Specify that debug messages should only go to the configured logfile, and +not to stderr. +.TP +.B logfile-rotate <max> <Mbytes> <hours> +Specify automatic rotation for the configured logfile as the maximum +number of old logfiles to retain, a maximum size in megabytes to allow a +logfile to grow before rotation, and a maximum age in hours for a logfile +to be used before rotation. The maximum number must be in the range 1-99. +Setting Mbytes or hours to zero disables the size or age check, respectively. +At least one of Mbytes or hours must be non-zero. By default no automatic +rotation will be performed. +.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. +.TP +.B write_coherence <integer> +Specify the number of seconds after a write operation is finished that +.B lloadd +will direct operations exclusively to the last selected backend. A write +operation is anything not handled internally (certain exops, abandon), +except search, compare and bind operations. Bind operations also reset this +restriction. The default is 0, write operations do not restrict selection. When +negative, the restriction is not time limited and will persist until the next +bind. +.TP +.B restrict_exop <OID> <action> +Tell +.B lloadd +that extended operation with a given OID should be handled in a specific way. +OID +.B 1.1 +is special, setting a default (only for operations not handled internally). +The meaning of the +.B <action> +argument is the same as in +.B restrict_control +below. +.TP +.B restrict_control <OID> <action> +Tell +.B lloadd +that a control with a given OID attached to any operation should be handled in +a specific way according to the +.B <action> +argument. At the moment, only operations passed intact are inspected in +this way, in particular, controls on bind and extended operations are +.B not +checked. + +In order of descending priority (the control with highest priority action +wins), this is the action made: +.RS +.RS +.PD 0 +.TP +.B reject +operations that carry this control will be rejected. +.TP +.B connection +once an upstream is selected, every future operation from this client will be +directed to the same connection. Useful when state is shared between client and +upstream that the load balancer doesn't track. +.TP +.B backend +like +.B write +except this does not time out. +.TP +.B write +this is treated like a write operation (see +.BR write_coherence ) +above. +.TP +.B ignore +does not influence restrictions, useful when changing the global exop default. +This is the default handling for exops/controls not handled by the load balancer +internally. +.PD +.RE + +.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. Backends are organised in groups +.RB ( tiers ). +Backends in the first tier are tried first, if none of them are reachable, the +following tier is tried in the same way. If there is a backend in the tier that +has suitable connections, but they are busy, no further tier is consulted. This +is useful in high availability scenarios where a group of servers (e.g. the +local environment) should be contacted if possible. + +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 [keepalive=<idle>:<probes>:<interval>] +.B [tcp\-user\-timeout=<milliseconds>] +.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>]] + +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 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 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 TIER OPTIONS + +.TP +.B tier +.B <tier type> + +Groups servers which should be considered in the same try. If a viable +connection is found even if busy, the load balancer does not proceed to the +next tier. The process of selection a connection within a tier depends on the +tier's type. + +.RE +Available types are: +.TP +.B roundrobin +Servers are tried in order and if one is selected successfully, the following +search will try from the one next on the list. +.TP +.B weighted +Backend servers accept a new option +.B weight=<int> +which indicates how often it should be selected. If unspecified, weight +defaults to 0 and such backends have a slight chance of being selected even +when a non-zero weight backend is configured in the tier. The selection process +is along the lines of +.BR RFC2782 . +.TP +.B bestof +Like with +.BI weighted , +backends accept the +.B weight=<int> +option. Average latency multiplied by +.B weight +is measured over time. The selection process chooses 2 backends at random, +compares their weighted latencies and the backend with a better (lower) score +is tried. If the backend is not available (or is busy), the other backend is +tried, then backends are chosen in a round-robin order. + +Note that unlike +.BI weighted , +the higher the weight, the higher the "effective" latency and lower the chance +a backend is selected. + +.SH BACKEND OPTIONS + +.TP +.B backend-server +.B uri=ldap[s]://<hostname>[:port] +.B [retry=<retry interval in ms>] +.B [starttls=yes|critical] +.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 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 + +# cancel not supported yet +restrict_exop 1.3.6.1.1.8 reject + +# turn not supported +restrict_exop 1.3.6.1.1.19 reject + +# TXN Exop if desired, otherwise reject +restrict_exop 1.3.6.1.1.21.1 connection + +# Paged results control +restrict_control 1.2.840.113556.1.4.319 connection + +# VLV control +restrict_control 2.16.840.1.113730.3.4.9 connection + +bindconf + bindmethod=simple + binddn=cn=test + credentials=pass + +tier weighted +backend-server + uri=ldap://ldap1.example.com + numconns=3 + bindconns=2 + retry=5000 + max-pending-ops=5 + conn-max-pending=3 + weight=5 + +backend-server + uri=ldap://ldap2.example.com + numconns=3 + bindconns=2 + retry=5000 + max-pending-ops=5 + conn-max-pending=3 + weight=10 +.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 certificate 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..84341d3 --- /dev/null +++ b/doc/man/man5/slapd-asyncmeta.5 @@ -0,0 +1,531 @@ +.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, a new connection is chosen using round\-robin scheduling. +.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..c1fa9c4 --- /dev/null +++ b/doc/man/man5/slapd-config.5 @@ -0,0 +1,2303 @@ +.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: { TRUE | FALSE } +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. These messages are +unrelated to messages exposed by the +.B olcLogLevel +configuration parameter. This setting only affects the slapd daemon and has +no effect on the command line tools. By default these messages +only go to stderr and are not recorded anywhere else. +Specifying a logfile copies messages to both stderr and the logfile. +.TP +.B olcLogFileFormat: debug | syslog-utc | syslog-localtime +Specify the prefix format for messages written to the logfile. The debug +format is the normal format used for slapd debug messages, with a timestamp +in hexadecimal, followed by a thread ID. The other options are to +use syslog(3) style prefixes, with timestamps either in UTC or in the +local timezone. The default is debug format. +.TP +.B olcLogFileOnly: TRUE | FALSE +Specify that debug messages should only go to the configured logfile, and +not to stderr. +.TP +.B olcLogFileRotate: <max> <Mbytes> <hours> +Specify automatic rotation for the configured logfile as the maximum +number of old logfiles to retain, a maximum size in megabytes to allow a +logfile to grow before rotation, and a maximum age in hours for a logfile +to be used before rotation. The maximum number must be in the range 1-99. +Setting Mbytes or hours to zero disables the size or age check, respectively. +At least one of Mbytes or hours must be non-zero. By default no automatic +rotation will be performed. +.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 directories that contain 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. Multiple directories may be specified, +separated by a semi-colon. +.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 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 olcLastBindPrecision: <integer> +If olcLastBind is enabled, specifies how frequently pwdLastSuccess +will be updated. More than +.B integer +seconds must have passed since the last successful bind. In a +replicated environment with frequent bind activity it may be +useful to set this to a large value. +.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..4d7251a --- /dev/null +++ b/doc/man/man5/slapd-ldap.5 @@ -0,0 +1,713 @@ +.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 after a given ttl, +regardless of being idle or not. If a client connection outlives the remote +connection, the client will receive +.IR LDAP_UNAVAILABLE +when it executes the next operation. + + +.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. +.RE + +.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 after it has been idle +for the specified time. If a client connection outlives the remote connection, +the client will receive +.IR LDAP_UNAVAILABLE +when it executes the next operation. + +.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 . +Note, however, that connection is not re-established automatically after it +was dropped due to +.B idle\-timeout +or +.B conn\-ttl . + +.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-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..eb7034a --- /dev/null +++ b/doc/man/man5/slapd-sock.5 @@ -0,0 +1,344 @@ +.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 that 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 high 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 uses 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 +.B sockresps +includes +.BR result +or +.BR search , +the overlay will also send any response messages to the external program (also +see KNOWN LIMITATIONS). These will appear as an extended RESULT message or an +ENTRY message respectively, both are defined below and the program is not +expected to respond to these. + +The extended 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. + +If +.B sockresps +is configured, +.B sock +overlay does not consider +.B sockops +nor +.B sockdnpat +to decide which responses are passed onto the external program, instead, all +responses are currently passed on. + +.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..336353c --- /dev/null +++ b/doc/man/man5/slapd.access.5 @@ -0,0 +1,1212 @@ +.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. + +.LP +The SASL +.B authzID +mapping and the LDAP +.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 both cases, it is the authorizing identity that requires the privileges +(i.e. the identity that has authenticated and is now trying to do +some operation using another entity's permissions). + +.LP +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 slapd\-mdb (5). + +Some other backend, like +.BR slapd\-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..c5640e0 --- /dev/null +++ b/doc/man/man5/slapd.backends.5 @@ -0,0 +1,133 @@ +.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 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\-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..36622d5 --- /dev/null +++ b/doc/man/man5/slapd.conf.5 @@ -0,0 +1,2168 @@ +.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. These messages are +unrelated to messages exposed by the +.B loglevel +configuration parameter. This setting only affects the slapd daemon and has +no effect on the command line tools. By default these messages +only go to stderr and are not recorded anywhere else. +Specifying a logfile copies messages to both stderr and the logfile. +.TP +.B logfile-format debug | syslog-utc | syslog-localtime +Specify the prefix format for messages written to the logfile. The debug +format is the normal format used for slapd debug messages, with a timestamp +in hexadecimal, followed by a thread ID. The other options are to +use syslog(3) style prefixes, with timestamps either in UTC or in the +local timezone. The default is debug format. +.TP +.B logfile-only on | off +Specify that debug messages should only go to the configured logfile, and +not to stderr. +.TP +.B logfile-rotate <max> <Mbytes> <hours> +Specify automatic rotation for the configured logfile as the maximum +number of old logfiles to retain, a maximum size in megabytes to allow a +logfile to grow before rotation, and a maximum age in hours for a logfile +to be used before rotation. The maximum number must be in the range 1-99. +Setting Mbytes or hours to zero disables the size or age check, respectively. +At least one of Mbytes or hours must be non-zero. By default no automatic +rotation will be performed. +.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 directories that contain 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. Multiple directories may be specified, +separated by a semi-colon. +.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 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 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 lastbind-precision <integer> +If lastbind is enabled, specifies how frequently pwdLastSuccess +will be updated. More than +.B integer +seconds must have passed since the last successful bind. In a +replicated environment with frequent bind activity it may be +useful to set this to a large value. +.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..7fe0f70 --- /dev/null +++ b/doc/man/man5/slapo-dynlist.5 @@ -0,0 +1,320 @@ +.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 lists and groups. +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. + +For a dynamic list, the values +of the attributes listed in the URI are added from the matching entries 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. + +For a dynamic group, the DNs of the matching entries are added to a member attribute +in the original entry. + +All dynamic behavior is disabled when the \fImanageDSAit\fP +control (RFC 3296) is used. +In that case, the contents of the original 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> [options] + +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 remaining options depend on whether a dynamic list or a dynamic group +is being configured. + +For a dynamic list, the allowed options have the form + +.B [<mapped-ad>:<list-ad> ...] + +The +.B mapped-ad +can be used to remap attributes obtained through expansion. +The +.B list-ad +must be one of the attributes returned in the expansion of the URIs in the +.B URL-ad +attribute of the dynamic entry. Multiple mapping statements can be used. +Note that in order for dynamic lists +to be usable in a search filter, the dynamic attributes to be filtered +must be explicitly mapped. They can be mapped to themselves +if no transformation is required. + +For a dynamic group, the allowed options are + +.B <member-ad>[+<memberOf-ad>[@<static-oc>[*]]] + +The +.B member-ad +is required; 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. + +.TP +.B dynlist\-simple TRUE | FALSE +This option downgrades to the behavior of the OpenLDAP 2.4 dynlist overlay. +It disables memberOf processing, nested group support, and filter evaluation +of dynamically generated values. +The default is FALSE. + +.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. + +The values of the above list can not be evaluated in a search filter. To enable +filter evaluation on the dynamic list, the configuration must be changed to +explicitly map the dynamic attributes to be filtered. In this case +.B mail +is just mapped to itself. + +.LP +.nf + include /path/to/dyngroup.schema + # ... + + database <database> + # ... + + overlay dynlist + dynlist\-attrset groupOfURLs memberURL mail:mail +.fi + +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..cb1ac5b --- /dev/null +++ b/doc/man/man5/slapo-homedir.5 @@ -0,0 +1,157 @@ +.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 olcHomedirArchivePath: 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 EXAMPLE +The following LDIF could be used to add this overlay to +.B cn=config +(adjust to suit) +.LP +.RS +.nf +dn: cn=module{0},cn=config +changetype: modify +add: olcModuleLoad +olcModuleLoad: homedir + +dn: olcOverlay=homedir,olcDatabase={1}mdb,cn=config +changetype: add +objectClass: olcOverlayConfig +objectClass: olcHomedirConfig +olcOverlay: homedir +olcSkeletonPath: /etc/skel +olcMinimumUidNumber: 1000 +olcHomedirRegexp: ^(/home/[-_/a-z0-9]+)$ /export/$1 +olcHomedirDeleteStyle: ARCHIVE +olcHomedirArchivePath: /archive +.fi +.RE +.LP + +.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..3dd0141 --- /dev/null +++ b/doc/man/man5/slapo-pcache.5 @@ -0,0 +1,330 @@ +.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. +The "undef" keyword cannot be used with the +.BR slapd\-mdb(5) +backend as it requires all schema elements be fully defined. + +.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 +maxsize 1073741824 +.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..7a639f0 --- /dev/null +++ b/doc/man/man5/slapo-ppolicy.5 @@ -0,0 +1,1093 @@ +.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. +.TP +.B ppolicy_check_module <path> +Specify the path of a loadable module containing a +.B check_password() +function for additional password quality checks. The use of this module +is described further below in the description of the +.B pwdPolicyChecker +objectclass. + +Note: The user-defined loadable module must be in +.B slapd's +standard executable search PATH, or an absolute path must be provided. + +Note: Use of a +.B ppolicy_check_module +is a non-standard extension to the LDAP password +policy proposal. + + +.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 $ pwdUseCheckModule ) ) +.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 +.B ppolicy_check_module +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 +.B ppolicy_check_module +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 pwdUseCheckModule / pwdCheckModuleArg +.P +The +.B pwdUseCheckModule +attribute enables use of a loadable module previously configured with +.B ppolicy_check_module +for the current policy. The module 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, struct berval *pErrmsg, Entry *pEntry, struct berval *pArg); +.RE +The +.B pPasswd +parameter contains the clear-text user password, the +.B pErrmsg +parameter points to a +.B struct berval +containing space +to return human-readable details about any error it encounters. +The +.B bv_len +field must contain the size of the space provided +by the +.B bv_val +field. + +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 pErrmsg +is NULL, then +.I funcName +must NOT attempt to use it. +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 pErrmsg +may be used to return a human-readable textual explanation of the +error. If the space passed in by the caller is too small, the function +may replace it with a dynamically allocated buffer, which will +be free()'d by slapd. + +The +.B pwdCheckModule +attribute is now obsolete and is ignored. + +.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 + OBSOLETE + 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 ) + +( 1.3.6.1.4.1.4754.1.99.3 + NAME 'pwdUseCheckModule' + EQUALITY booleanMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 + SINGLE\-VALUE ) +.RE + +.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..39d2471 --- /dev/null +++ b/doc/man/man5/slapo-rwm.5 @@ -0,0 +1,708 @@ +.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 \fIRFC4511\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. + +.TP +.B escape [escape2dn|escape2filter|unescapedn|unescapefilter]... +The +.B escape +map makes it possible use DNs or their parts in filter strings and vice versa. +It processes a value according to the operations listed in order. Supported +operations include: + +.RS +.TP +.B escape2dn +takes a string and escapes it so it can safely be pasted in a DN +.TP +.B escape2filter +takes a string and escapes it so it can safely be pasted in a filter +.TP +.B unescapedn +takes a string and undoes DN escaping +.TP +.B unescapefilter +takes a string and undoes filter escaping +.RE + +.RS +It is advised that each +.B escape +map ends with an +.B escape +operation as that is the only safe way to handle arbitrary strings. +.RE + +.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" ":" + +# Transform a DN value such that it can be used in a filter +rwm\-rewriteMap escape dn2filter unescapedn escape2filter + +# 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. +# +# While actual email addresses tend not to contain filter +# special characters, the provided Bind DN has no such +# restrictions. +rwm\-rewriteContext bindDN +rwm\-rewriteRule "^(mail=)([^,]+@[^,]+)$" + "${attr2dn($1${dn2filter($2)})}" ":@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..3ceef5e --- /dev/null +++ b/doc/man/man5/slapo-unique.5 @@ -0,0 +1,188 @@ +.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 when using +deprecated slapd.conf configurations. + +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. diff --git a/doc/man/man8/Makefile.in b/doc/man/man8/Makefile.in new file mode 100644 index 0000000..30f21e0 --- /dev/null +++ b/doc/man/man8/Makefile.in @@ -0,0 +1,16 @@ +# man8 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=8 diff --git a/doc/man/man8/lloadd.8 b/doc/man/man8/lloadd.8 new file mode 100644 index 0000000..3bd4f0e --- /dev/null +++ b/doc/man/man8/lloadd.8 @@ -0,0 +1,341 @@ +.TH LLOADD 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2017-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +lloadd \- LDAP Load Balancer Daemon +.SH SYNOPSIS +.B LIBEXECDIR/lloadd +[\c +.BR \-4 | \-6 ] +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ lloadd-config-file\fR] +[\c +.BI \-h \ URLs\fR] +[\c +.BI \-n \ service-name\fR] +[\c +.BI \-s \ syslog-level\fR] +[\c +.BI \-l \ syslog-local-user\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BI \-r \ directory\fR] +[\c +.BI \-u \ user\fR] +[\c +.BI \-g \ group\fR] +.SH DESCRIPTION +.LP +.B Lloadd +is the stand-alone LDAP daemon. It listens for LDAP connections on +any number of ports (default \fB389\fP), forwarding the LDAP operations +it receives over these connections to be handled by the configured +backends. +.B lloadd +is typically invoked at boot time, usually out of +.BR /etc/rc.local . +Upon startup, +.B lloadd +normally forks and disassociates itself from the invoking tty. +If configured in the config file, the +.B lloadd +process will print its process ID (see +.BR getpid (2)) +to a +.B .pid +file, as well as the command line options during invocation to an +.B .args +file (see +.BR lloadd.conf (5)). +If the +.B \-d +flag is given, even with a zero argument, +.B lloadd +will not fork and disassociate from the invoking tty. +.LP +See the "OpenLDAP Administrator's Guide" for more details on +.BR lloadd . +.SH OPTIONS +.TP +.B \-4 +Listen on IPv4 addresses only. +.TP +.B \-6 +Listen on IPv6 addresses only. +.TP +.BI \-d \ debug-level +Turn on debugging as defined by +.IR debug-level . +If this option is specified, even with a zero argument, +.B lloadd +will not fork or disassociate from the invoking terminal. Some general +operation and status messages are printed for any value of \fIdebug-level\fP. +\fIdebug-level\fP is taken as a bit string, with each bit corresponding to a +different kind of debugging information. See <ldap_log.h> for details. +Comma-separated arrays of friendly names can be specified to select +debugging output of the corresponding debugging information. +All the names recognized by the \fIloglevel\fP directive +described in \fBlloadd.conf\fP(5) are supported. +If \fIdebug-level\fP is \fB?\fP, a list of installed debug-levels is printed, +and lloadd exits. + +Remember that if you turn on packet logging, packets containing bind passwords +will be output, so if you redirect the log to a logfile, that file should +be read-protected. +.TP +.BI \-s \ syslog-level +This option tells +.B lloadd +at what debug-level debugging statements should be logged to the +.BR syslog (8) +facility. +The value \fIsyslog-level\fP can be set to any value or combination +allowed by the \fB\-d\fP switch. +Lloadd logs all messages selected by \fIsyslog-level\fP +at the +.BR syslog (3) +severity debug-level \fBDEBUG\fP, +on the unit specified with \fB\-l\fP. +.TP +.BI \-n \ service-name +Specifies the service name for logging and other purposes. Defaults +to basename of argv[0], i.e.: "lloadd". +.TP +.BI \-l \ syslog-local-user +Selects the local user of the +.BR syslog (8) +facility. Value can be +.BR LOCAL0 , +through +.BR LOCAL7 , +as well as +.B USER +and +.BR DAEMON . +The default is +.BR LOCAL4 . +However, this option is only permitted on systems that support +local users with the +.BR syslog (8) +facility. +Logging to syslog(8) occurs at the "DEBUG" severity debug-level. +.TP +.BI \-f \ lloadd-config-file +Specifies the lloadd configuration file. The default is +.BR ETCDIR/lloadd.conf . +.TP +.BI \-h \ URLlist +.B lloadd +will by default serve +.B ldap:/// +(LDAP over TCP on all interfaces on default LDAP port). That is, +it will bind using INADDR_ANY and port \fB389\fP. +The +.B \-h +option may be used to specify LDAP (and other scheme) URLs to serve. +For example, if lloadd is given +.BR "\-h \(dqldap://127.0.0.1:9009/ ldaps:/// ldapi:///\(dq" , +it will listen on 127.0.0.1:9009 for LDAP, 0.0.0.0:636 for LDAP over TLS, +and LDAP over IPC (Unix domain sockets). Host 0.0.0.0 represents +INADDR_ANY (any interface). +A space separated list of URLs is expected. The URLs should be of the LDAP, +PLDAP, LDAPS, PLDAPS, or LDAPI schemes, and generally without a DN or other +optional parameters (excepting as discussed below). Support for the latter +three schemes depends on selected configuration options. Hosts may be specified +by name or IPv4 and IPv6 address formats. Ports, if specified, must be +numeric. The default ldap:// port is \fB389\fP and the default ldaps:// port +is \fB636\fP, same for the proxy enabled variants. + +The PLDAP and PLDAPS URL schemes provide support for the HAProxy proxy protocol +version 2, which allows a load balancer or proxy server to provide the remote +client IP address to slapd to be used for access control or logging. Ports +configured for PLDAP or PLDAPS will only accept connections that include the +necessary proxy protocol header. Connections to these ports should be +restricted at the network level to only trusted load balancers or proxies to +avoid spoofing of client IP addresses by third parties. + +At the moment, the load balancer does not act on the recorded address in any +way. + +For LDAP over IPC, +.B name +is the name of the socket, and no +.B port +is required, nor allowed; note that directory separators must be +URL-encoded, like any other characters that are special to URLs; +so the socket + + /usr/local/var/ldapi + +must be specified as + + ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi + +The default location for the IPC socket is LOCALSTATEDIR/run/ldapi +.TP +.BI \-r \ directory +Specifies a directory to become the root directory. lloadd will +change the current working directory to this directory and +then +.BR chroot (2) +to this directory. This is done after opening listeners but before +reading any configuration file or initializing any backend. When +used as a security mechanism, it should be used in conjunction with +.B \-u +and +.B \-g +options. +.TP +.BI \-u \ user +.B lloadd +will run lloadd with the specified user name or id, and that user's +supplementary group access list as set with initgroups(3). The group ID +is also changed to this user's gid, unless the \fB\-g\fP option is used to +override. Note when used with +.BR \-r , +lloadd will use the user database in the change root environment. +.TP +.BI \-g \ group +.B lloadd +will run with the specified group name or id. Note when used with +.BR \-r , +lloadd will use the group database in the change root environment. +.TP +.BI \-o \ option\fR[ = value\fR] +This option provides a generic means to specify options without the need to reserve +a separate letter for them. + +It supports the following options: +.RS +.TP +.BR slp= { on \||\| off \||\| \fIslp-attrs\fP } +When SLP support is compiled into lloadd, disable it (\fBoff\fP), + enable it by registering at SLP DAs without specific SLP attributes (\fBon\fP), +or with specific SLP attributes +.I slp-attrs +that must be an SLP attribute list definition according to the SLP standard. + +For example, \fB"slp=(tree=production),(server-type=OpenLDAP),(server\-version=2.4.15)"\fP +registers at SLP DAs with the three SLP attributes tree, server-type and server-version +that have the values given above. +This allows one to specifically query the SLP DAs for LDAP servers holding the +.I production +tree in case multiple trees are available. +.RE + +.SH RELATION TO SLAPD(8) +.B Lloadd +can be compiled as a +.B slapd +loadable module. In that case, it can be loaded as such: +.LP +.nf +.ft tt + moduleload path/to/lloadd.la + backend lload + listen "listening URLs" +.ft +.fi + +This enables +.B lloadd +to provide additional features through the host slapd process like access to +run-time statistics in +.B cn=monitor +and dynamic configuration from +.BR cn=config . + +The listening sockets specified will be under direct control of +.B lloadd +and need to be different from the sockets slapd is configured to listen on. +Clients connecting to these are completely separate from regular LDAP clients +connecting to the usual +.B slapd +sockets - +.B lloadd +clients have no access to slapd databases, similarly, +.B slapd +client traffic does not propagate to the +.B lloadd +backend servers in any way. + +.SH CN=MONITOR INTERFACE +As part of +.BR lloadd 's +.B cn=monitor +interface it is possible to close a client connection it manages by writing to +the corresponding entry, +.B replacing +the +.B olmConnectionState +attribute with the value +.BR closing . +This is subject to ACLs configured on the monitor database. The server will +send a +.B Notice of Disconnection +to the client, refuse any new operations and once all pending operations have +finished, close the connection. + +For example, to close connection number 42: + +.LP +.nf +.ft tt + dn: cn=connection 42,cn=incoming connections,cn=load balancer,cn=backends,cn=monitor + changetype: modify + replace: olmConnectionState + olmConnectionState: closing +.ft +.fi + +.SH EXAMPLES +To start +.I lloadd +and have it fork and detach from the terminal and start load-balancing +the LDAP servers defined in the default config file, just type: +.LP +.nf +.ft tt + LIBEXECDIR/lloadd +.ft +.fi +.LP +To start +.B lloadd +with an alternate configuration file, and turn +on voluminous debugging which will be printed on standard error, type: +.LP +.nf +.ft tt + LIBEXECDIR/lloadd \-f /var/tmp/lloadd.conf \-d 255 +.ft +.fi +.LP +To start +.B lloadd +as a module inside a slapd process listening on ldap://:1389 and ldaps://, +put the following in your slapd.conf (or its equivalent in cn=config): +.LP +.nf +.ft tt + moduleload lloadd.la + backend lload + listen "ldap://:1389 ldaps://" +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR lloadd.conf (5), +.BR slapd-config (5), +.BR slapd-monitor (5), +.BR slapd (8). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH BUGS +See http://www.openldap.org/its/ +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapacl.8 b/doc/man/man8/slapacl.8 new file mode 100644 index 0000000..c283f11 --- /dev/null +++ b/doc/man/man8/slapacl.8 @@ -0,0 +1,205 @@ +.TH SLAPACL 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapacl \- Check access to a list of attributes. +.SH SYNOPSIS +.B SBINDIR/slapacl +.BI \-b \ DN +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-D \ authcDN\ \fR| +.BI \-U \ authcID\fR] +[\c +.BI \-f \ slapd.conf\fR] +[\c +.BI \-F \ confdir\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BR \-u ] +[\c +.BR \-v ] +[\c +.BI \-X \ authzID\ \fR| +.BI "\-o \ authzDN=" DN\fR] +[\c +.IR attr [\fB/\fI access ][\fB:\fI value ]]\fR\ [...] +.LP +.SH DESCRIPTION +.LP +.B slapacl +is used to check the behavior of +.BR slapd (8) +by verifying access to directory data according to the access control list +directives defined in its configuration. +. +It opens the +.BR slapd.conf (5) +configuration file or the +.BR slapd\-config (5) +backend, reads in the +.BR access / olcAccess +directives, and then parses the +.B attr +list given on the command-line; if none is given, access to the +.B entry +pseudo-attribute is tested. +.LP +.SH OPTIONS +.TP +.BI \-b \ DN +specify the +.I DN +which access is requested to; the corresponding entry is fetched +from the database, and thus it must exist. +The +.I DN +is also used to determine what rules apply; thus, it must be +in the naming context of a configured database. By default, the first +database that supports the requested operation is used. See also +.BR \-u . + +.TP +.BI \-d \ debug-level +enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-D \ authcDN +specify a DN to be used as identity through the test session +when selecting appropriate +.B <by> +clauses in access lists. +.TP +.BI \-f \ slapd.conf +specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, an attempt to read the +default config directory will be made before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + +.fi +.RS +Possible options/values specific to +.B slapacl +are: +.RE +.nf + + authzDN + domain + peername + sasl_ssf + sockname + sockurl + ssf + tls_ssf + transport_ssf + +.fi +.RS +See the related fields in +.BR slapd.access (5) +for details. +.RE +.TP +.BI \-u +do not fetch the entry from the database. +In this case, if the entry does not exist, a fake entry with the +.I DN +given with the +.B \-b +option is used, with no attributes. +As a consequence, those rules that depend on the contents +of the target object will not behave as with the real object. +The +.I DN +given with the +.B \-b +option is still used to select what rules apply; thus, it must be +in the naming context of a configured database. +See also +.BR \-b . +.TP +.BI \-U \ authcID +specify an ID to be mapped to a +.B DN +as by means of +.B authz\-regexp +or +.B authz\-rewrite +rules (see +.BR slapd.conf (5) +for details); mutually exclusive with +.BR \-D . +.TP +.B \-v +enable verbose mode. +.TP +.BI \-X \ authzID +specify an authorization ID to be mapped to a +.B DN +as by means of +.B authz\-regexp +or +.B authz\-rewrite +rules (see +.BR slapd.conf (5) +for details); mutually exclusive with \fB\-o\fP \fBauthzDN=\fIDN\fR. +.SH EXAMPLES +The command +.LP +.nf +.ft tt + SBINDIR/slapacl \-f ETCDIR/slapd.conf \-v \\ + \-U bjorn \-b "o=University of Michigan,c=US" \\ + "o/read:University of Michigan" + +.ft +.fi +tests whether the user +.I bjorn +can access the attribute +.I o +of the entry +.I o=University of Michigan,c=US +at +.I read +level. +.SH "SEE ALSO" +.BR ldap (3), +.BR slapd (8), +.BR slaptest (8), +.BR slapauth (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapadd.8 b/doc/man/man8/slapadd.8 new file mode 100644 index 0000000..d31d440 --- /dev/null +++ b/doc/man/man8/slapadd.8 @@ -0,0 +1,218 @@ +.TH SLAPADD 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapadd \- Add entries to a SLAPD database +.SH SYNOPSIS +.B SBINDIR/slapadd +[\c +.BI \-b \ suffix\fR] +[\c +.BR \-c ] +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ slapd.conf\fR] +[\c +.BI \-F \ confdir\fR] +[\c +.BR \-g ] +[\c +.BI \-j \ lineno\fR] +[\c +.BI \-l \ ldif-file\fR] +[\c +.BI \-n \ dbnum\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BR \-q ] +[\c +.BR \-s ] +[\c +.BI \-S \ SID\fR] +[\c +.BR \-u ] +[\c +.BR \-v ] +[\c +.BR \-w ] +.SH DESCRIPTION +.LP +.B Slapadd +is used to add entries specified in LDAP Directory Interchange Format +(LDIF) to a +.BR slapd (8) +database. +It opens the given database determined by the database number or +suffix and adds entries corresponding to the provided LDIF to +the database. +Databases configured as +.B subordinate +of this one are also updated, unless \fB\-g\fP is specified. +The LDIF input is read from standard input or the specified file. + +All files eventually created by +.BR slapadd +will belong to the identity +.BR slapadd +is run as, so make sure you either run +.BR slapadd +with the same identity +.BR slapd (8) +will be run as (see option +.B \-u +in +.BR slapd (8)), +or change file ownership before running +.BR slapd (8). + +Note: slapadd will also perform the relevant indexing whilst adding the database if +any are configured. For specific details, please see +.BR slapindex (8). +.SH OPTIONS +.TP +.BI \-b \ suffix +Use the specified \fIsuffix\fR to determine which database to +add entries to. By default, the first database that supports the requested +operation is used. The \fB\-b\fP cannot be used in conjunction with the +.B \-n +option. +.TP +.B \-c +enable continue (ignore errors) mode. +.TP +.BI \-d \ debug-level +enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-f \ slapd.conf +specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, an attempt to read the +default config directory will be made before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. If dry-run mode is also specified, +no conversion will occur. +.TP +.B \-g +disable subordinate gluing. Only the specified database will be +processed, and not its glued subordinates (if any). +.TP +.BI \-j \ lineno +Jump to the specified line number in the LDIF file before processing +any entries. This allows a load that was aborted due to errors in the +input LDIF to be resumed after the errors are corrected. +.TP +.BI \-l \ ldif-file +Read LDIF from the specified file instead of standard input. +.TP +.BI \-n \ dbnum +Add entries to the \fIdbnum\fR-th database listed in the +configuration file. The +.B \-n +cannot be used in conjunction with the +.B \-b +option. +To populate the config database +.BR slapd\-config (5), +use +.B \-n 0 +as it is always the first database. It must physically exist +on the filesystem prior to this, however. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + + schema-check={yes|no} + value-check={yes|no} + +.in +The \fIschema\-check\fR option toggles schema checking (default on); +the \fIvalue\-check\fR option toggles value checking (default off). +The latter is incompatible with \fB-q\fR. +.TP +.B \-q +enable quick (fewer integrity checks) mode. Does fewer consistency checks +on the input data, and no consistency checks when writing the database. +Improves the load time but if any errors or interruptions occur the resulting +database will be unusable. +.TP +.B \-s +disable schema checking. This option is intended to be used when loading +databases containing special objects, such as fractional objects on a +partial consumer. Loading normal objects which do not conform to +schema may result in unexpected and ill behavior. +.TP +.BI \-S \ SID +Server ID to use in generated entryCSN. Also used for contextCSN +if \fB\-w\fP is set as well. Defaults to \fB0\fP. +.TP +.B \-u +enable dry-run (don't write to backend) mode. +.TP +.B \-v +enable verbose mode. +.TP +.BI \-w +write syncrepl context information. +After all entries are added, the contextCSN +will be updated with the greatest CSN in the database. +.SH LIMITATIONS +Your +.BR slapd (8) +should not be running +when you do this to ensure consistency of the database. +.LP +.B slapadd +may not provide naming or schema checks. It is advisable to +use +.BR ldapadd (1) +when adding new entries into an existing directory. +.SH EXAMPLES +To import the entries specified in file +.B ldif +into your +.BR slapd (8) +database give the command: +.LP +.nf +.ft tt + SBINDIR/slapadd \-l ldif +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR ldif (5), +.BR slapcat (8), +.BR slapindex (8), +.BR slapmodify (8), +.BR ldapadd (1), +.BR slapd (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapauth.8 b/doc/man/man8/slapauth.8 new file mode 100644 index 0000000..17e529e --- /dev/null +++ b/doc/man/man8/slapauth.8 @@ -0,0 +1,152 @@ +.TH SLAPAUTH 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapauth \- Check a list of string-represented IDs for LDAP authc/authz +.SH SYNOPSIS +.B SBINDIR/slapauth +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ slapd.conf\fR] +[\c +.BI \-F \ confdir\fR] +[\c +.BI \-M \ mech\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BI \-R \ realm\fR] +[\c +.BI \-U \ authcID\fR] +[\c +.BR \-v ] +[\c +.BI \-X \ authzID\fR] +.IR ID \ [ ... ] +.LP +.SH DESCRIPTION +.LP +.B Slapauth +is used to check the behavior of the slapd in mapping identities +for authentication and authorization purposes, as specified in +.BR slapd.conf (5). +It opens the +.BR slapd.conf (5) +configuration file or the +.BR slapd\-config (5) +backend, reads in the +.BR authz\-policy / olcAuthzPolicy +and +.BR authz\-regexp / olcAuthzRegexp +directives, and then parses the +.I ID +list given on the command-line. +.LP +.SH OPTIONS +.TP +.BI \-d \ debug-level +enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-f \ slapd.conf +specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, an attempt to read the +default config directory will be made before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. +.TP +.BI \-M \ mech +specify a mechanism. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + +.fi +.TP +.BI \-R \ realm +specify a realm. +.TP +.BI \-U \ authcID +specify an ID to be used as +.I authcID +throughout the test session. +If present, and if no +.I authzID +is given, the IDs in the ID list are treated as +.IR authzID . +.TP +.BI \-X \ authzID +specify an ID to be used as +.I authzID +throughout the test session. +If present, and if no +.I authcID +is given, the IDs in the ID list are treated as +.IR authcID . +If both +.I authcID +and +.I authzID +are given via command line switch, the ID list cannot be present. +.TP +.B \-v +enable verbose mode. +.SH EXAMPLES +The command +.LP +.nf +.ft tt + SBINDIR/slapauth \-f /ETCDIR/slapd.conf \-v \\ + \-U bjorn \-X u:bjensen + +.ft +.fi +tests whether the user +.I bjorn +can assume the identity of the user +.I bjensen +provided the directives +.LP +.nf +.ft tt + authz\-policy from + authz\-regexp "^uid=([^,]+).*,cn=auth$" + "ldap:///dc=example,dc=net??sub?uid=$1" + +.ft +.fi +are defined in +.BR slapd.conf (5). +.SH "SEE ALSO" +.BR ldap (3), +.BR slapd (8), +.BR slaptest (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapcat.8 b/doc/man/man8/slapcat.8 new file mode 100644 index 0000000..c836a04 --- /dev/null +++ b/doc/man/man8/slapcat.8 @@ -0,0 +1,203 @@ +.TH SLAPCAT 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapcat \- SLAPD database to LDIF utility +.SH SYNOPSIS +.B SBINDIR/slapcat +[\c +.BI \-a filter\fR] +[\c +.BI \-b suffix\fR] +[\c +.BR \-c ] +[\c +.BI \-d debug-level\fR] +[\c +.BI \-f slapd.conf\fR] +[\c +.BI \-F confdir\fR] +[\c +.BR \-g ] +[\c +.BI \-H URI\fR] +[\c +.BI \-l ldif-file\fR] +[\c +.BI \-n dbnum\fR] +[\c +.BI \-o option\fR[ = value\fR]] +[\c +.BI \-s subtree-dn\fR] +[\c +.BR \-v ] +.LP +.SH DESCRIPTION +.LP +.B Slapcat +is used to generate an LDAP Directory Interchange Format +(LDIF) output based upon the contents of a +.BR slapd (8) +database. +It opens the given database determined by the database number or +suffix and writes the corresponding LDIF to standard output or +the specified file. +Databases configured as +.B subordinate +of this one are also output, unless \fB\-g\fP is specified. +.LP +The entry records are presented in database order, not superior first +order. The entry records will include all (user and operational) +attributes stored in the database. The entry records will not include +dynamically generated attributes (such as subschemaSubentry). +.LP +The output of slapcat is intended to be used as input to +.BR slapadd (8). +The output of slapcat cannot generally be used as input to +.BR ldapadd (1) +or other LDAP clients without first editing the output. +This editing would normally include reordering the records +into superior first order and removing no-user-modification +operational attributes. +.SH OPTIONS +.TP +.BI \-a \ filter +Only dump entries matching the asserted filter. +For example + +slapcat \-a \\ + "(!(entryDN:dnSubtreeMatch:=ou=People,dc=example,dc=com))" + +will dump all but the "ou=People,dc=example,dc=com" subtree +of the "dc=example,dc=com" database. +Deprecated; use \fB-H\fP \fIldap:///???(filter)\fP instead. +.TP +.BI \-b \ suffix +Use the specified \fIsuffix\fR to determine which database to +generate output for. By default, the first database that supports the requested +operation is used. The \fB\-b\fP cannot be used in conjunction with the +.B \-n +option. +.TP +.B \-c +Enable continue (ignore errors) mode. +Multiple occurrences of +.B \-c +make +.BR slapcat (8) +try harder. +.TP +.BI \-d \ debug-level +Enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-f \ slapd.conf +Specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, an attempt to read the +default config directory will be made before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. +.TP +.B \-g +disable subordinate gluing. Only the specified database will be +processed, and not its glued subordinates (if any). +.TP +.B \-H \ URI +use dn, scope and filter from URI to only handle matching entries. +.TP +.BI \-l \ ldif-file +Write LDIF to specified file instead of standard output. +.TP +.BI \-n \ dbnum +Generate output for the \fIdbnum\fR-th database listed in the +configuration file. The config database +.BR slapd\-config (5), +is always the first database, so use +.B \-n 0 +to select it. + +The +.B \-n +cannot be used in conjunction with the +.B \-b +option. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + + ldif_wrap={no|<n>} + +.in +\fIn\fP is the number of columns allowed for the LDIF output +(\fIn\fP equal to \fI0\fP uses the default, corresponding to 78). +The minimum is 2, leaving space for one character and one +continuation character. +Use \fIno\fP for no wrap. +.TP +.BI \-s \ subtree-dn +Only dump entries in the subtree specified by this DN. +Implies \fB\-b\fP \fIsubtree-dn\fP if no +.B \-b +or +.B \-n +option is given. +Deprecated; use \fB-H\fP \fIldap:///subtree-dn\fP instead. +.TP +.B \-v +Enable verbose mode. +.SH LIMITATIONS +For some backend types, your +.BR slapd (8) +should not be running (at least, not in read-write +mode) when you do this to ensure consistency of the database. It is +always safe to run +.B slapcat +with the +.BR slapd\-mdb (5), +and +.BR slapd\-null (5) +backends. +.SH EXAMPLES +To make a text backup of your SLAPD database and put it in a file called +.BR ldif , +give the command: +.LP +.nf +.ft tt + SBINDIR/slapcat \-l ldif +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR ldif (5), +.BR slapadd (8), +.BR ldapadd (1), +.BR slapd (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapd.8 b/doc/man/man8/slapd.8 new file mode 100644 index 0000000..809f9e7 --- /dev/null +++ b/doc/man/man8/slapd.8 @@ -0,0 +1,379 @@ +.TH SLAPD 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd \- Stand-alone LDAP Daemon +.SH SYNOPSIS +.B LIBEXECDIR/slapd +[\c +.BR \-V [ V [ V ]] +[\c +.BR \-4 | \-6 ] +[\c +.BR \-T \ { acl \||\| a [ dd ]\||\| auth \||\| c [ at ]\||\| +.BR d [ n ]\||\| i [ ndex ]\||\| m [ odify ]\||\| p [ asswd ]\||\| s [ chema ]\||\| t [ est ]}] +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ slapd-config-file\fR] +[\c +.BI \-F \ slapd-config-directory\fR] +[\c +.BI \-h \ URLs\fR] +[\c +.BI \-n \ service-name\fR] +[\c +.BI \-s \ syslog-level\fR] +[\c +.BI \-l \ syslog-local-user\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BI \-r \ directory\fR] +[\c +.BI \-u \ user\fR] +[\c +.BI \-g \ group\fR] +[\c +.BI \-c \ cookie\fR] +.SH DESCRIPTION +.LP +.B Slapd +is the stand-alone LDAP daemon. It listens for LDAP connections on +any number of ports (default \fB389\fP), responding +to the LDAP operations it receives over these connections. +.B slapd +is typically invoked at boot time, usually out of +.BR /etc/rc.local . +Upon startup, +.B slapd +normally forks and disassociates itself from the invoking tty. +If configured in the config file (or config directory), +the +.B slapd +process will print its process ID (see +.BR getpid (2)) +to a +.B .pid +file, as well as the command line options during invocation to an +.B .args +file (see +.BR slapd.conf (5)). +If the +.B \-d +flag is given, even with a zero argument, +.B slapd +will not fork and disassociate from the invoking tty. +.LP +See the "OpenLDAP Administrator's Guide" for more details on +.BR slapd . +.SH OPTIONS +.TP +.BR \-V [ V [ V ]] +Print version info and proceed with startup. +If \fB\-VV\fP is given, exit after providing version info. If \fB\-VVV\fP is +given, additionally provide information on static overlays and backends. +.TP +.B \-4 +Listen on IPv4 addresses only. +.TP +.B \-6 +Listen on IPv6 addresses only. +.TP +.BI \-T \ tool +Run in Tool mode. The \fItool\fP argument selects whether to run as +.IR slapadd , +.IR slapcat , +.IR slapdn , +.IR slapindex , +.IR slapmodify , +.IR slappasswd , +.IR slapschema , +or +.I slaptest +(\fIslapacl\fP and \fIslapauth\fP need the entire \fBacl\fP and \fBauth\fP +option value to be spelled out, as \fBa\fP is reserved to +.IR slapadd ). +This option should be the first option specified when it is used; +any remaining options will be interpreted by the corresponding +slap tool program, according to the respective man pages. +Note that these tool programs will usually be symbolic links to +.BR slapd . +This option is provided for situations where symbolic links +are not provided or not usable. +.TP +.BI \-d \ debug-level +Turn on debugging as defined by +.IR debug-level . +If this option is specified, even with a zero argument, +.B slapd +will not fork or disassociate from the invoking terminal. Some general +operation and status messages are printed for any value of \fIdebug-level\fP. +\fIdebug-level\fP is taken as a bit string, with each bit corresponding to a +different kind of debugging information. See <ldap_log.h> for details. +Comma-separated arrays of friendly names can be specified to select +debugging output of the corresponding debugging information. +All the names recognized by the \fIloglevel\fP directive +described in \fBslapd.conf\fP(5) are supported. +If \fIdebug-level\fP is \fB?\fP, a list of installed debug-levels is printed, +and slapd exits. + +Remember that if you turn on packet logging, packets containing bind passwords +will be output, so if you redirect the log to a logfile, that file should +be read-protected. +.TP +.BI \-s \ syslog-level +This option tells +.B slapd +at what debug-level debugging statements should be logged to the +.BR syslog (8) +facility. +The value \fIsyslog-level\fP can be set to any value or combination +allowed by the \fB\-d\fP switch. +Slapd logs all messages selected by \fIsyslog-level\fP +at the +.BR syslog (3) +severity debug-level \fBDEBUG\fP, +on the unit specified with \fB\-l\fP. +.TP +.BI \-n \ service-name +Specifies the service name for logging and other purposes. Defaults +to basename of argv[0], i.e.: "slapd". +.TP +.BI \-l \ syslog-local-user +Selects the local user of the +.BR syslog (8) +facility. Value can be +.BR LOCAL0 , +through +.BR LOCAL7 , +as well as +.B USER +and +.BR DAEMON . +The default is +.BR LOCAL4 . +However, this option is only permitted on systems that support +local users with the +.BR syslog (8) +facility. +Logging to syslog(8) occurs at the "DEBUG" severity debug-level. +.TP +.BI \-f \ slapd-config-file +Specifies the slapd configuration file. The default is +.BR ETCDIR/slapd.conf . +.TP +.BI \-F \ slapd-config-directory +Specifies the slapd configuration directory. The default is +.BR ETCDIR/slapd.d . +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, slapd will attempt to read the +default config directory before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. All of the slap tools that +use the config options observe this same behavior. +.TP +.BI \-h \ URLlist +.B slapd +will by default serve +.B ldap:/// +(LDAP over TCP on all interfaces on default LDAP port). That is, +it will bind using INADDR_ANY and port \fB389\fP. +The +.B \-h +option may be used to specify LDAP (and other scheme) URLs to serve. +For example, if slapd is given +.BR "\-h \(dqldap://127.0.0.1:9009/ ldaps:/// ldapi:///\(dq" , +it will listen on 127.0.0.1:9009 for LDAP, 0.0.0.0:636 for LDAP over TLS, +and LDAP over IPC (Unix domain sockets). Host 0.0.0.0 represents +INADDR_ANY (any interface). +A space separated list of URLs is expected. The URLs should be of the LDAP, +PLDAP, LDAPS, PLDAPS, or LDAPI schemes, and generally without a DN or other +optional parameters (excepting as discussed below). Support for the latter +three schemes depends on selected configuration options. Hosts may be specified +by name or IPv4 and IPv6 address formats. Ports, if specified, must be +numeric. The default ldap:// port is \fB389\fP and the default ldaps:// port +is \fB636\fP, same for the proxy enabled variants. + +The PLDAP and PLDAPS URL schemes provide support for the HAProxy proxy protocol +version 2, which allows a load balancer or proxy server to provide the remote +client IP address to slapd to be used for access control or logging. Ports +configured for PLDAP or PLDAPS will only accept connections that include the +necessary proxy protocol header. Connections to these ports should be +restricted at the network level to only trusted load balancers or proxies to +avoid spoofing of client IP addresses by third parties. + +For LDAP over IPC, +.B name +is the name of the socket, and no +.B port +is required, nor allowed; note that directory separators must be +URL-encoded, like any other characters that are special to URLs; +so the socket + + /usr/local/var/ldapi + +must be specified as + + ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi + +The default location for the IPC socket is LOCALSTATEDIR/run/ldapi + +The listener permissions are indicated by +"x\-mod=\-rwxrwxrwx", "x\-mod=0777" or "x\-mod=777", where any +of the "rwx" can be "\-" to suppress the related permission, while any +of the "7" can be any legal octal digit, according to chmod(1). +The listeners can take advantage of the "x\-mod" +extension to apply rough limitations to operations, e.g. allow read operations +("r", which applies to search and compare), write operations ("w", +which applies to add, delete, modify and modrdn), and execute operations +("x", which means bind is required). +"User" permissions apply to authenticated users, while "other" apply +to anonymous users; "group" permissions are ignored. +For example, "ldap:///????x\-mod=\-rw\-\-\-\-\-\-\-" means that read and write is only allowed +for authenticated connections, and bind is required for all operations. +This feature is experimental, and requires to be manually enabled +at configure time. +.TP +.BI \-r \ directory +Specifies a directory to become the root directory. slapd will +change the current working directory to this directory and +then +.BR chroot (2) +to this directory. This is done after opening listeners but before +reading any configuration file or initializing any backend. When +used as a security mechanism, it should be used in conjunction with +.B \-u +and +.B \-g +options. +.TP +.BI \-u \ user +.B slapd +will run slapd with the specified user name or id, and that user's +supplementary group access list as set with initgroups(3). The group ID +is also changed to this user's gid, unless the \fB\-g\fP option is used to +override. Note when used with +.BR \-r , +slapd will use the user database in the change root environment. + +Note that on some systems, running as a non-privileged user will prevent +passwd back-ends from accessing the encrypted passwords. Note also that +any shell back-ends will run as the specified non-privileged user. +.TP +.BI \-g \ group +.B slapd +will run with the specified group name or id. Note when used with +.BR \-r , +slapd will use the group database in the change root environment. +.TP +.BI \-c \ cookie +This option provides a cookie for the syncrepl replication consumer. +The cookie is a comma separated list of \fIname=value\fP pairs. +Currently supported syncrepl cookie fields are +.BR rid , +.BR sid , +and +.BR csn . +.B rid +identifies a replication thread within the consumer server +and is used to find the syncrepl specification in +.BR slapd.conf (5) +or +.BR slapd\-config (5) +having the matching replication identifier in its definition. The +.B rid +must be provided in order for any other specified values to be used. +.B sid +is the server id in a multi-provider configuration. +.B csn +is the commit sequence number received by a previous synchronization +and represents the state of the consumer content which the +syncrepl engine will synchronize to the current provider content. +In case of \fImulti-provider\fP replication agreement, +multiple +.B csn +values, semicolon separated, can appear. +Use only the +.B rid +part to force a full reload. +.TP +.BI \-o \ option\fR[ = value\fR] +This option provides a generic means to specify options without the need to reserve +a separate letter for them. + +It supports the following options: +.RS +.TP +.BR slp= { on \||\| off \||\| \fIslp-attrs\fP } +When SLP support is compiled into slapd, disable it (\fBoff\fP), + enable it by registering at SLP DAs without specific SLP attributes (\fBon\fP), +or with specific SLP attributes +.I slp-attrs +that must be an SLP attribute list definition according to the SLP standard. + +For example, \fB"slp=(tree=production),(server-type=OpenLDAP),(server\-version=2.4.15)"\fP +registers at SLP DAs with the three SLP attributes tree, server-type and server-version +that have the values given above. +This allows one to specifically query the SLP DAs for LDAP servers holding the +.I production +tree in case multiple trees are available. +.RE +.SH EXAMPLES +To start +.I slapd +and have it fork and detach from the terminal and start serving +the LDAP databases defined in the default config file, just type: +.LP +.nf +.ft tt + LIBEXECDIR/slapd +.ft +.fi +.LP +To start +.B slapd +with an alternate configuration file, and turn +on voluminous debugging which will be printed on standard error, type: +.LP +.nf +.ft tt + LIBEXECDIR/slapd \-f /var/tmp/slapd.conf \-d 255 +.ft +.fi +.LP +To test whether the configuration file is correct or not, type: +.LP +.nf +.ft tt + LIBEXECDIR/slapd \-Tt +.ft +.fi +.LP +.SH "SEE ALSO" +.BR ldap (3), +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd.access (5), +.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 slapschema (8), +.BR slaptest (8). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH BUGS +See http://www.openldap.org/its/ +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapdn.8 b/doc/man/man8/slapdn.8 new file mode 100644 index 0000000..424bf83 --- /dev/null +++ b/doc/man/man8/slapdn.8 @@ -0,0 +1,108 @@ +.TH SLAPDN 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapdn \- Check a list of string-represented LDAP DNs based on schema syntax +.SH SYNOPSIS +.B SBINDIR/slapdn +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ slapd.conf\fR] +[\c +.BI \-F \ confdir\fR] +[\c +.BR \-N | \-P ] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BR \-v ] +.IR DN \ [...] +.LP +.SH DESCRIPTION +.LP +.B Slapdn +is used to check the conformance of a DN based on the schema +defined in +.BR slapd (8) +and that loaded via +.BR slapd.conf (5). +It opens the +.BR slapd.conf (5) +configuration file or the slapd\-config (5) backend, reads in the schema definitions, and then +parses the +.I DN +list given on the command-line. +.LP +.SH OPTIONS +.TP +.BI \-d \ debug-level +enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-f \ slapd.conf +specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, an attempt to read the +default config directory will be made before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. +.TP +.BI \-N +only output a normalized form of the \fIDN\fP, suitable to be used +in a normalization tool; incompatible with +.BR \-P . +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + +.fi +.TP +.BI \-P +only output a prettified form of the \fIDN\fP, suitable to be used +in a check and beautification tool; incompatible with +.BR \-N . +.TP +.B \-v +enable verbose mode. +.SH EXAMPLES +To check a +.B DN +give the command: +.LP +.nf +.ft tt + SBINDIR/slapdn \-f /ETCDIR/slapd.conf \-v DN +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR slapd (8), +.BR slaptest (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapindex.8 b/doc/man/man8/slapindex.8 new file mode 100644 index 0000000..9cadb64 --- /dev/null +++ b/doc/man/man8/slapindex.8 @@ -0,0 +1,178 @@ +.TH SLAPINDEX 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapindex \- Reindex entries in a SLAPD database +.SH SYNOPSIS +.B SBINDIR/slapindex +[\c +.BI \-b \ suffix\fR] +[\c +.BR \-c ] +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ slapd.conf\fR] +[\c +.BI \-F \ confdir\fR] +[\c +.BR \-g ] +[\c +.BI \-n \ dbnum\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BR \-q ] +[\c +.BR \-t ] +[\c +.BR \-v ] +[\c +.IR attr [ ... ]] +.B +.LP +.SH DESCRIPTION +.LP +.B Slapindex +is used to regenerate +.BR slapd (8) +indices based upon the current contents of a database. +It opens the given database determined by the database number or +suffix and updates the indices for all values of all attributes +of all entries. If a list of specific attributes is provided +on the command line, only the indices for those attributes will +be regenerated. +Databases configured as +.B subordinate +of this one are also re-indexed, unless \fB\-g\fP is specified. + +All files eventually created by +.BR slapindex +will belong to the identity +.BR slapindex +is run as, so make sure you either run +.BR slapindex +with the same identity +.BR slapd (8) +will be run as (see option +.B \-u +in +.BR slapd (8)), +or change file ownership before running +.BR slapd (8). +.SH OPTIONS +.TP +.BI \-b \ suffix +Use the specified \fIsuffix\fR to determine which database to +generate output for. By default, the first database that supports the requested +operation is used. The \fB\-b\fP cannot be used in conjunction with the +.B \-n +option. +.TP +.B \-c +enable continue (ignore errors) mode. +.TP +.BI \-d \ debug-level +enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-f \ slapd.conf +specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, an attempt to read the +default config directory will be made before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. +.TP +.B \-g +disable subordinate gluing. Only the specified database will be +processed, and not its glued subordinates (if any). +.TP +.BI \-n \ dbnum +Generate output for the \fIdbnum\fR-th database listed in the +configuration file. The config database +.BR slapd\-config (5), +is always the first database, so use +.B \-n 0 + +The +.B \-n +cannot be used in conjunction with the +.B \-b +option. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + +.fi +.TP +.B \-q +enable quick (fewer integrity checks) mode. Performs no consistency checks +when writing the database. Improves indexing time, +.B however +the database will most likely be unusable if any errors or +interruptions occur. +.TP +.B \-t +enable truncate mode. Truncates (empties) an index database before indexing +any entries. May only be used with back-mdb. +.TP +.B \-v +enable verbose mode. +.SH LIMITATIONS +Your +.BR slapd (8) +should not be running (at least, not in read-write +mode) when you do this to ensure consistency of the database. +.LP +This command provides ample opportunity for the user to obtain +and drink their favorite beverage. +.SH EXAMPLES +To reindex your SLAPD database, give the command: +.LP +.nf +.ft tt + SBINDIR/slapindex +.ft +.fi +To regenerate the index for only a specific attribute, e.g. "uid", +give the command: +.LP +.nf +.ft tt + SBINDIR/slapindex uid +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR ldif (5), +.BR slapadd (8), +.BR ldapadd (1), +.BR slapd (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapmodify.8 b/doc/man/man8/slapmodify.8 new file mode 100644 index 0000000..98069be --- /dev/null +++ b/doc/man/man8/slapmodify.8 @@ -0,0 +1,222 @@ +.TH SLAPMODIFY 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapmodify \- Modify entries in a SLAPD database +.SH SYNOPSIS +.B SBINDIR/slapmodify +[\c +.BI \-b \ suffix\fR] +[\c +.BR \-c ] +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ slapd.conf\fR] +[\c +.BI \-F \ confdir\fR] +[\c +.BR \-g ] +[\c +.BI \-j \ lineno\fR] +[\c +.BI \-l \ ldif-file\fR] +[\c +.BI \-n \ dbnum\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BR \-q ] +[\c +.BR \-s ] +[\c +.BI \-S \ SID\fR] +[\c +.BR \-u ] +[\c +.BR \-v ] +[\c +.BR \-w ] +.SH DESCRIPTION +.LP +.B Slapmodify +is used to apply modifications specified in LDAP Directory Interchange Format +(LDIF) to a +.BR slapd (8) +database. +It opens the given database determined by the database number or +suffix and performs modifications corresponding to the provided LDIF to +the database. +Databases configured as +.B subordinate +of this one are also updated, unless \fB\-g\fP is specified. +The LDIF input is read from standard input or the specified file. + +All files eventually created by +.BR slapmodify +will belong to the identity +.BR slapmodify +is run as, so make sure you either run +.BR slapmodify +with the same identity +.BR slapd (8) +will be run as (see option +.B \-u +in +.BR slapd (8)), +or change file ownership before running +.BR slapd (8). + +Note: slapmodify will also perform the relevant indexing whilst modifying the database if +any are configured. For specific details, please see +.BR slapindex (8). +.SH OPTIONS +.TP +.BI \-b \ suffix +Use the specified \fIsuffix\fR to determine which database to +add entries to. The \fB\-b\fP cannot be used in conjunction +with the +.B \-n +option. +.TP +.B \-c +enable continue (ignore errors) mode. +.TP +.BI \-d \ debug-level +enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-f \ slapd.conf +specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, an attempt to read the +default config directory will be made before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. If dry-run mode is also specified, +no conversion will occur. +.TP +.B \-g +disable subordinate gluing. Only the specified database will be +processed, and not its glued subordinates (if any). +.TP +.BI \-j \ lineno +Jump to the specified line number in the LDIF file before processing +any entries. This allows a modification that was aborted due to errors in the +input LDIF to be resumed after the errors are corrected. +.TP +.BI \-l \ ldif-file +Read LDIF from the specified file instead of standard input. +.TP +.BI \-n \ dbnum +Perform changes on the \fIdbnum\fR-th database listed in the +configuration file. The +.B \-n +cannot be used in conjunction with the +.B \-b +option. +To manipulate the config database +.BR slapd\-config (5), +use +.B \-n 0 +as it is always the first database. It must physically exist +on the filesystem prior to this, however. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + + schema-check={yes|no} + value-check={yes|no} + +.in +The \fIschema\-check\fR option toggles schema checking (default on); +the \fIvalue\-check\fR option toggles value checking (default off). +The latter is incompatible with \fB-q\fR. +.TP +.B \-q +enable quick (fewer integrity checks) mode. Does fewer consistency checks +on the input data, and no consistency checks when writing the database. +Improves the run time but if any errors or interruptions occur the resulting +database will be unusable. +.TP +.B \-s +disable schema checking. This option is intended to be used when +manipulating databases containing special objects, such as fractional +objects on a partial replica. Creating normal objects which do not +conform to schema may result in unexpected and ill behavior. +.TP +.BI \-S \ SID +Server ID to use in generated entryCSN. Also used for contextCSN +if \fB\-w\fP is set as well. Defaults to \fB0\fP. +.TP +.B \-u +enable dry-run (don't write to backend) mode. +.TP +.B \-v +enable verbose mode. +.TP +.BI \-w +write syncrepl context information. +After all entries are added, the contextCSN +will be updated with the greatest CSN in the database. +.SH LIMITATIONS +Your +.BR slapd (8) +should not be running +when you do this to ensure consistency of the database. +.LP +Not all backends support all types of modification, \fImodrdn\fR +changetype in particular is not implemented for any of the current +backends. +.LP +.B slapmodify +may not provide naming or schema checks. It is advisable to +use +.BR ldapmodify (1) +when possible. +.SH EXAMPLES +To make modifications specified in file +.B ldif +into your +.BR slapd (8) +database give the command: +.LP +.nf +.ft tt + SBINDIR/slapmodify \-l ldif +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR ldif (5), +.BR slapcat (8), +.BR slapadd (8), +.BR slapindex (8), +.BR ldapmodify (1), +.BR slapd (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slappasswd.8 b/doc/man/man8/slappasswd.8 new file mode 100644 index 0000000..7bca21d --- /dev/null +++ b/doc/man/man8/slappasswd.8 @@ -0,0 +1,203 @@ +.TH SLAPPASSWD 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slappasswd \- OpenLDAP password utility +.SH SYNOPSIS +.B SBINDIR/slappasswd +[\c +.BR \-v ] +[\c +.BR \-u ] +[\c +.BR \-g \||\| \-s \ \fIsecret\fR \||\| \fB\-T \ \fIfile\fR] +[\c +.BI \-h \ hash\fR] +[\c +.BI \-c \ salt-format\fR] +[\c +.BR \-n ] +[\c +.BI \-o \ option\fR[ = value\fR]] +.LP +.SH DESCRIPTION +.LP +.B Slappasswd +is used to generate an userPassword value +suitable for use with +.BR ldapmodify (1), +.BR slapd.conf (5) +.I rootpw +configuration directive or the +.BR slapd\-config (5) +.I olcRootPW +configuration directive. +. +.SH OPTIONS +.TP +.B \-v +enable verbose mode. +.TP +.B \-u +Generate RFC 2307 userPassword values (the default). Future +versions of this program may generate alternative syntaxes +by default. This option is provided for forward compatibility. +.TP +.BI \-s \ secret +The secret to hash. +If this, +.B \-g +and +.B \-T +are absent, the user will be prompted for the secret to hash. +.BR \-s , +.B \-g +and +.B \-T +are mutually exclusive flags. +.TP +.BI \-g +Generate the secret. +If this, +.B \-s +and +.B \-T +are absent, the user will be prompted for the secret to hash. +.BR \-s , +.B \-g +and +.B \-T +are mutually exclusive flags. +If this is present, +.I {CLEARTEXT} +is used as scheme. +.B \-g +and +.B \-h +are mutually exclusive flags. +.TP +.BI \-T \ "file" +Hash the contents of the file. +If this, +.B \-g +and +.B \-s +are absent, the user will be prompted for the secret to hash. +.BR \-s , +.B \-g +and +.B \-T +and mutually exclusive flags. +.TP +.BI \-h \ "scheme" +If \fB\-h\fP is specified, one of the following RFC 2307 schemes may +be specified: +.BR {CRYPT} , +.BR {MD5} , +.BR {SMD5} , +.BR {SSHA} ", and" +.BR {SHA} . +The default is +.BR {SSHA} . + +Note that scheme names may need to be protected, due to +.B { +and +.BR } , +from expansion by the user's command interpreter. + +.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. +Unless +.I {CLEARTEXT} +is used, this flag is incompatible with option +.BR \-g . +.TP +.BI \-c \ crypt-salt-format +Specify the format of the salt passed to +.BR crypt (3) +when generating {CRYPT} passwords. +This string needs to be in +.BR sprintf (3) +format and may include one (and only one) +.B %s +conversion. +This conversion will be substituted with a string of random +characters from [A\-Za\-z0\-9./]. For example, +.RB ' %.2s ' +provides a two character salt and +.RB ' $1$%.8s ' +tells some +versions of +.BR crypt (3) +to use an MD5 algorithm and provides +8 random characters of salt. +The default is +.RB ' %s ' , +which provides 31 characters of salt. +.TP +.BI \-n +Omit the trailing newline; useful to pipe the credentials +into a command. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + module\-path=<pathspec> (see `\fBmodulepath\fP' in slapd.conf(5)) + module\-load="<filename> [<arguments>...]" (see `\fBmoduleload\fP' in slapd.conf(5)) + +.in +You can load a dynamically loadable password hash module by +using this option. +.SH LIMITATIONS +The practice of storing hashed passwords in userPassword violates +Standard Track (RFC 4519) schema specifications and may hinder +interoperability. A new attribute type, authPassword, to hold +hashed passwords has been defined (RFC 3112), but is not yet +implemented in +.BR slapd (8). +.LP +It should also be noted that the behavior of +.BR crypt (3) +is platform specific. +.SH "SECURITY CONSIDERATIONS" +Use of hashed passwords does not protect passwords during +protocol transfer. TLS or other eavesdropping protections +should be in-place before using LDAP simple bind. +.LP +The hashed password values should be protected as if they +were clear text passwords. +.SH "SEE ALSO" +.BR ldappasswd (1), +.BR ldapmodify (1), +.BR slapd (8), +.BR slapd.conf (5), +.BR slapd\-config (5), +.B RFC 2307\fP, +.B RFC 4519\fP, +.B RFC 3112 +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slapschema.8 b/doc/man/man8/slapschema.8 new file mode 100644 index 0000000..8b91f8a --- /dev/null +++ b/doc/man/man8/slapschema.8 @@ -0,0 +1,193 @@ +.TH SLAPSCHEMA 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapschema \- SLAPD in-database schema checking utility +.SH SYNOPSIS +.B SBINDIR/slapschema +[\c +.BI \-a filter\fR] +[\c +.BI \-b suffix\fR] +[\c +.BR \-c ] +[\c +.BI \-d debug-level\fR] +[\c +.BI \-f slapd.conf\fR] +[\c +.BI \-F confdir\fR] +[\c +.BR \-g ] +[\c +.BI \-H URI\fR] +[\c +.BI \-l error-file\fR] +[\c +.BI \-n dbnum\fR] +[\c +.BI \-o option\fR[ = value\fR]] +[\c +.BI \-s subtree-dn\fR] +[\c +.BR \-v ] +.LP +.SH DESCRIPTION +.LP +.B Slapschema +is used to check schema compliance of the contents of a +.BR slapd (8) +database. +It opens the given database determined by the database number or +suffix and checks the compliance of its contents with the corresponding +schema. Errors are written to standard output or the specified file. +Databases configured as +.B subordinate +of this one are also output, unless \fB\-g\fP is specified. +.LP +Administrators may need to modify existing schema items, including +adding new required attributes to objectClasses, +removing existing required or allowed attributes from objectClasses, +entirely removing objectClasses, +or any other change that may result in making perfectly valid entries +no longer compliant with the modified schema. +The execution of the +.B slapschema +tool after modifying the schema can point out +inconsistencies that would otherwise surface only when +inconsistent entries need to be modified. + +.LP +The entry records are checked in database order, not superior first +order. The entry records will be checked considering all +(user and operational) attributes stored in the database. +Dynamically generated attributes (such as subschemaSubentry) +will not be considered. +.SH OPTIONS +.TP +.BI \-a \ filter +Only check entries matching the asserted filter. +For example + +slapschema \-a \\ + "(!(entryDN:dnSubtreeMatch:=ou=People,dc=example,dc=com))" + +will check all but the "ou=People,dc=example,dc=com" subtree +of the "dc=example,dc=com" database. +Deprecated; use \fB-H\fP \fIldap:///???(filter)\fP instead. +.TP +.BI \-b \ suffix +Use the specified \fIsuffix\fR to determine which database to +check. By default, the first database that supports the requested operation is +used. The \fB\-b\fP cannot be used in conjunction with the +.B \-n +option. +.TP +.B \-c +Enable continue (ignore errors) mode. +.TP +.BI \-d \ debug-level +Enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-f \ slapd.conf +Specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, an attempt to read the +default config directory will be made before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. +.TP +.B \-g +disable subordinate gluing. Only the specified database will be +processed, and not its glued subordinates (if any). +.TP +.B \-H \ URI +use dn, scope and filter from URI to only handle matching entries. +.TP +.BI \-l \ error-file +Write errors to specified file instead of standard output. +.TP +.BI \-n \ dbnum +Check the \fIdbnum\fR\-th database listed in the +configuration file. The config database +.BR slapd\-config (5), +is always the first database, so use +.B \-n 0 + +The +.B \-n +cannot be used in conjunction with the +.B \-b +option. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + +.fi +.TP +.BI \-s \ subtree-dn +Only check entries in the subtree specified by this DN. +Implies \fB\-b\fP \fIsubtree-dn\fP if no +.B \-b +nor +.B \-n +option is given. +Deprecated; use \fB-H\fP \fIldap:///subtree-dn\fP instead. +.TP +.B \-v +Enable verbose mode. +.SH LIMITATIONS +For some backend types, your +.BR slapd (8) +should not be running (at least, not in read-write +mode) when you do this to ensure consistency of the database. It is +always safe to run +.B slapschema +with the +.BR slapd\-mdb (5), +and +.BR slapd\-null (5) +backends. +.SH EXAMPLES +To check the schema compliance of your SLAPD database after modifications +to the schema, and put any error in a file called +.BR errors.ldif , +give the command: +.LP +.nf +.ft tt + SBINDIR/slapschema \-l errors.ldif +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR ldif (5), +.BR slapd (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man8/slaptest.8 b/doc/man/man8/slaptest.8 new file mode 100644 index 0000000..9effa9f --- /dev/null +++ b/doc/man/man8/slaptest.8 @@ -0,0 +1,117 @@ +.TH SLAPTEST 8C "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2004-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slaptest \- Check the suitability of the OpenLDAP slapd configuration +.SH SYNOPSIS +.B SBINDIR/slaptest +[\c +.BI \-d \ debug-level\fR] +[\c +.BI \-f \ slapd.conf\fR] +[\c +.BI \-F \ confdir\fR] +[\c +.BI \-n dbnum\fR] +[\c +.BI \-o \ option\fR[ = value\fR]] +[\c +.BR \-Q ] +[\c +.BR \-u ] +[\c +.BR \-v ] +.LP +.SH DESCRIPTION +.LP +.B Slaptest +is used to check the conformance of the +.BR slapd (8) +configuration. +It opens the +.BR slapd.conf (5) +configuration file or the +.BR slapd\-config (5) +backend, and parses it according to the general and the backend-specific +rules, checking its sanity. +.LP +.SH OPTIONS +.TP +.BI \-d \ debug-level +enable debugging messages as defined by the specified +.IR debug-level ; +see +.BR slapd (8) +for details. +.TP +.BI \-f \ slapd.conf +specify an alternative +.BR slapd.conf (5) +file. +.TP +.BI \-F \ confdir +specify a config directory. +If both +.B \-f +and +.B \-F +are specified, the config file will be read and converted to +config directory format and written to the specified directory. +If neither option is specified, slaptest will attempt to read the +default config directory before trying to use the default +config file. If a valid config directory exists then the +default config file is ignored. If dry-run mode is also specified, +no conversion will occur. +.TP +.BI \-n \ dbnum +Just open and test the \fIdbnum\fR-th database listed in the +configuration file. +To only test the config database +.BR slapd\-config (5), +use +.B \-n 0 +as it is always the first database. +.TP +.BI \-o \ option\fR[ = value\fR] +Specify an +.I option +with a(n optional) +.IR value . +Possible generic options/values are: +.LP +.nf + syslog=<subsystems> (see `\-s' in slapd(8)) + syslog\-level=<level> (see `\-S' in slapd(8)) + syslog\-user=<user> (see `\-l' in slapd(8)) + +.fi +.TP +.BI \-Q +Be extremely quiet: only the exit code indicates success (0) or not +(any other value). +.TP +.B \-u +enable dry-run mode (i.e. don't fail if databases cannot be opened, +but config is fine). +.TP +.B \-v +enable verbose mode. +.SH EXAMPLES +To check a +.BR slapd.conf (5) +give the command: +.LP +.nf +.ft tt + SBINDIR/slaptest \-f /ETCDIR/slapd.conf \-v +.ft +.fi +.SH "SEE ALSO" +.BR ldap (3), +.BR slapd (8), +.BR slapdn (8) +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project |