1.lf 1 stdin 2.TH SLAPD-SOCK 5 "2020/04/28" "OpenLDAP 2.4.50" 3.\" Copyright 2007-2020 The OpenLDAP Foundation All Rights Reserved. 4.\" Copying restrictions apply. See COPYRIGHT/LICENSE. 5.\" $OpenLDAP$ 6.SH NAME 7slapd\-sock \- Socket backend/overlay to slapd 8.SH SYNOPSIS 9/etc/openldap/slapd.conf 10.SH DESCRIPTION 11The Socket backend to 12.BR slapd (8) 13uses an external program to handle queries, similarly to 14.BR slapd\-shell (5). 15However, in this case the external program listens on a Unix domain socket. 16This makes it possible to have a pool of processes, which persist between 17requests. This allows multithreaded operation and a higher level of 18efficiency. The external program must have been started independently; 19.BR slapd (8) 20itself will not start it. 21 22This module may also be used as an overlay on top of some other database. 23Use as an overlay allows external actions to be triggered in response to 24operations on the main database. 25.SH CONFIGURATION 26These 27.B slapd.conf 28options apply to the SOCK backend database. 29That is, they must follow a "database sock" line and come before any 30subsequent "backend" or "database" lines. 31Other database options are described in the 32.BR slapd.conf (5) 33manual page. 34 35Alternatively, to use this module as an overlay, these directives must 36follow an "overlay sock" line within an existing database definition. 37.TP 38.B extensions [ binddn | peername | ssf | connid ]* 39Enables the sending of additional meta-attributes with each request. 40.nf 41binddn: <bound DN> 42peername: IP=<address>:<port> 43ssf: <SSF value> 44connid: <connection ID> 45.fi 46.TP 47.B socketpath <pathname> 48Gives the path to a Unix domain socket to which the commands will 49be sent and from which replies are received. 50 51When used as an overlay, these additional directives are defined: 52.TP 53.B sockops [ bind | unbind | search | compare | modify | modrdn | add | delete | extended ]* 54Specify which request types to send to the external program. The default is 55empty (no requests are sent). 56.TP 57.B sockresps [ result | search ]* 58Specify which response types to send to the external program. "result" 59sends just the results of an operation. "search" sends all entries that 60the database returned for a search request. The default is empty 61(no responses are sent). 62.TP 63.B sockdnpat <regexp> 64Specify DN patterns for which the overlay will act. Only operations on 65DNs matching the specified regular expression will be processed. The default 66is empty (all DNs are processed). 67 68.SH PROTOCOL 69The protocol is essentially the same as 70.BR slapd\-shell (5) 71with the addition of a newline to terminate the command parameters. The 72following commands are sent: 73.RS 74.nf 75ADD 76msgid: <message id> 77<repeat { "suffix:" <database suffix DN> }> 78<entry in LDIF format> 79<blank line> 80.fi 81.RE 82.PP 83.RS 84.nf 85BIND 86msgid: <message id> 87<repeat { "suffix:" <database suffix DN> }> 88dn: <DN> 89method: <method number> 90credlen: <length of <credentials>> 91cred: <credentials> 92<blank line> 93.fi 94.RE 95.PP 96.RS 97.nf 98COMPARE 99msgid: <message id> 100<repeat { "suffix:" <database suffix DN> }> 101dn: <DN> 102<attribute>: <value> 103<blank line> 104.fi 105.RE 106.PP 107.RS 108.nf 109DELETE 110msgid: <message id> 111<repeat { "suffix:" <database suffix DN> }> 112dn: <DN> 113<blank line> 114.fi 115.RE 116.PP 117.RS 118.nf 119EXTENDED 120msgid: <message id> 121<repeat { "suffix:" <database suffix DN> }> 122oid: <OID> 123value: <base64-value> 124<blank line> 125.fi 126.RE 127.PP 128.RS 129.nf 130MODIFY 131msgid: <message id> 132<repeat { "suffix:" <database suffix DN> }> 133dn: <DN> 134<repeat { 135 <"add"/"delete"/"replace">: <attribute> 136 <repeat { <attribute>: <value> }> 137 \- 138}> 139<blank line> 140.fi 141.RE 142.PP 143.RS 144.nf 145MODRDN 146msgid: <message id> 147<repeat { "suffix:" <database suffix DN> }> 148dn: <DN> 149newrdn: <new RDN> 150deleteoldrdn: <0 or 1> 151<if new superior is specified: "newSuperior: <DN>"> 152<blank line> 153.fi 154.RE 155.PP 156.RS 157.nf 158SEARCH 159msgid: <message id> 160<repeat { "suffix:" <database suffix DN> }> 161base: <base DN> 162scope: <0-2, see ldap.h> 163deref: <0-3, see ldap.h> 164sizelimit: <size limit> 165timelimit: <time limit> 166filter: <filter> 167attrsonly: <0 or 1> 168attrs: <"all" or space-separated attribute list> 169<blank line> 170.fi 171.RE 172.PP 173.RS 174.nf 175UNBIND 176msgid: <message id> 177<repeat { "suffix:" <database suffix DN> }> 178<blank line> 179.fi 180.RE 181.LP 182The commands - except \fBunbind\fP - should output: 183.RS 184.nf 185RESULT 186code: <integer> 187matched: <matched DN> 188info: <text> 189.fi 190.RE 191where only RESULT is mandatory, and then close the socket. 192The \fBsearch\fP RESULT should be preceded by the entries in LDIF 193format, each entry followed by a blank line. 194Lines starting with `#' or `DEBUG:' are ignored. 195 196When used as an overlay, the external program should return a 197CONTINUE response if request processing should continue normally, or 198a regular RESULT response if the external program wishes to bypass the 199underlying database. 200 201If the overlay is configured to send response messages to the external 202program, they will appear as an extended RESULT message or as an 203ENTRY message, defined below. The RESULT message is similar to 204the one above, but also includes the msgid and any configured 205extensions: 206.RS 207.nf 208RESULT 209msgid: <message id> 210code: <integer> 211matched: <matched DN> 212info: <text> 213<blank line> 214.fi 215.RE 216 217Typically both the msgid and the connid will be needed to match 218a result message to a request. The ENTRY message has the form 219.RS 220.nf 221ENTRY 222msgid: <message id> 223<entry in LDIF format> 224<blank line> 225.fi 226.RE 227 228.SH KNOWN LIMITATIONS 229The 230.B sock 231backend does not process extended operation results from an external program. 232 233.SH ACCESS CONTROL 234The 235.B sock 236backend does not honor all ACL semantics as described in 237.BR slapd.access (5). 238In general, access to objects is checked by using a dummy object 239that contains only the DN, so access rules that rely on the contents 240of the object are not honored. 241In detail: 242.LP 243The 244.B add 245operation does not require 246.B write (=w) 247access to the 248.B children 249pseudo-attribute of the parent entry. 250.LP 251The 252.B bind 253operation requires 254.B auth (=x) 255access to the 256.B entry 257pseudo-attribute of the entry whose identity is being assessed; 258.B auth (=x) 259access to the credentials is not checked, but rather delegated 260to the underlying program. 261.LP 262The 263.B compare 264operation requires 265.B compare (=c) 266access to the 267.B entry 268pseudo-attribute 269of the object whose value is being asserted; 270.B compare (=c) 271access to the attribute whose value is being asserted is not checked. 272.LP 273The 274.B delete 275operation does not require 276.B write (=w) 277access to the 278.B children 279pseudo-attribute of the parent entry. 280.LP 281The 282.B modify 283operation requires 284.B write (=w) 285access to the 286.B entry 287pseudo-attribute; 288.B write (=w) 289access to the specific attributes that are modified is not checked. 290.LP 291The 292.B modrdn 293operation does not require 294.B write (=w) 295access to the 296.B children 297pseudo-attribute of the parent entry, nor to that of the new parent, 298if different; 299.B write (=w) 300access to the distinguished values of the naming attributes 301is not checked. 302.LP 303The 304.B search 305operation does not require 306.B search (=s) 307access to the 308.B entry 309pseudo_attribute of the searchBase; 310.B search (=s) 311access to the attributes and values used in the filter is not checked. 312.LP 313The 314.B extended 315operation does not require any access special rights. 316The external program has to implement any sort of access control. 317 318.SH EXAMPLE 319There is an example script in the slapd/back\-sock/ directory 320in the OpenLDAP source tree. 321.SH FILES 322.TP 323/etc/openldap/slapd.conf 324default slapd configuration file 325.SH SEE ALSO 326.BR slapd.conf (5), 327.BR slapd\-config (5), 328.BR slapd (8). 329.SH AUTHOR 330Brian Candler, with enhancements by Howard Chu 331