From 5ea77a75dd2d2158401331879f3c8f47940a732c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 18:35:32 +0200 Subject: Adding upstream version 2.5.13+dfsg. Signed-off-by: Daniel Baumann --- doc/man/Makefile.in | 16 + doc/man/Project | 5 + doc/man/man1/Makefile.in | 16 + doc/man/man1/ldapcompare.1 | 241 +++ doc/man/man1/ldapdelete.1 | 252 +++ doc/man/man1/ldapexop.1 | 242 +++ doc/man/man1/ldapmodify.1 | 390 +++++ doc/man/man1/ldapmodify.1.links | 1 + doc/man/man1/ldapmodrdn.1 | 268 +++ doc/man/man1/ldappasswd.1 | 231 +++ doc/man/man1/ldapsearch.1 | 495 ++++++ doc/man/man1/ldapurl.1 | 168 ++ doc/man/man1/ldapvc.1 | 213 +++ doc/man/man1/ldapwhoami.1 | 194 +++ doc/man/man3/Deprecated | 7 + doc/man/man3/Makefile.in | 16 + doc/man/man3/lber-decode.3 | 357 ++++ doc/man/man3/lber-decode.3.links | 13 + doc/man/man3/lber-encode.3 | 288 ++++ doc/man/man3/lber-encode.3.links | 11 + doc/man/man3/lber-memory.3 | 49 + doc/man/man3/lber-sockbuf.3 | 199 +++ doc/man/man3/lber-types.3 | 188 +++ doc/man/man3/lber-types.3.links | 11 + doc/man/man3/ldap.3 | 278 ++++ doc/man/man3/ldap_abandon.3 | 69 + doc/man/man3/ldap_abandon.3.links | 1 + doc/man/man3/ldap_add.3 | 81 + doc/man/man3/ldap_add.3.links | 3 + doc/man/man3/ldap_bind.3 | 334 ++++ doc/man/man3/ldap_bind.3.links | 10 + doc/man/man3/ldap_compare.3 | 79 + doc/man/man3/ldap_compare.3.links | 3 + doc/man/man3/ldap_controls.3 | 84 + doc/man/man3/ldap_controls.3.links | 6 + doc/man/man3/ldap_delete.3 | 89 + doc/man/man3/ldap_delete.3.links | 3 + doc/man/man3/ldap_dup.3 | 125 ++ doc/man/man3/ldap_dup.3.links | 1 + doc/man/man3/ldap_error.3 | 224 +++ doc/man/man3/ldap_error.3.links | 5 + doc/man/man3/ldap_extended_operation.3 | 75 + doc/man/man3/ldap_extended_operation.3.links | 2 + doc/man/man3/ldap_first_attribute.3 | 97 ++ doc/man/man3/ldap_first_attribute.3.links | 2 + doc/man/man3/ldap_first_entry.3 | 80 + doc/man/man3/ldap_first_entry.3.links | 2 + doc/man/man3/ldap_first_message.3 | 82 + doc/man/man3/ldap_first_message.3.links | 2 + doc/man/man3/ldap_first_reference.3 | 71 + doc/man/man3/ldap_first_reference.3.links | 2 + doc/man/man3/ldap_get_dn.3 | 246 +++ doc/man/man3/ldap_get_dn.3.links | 9 + doc/man/man3/ldap_get_option.3 | 932 +++++++++++ doc/man/man3/ldap_get_option.3.links | 1 + doc/man/man3/ldap_get_values.3 | 102 ++ doc/man/man3/ldap_get_values.3.links | 5 + doc/man/man3/ldap_memory.3 | 50 + doc/man/man3/ldap_memory.3.links | 6 + doc/man/man3/ldap_modify.3 | 134 ++ doc/man/man3/ldap_modify.3.links | 4 + doc/man/man3/ldap_modrdn.3 | 81 + doc/man/man3/ldap_modrdn.3.links | 3 + doc/man/man3/ldap_open.3 | 236 +++ doc/man/man3/ldap_open.3.links | 4 + doc/man/man3/ldap_parse_reference.3 | 61 + doc/man/man3/ldap_parse_result.3 | 114 ++ doc/man/man3/ldap_parse_result.3.links | 3 + doc/man/man3/ldap_parse_sort_control.3 | 40 + doc/man/man3/ldap_parse_vlv_control.3 | 49 + doc/man/man3/ldap_rename.3 | 66 + doc/man/man3/ldap_rename.3.links | 1 + doc/man/man3/ldap_result.3 | 136 ++ doc/man/man3/ldap_result.3.links | 3 + doc/man/man3/ldap_schema.3 | 320 ++++ doc/man/man3/ldap_schema.3.links | 17 + doc/man/man3/ldap_search.3 | 144 ++ doc/man/man3/ldap_search.3.links | 4 + doc/man/man3/ldap_sort.3 | 21 + doc/man/man3/ldap_sort.3.links | 3 + doc/man/man3/ldap_sync.3 | 326 ++++ doc/man/man3/ldap_tls.3 | 41 + doc/man/man3/ldap_tls.3.links | 4 + doc/man/man3/ldap_url.3 | 83 + doc/man/man3/ldap_url.3.links | 3 + doc/man/man5/Makefile.in | 16 + doc/man/man5/ldap.conf.5 | 529 ++++++ doc/man/man5/ldif.5 | 277 ++++ doc/man/man5/lloadd.conf.5 | 848 ++++++++++ doc/man/man5/slapd-asyncmeta.5 | 532 ++++++ doc/man/man5/slapd-config.5 | 2274 ++++++++++++++++++++++++++ doc/man/man5/slapd-dnssrv.5 | 49 + doc/man/man5/slapd-ldap.5 | 700 ++++++++ doc/man/man5/slapd-ldif.5 | 54 + doc/man/man5/slapd-mdb.5 | 241 +++ doc/man/man5/slapd-meta.5 | 1378 ++++++++++++++++ doc/man/man5/slapd-monitor.5 | 126 ++ doc/man/man5/slapd-ndb.5 | 127 ++ doc/man/man5/slapd-null.5 | 72 + doc/man/man5/slapd-passwd.5 | 56 + doc/man/man5/slapd-perl.5 | 199 +++ doc/man/man5/slapd-relay.5 | 207 +++ doc/man/man5/slapd-sock.5 | 329 ++++ doc/man/man5/slapd-sock.5.links | 1 + doc/man/man5/slapd-sql.5 | 699 ++++++++ doc/man/man5/slapd-wt.5 | 97 ++ doc/man/man5/slapd.access.5 | 1205 ++++++++++++++ doc/man/man5/slapd.backends.5 | 140 ++ doc/man/man5/slapd.conf.5 | 2140 ++++++++++++++++++++++++ doc/man/man5/slapd.overlays.5 | 204 +++ doc/man/man5/slapd.plugin.5 | 124 ++ doc/man/man5/slapo-accesslog.5 | 514 ++++++ doc/man/man5/slapo-auditlog.5 | 98 ++ doc/man/man5/slapo-autoca.5 | 120 ++ doc/man/man5/slapo-chain.5 | 152 ++ doc/man/man5/slapo-collect.5 | 52 + doc/man/man5/slapo-constraint.5 | 155 ++ doc/man/man5/slapo-dds.5 | 271 +++ doc/man/man5/slapo-deref.5 | 80 + doc/man/man5/slapo-dyngroup.5 | 58 + doc/man/man5/slapo-dynlist.5 | 275 ++++ doc/man/man5/slapo-homedir.5 | 130 ++ doc/man/man5/slapo-memberof.5 | 145 ++ doc/man/man5/slapo-otp.5 | 138 ++ doc/man/man5/slapo-pbind.5 | 61 + doc/man/man5/slapo-pcache.5 | 327 ++++ doc/man/man5/slapo-ppolicy.5 | 1060 ++++++++++++ doc/man/man5/slapo-refint.5 | 78 + doc/man/man5/slapo-remoteauth.5 | 160 ++ doc/man/man5/slapo-retcode.5 | 257 +++ doc/man/man5/slapo-rwm.5 | 669 ++++++++ doc/man/man5/slapo-sssvlv.5 | 57 + doc/man/man5/slapo-syncprov.5 | 81 + doc/man/man5/slapo-translucent.5 | 133 ++ doc/man/man5/slapo-unique.5 | 187 +++ doc/man/man5/slapo-valsort.5 | 97 ++ doc/man/man5/slappw-argon2.5 | 131 ++ doc/man/man8/Makefile.in | 16 + doc/man/man8/lloadd.8 | 312 ++++ doc/man/man8/slapacl.8 | 205 +++ doc/man/man8/slapadd.8 | 218 +++ doc/man/man8/slapauth.8 | 152 ++ doc/man/man8/slapcat.8 | 203 +++ doc/man/man8/slapd.8 | 377 +++++ doc/man/man8/slapdn.8 | 108 ++ doc/man/man8/slapindex.8 | 178 ++ doc/man/man8/slapmodify.8 | 222 +++ doc/man/man8/slappasswd.8 | 203 +++ doc/man/man8/slapschema.8 | 193 +++ doc/man/man8/slaptest.8 | 117 ++ 150 files changed, 29547 insertions(+) create mode 100644 doc/man/Makefile.in create mode 100644 doc/man/Project create mode 100644 doc/man/man1/Makefile.in create mode 100644 doc/man/man1/ldapcompare.1 create mode 100644 doc/man/man1/ldapdelete.1 create mode 100644 doc/man/man1/ldapexop.1 create mode 100644 doc/man/man1/ldapmodify.1 create mode 100644 doc/man/man1/ldapmodify.1.links create mode 100644 doc/man/man1/ldapmodrdn.1 create mode 100644 doc/man/man1/ldappasswd.1 create mode 100644 doc/man/man1/ldapsearch.1 create mode 100644 doc/man/man1/ldapurl.1 create mode 100644 doc/man/man1/ldapvc.1 create mode 100644 doc/man/man1/ldapwhoami.1 create mode 100644 doc/man/man3/Deprecated create mode 100644 doc/man/man3/Makefile.in create mode 100644 doc/man/man3/lber-decode.3 create mode 100644 doc/man/man3/lber-decode.3.links create mode 100644 doc/man/man3/lber-encode.3 create mode 100644 doc/man/man3/lber-encode.3.links create mode 100644 doc/man/man3/lber-memory.3 create mode 100644 doc/man/man3/lber-sockbuf.3 create mode 100644 doc/man/man3/lber-types.3 create mode 100644 doc/man/man3/lber-types.3.links create mode 100644 doc/man/man3/ldap.3 create mode 100644 doc/man/man3/ldap_abandon.3 create mode 100644 doc/man/man3/ldap_abandon.3.links create mode 100644 doc/man/man3/ldap_add.3 create mode 100644 doc/man/man3/ldap_add.3.links create mode 100644 doc/man/man3/ldap_bind.3 create mode 100644 doc/man/man3/ldap_bind.3.links create mode 100644 doc/man/man3/ldap_compare.3 create mode 100644 doc/man/man3/ldap_compare.3.links create mode 100644 doc/man/man3/ldap_controls.3 create mode 100644 doc/man/man3/ldap_controls.3.links create mode 100644 doc/man/man3/ldap_delete.3 create mode 100644 doc/man/man3/ldap_delete.3.links create mode 100644 doc/man/man3/ldap_dup.3 create mode 100644 doc/man/man3/ldap_dup.3.links create mode 100644 doc/man/man3/ldap_error.3 create mode 100644 doc/man/man3/ldap_error.3.links create mode 100644 doc/man/man3/ldap_extended_operation.3 create mode 100644 doc/man/man3/ldap_extended_operation.3.links create mode 100644 doc/man/man3/ldap_first_attribute.3 create mode 100644 doc/man/man3/ldap_first_attribute.3.links create mode 100644 doc/man/man3/ldap_first_entry.3 create mode 100644 doc/man/man3/ldap_first_entry.3.links create mode 100644 doc/man/man3/ldap_first_message.3 create mode 100644 doc/man/man3/ldap_first_message.3.links create mode 100644 doc/man/man3/ldap_first_reference.3 create mode 100644 doc/man/man3/ldap_first_reference.3.links create mode 100644 doc/man/man3/ldap_get_dn.3 create mode 100644 doc/man/man3/ldap_get_dn.3.links create mode 100644 doc/man/man3/ldap_get_option.3 create mode 100644 doc/man/man3/ldap_get_option.3.links create mode 100644 doc/man/man3/ldap_get_values.3 create mode 100644 doc/man/man3/ldap_get_values.3.links create mode 100644 doc/man/man3/ldap_memory.3 create mode 100644 doc/man/man3/ldap_memory.3.links create mode 100644 doc/man/man3/ldap_modify.3 create mode 100644 doc/man/man3/ldap_modify.3.links create mode 100644 doc/man/man3/ldap_modrdn.3 create mode 100644 doc/man/man3/ldap_modrdn.3.links create mode 100644 doc/man/man3/ldap_open.3 create mode 100644 doc/man/man3/ldap_open.3.links create mode 100644 doc/man/man3/ldap_parse_reference.3 create mode 100644 doc/man/man3/ldap_parse_result.3 create mode 100644 doc/man/man3/ldap_parse_result.3.links create mode 100644 doc/man/man3/ldap_parse_sort_control.3 create mode 100644 doc/man/man3/ldap_parse_vlv_control.3 create mode 100644 doc/man/man3/ldap_rename.3 create mode 100644 doc/man/man3/ldap_rename.3.links create mode 100644 doc/man/man3/ldap_result.3 create mode 100644 doc/man/man3/ldap_result.3.links create mode 100644 doc/man/man3/ldap_schema.3 create mode 100644 doc/man/man3/ldap_schema.3.links create mode 100644 doc/man/man3/ldap_search.3 create mode 100644 doc/man/man3/ldap_search.3.links create mode 100644 doc/man/man3/ldap_sort.3 create mode 100644 doc/man/man3/ldap_sort.3.links create mode 100644 doc/man/man3/ldap_sync.3 create mode 100644 doc/man/man3/ldap_tls.3 create mode 100644 doc/man/man3/ldap_tls.3.links create mode 100644 doc/man/man3/ldap_url.3 create mode 100644 doc/man/man3/ldap_url.3.links create mode 100644 doc/man/man5/Makefile.in create mode 100644 doc/man/man5/ldap.conf.5 create mode 100644 doc/man/man5/ldif.5 create mode 100644 doc/man/man5/lloadd.conf.5 create mode 100644 doc/man/man5/slapd-asyncmeta.5 create mode 100644 doc/man/man5/slapd-config.5 create mode 100644 doc/man/man5/slapd-dnssrv.5 create mode 100644 doc/man/man5/slapd-ldap.5 create mode 100644 doc/man/man5/slapd-ldif.5 create mode 100644 doc/man/man5/slapd-mdb.5 create mode 100644 doc/man/man5/slapd-meta.5 create mode 100644 doc/man/man5/slapd-monitor.5 create mode 100644 doc/man/man5/slapd-ndb.5 create mode 100644 doc/man/man5/slapd-null.5 create mode 100644 doc/man/man5/slapd-passwd.5 create mode 100644 doc/man/man5/slapd-perl.5 create mode 100644 doc/man/man5/slapd-relay.5 create mode 100644 doc/man/man5/slapd-sock.5 create mode 100644 doc/man/man5/slapd-sock.5.links create mode 100644 doc/man/man5/slapd-sql.5 create mode 100644 doc/man/man5/slapd-wt.5 create mode 100644 doc/man/man5/slapd.access.5 create mode 100644 doc/man/man5/slapd.backends.5 create mode 100644 doc/man/man5/slapd.conf.5 create mode 100644 doc/man/man5/slapd.overlays.5 create mode 100644 doc/man/man5/slapd.plugin.5 create mode 100644 doc/man/man5/slapo-accesslog.5 create mode 100644 doc/man/man5/slapo-auditlog.5 create mode 100644 doc/man/man5/slapo-autoca.5 create mode 100644 doc/man/man5/slapo-chain.5 create mode 100644 doc/man/man5/slapo-collect.5 create mode 100644 doc/man/man5/slapo-constraint.5 create mode 100644 doc/man/man5/slapo-dds.5 create mode 100644 doc/man/man5/slapo-deref.5 create mode 100644 doc/man/man5/slapo-dyngroup.5 create mode 100644 doc/man/man5/slapo-dynlist.5 create mode 100644 doc/man/man5/slapo-homedir.5 create mode 100644 doc/man/man5/slapo-memberof.5 create mode 100644 doc/man/man5/slapo-otp.5 create mode 100644 doc/man/man5/slapo-pbind.5 create mode 100644 doc/man/man5/slapo-pcache.5 create mode 100644 doc/man/man5/slapo-ppolicy.5 create mode 100644 doc/man/man5/slapo-refint.5 create mode 100644 doc/man/man5/slapo-remoteauth.5 create mode 100644 doc/man/man5/slapo-retcode.5 create mode 100644 doc/man/man5/slapo-rwm.5 create mode 100644 doc/man/man5/slapo-sssvlv.5 create mode 100644 doc/man/man5/slapo-syncprov.5 create mode 100644 doc/man/man5/slapo-translucent.5 create mode 100644 doc/man/man5/slapo-unique.5 create mode 100644 doc/man/man5/slapo-valsort.5 create mode 100644 doc/man/man5/slappw-argon2.5 create mode 100644 doc/man/man8/Makefile.in create mode 100644 doc/man/man8/lloadd.8 create mode 100644 doc/man/man8/slapacl.8 create mode 100644 doc/man/man8/slapadd.8 create mode 100644 doc/man/man8/slapauth.8 create mode 100644 doc/man/man8/slapcat.8 create mode 100644 doc/man/man8/slapd.8 create mode 100644 doc/man/man8/slapdn.8 create mode 100644 doc/man/man8/slapindex.8 create mode 100644 doc/man/man8/slapmodify.8 create mode 100644 doc/man/man8/slappasswd.8 create mode 100644 doc/man/man8/slapschema.8 create mode 100644 doc/man/man8/slaptest.8 (limited to 'doc/man') 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 . +## +## 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 +## . + +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 . +.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 . +## +## Copyright 1998-2022 The OpenLDAP Foundation. +## All rights reserved. +## +## Redistribution and use in source and binary forms, with or without +## modification, are permitted only as authorized by the OpenLDAP +## Public License. +## +## A copy of this license is available in the file LICENSE in the +## top-level directory of the distribution or, alternatively, at +## . + +MANSECT=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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: +.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 +.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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: +.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 +.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 . +.\" 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 [] 1.3.6.1.4.1.4203.1.11.3 + +.fi +yields +.nf + + # extended operation response + data:: + +.fi +while calling it with the keyword \fBwhoami\fP +.nf + + ldapexop [] whoami + +.fi +results in +.nf + + dn: + +.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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: +.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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: +.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 +.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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: +.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 +.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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: \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 +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man1/ldapsearch.1 b/doc/man/man1/ldapsearch.1 new file mode 100644 index 0000000..2aec7c5 --- /dev/null +++ b/doc/man/man1/ldapsearch.1 @@ -0,0 +1,495 @@ +.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: +\fB/var/tmp/\fP) +.TP +.BI \-F \ prefix +URL prefix for temporary files. Default is \fBfile://\fIpath\fP where +\fIpath\fP is \fB/var/tmp/\fP or 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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (matched values filter) + [!]pr=[/prompt|noprompt] (paged results/prompt) + [!]sss=[\-][/[\-]...] (server side sorting) + [!]subentries[=true|false] (subentries) + [!]sync=ro[/] (LDAP Sync refreshOnly) + rp[/][/] (LDAP Sync refreshAndPersist) + [!]vlv=/(//|:) (virtual list view) + [!]deref=derefAttr:attr[,attr[...]][;derefAttr:attr[,attr[...]]] + [!][=:|::] +.fi +.TP +.BI \-o \ opt \fR[= optparam \fR] + +Specify any +.BR ldap.conf (5) +option or one of the following: +.nf + nettimeout= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: +.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 +.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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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 +.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= (an RFC 4515 Filter) + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (SASL Authentication Identity "dn:" or "u:") + authzid= (SASL Authorization Identity "dn:" or "u:") + mech= (SASL mechanism default e.g. Simple) + 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= (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= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: +.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 +.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= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + 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= (in seconds, or "none" or "max") + ldif_wrap= (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: "" +or +.BI u: +.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 +.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 . +## +## Copyright 1998-2022 The OpenLDAP Foundation. +## All rights reserved. +## +## Redistribution and use in source and binary forms, with or without +## modification, are permitted only as authorized by the OpenLDAP +## Public License. +## +## A copy of this license is available in the file LICENSE in the +## top-level directory of the distribution or, alternatively, at +## . + +MANSECT=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 +.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 +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 +.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 + 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 +.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 +.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 +.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 +.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 \ +.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 +.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 +.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..7b9e2de --- /dev/null +++ b/doc/man/man3/ldap_bind.3 @@ -0,0 +1,334 @@ +.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 +.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. +.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 +.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 +.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_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 +.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 +.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 +.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 +. + +.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 +.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 +.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 +.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 +.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 +.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 +.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..b98ad60 --- /dev/null +++ b/doc/man/man3/ldap_get_option.3 @@ -0,0 +1,932 @@ +.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 +.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= , +.BR maxssf= , +.BR 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 directory containing CA certificates. +.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 ":" +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 + +.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 +.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 +.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 . +.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 +.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 +.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 +.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 +.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 +.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 +.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 +.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 +.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 +.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 +#include +.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 +#include +.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 . +.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 +.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 +.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 +.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" " " +.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 . +## +## Copyright 1998-2022 The OpenLDAP Foundation. +## All rights reserved. +## +## Redistribution and use in source and binary forms, with or without +## modification, are permitted only as authorized by the OpenLDAP +## Public License. +## +## A copy of this license is available in the file LICENSE in the +## top-level directory of the distribution or, alternatively, at +## . + +MANSECT=5 diff --git a/doc/man/man5/ldap.conf.5 b/doc/man/man5/ldap.conf.5 new file mode 100644 index 0000000..df357ab --- /dev/null +++ b/doc/man/man5/ldap.conf.5 @@ -0,0 +1,529 @@ +.TH LDAP.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap.conf, .ldaprc \- LDAP configuration file/environment variables +.SH SYNOPSIS +ETCDIR/ldap.conf, ldaprc, .ldaprc, $LDAP +.SH DESCRIPTION +If the environment variable \fBLDAPNOINIT\fP is defined, all +defaulting is disabled. +.LP +The +.I ldap.conf +configuration file is used to set system-wide defaults to be applied when +running +.I ldap +clients. +.LP +Users may create an optional configuration file, +.I ldaprc +or +.IR .ldaprc , +in their home directory which will be used to override the system-wide +defaults file. +The file +.I ldaprc +in the current working directory is also used. +.LP +.LP +Additional configuration files can be specified using +the \fBLDAPCONF\fP and \fBLDAPRC\fP environment variables. +\fBLDAPCONF\fP may be set to the path of a configuration file. This +path can be absolute or relative to the current working directory. +The \fBLDAPRC\fP, if defined, should be the basename of a file +in the current working directory or in the user's home directory. +.LP +Environmental variables may also be used to augment the file based defaults. +The name of the variable is the option name with an added prefix of \fBLDAP\fP. +For example, to define \fBBASE\fP via the environment, set the variable +\fBLDAPBASE\fP to the desired value. +.LP +Some options are user-only. Such options are ignored if present +in the +.I ldap.conf +(or file specified by +.BR LDAPCONF ). +.LP +Thus the following files and variables are read, in order: +.nf + variable $LDAPNOINIT, and if that is not set: + system file ETCDIR/ldap.conf, + user files $HOME/ldaprc, $HOME/.ldaprc, ./ldaprc, + system file $LDAPCONF, + user files $HOME/$LDAPRC, $HOME/.$LDAPRC, ./$LDAPRC, + variables $LDAP. +.fi +Settings late in the list override earlier ones. +.SH SYNTAX +The configuration options are case-insensitive; +their value, on a case by case basis, may be case-sensitive. +.LP +Blank lines are ignored. +.br +Lines beginning with a hash mark (`#') are comments, and ignored. +.LP +Valid lines are made of an option's name (a sequence of non-blanks, +conventionally written in uppercase, although not required), +followed by a value. +The value starts with the first non-blank character after +the option's name, and terminates at the end of the line, +or at the last sequence of blanks before the end of the line. +The tokenization of the value, if any, is delegated to the handler(s) +for that option, if any. Quoting values that contain blanks +may be incorrect, as the quotes would become part of the value. +For example, + +.nf + # Wrong - erroneous quotes: + URI "ldap:// ldaps://" + + # Right - space-separated list of URIs, without quotes: + URI ldap:// ldaps:// + + # Right - DN syntax needs quoting for Example, Inc: + BASE ou=IT staff,o="Example, Inc",c=US + # or: + BASE ou=IT staff,o=Example\\2C Inc,c=US + + # Wrong - comment on same line as option: + DEREF never # Never follow aliases +.fi +.LP +A line cannot be longer than LINE_MAX, which should be more than 2000 bytes +on all platforms. +There is no mechanism to split a long line on multiple lines, either for +beautification or to overcome the above limit. +.SH OPTIONS +The different configuration options are: +.TP +.B URI +Specifies the URI(s) of an LDAP server(s) to which the +.I LDAP +library should connect. The URI scheme may be any of +.BR ldap , +.B ldaps +or +.BR ldapi , +which refer to LDAP over TCP, LDAP over SSL (TLS) and LDAP +over IPC (UNIX domain sockets), respectively. +Each server's name can be specified as a +domain-style name or an IP address literal. Optionally, the +server's name can followed by a ':' and the port number the LDAP +server is listening on. If no port number is provided, the default +port for the scheme is used (389 for ldap://, 636 for ldaps://). +For LDAP over IPC, +.B name +is the name of the socket, and no +.B port +is required, nor allowed; note that directory separators must be +URL-encoded, like any other characters that are special to URLs; +so the socket + + /usr/local/var/ldapi + +must be specified as + + ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi + +A space separated list of URIs may be provided. +.TP +.B BASE +Specifies the default base DN to use when performing ldap operations. +The base must be specified as a Distinguished Name in LDAP format. +.TP +.B BINDDN +Specifies the default bind DN to use when performing ldap operations. +The bind DN must be specified as a Distinguished Name in LDAP format. +.B This is a user-only option. +.TP +.B DEREF +Specifies how alias dereferencing is done when performing a search. The +.B +can be specified as one of the following keywords: +.RS +.TP +.B never +Aliases are never dereferenced. This is the default. +.TP +.B searching +Aliases are dereferenced in subordinates of the base object, but +not in locating the base object of the search. +.TP +.B finding +Aliases are only dereferenced when locating the base object of the search. +.TP +.B always +Aliases are dereferenced both in searching and in locating the base object +of the search. +.RE +.TP +.TP +.B HOST +Specifies the name(s) of an LDAP server(s) to which the +.I LDAP +library should connect. Each server's name can be specified as a +domain-style name or an IP address and optionally followed by a ':' and +the port number the ldap server is listening on. A space separated +list of hosts may be provided. +.B HOST +is deprecated in favor of +.BR URI . +.TP +.B KEEPALIVE_IDLE +Sets/gets the number of seconds a connection needs to remain idle +before TCP starts sending keepalive probes. Linux only. +.TP +.B KEEPALIVE_PROBES +Sets/gets the maximum number of keepalive probes TCP should send +before dropping the connection. Linux only. +.TP +.B KEEPALIVE_INTERVAL +Sets/gets the interval in seconds between individual keepalive probes. +Linux only. +.TP +.B NETWORK_TIMEOUT +Specifies the timeout (in seconds) after which the poll(2)/select(2) +following a connect(2) returns in case of no activity. +.TP +.B PORT +Specifies the default port used when connecting to LDAP servers(s). +The port may be specified as a number. +.B PORT +is deprecated in favor of +.BR URI. +.TP +.B REFERRALS +Specifies if the client should automatically follow referrals returned +by LDAP servers. +The default is on. +Note that the command line tools +.BR ldapsearch (1) +&co always override this option. +.\" This should only be allowed via ldap_set_option(3) +.\".TP +.\".B RESTART +.\"Determines whether the library should implicitly restart connections (FIXME). +.TP +.B SIZELIMIT +Specifies a size limit (number of entries) to use when performing searches. +The number should be a non-negative integer. \fISIZELIMIT\fP of zero (0) +specifies a request for unlimited search size. Please note that the server +may still apply any server-side limit on the amount of entries that can be +returned by a search operation. +.TP +.B SOCKET_BIND_ADDRESSES +Specifies the source bind IP to be used for connecting to target LDAP server. +Multiple IP addresses must be space separated. Only one valid IPv4 +address and/or one valid IPv6 address are allowed in the list. +.TP +.B TIMELIMIT +Specifies a time limit (in seconds) to use when performing searches. +The number should be a non-negative integer. \fITIMELIMIT\fP of zero (0) +specifies unlimited search time to be used. Please note that the server +may still apply any server-side limit on the duration of a search operation. +.TP +.B VERSION {2|3} +Specifies what version of the LDAP protocol should be used. +.TP +.B TIMEOUT +Specifies a timeout (in seconds) after which calls to synchronous LDAP +APIs will abort if no response is received. Also used for any +.BR ldap_result (3) +calls where a NULL timeout parameter is supplied. +.SH SASL OPTIONS +If OpenLDAP is built with Simple Authentication and Security Layer support, +there are more options you can specify. +.TP +.B SASL_MECH +Specifies the SASL mechanism to use. +.TP +.B SASL_REALM +Specifies the SASL realm. +.TP +.B SASL_AUTHCID +Specifies the authentication identity. +.B This is a user-only option. +.TP +.B SASL_AUTHZID +Specifies the proxy authorization identity. +.B This is a user-only option. +.TP +.B SASL_SECPROPS +Specifies Cyrus SASL security properties. The +.B +can be specified as a comma-separated list of the following: +.RS +.TP +.B none +(without any other properties) causes the properties +defaults ("noanonymous,noplain") to be cleared. +.TP +.B noplain +disables mechanisms susceptible to simple passive attacks. +.TP +.B noactive +disables mechanisms susceptible to active attacks. +.TP +.B nodict +disables mechanisms susceptible to passive dictionary attacks. +.TP +.B noanonymous +disables mechanisms which support anonymous login. +.TP +.B forwardsec +requires forward secrecy between sessions. +.TP +.B passcred +requires mechanisms which pass client credentials (and allows +mechanisms which can pass credentials to do so). +.TP +.B minssf= +specifies the minimum acceptable +.I security strength factor +as an integer approximate to effective key length used for +encryption. 0 (zero) implies no protection, 1 implies integrity +protection only, 128 allows RC4, Blowfish and other similar ciphers, +256 will require modern ciphers. The default is 0. +.TP +.B maxssf= +specifies the maximum acceptable +.I security strength factor +as an integer (see +.B minssf +description). The default is +.BR INT_MAX . +.TP +.B maxbufsize= +specifies the maximum security layer receive buffer +size allowed. 0 disables security layers. The default is 65536. +.RE +.TP +.B SASL_NOCANON +Do not perform reverse DNS lookups to canonicalize SASL host names. The default is off. +.TP +.B SASL_CBINDING +The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING. The default is none. +.SH GSSAPI OPTIONS +If OpenLDAP is built with Generic Security Services Application Programming Interface support, +there are more options you can specify. +.TP +.B GSSAPI_SIGN +Specifies if GSSAPI signing (GSS_C_INTEG_FLAG) should be used. +The default is off. +.TP +.B GSSAPI_ENCRYPT +Specifies if GSSAPI encryption (GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG) +should be used. The default is off. +.TP +.B GSSAPI_ALLOW_REMOTE_PRINCIPAL +Specifies if GSSAPI based authentication should try to form the +target principal name out of the ldapServiceName or dnsHostName +attribute of the targets RootDSE entry. The default is off. +.SH TLS OPTIONS +If OpenLDAP is built with Transport Layer Security support, there +are more options you can specify. These options are used when an +.B ldaps:// URI +is selected (by default or otherwise) or when the application +negotiates TLS by issuing the LDAP StartTLS operation. +.TP +.B TLS_CACERT +Specifies the file that contains certificates for all of the Certificate +Authorities the client will recognize. +.TP +.B TLS_CACERTDIR +Specifies the path of a directory that contains Certificate Authority +certificates in separate individual files. The +.B TLS_CACERT +is always used before +.B TLS_CACERTDIR. +.TP +.B TLS_CERT +Specifies the file that contains the client certificate. +.B This is a user-only option. +.TP +.B TLS_ECNAME +Specify the name of the curve(s) to use for Elliptic curve Diffie-Hellman +ephemeral key exchange. This option is only used for OpenSSL. +This option is not used with GnuTLS; the curves may be +chosen in the GnuTLS ciphersuite specification. +.TP +.B TLS_KEY +Specifies the file that contains the private key that matches the certificate +stored in the +.B TLS_CERT +file. Currently, the private key must not be protected with a password, so +it is of critical importance that the key file is protected carefully. +.B This is a user-only option. +.TP +.B TLS_CIPHER_SUITE +Specifies acceptable cipher suite and preference order. + should be a cipher specification for +the TLS library in use (OpenSSL or GnuTLS). +Example: +.RS +.RS +.TP +.I OpenSSL: +TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv2 +.TP +.I GnuTLS: +TLS_CIPHER_SUITE SECURE256:!AES-128-CBC +.RE + +To check what ciphers a given spec selects in OpenSSL, use: + +.nf + openssl ciphers \-v +.fi + +With GnuTLS the available specs can be found in the manual page of +.BR gnutls\-cli (1) +(see the description of the +option +.BR \-\-priority ). + +In older versions of GnuTLS, where gnutls\-cli does not support the option +\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling: + +.nf + gnutls\-cli \-l +.fi +.RE +.TP +.B TLS_PROTOCOL_MIN [.] +Specifies minimum SSL/TLS protocol version that will be negotiated. +If the server doesn't support at least that version, +the SSL handshake will fail. +To require TLS 1.x or higher, set this option to 3.(x+1), +e.g., + +.nf + TLS_PROTOCOL_MIN 3.2 +.fi + +would require TLS 1.1. +Specifying a minimum that is higher than that supported by the +OpenLDAP implementation will result in it requiring the +highest level that it does support. +This parameter is ignored with GnuTLS. +.TP +.B TLS_RANDFILE +Specifies the file to obtain random bits from when /dev/[u]random is +not available. Generally set to the name of the EGD/PRNGD socket. +The environment variable RANDFILE can also be used to specify the filename. +This parameter is ignored with GnuTLS. +.TP +.B TLS_REQCERT +Specifies what checks to perform on server certificates in a TLS session. +The +.B +can be specified as one of the following keywords: +.RS +.TP +.B never +The client will not request or check any server certificate. +.TP +.B allow +The server certificate is requested. If a bad certificate is provided, it will +be ignored and the session proceeds normally. +.TP +.B try +The server certificate is requested. If a bad certificate is provided, +the session is immediately terminated. +.TP +.B demand | hard +These keywords are equivalent and the same as +.BR try . +This is the default setting. +.RE +.TP +.B TLS_REQSAN +Specifies what checks to perform on the subjectAlternativeName +(SAN) extensions in a server certificate when validating the certificate +name against the specified hostname of the server. The +.B +can be specified as one of the following keywords: +.RS +.TP +.B never +The client will not check any SAN in the certificate. +.TP +.B allow +The SAN is checked against the specified hostname. If a SAN is +present but none match the specified hostname, the SANs are ignored +and the usual check against the certificate DN is used. +This is the default setting. +.TP +.B try +The SAN is checked against the specified hostname. If no SAN is present +in the server certificate, the usual check against the certificate DN +is used. If a SAN is present but doesn't match the specified hostname, +the session is immediately terminated. This setting may be preferred +when a mix of certs with and without SANs are in use. +.TP +.B demand | hard +These keywords are equivalent. The SAN is checked against the specified +hostname. If no SAN is present in the server certificate, or no SANs +match, the session is immediately terminated. This setting should be +used when only certificates with SANs are in use. +.RE +.TP +.B TLS_CRLCHECK +Specifies if the Certificate Revocation List (CRL) of the CA should be +used to verify if the server certificates have not been revoked. This +requires +.B TLS_CACERTDIR +parameter to be set. This parameter is ignored with GnuTLS. +.B +can be specified as one of the following keywords: +.RS +.TP +.B none +No CRL checks are performed +.TP +.B peer +Check the CRL of the peer certificate +.TP +.B all +Check the CRL for a whole certificate chain +.RE +.TP +.B TLS_CRLFILE +Specifies the file containing a Certificate Revocation List to be used +to verify if the server certificates have not been revoked. This +parameter is only supported with GnuTLS. +.SH "ENVIRONMENT VARIABLES" +.TP +LDAPNOINIT +disable all defaulting +.TP +LDAPCONF +path of a configuration file +.TP +LDAPRC +basename of ldaprc file in $HOME or $CWD +.TP +LDAP +Set as from ldap.conf +.SH FILES +.TP +.I ETCDIR/ldap.conf +system-wide ldap configuration file +.TP +.I $HOME/ldaprc, $HOME/.ldaprc +user ldap configuration file +.TP +.I $CWD/ldaprc +local ldap configuration file +.SH "SEE ALSO" +.BR ldap (3), +.BR ldap_set_option (3), +.BR ldap_result (3), +.BR openssl (1), +.BR sasl (3) +.SH AUTHOR +Kurt Zeilenga, The OpenLDAP Project +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/ldif.5 b/doc/man/man5/ldif.5 new file mode 100644 index 0000000..d3fa232 --- /dev/null +++ b/doc/man/man5/ldif.5 @@ -0,0 +1,277 @@ +.TH LDIF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldif \- LDAP Data Interchange Format +.SH DESCRIPTION +The LDAP Data Interchange Format (LDIF) is used to represent LDAP +entries and change records in text form. LDAP tools, such as +.BR ldapadd (1) +and +.BR ldapsearch (1), +read and write LDIF entry +records. +.BR ldapmodify (1) +reads LDIF change records. +.LP +This manual page provides a basic description of LDIF. A +formal specification of LDIF is published in RFC 2849. +.SH ENTRY RECORDS +.LP +LDIF entry records are used to represent directory entries. The basic +form of an entry record is: +.LP +.nf +.ft tt + dn: + : + : + :: + :< + ... +.ft +.fi +.LP +The value may be specified as UTF-8 text or as base64 encoded data, +or a URI may be provided to the location of the attribute value. +.LP +A line may be continued by starting the next line with a single space +or tab, e.g., +.LP +.nf +.ft tt + dn: cn=Barbara J Jensen,dc=exam + ple,dc=com +.ft +.fi +.LP +Lines beginning with a sharp sign ('#') are ignored. +.LP +Multiple attribute values are specified on separate lines, e.g., +.LP +.nf +.ft tt + cn: Barbara J Jensen + cn: Babs Jensen +.ft +.fi +.LP +If an value contains a non-printing character, or begins +with a space or a colon ':', the is followed by a +double colon and the value is encoded in base 64 notation. e.g., +the value " begins with a space" would be encoded like this: +.LP +.nf +.ft tt + cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U= +.ft +.fi +.LP +If the attribute value is located in a file, the is +followed by a ':<' and a file: URI. e.g., the value contained +in the file /tmp/value would be listed like this: +.LP +.nf +.ft tt + cn:< file:///tmp/value +.ft +.fi +Other URI schemes (ftp,http) may be supported as well. +.LP +Multiple entries within the same LDIF file are separated by blank +lines. +.SH ENTRY RECORD EXAMPLE +Here is an example of an LDIF file containing three entries. +.LP +.nf +.ft tt + dn: cn=Barbara J Jensen,dc=example,dc=com + cn: Barbara J Jensen + cn: Babs Jensen + objectclass: person + description:< file:///tmp/babs + sn: Jensen + + dn: cn=Bjorn J Jensen,dc=example,dc=com + cn: Bjorn J Jensen + cn: Bjorn Jensen + objectclass: person + sn: Jensen + + dn: cn=Jennifer J Jensen,dc=example,dc=com + cn: Jennifer J Jensen + cn: Jennifer Jensen + objectclass: person + sn: Jensen + jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD + A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ + ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG + ... +.ft +.fi +.LP +Note that the description in Barbara Jensen's entry is +read from file:///tmp/babs and the jpegPhoto in Jennifer +Jensen's entry is encoded using base 64. +.SH CHANGE RECORDS +LDIF change records are used to represent directory change requests. +Each change record starts with line indicating the distinguished +name of the entry being changed: +.LP +.nf + dn: +.fi +.LP +.nf + changetype: <[modify|add|delete|modrdn]> +.fi +.LP +Finally, the change information itself is given, the format of which +depends on what kind of change was specified above. For a \fIchangetype\fP +of \fImodify\fP, the format is one or more of the following: +.LP +.nf + add: + : + : + ... + \- +.fi +.LP +Or, for a replace modification: +.LP +.nf + replace: + : + : + ... + \- +.fi +.LP +If no \fIattributetype\fP lines are given to replace, +the entire attribute is to be deleted (if present). +.LP +Or, for a delete modification: +.LP +.nf + delete: + : + : + ... + \- +.fi +.LP +If no \fIattributetype\fP lines are given to delete, +the entire attribute is to be deleted. +.LP +For a \fIchangetype\fP of \fIadd\fP, the format is: +.LP +.nf + : + : + ... + : + : +.fi +.LP +For a \fIchangetype\fP of \fImodrdn\fP or \fImoddn\fP, +the format is: +.LP +.nf + newrdn: + deleteoldrdn: 0 | 1 + newsuperior: +.fi +.LP +where a value of 1 for deleteoldrdn means to delete the values +forming the old rdn from the entry, and a value of 0 means to +leave the values as non-distinguished attributes in the entry. +The newsuperior line is optional and, if present, specifies the +new superior to move the entry to. +.LP +For a \fIchangetype\fP of \fIdelete\fP, no additional information +is needed in the record. +.LP +Note that attribute values may be presented using base64 or in +files as described for entry records. Lines in change records +may be continued in the manner described for entry records as +well. +.SH CHANGE RECORD EXAMPLE +The following sample LDIF file contains a change record +of each type of change. +.LP +.nf + dn: cn=Babs Jensen,dc=example,dc=com + changetype: add + objectclass: person + objectclass: extensibleObject + cn: babs + cn: babs jensen + sn: jensen + + dn: cn=Babs Jensen,dc=example,dc=com + changetype: modify + add: givenName + givenName: Barbara + givenName: babs + \- + replace: description + description: the fabulous babs + \- + delete: sn + sn: jensen + \- + + dn: cn=Babs Jensen,dc=example,dc=com + changetype: modrdn + newrdn: cn=Barbara J Jensen + deleteoldrdn: 0 + newsuperior: ou=People,dc=example,dc=com + + dn: cn=Barbara J Jensen,ou=People,dc=example,dc=com + changetype: delete +.fi + +.SH INCLUDE STATEMENT +The LDIF parser has been extended to support an +.B include +statement for referencing other LDIF files. The +.B include +statement must be separated from other records by a blank line. +The referenced file is specified using a file: URI and all of its +contents are incorporated as if they were part of the original +LDIF file. As above, other URI schemes may be supported. For example: +.LP +.nf + dn: dc=example,dc=com + objectclass: domain + dc: example + + include: file:///tmp/example.com.ldif + + dn: dc=example,dc=org + objectclass: domain + dc: example +.fi +This feature is not part of the LDIF specification in RFC 2849 but +is expected to appear in a future revision of this spec. It is supported +by the +.BR ldapadd (1), +.BR ldapmodify (1), +and +.BR slapadd (8) +commands. + +.SH SEE ALSO +.BR ldap (3), +.BR ldapsearch (1), +.BR ldapadd (1), +.BR ldapmodify (1), +.BR slapadd (8), +.BR slapcat (8), +.BR slapd\-ldif (5). +.LP +"LDAP Data Interchange Format," Good, G., RFC 2849. +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/lloadd.conf.5 b/doc/man/man5/lloadd.conf.5 new file mode 100644 index 0000000..53f50ba --- /dev/null +++ b/doc/man/man5/lloadd.conf.5 @@ -0,0 +1,848 @@ +.TH LLOADD.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +lloadd.conf \- configuration file for lloadd, the stand-alone LDAP daemon +.SH SYNOPSIS +ETCDIR/lloadd.conf +.SH DESCRIPTION +The file +.B ETCDIR/lloadd.conf +contains configuration information for the +.BR lloadd (8) daemon. +.LP +The +.B lloadd.conf +file consists of a series of global configuration options that apply to +.B lloadd +as a whole (including all backends), followed by zero or more +backend definitions that contain information specific how a backend +instance should be contacted. +The configuration options are case-insensitive; +their value, on a case by case basis, may be case-sensitive. +.LP +The general format of +.B lloadd.conf +is as follows: +.LP +.nf + # comment - these options apply to the server as a whole + + # first backend definition + backend-server + # subsequent backend definitions + ... +.fi +.LP +As many backend servers may be configured as desired. +.LP +If a line begins with white space, it is considered a continuation +of the previous line. No physical line should be over 2000 bytes +long. +.LP +Blank lines and comment lines beginning with +a `#' character are ignored. Note: continuation lines are unwrapped +before comment processing is applied. +.LP +Arguments on configuration lines are separated by white space. If an +argument contains white space, the argument should be enclosed in +double quotes. If an argument contains a double quote (`"') or a +backslash character (`\\'), the character should be preceded by a +backslash character. +.LP +The specific configuration options available are discussed below in the +Global Configuration Options and General Backend Options. +Refer to the "OpenLDAP Administrator's Guide" for more +details on the lloadd configuration file. + +.SH SLAPD INTEGRATION +Note that when +.B lloadd +is configured as a +.B slapd +module, any option that shares the same name as an option in +.BR slapd.conf (5), +the +.B slapd +interpretation wins and the +.B lloadd +option mentioned is unavailable through +.BR slapd.conf (5) +directly, instead, it would have to be configured via a dedicated attribute in +cn=config. In particular, unless the +.B TLSShareSlapdCTX +option is set, +.B lloadd +keeps its own TLS context which cannot be configured except +through the dynamic configuration. + +An additional option is available when running as a +.B slapd +module: +.TP +.B listen "" +The URIs the Load Balancer module should listen on. Must not overlap with the +ones that +.B slapd +uses for its own listening sockets. The related +.B cn=config +attribute is +.B olcBkLloadListen +with each URI provided as a separate value. No changes to this attribute made +after the server has started up will take effect until it is restarted. + +.SH GLOBAL CONFIGURATION OPTIONS +Options described in this section apply to all backends. Arguments that should +be replaced by actual text are shown in brackets <>. +.TP +.B argsfile +The (absolute) name of a file that will hold the +.B lloadd +server's command line (program name and options). +.TP +.B concurrency +Specify a desired level of concurrency. Provided to the underlying +thread system as a hint. The default is not to provide any hint. +.\" .TP +.\" .B gentlehup { on | off } +.\" A SIGHUP signal will only cause a 'gentle' shutdown-attempt: +.\" .B Lloadd +.\" will stop listening for new connections, but will not close the +.\" connections to the current clients. Future write operations return +.\" unwilling-to-perform, though. Lloadd terminates when all clients +.\" have closed their connections (if they ever do), or - as before - +.\" if it receives a SIGTERM signal. This can be useful if you wish to +.\" terminate the server and start a new +.\" .B lloadd +.\" server +.\" .B with another database, +.\" without disrupting the currently active clients. +.\" The default is off. You may wish to use +.\" .B idletimeout +.\" along with this option. +.\" .TP +.\" .B idletimeout +.\" Specify the number of seconds to wait before forcibly closing +.\" an idle client connection. A idletimeout of 0 disables this +.\" feature. The default is 0. You may also want to set the +.\" .B iotimeout +.\" option. +.TP +.B feature [...] +Switch additional features supported by the LDAP Load Balancer on. +Supported features are: +.RS +.RS +.PD 0 +.TP +.B proxyauthz +when proxying an operation, pass the client's authorized identity using +the proxy authorization control (RFC 4370). No control is added to the +operation if initiated by a client whose bound identity matches the identity +configured in +.B bindconf +(no normalisation of the DN is attempted). + +If SASL binds are issued by clients and this feature is enabled, backend +servers need to support LDAP Who Am I? extended operation for the Load Balancer +to detect the correct authorization identity. +.\" .TP +.\" .B vc +.\" when receiving a bind operation from a client, pass it onto a backend +.\" as a verify credentials external operation request. With this enabled, +.\" the +.\" .BR backend 's +.\" .B bindconns +.\" option has no effect as there is no need to maintain dedicated bind +.\" connections anymore. +.PD +.RE +.RE +.TP +.B include +Read additional configuration information from the given file before +continuing with the next line of the current file. +.TP +.B io-threads +Specify the number of threads to use for the connection manager. +The default is 1 and this is typically adequate for up to 16 CPU cores. +The value should be set to a power of 2. + +If modified after server starts up, a change to this option will not take +effect until the server has been restarted. +.TP +.B logfile +Specify a file for recording lloadd debug messages. By default these messages +only go to stderr, are not recorded anywhere else, and are unrelated to +messages exposed by the +.B loglevel +configuration parameter. Specifying a logfile copies messages to both stderr +and the logfile. +.TP +.B loglevel [...] +Specify the level at which debugging statements and operation +statistics should be syslogged (currently logged to the +.BR syslogd (8) +LOG_LOCAL4 facility). +They must be considered subsystems rather than increasingly verbose +log levels. +Some messages with higher priority are logged regardless +of the configured loglevel as soon as any logging is configured. +Log levels are additive, and available levels are: +.RS +.RS +.PD 0 +.TP +.B 1 +.B (0x1 trace) +trace function calls +.TP +.B 2 +.B (0x2 packets) +debug packet handling +.TP +.B 4 +.B (0x4 args) +heavy trace debugging (function args) +.TP +.B 8 +.B (0x8 conns) +connection management +.TP +.B 16 +.B (0x10 BER) +print out packets sent and received +.\" .TP +.\" .B 32 +.\" .B (0x20 filter) +.\" search filter processing +.TP +.B 64 +.B (0x40 config) +configuration file processing +.\" .TP +.\" .B 128 +.\" .B (0x80 ACL) +.\" access control list processing +.TP +.B 256 +.B (0x100 stats) +connections, LDAP operations, results (recommended) +.TP +.B 512 +.B (0x200 stats2) +stats log entries sent +.\" .TP +.\" .B 1024 +.\" .B (0x400 shell) +.\" print communication with shell backends +.\" .TP +.\" .B 2048 +.\" .B (0x800 parse) +.\" entry parsing +\".TP +\".B 4096 +\".B (0x1000 cache) +\"caching (unused) +\".TP +\".B 8192 +\".B (0x2000 index) +\"data indexing (unused) +.\" .TP +.\" .B 16384 +.\" .B (0x4000 sync) +.\" LDAPSync replication +.TP +.B 32768 +.B (0x8000 none) +only messages that get logged whatever log level is set +.PD +.RE +The desired log level can be input as a single integer that combines +the (ORed) desired levels, both in decimal or in hexadecimal notation, +as a list of integers (that are ORed internally), +or as a list of the names that are shown between parentheses, such that +.LP +.nf + loglevel 513 + loglevel 0x201 + loglevel 512 1 + loglevel 0x200 0x1 + loglevel stats trace +.fi +.LP +are equivalent. +The keyword +.B any +can be used as a shortcut to enable logging at all levels (equivalent to \-1). +The keyword +.BR none , +or the equivalent integer representation, causes those messages +that are logged regardless of the configured loglevel to be logged. +In fact, if loglevel is set to 0, no logging occurs, +so at least the +.B none +level is required to have high priority messages logged. + +The loglevel defaults to \fBstats\fP. +This level should usually also be included when using other loglevels, to +help analyze the logs. +.RE +.TP +.B pidfile +The (absolute) name of a file that will hold the +.B lloadd +server's process ID (see +.BR getpid (2)). +.TP +.B sockbuf_max_incoming_client +Specify the maximum LDAP PDU size accepted coming from clients. +The default is 262143. +.TP +.B sockbuf_max_incoming_upstream +Specify the maximum LDAP PDU size accepted coming from upstream +connections. +The default is 4194303. +.TP +.B tcp-buffer [listener=] [{read|write}=] +Specify the size of the TCP buffer. +A global value for both read and write TCP buffers related to any listener +is defined, unless the listener is explicitly specified, +or either the read or write qualifiers are used. +See +.BR tcp (7) +for details. +Note that some OS-es implement automatic TCP buffer tuning. +.TP +.B threads +Specify the maximum size of the primary thread pool. +The default is 16; the minimum value is 2. +.TP +.B threadqueues +Specify the number of work queues to use for the primary thread pool. +The default is 1 and this is typically adequate for up to 8 CPU cores. +The value should not exceed the number of CPUs in the system. +.TP +.B max_pdus_per_cycle +If set to 0, PDUs are handled by the I/O threads directly, otherwise +a task is queued to be picked up by the thread pool. This task will +process PDUs from the connection until there is no more data to be +read or this limit is reached when the I/O thread can pick it up again. +Very high values have a potential to cause some connections to be +starved in a very high-bandwidth environment. The default is 1000. +.TP +.B client_max_pending +Will cause the load balancer to limit the number unfinished operations for each +client connection. The default is 0, unlimited. +.TP +.B iotimeout +Specify the number of milliseconds to wait before forcibly closing +a connection with an outstanding write. This allows faster recovery from +various network hang conditions. An iotimeout of 0 disables this feature. +The default is 10000. + +.SH TLS OPTIONS +If +.B lloadd +is built with support for Transport Layer Security, there are more options +you can specify. + +.TP +.B TLSShareSlapdCTX { on | off } +If set to no (the default), +.B lloadd +will use its own TLS context (needs to be configured via +.B cn=config +unless +.B lloadd +is run as a standalone daemon). If enabled, the options for +.B slapd +apply instead, since the +.BR slapd 's +TLS context is used then. + +.LP + +The following options are available only when compiled as a standalone daemon. +When compiled as a +.BR slapd (8) +module, the cn=config equivalents need to be used if a separate TLS context for +the module is needed, otherwise use the +.B TLSShareSlapdCTX +option. + +.TP +.B TLSCipherSuite +Permits configuring what ciphers will be accepted and the preference order. + should be a cipher specification for the TLS library +in use (OpenSSL, GnuTLS, or Mozilla NSS). +Example: +.RS +.RS +.TP +.I OpenSSL: +TLSCipherSuite HIGH:MEDIUM:+SSLv2 +.TP +.I GnuTLS: +TLSCiphersuite SECURE256:!AES-128-CBC +.RE + +To check what ciphers a given spec selects in OpenSSL, use: + +.nf + openssl ciphers \-v +.fi + +With GnuTLS the available specs can be found in the manual page of +.BR gnutls\-cli (1) +(see the description of the +option +.BR \-\-priority ). + +In older versions of GnuTLS, where gnutls\-cli does not support the option +\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling: + +.nf + gnutls\-cli \-l +.fi + +When using Mozilla NSS, the OpenSSL cipher suite specifications are used and +translated into the format used internally by Mozilla NSS. There isn't an easy +way to list the cipher suites from the command line. The authoritative list +is in the source code for Mozilla NSS in the file sslinfo.c in the structure +.nf + static const SSLCipherSuiteInfo suiteInfo[] +.fi +.RE +.TP +.B TLSCACertificateFile +Specifies the file that contains certificates for all of the Certificate +Authorities that +.B lloadd +will recognize. The certificate for +the CA that signed the server certificate must be included among +these certificates. If the signing CA was not a top-level (root) CA, +certificates for the entire sequence of CA's from the signing CA to +the top-level CA should be present. Multiple certificates are simply +appended to the file; the order is not significant. +.TP +.B TLSCACertificatePath +Specifies the path of a directory that contains Certificate Authority +certificates in separate individual files. Usually only one of this +or the TLSCACertificateFile is used. This directive is not supported +when using GnuTLS. + +When using Mozilla NSS, may contain a Mozilla NSS cert/key +database. If contains a Mozilla NSS cert/key database and +CA cert files, OpenLDAP will use the cert/key database and will +ignore the CA cert files. +.TP +.B TLSCertificateFile +Specifies the file that contains the +.B lloadd +server certificate. + +When using Mozilla NSS, if using a cert/key database (specified with +TLSCACertificatePath), TLSCertificateFile specifies +the name of the certificate to use: +.nf + TLSCertificateFile Server-Cert +.fi +If using a token other than the internal built in token, specify the +token name first, followed by a colon: +.nf + TLSCertificateFile my hardware device:Server-Cert +.fi +Use certutil \-L to list the certificates by name: +.nf + certutil \-d /path/to/certdbdir \-L +.fi +.TP +.B TLSCertificateKeyFile +Specifies the file that contains the +.B lloadd +server private key that matches the certificate stored in the +.B TLSCertificateFile +file. Currently, the private key must not be protected with a password, so +it is of critical importance that it is protected carefully. + +When using Mozilla NSS, TLSCertificateKeyFile specifies the name of +a file that contains the password for the key for the certificate specified with +TLSCertificateFile. The modutil command can be used to turn off password +protection for the cert/key database. For example, if TLSCACertificatePath +specifies /etc/openldap/certdb as the location of the cert/key database, use +modutil to change the password to the empty string: +.nf + modutil \-dbdir /etc/openldap/certdb \-changepw 'NSS Certificate DB' +.fi +You must have the old password, if any. Ignore the WARNING about the running +browser. Press 'Enter' for the new password. +.TP +.B TLSDHParamFile +This directive specifies the file that contains parameters for Diffie-Hellman +ephemeral key exchange. This is required in order to use a DSA certificate on +the server, or an RSA certificate missing the "key encipherment" key usage. +Note that setting this option may also enable +Anonymous Diffie-Hellman key exchanges in certain non-default cipher suites. +Anonymous key exchanges should generally be avoided since they provide no +actual client or server authentication and provide no protection against +man-in-the-middle attacks. +You should append "!ADH" to your cipher suites to ensure that these suites +are not used. +When using Mozilla NSS these parameters are always generated randomly +so this directive is ignored. +.TP +.B TLSECName +Specify the name of a curve to use for Elliptic curve Diffie-Hellman +ephemeral key exchange. This is required to enable ECDHE algorithms in +OpenSSL. This option is not used with GnuTLS; the curves may be +chosen in the GnuTLS ciphersuite specification. This option is also +ignored for Mozilla NSS. +.TP +.B TLSProtocolMin [.] +Specifies minimum SSL/TLS protocol version that will be negotiated. +If the server doesn't support at least that version, +the SSL handshake will fail. +To require TLS 1.x or higher, set this option to 3.(x+1), +e.g., + +.nf + TLSProtocolMin 3.2 +.fi + +would require TLS 1.1. +Specifying a minimum that is higher than that supported by the +OpenLDAP implementation will result in it requiring the +highest level that it does support. +This directive is ignored with GnuTLS. +.TP +.B TLSRandFile +Specifies the file to obtain random bits from when /dev/[u]random +is not available. Generally set to the name of the EGD/PRNGD socket. +The environment variable RANDFILE can also be used to specify the filename. +This directive is ignored with GnuTLS and Mozilla NSS. +.TP +.B TLSVerifyClient +Specifies what checks to perform on client certificates in an +incoming TLS session, if any. +The +.B +can be specified as one of the following keywords: +.RS +.TP +.B never +This is the default. +.B lloadd +will not ask the client for a certificate. +.TP +.B allow +The client certificate is requested. If no certificate is provided, +the session proceeds normally. If a bad certificate is provided, +it will be ignored and the session proceeds normally. +.TP +.B try +The client certificate is requested. If no certificate is provided, +the session proceeds normally. If a bad certificate is provided, +the session is immediately terminated. +.TP +.B demand | hard | true +These keywords are all equivalent, for compatibility reasons. +The client certificate is requested. If no certificate is provided, +or a bad certificate is provided, the session is immediately terminated. +.TP +.B TLSCRLCheck +Specifies if the Certificate Revocation List (CRL) of the CA should be +used to verify if the client certificates have not been revoked. This +requires +.B TLSCACertificatePath +parameter to be set. This directive is ignored with GnuTLS and Mozilla NSS. +.B +can be specified as one of the following keywords: +.RS +.TP +.B none +No CRL checks are performed +.TP +.B peer +Check the CRL of the peer certificate +.TP +.B all +Check the CRL for a whole certificate chain +.RE +.TP +.B TLSCRLFile +Specifies a file containing a Certificate Revocation List to be used +for verifying that certificates have not been revoked. This directive is +only valid when using GnuTLS and Mozilla NSS. + +.SH BACKEND CONFIGURATION +Options in this section describe how the +.B lloadd +connects and authenticates to the backend servers. + +It is assumed all backend servers serve the same data. On startup, the +configured connections are set up and those not dedicated to handle bind +requests are authenticated with the backend using the information in the +.B bindconf +option. The authentication configuration is shared between them. +.TP +.B bindconf +.B [bindmethod=simple|sasl] +.B [binddn=] +.B [saslmech=] +.B [authcid=] +.B [authzid=] +.B [credentials=] +.B [realm=] +.B [secprops=] +.B [timeout=] +.B [network\-timeout=] +.B [tcp\-user\-timeout=] + +Specifies the bind credentials +.B lloadd +uses when setting up its regular connections to all backends. + +A +.B bindmethod +of +.B simple +requires the options +.B binddn +and +.B credentials +and should only be used when adequate security services +(e.g. TLS or IPSEC) are in place. +.B REMEMBER: simple bind credentials must be in cleartext! +A +.B bindmethod +of +.B sasl +requires the option +.B saslmech. +Depending on the mechanism, an authentication identity and/or +credentials can be specified using +.B authcid +and +.B credentials. +The +.B authzid +parameter may be used to specify an authorization identity. +Specific security properties (as with the +.B sasl\-secprops +keyword above) for a SASL bind can be set with the +.B secprops +option. A non default SASL realm can be set with the +.B realm +option. + +The +.B timeout +parameter indicates how long an operation can be pending a response (result, +search entry, ...) from the server in seconds. Due to how timeouts are +detected, the timeout might not be detected and handled up to +.B timeout +seconds after it happens. + +The +.B network\-timeout +parameter sets how long the consumer will wait to establish a +network connection to the provider. Once a connection is +established, the +.B timeout +parameter determines how long the consumer will wait for the initial +Bind request to complete. + +Timeout set to 0 means no timeout is in effect and by default, no timeouts are +in effect. + +The +.B tcp\-user\-timeout +parameter, if non-zero, corresponds to the +.B TCP_USER_TIMEOUT +set on the upstream connections, overriding the operating system setting. +Only some systems support the customization of this parameter, it is +ignored otherwise and system-wide settings are used. + +.SH BACKEND OPTIONS + +.TP +.B backend-server +.B uri=ldap[s]://[:port] +.B [retry=] +.B [keepalive=::] +.B [starttls=yes|critical] +.B [tls_cert=] +.B [tls_key=] +.B [tls_cacert=] +.B [tls_cacertdir=] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_cipher_suite=] +.B [tls_crlcheck=none|peer|all] +.B [tls_protocol_min=[.]] +.B [numconns=] +.B [bindconns=] +.B [max-pending-ops=] +.B [conn-max-pending=] + +Marks the beginning of a backend definition. + +.B uri +specifies the backend as an LDAP URI. If is not given, the standard +LDAP port number (389 or 636) is used. + +Lloadd will attempt to maintain +.B numconns +active connections and +.\" unless the +.\" .B vc +.\" feature is enabled, +also +.B bindconns +active connections dedicated to handling client bind requests. + +If an error occurs on a working connection, a new connection attempt is +made immediately, if one happens on establishing a new connection to this +backend, lloadd will wait before a new reconnect attempt is made +according to the +.B retry +parameter (default is 5 seconds). + +Operations will be distributed across the backend's connections +.RB ( upstreams ). + +The parameter +.B conn-max-pending +unless set to +.B 0 +(the default), will limit the number unfinished operations per upstream +connection. Similarly, +.B max-pending-ops +will limit the total number or unfinished operations across all backend's +connections, +.BR 0 , +the default, means no limit will be imposed for this backend. + +The +.B keepalive +parameter sets the values of \fIidle\fP, \fIprobes\fP, and \fIinterval\fP +used to check whether a socket is alive; +.I idle +is the number of seconds a connection needs to remain idle before TCP +starts sending keepalive probes; +.I probes +is the maximum number of keepalive probes TCP should send before dropping +the connection; +.I interval +is interval in seconds between individual keepalive probes. +Only some systems support the customization of these values; +the +.B keepalive +parameter is ignored otherwise, and system-wide settings are used. + +The +.B starttls +parameter specifies use of the StartTLS extended operation +to establish a TLS session before Binding to the provider. If the +.B critical +argument is supplied, the session will be aborted if the StartTLS request +fails. Otherwise the syncrepl session continues without TLS. The +tls_reqcert setting defaults to "demand" and the other TLS settings +default to the same as the main slapd TLS settings. + +.\" .TP +.\" .B readonly on | off +.\" This option puts the backend into "read-only" mode. Only read +.\" operations (i.e. bind, search, compare) will be directed towards this +.\" backend. By default, readonly is off. +.\" .TP +.\" .B restrict +.\" Specify a whitespace separated list of operations that are restricted. +.\" If defined inside a database specification, restrictions apply only +.\" to that database, otherwise they are global. +.\" Operations can be any of +.\" .BR add , +.\" .BR bind , +.\" .BR compare , +.\" .BR delete , +.\" .BR extended[=] , +.\" .BR modify , +.\" .BR rename , +.\" .BR search , +.\" or the special pseudo-operations +.\" .B read +.\" and +.\" .BR write , +.\" which respectively summarize read and write operations. +.\" The use of +.\" .I restrict write +.\" is equivalent to +.\" .I readonly on +.\" (see above). +.\" The +.\" .B extended +.\" keyword allows one to indicate the OID of the specific operation +.\" to be restricted. + +.SH EXAMPLES +.LP +Here is a short example of a configuration file: +.LP +.RS +.nf +argsfile LOCALSTATEDIR/run/lloadd.args +pidfile LOCALSTATEDIR/run/lloadd.pid + +bindconf + bindmethod=simple + binddn=cn=test + credentials=pass + +backend-server + uri=ldap://ldap1.example.com + numconns=3 + bindconns=2 + retry=5000 + max-pending-ops=5 + conn-max-pending=3 + +backend-server + uri=ldap://ldap2.example.com + numconns=3 + bindconns=2 + retry=5000 + max-pending-ops=5 + conn-max-pending=3 +.fi +.RE +.LP +"OpenLDAP Administrator's Guide" contains a longer annotated +example of a configuration file. +The original ETCDIR/lloadd.conf is another example. + +.SH LIMITATIONS +Support for proxying SASL Binds is limited to the +.B EXTERNAL +mechanism (and only to extract the DN of a client TLS cerificate if used during +the last renegotiation) and mechanisms that rely neither on connection metadata +(as Kerberos does) nor establish a SASL integrity/confidentialiy layer (again, +some Kerberos mechanisms, +.B DIGEST-MD5 +can negotiate this). + +.SH FILES +.TP +ETCDIR/lloadd.conf +default lloadd configuration file +.SH SEE ALSO +.BR ldap (3), +.BR gnutls\-cli (1), +.BR slapd.conf (5), +.BR tcp (7), +.BR lloadd (8), +.BR slapd (8). +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/doc/man/man5/slapd-asyncmeta.5 b/doc/man/man5/slapd-asyncmeta.5 new file mode 100644 index 0000000..743d3ef --- /dev/null +++ b/doc/man/man5/slapd-asyncmeta.5 @@ -0,0 +1,532 @@ +.TH SLAPD-ASYNCMETA 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2016-2022 The OpenLDAP Foundation. +.\" Portions Copyright 2016 Symas Corporation. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.\" + +.SH NAME +slapd\-asyncmeta \- asynchronous metadirectory backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B asyncmeta +backend to +.BR slapd (8) +performs basic LDAP proxying with respect to a set of remote LDAP +servers, called "targets". +The information contained in these servers can be presented as +belonging to a single Directory Information Tree (DIT). + +.LP +A good knowledge of the functionality of the +.BR slapd\-meta(5) +backend is recommended. This backend has been designed as +an asynchronous version of the +.B meta +backend. Unlike +.B meta +, the operation handling threads are no longer pending +on the response from the remote server, thus decreasing the +number of threads necessary to handle the same load. While +.B asyncmeta +maintains the functionality of +.B meta +and has a largely similar codebase, +some changes in operation and some new configuration directives have been +added. Some configuration options, such as +.B conn\-pool\-max , +.B conn\-ttl , +.B single\-conn , +and +.B use\-temporary\-conn +have been removed, as they are no longer relevant. +.LP +.B New connection handling: +.LP + +Unlike +.B meta, +which caches bound connections, the +.B asyncmeta +works with a configured maximum number of connections per target. +For each request redirected to a target, a different connection is selected. +Each connection has a queue, to which the request is added before it is sent to the +remote server, and is removed after the last response for that request is received. + For each new request, the connection with the smallest number of pending requests +is selected, or using round\-robin if the numbers are equal. +.LP +.B Overlays: +.LP +Due to implementation specifics, there is no guarantee that any of the existing OpenLDAP overlays will work with +.B asyncmeta +backend. + +.SH EXAMPLES +Refer to +.B slapd\-meta(5) +for configuration examples. + +.SH CONFIGURATION +These +.B slapd.conf +options apply to the ASYNCMETA backend database. +That is, they must follow a "database asyncmeta" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. + +.SH SPECIAL CONFIGURATION DIRECTIVES +Target configuration starts with the "uri" directive. +All the configuration directives that are not specific to targets +should be defined first for clarity, including those that are common +to all backends. +They are: + +.TP +.B default\-target none +This directive forces the backend to reject all those operations +that must resolve to a single target in case none or multiple +targets are selected. +They include: add, delete, modify, modrdn; compare is not included, as +well as bind since, as they don't alter entries, in case of multiple +matches an attempt is made to perform the operation on any candidate +target, with the constraint that at most one must succeed. +This directive can also be used when processing targets to mark a +specific target as default. + +.TP +.B dncache\-ttl {DISABLED|forever|} +This directive sets the time-to-live of the DN cache. +This caches the target that holds a given DN to speed up target +selection in case multiple targets would result from an uncached +search; forever means cache never expires; disabled means no DN +caching; otherwise a valid ( > 0 ) ttl is required, in the format +illustrated for the +.B idle\-timeout +directive. + +.TP +.B onerr {CONTINUE|report|stop} +This directive allows one to select the behavior in case an error is returned +by one target during a search. +The default, \fBcontinue\fP, consists in continuing the operation, +trying to return as much data as possible. +If the value is set to \fBstop\fP, the search is terminated as soon +as an error is returned by one target, and the error is immediately +propagated to the client. +If the value is set to \fBreport\fP, the search is continued to the end +but, in case at least one target returned an error code, the first +non-success error code is returned. + +.TP +.B max\-timeout\-ops +Specify the number of consecutive timed out requests, +after which the connection will be considered faulty and dropped. + +.TP +.B max\-pending\-ops +The maximum number of pending requests stored in a connection's queue. +The default is 128. When this number is exceeded, +.B LDAP_BUSY +will be returned to the client. + +.TP +.B max\-target\-conns +The maximum number of connections per target. Unlike +.B slapd\-meta(5), +no new connections will be created +once this number is reached. The default value is 255. + +.TP +.B norefs +If +.BR yes , +do not return search reference responses. +By default, they are returned unless request is LDAPv2. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B noundeffilter +If +.BR yes , +return success instead of searching if a filter is undefined or contains +undefined portions. +By default, the search is propagated after replacing undefined portions +with +.BR (!(objectClass=*)) , +which corresponds to the empty result set. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B protocol\-version {0,2,3} +This directive indicates what protocol version must be used to contact +the remote server. +If set to 0 (the default), the proxy uses the same protocol version +used by the client, otherwise the requested protocol is used. +The proxy returns \fIunwillingToPerform\fP if an operation that is +incompatible with the requested protocol is attempted. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B pseudoroot\-bind\-defer {YES|no} +This directive, when set to +.BR yes , +causes the authentication to the remote servers with the pseudo-root +identity (the identity defined in each +.B idassert-bind +directive) to be deferred until actually needed by subsequent operations. +Otherwise, all binds as the rootdn are propagated to the targets. + +.TP +.B quarantine ,[;,[...]] +Turns on quarantine of URIs that returned +.IR LDAP_UNAVAILABLE , +so that an attempt to reconnect only occurs at given intervals instead +of any time a client requests an operation. +The pattern is: retry only after at least +.I interval +seconds elapsed since last attempt, for exactly +.I num +times; then use the next pattern. +If +.I num +for the last pattern is "\fB+\fP", it retries forever; otherwise, +no more retries occur. +This directive must appear before any target specification; +it affects all targets with the same pattern. + +.TP +.B rebind\-as\-user {NO|yes} +If this option is given, the client's bind credentials are remembered +for rebinds, when trying to re-establish a broken connection, +or when chasing a referral, if +.B chase\-referrals +is set to +.IR yes . + +.TP +.B session\-tracking\-request {NO|yes} +Adds session tracking control for all requests. +The client's IP and hostname, and the identity associated to each request, +if known, are sent to the remote server for informational purposes. +This directive is incompatible with setting \fIprotocol\-version\fP to 2. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.SH TARGET SPECIFICATION +Target specification starts with a "uri" directive: + +.TP +.B uri ://[]/ [...] +Identical to +.B meta. +See +.B slapd\-meta(5) +for details. + +.TP +.B acl\-authcDN "" +DN which is used to query the target server for acl checking, +as in the LDAP backend; it is supposed to have read access +on the target server to attributes used on the proxy for acl checking. +There is no risk of giving away such values; they are only used to +check permissions. +.B The acl\-authcDN identity is by no means implicitly used by the proxy +.B when the client connects anonymously. + +.TP +.B acl\-passwd +Password used with the +.B acl\-authcDN +above. + +.TP +.B bind\-timeout +This directive defines the timeout, in microseconds, used when polling +for response after an asynchronous bind connection. See +.B slapd\-meta(5) +for details. + +.TP +.B chase\-referrals {YES|no} +enable/disable automatic referral chasing, which is delegated to the +underlying libldap, with rebinding eventually performed if the +\fBrebind\-as\-user\fP directive is used. The default is to chase referrals. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B client\-pr {accept-unsolicited|DISABLE|} +This feature allows one to use RFC 2696 Paged Results control when performing +search operations with a specific target, +irrespective of the client's request. See +.B slapd\-meta(5) +for details. + +.TP +.B default\-target [] +The "default\-target" directive can also be used during target specification. +With no arguments it marks the current target as the default. +The optional number marks target as the default one, starting +from 1. +Target must be defined. + +.TP +.B filter +This directive allows specifying a +.BR regex (5) +pattern to indicate what search filter terms are actually served by a target. + +In a search request, if the search filter matches the \fIpattern\fP +the target is considered while fulfilling the request; otherwise +the target is ignored. There may be multiple occurrences of +the +.B filter +directive for each target. + +.TP +.B idassert\-authzFrom +if defined, selects what +.I local +identities are authorized to exploit the identity assertion feature. +The string +.B +follows the rules defined for the +.I authzFrom +attribute. +See +.BR slapd.conf (5), +section related to +.BR authz\-policy , +for details on the syntax of this field. + +.HP +.hy 0 +.B idassert\-bind +.B bindmethod=none|simple|sasl [binddn=] [credentials=] +.B [saslmech=] [secprops=] [realm=] +.B [authcId=] [authzId=] +.B [authz={native|proxyauthz}] [mode=] [flags=] +.B [starttls=no|yes|critical] +.B [tls_cert=] +.B [tls_key=] +.B [tls_cacert=] +.B [tls_cacertdir=] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=] +.B [tls_ecname=] +.B [tls_protocol_min=[.]] +.B [tls_crlcheck=none|peer|all] +Allows one to define the parameters of the authentication method that is +internally used by the proxy to authorize connections that are +authenticated by other databases. See +.B slapd\-meta(5) +for details. + +.TP +.B idle\-timeout