diff options
Diffstat (limited to 'doc/man/man5/slapd-sock.5')
-rw-r--r-- | doc/man/man5/slapd-sock.5 | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/doc/man/man5/slapd-sock.5 b/doc/man/man5/slapd-sock.5 new file mode 100644 index 0000000..74197df --- /dev/null +++ b/doc/man/man5/slapd-sock.5 @@ -0,0 +1,329 @@ +.TH SLAPD-SOCK 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2007-2021 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.\" $OpenLDAP$ +.SH NAME +slapd\-sock \- Socket backend/overlay to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The Socket backend to +.BR slapd (8) +uses an external program to handle queries, similarly to +.BR slapd\-shell (5). +However, in this case the external program listens on a Unix domain socket. +This makes it possible to have a pool of processes, which persist between +requests. This allows multithreaded operation and a higher level of +efficiency. The external program must have been started independently; +.BR slapd (8) +itself will not start it. + +This module may also be used as an overlay on top of some other database. +Use as an overlay allows external actions to be triggered in response to +operations on the main database. +.SH CONFIGURATION +These +.B slapd.conf +options apply to the SOCK backend database. +That is, they must follow a "database sock" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. + +Alternatively, to use this module as an overlay, these directives must +follow an "overlay sock" line within an existing database definition. +.TP +.B extensions [ binddn | peername | ssf | connid ]* +Enables the sending of additional meta-attributes with each request. +.nf +binddn: <bound DN> +peername: IP=<address>:<port> +ssf: <SSF value> +connid: <connection ID> +.fi +.TP +.B socketpath <pathname> +Gives the path to a Unix domain socket to which the commands will +be sent and from which replies are received. + +When used as an overlay, these additional directives are defined: +.TP +.B sockops [ bind | unbind | search | compare | modify | modrdn | add | delete | extended ]* +Specify which request types to send to the external program. The default is +empty (no requests are sent). +.TP +.B sockresps [ result | search ]* +Specify which response types to send to the external program. "result" +sends just the results of an operation. "search" sends all entries that +the database returned for a search request. The default is empty +(no responses are sent). +.TP +.B sockdnpat <regexp> +Specify DN patterns for which the overlay will act. Only operations on +DNs matching the specified regular expression will be processed. The default +is empty (all DNs are processed). + +.SH PROTOCOL +The protocol is essentially the same as +.BR slapd\-shell (5) +with the addition of a newline to terminate the command parameters. The +following commands are sent: +.RS +.nf +ADD +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +<entry in LDIF format> +<blank line> +.fi +.RE +.PP +.RS +.nf +BIND +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +method: <method number> +credlen: <length of <credentials>> +cred: <credentials> +<blank line> +.fi +.RE +.PP +.RS +.nf +COMPARE +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +<attribute>: <value> +<blank line> +.fi +.RE +.PP +.RS +.nf +DELETE +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +<blank line> +.fi +.RE +.PP +.RS +.nf +EXTENDED +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +oid: <OID> +value: <base64-value> +<blank line> +.fi +.RE +.PP +.RS +.nf +MODIFY +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +<repeat { + <"add"/"delete"/"replace">: <attribute> + <repeat { <attribute>: <value> }> + \- +}> +<blank line> +.fi +.RE +.PP +.RS +.nf +MODRDN +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +dn: <DN> +newrdn: <new RDN> +deleteoldrdn: <0 or 1> +<if new superior is specified: "newSuperior: <DN>"> +<blank line> +.fi +.RE +.PP +.RS +.nf +SEARCH +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +base: <base DN> +scope: <0-2, see ldap.h> +deref: <0-3, see ldap.h> +sizelimit: <size limit> +timelimit: <time limit> +filter: <filter> +attrsonly: <0 or 1> +attrs: <"all" or space-separated attribute list> +<blank line> +.fi +.RE +.PP +.RS +.nf +UNBIND +msgid: <message id> +<repeat { "suffix:" <database suffix DN> }> +<blank line> +.fi +.RE +.LP +The commands - except \fBunbind\fP - should output: +.RS +.nf +RESULT +code: <integer> +matched: <matched DN> +info: <text> +.fi +.RE +where only RESULT is mandatory, and then close the socket. +The \fBsearch\fP RESULT should be preceded by the entries in LDIF +format, each entry followed by a blank line. +Lines starting with `#' or `DEBUG:' are ignored. + +When used as an overlay, the external program should return a +CONTINUE response if request processing should continue normally, or +a regular RESULT response if the external program wishes to bypass the +underlying database. + +If the overlay is configured to send response messages to the external +program, they will appear as an extended RESULT message or as an +ENTRY message, defined below. The RESULT message is similar to +the one above, but also includes the msgid and any configured +extensions: +.RS +.nf +RESULT +msgid: <message id> +code: <integer> +matched: <matched DN> +info: <text> +<blank line> +.fi +.RE + +Typically both the msgid and the connid will be needed to match +a result message to a request. The ENTRY message has the form +.RS +.nf +ENTRY +msgid: <message id> +<entry in LDIF format> +<blank line> +.fi +.RE + +.SH KNOWN LIMITATIONS +The +.B sock +backend does not process extended operation results from an external program. + +.SH ACCESS CONTROL +The +.B sock +backend does not honor all ACL semantics as described in +.BR slapd.access (5). +In general, access to objects is checked by using a dummy object +that contains only the DN, so access rules that rely on the contents +of the object are not honored. +In detail: +.LP +The +.B add +operation does not require +.B write (=w) +access to the +.B children +pseudo-attribute of the parent entry. +.LP +The +.B bind +operation requires +.B auth (=x) +access to the +.B entry +pseudo-attribute of the entry whose identity is being assessed; +.B auth (=x) +access to the credentials is not checked, but rather delegated +to the underlying program. +.LP +The +.B compare +operation requires +.B compare (=c) +access to the +.B entry +pseudo-attribute +of the object whose value is being asserted; +.B compare (=c) +access to the attribute whose value is being asserted is not checked. +.LP +The +.B delete +operation does not require +.B write (=w) +access to the +.B children +pseudo-attribute of the parent entry. +.LP +The +.B modify +operation requires +.B write (=w) +access to the +.B entry +pseudo-attribute; +.B write (=w) +access to the specific attributes that are modified is not checked. +.LP +The +.B modrdn +operation does not require +.B write (=w) +access to the +.B children +pseudo-attribute of the parent entry, nor to that of the new parent, +if different; +.B write (=w) +access to the distinguished values of the naming attributes +is not checked. +.LP +The +.B search +operation does not require +.B search (=s) +access to the +.B entry +pseudo_attribute of the searchBase; +.B search (=s) +access to the attributes and values used in the filter is not checked. +.LP +The +.B extended +operation does not require any access special rights. +The external program has to implement any sort of access control. + +.SH EXAMPLE +There is an example script in the slapd/back\-sock/ directory +in the OpenLDAP source tree. +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-config (5), +.BR slapd (8). +.SH AUTHOR +Brian Candler, with enhancements by Howard Chu |