.TH SLAPD-SOCK 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 2007-2009 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 2007-2011 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
.\" $OpenLDAP$
.SH NAME
-slapd-sock \- Socket backend to slapd
+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).
+.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
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 ]*
+.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 ]*
+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).
+
.SH PROTOCOL
The protocol is essentially the same as
-.BR slapd-shell (5)
+.BR slapd\-shell (5)
with the addition of a newline to terminate the command parameters. The
following commands are sent:
.RS
<repeat {
<"add"/"delete"/"replace">: <attribute>
<repeat { <attribute>: <value> }>
- -
+ \-
}>
<blank line>
.fi
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 ACCESS CONTROL
The
.B sock
access to the attributes and values used in the filter is not checked.
.SH EXAMPLE
-There is an example script in the slapd/back-sock/ directory
+There is an example script in the slapd/back\-sock/ directory
in the OpenLDAP source tree.
.SH FILES
.TP
.BR slapd\-config (5),
.BR slapd (8).
.SH AUTHOR
-Brian Candler
+Brian Candler, with enhancements by Howard Chu
projects / openldap / blobdiff