Provided by: slapd_2.5.13+dfsg-1ubuntu1_amd64 bug

NAME

       slapd-sock - Socket backend/overlay to slapd

SYNOPSIS

       /etc/ldap/slapd.conf

DESCRIPTION

       The  Socket  backend  to slapd(8) uses an external program to handle queries, similarly to
       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; 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.

CONFIGURATION

       These  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 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.

       extensions [ binddn | peername | ssf | connid ]*
              Enables the sending of additional meta-attributes with each request.
              binddn: <bound DN>
              peername: IP=<address>:<port>
              ssf: <SSF value>
              connid: <connection ID>

       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:

       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).

       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).

       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).

PROTOCOL

       The  protocol  is essentially the same as slapd-shell(5) with the addition of a newline to
       terminate the command parameters. The following commands are sent:
              ADD
              msgid: <message id>
              <repeat { "suffix:" <database suffix DN> }>
              <entry in LDIF format>
              <blank line>

              BIND
              msgid: <message id>
              <repeat { "suffix:" <database suffix DN> }>
              dn: <DN>
              method: <method number>
              credlen: <length of <credentials>>
              cred: <credentials>
              <blank line>

              COMPARE
              msgid: <message id>
              <repeat { "suffix:" <database suffix DN> }>
              dn: <DN>
              <attribute>: <value>
              <blank line>

              DELETE
              msgid: <message id>
              <repeat { "suffix:" <database suffix DN> }>
              dn: <DN>
              <blank line>

              EXTENDED
              msgid: <message id>
              <repeat { "suffix:" <database suffix DN> }>
              oid: <OID>
              value: <base64-value>
              <blank line>

              MODIFY
              msgid: <message id>
              <repeat { "suffix:" <database suffix DN> }>
              dn: <DN>
              <repeat {
                  <"add"/"delete"/"replace">: <attribute>
                  <repeat { <attribute>: <value> }>
                  -
              }>
              <blank line>

              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>

              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>

              UNBIND
              msgid: <message id>
              <repeat { "suffix:" <database suffix DN> }>
              <blank line>

       The commands - except unbind - should output:
              RESULT
              code: <integer>
              matched: <matched DN>
              info: <text>
       where only RESULT is mandatory, and then close the socket.  The search  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:
              RESULT
              msgid: <message id>
              code: <integer>
              matched: <matched DN>
              info: <text>
              <blank line>

       Typically  both  the  msgid  and  the connid will be needed to match a result message to a
       request. The ENTRY message has the form
              ENTRY
              msgid: <message id>
              <entry in LDIF format>
              <blank line>

KNOWN LIMITATIONS

       The sock backend does not process extended operation results from an external program.

ACCESS CONTROL

       The sock backend does not honor all ACL semantics as  described  in  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:

       The add operation does not require write (=w) access to the children  pseudo-attribute  of
       the parent entry.

       The  bind  operation  requires auth (=x) access to the entry pseudo-attribute of the entry
       whose identity is being assessed; auth (=x) access to the credentials is not checked,  but
       rather delegated to the underlying program.

       The  compare  operation  requires compare (=c) access to the entry pseudo-attribute of the
       object whose value is being asserted; compare (=c) access to the attribute whose value  is
       being asserted is not checked.

       The  delete  operation does not require write (=w) access to the children pseudo-attribute
       of the parent entry.

       The modify operation requires write (=w) access to the entry pseudo-attribute; write  (=w)
       access to the specific attributes that are modified is not checked.

       The  modrdn  operation does not require write (=w) access to the children pseudo-attribute
       of the parent entry, nor to that of the new parent, if different; write (=w) access to the
       distinguished values of the naming attributes is not checked.

       The  search operation does not require search (=s) access to the entry pseudo_attribute of
       the searchBase; search (=s) access to the attributes and values used in the filter is  not
       checked.

       The  extended  operation does not require any access special rights.  The external program
       has to implement any sort of access control.

EXAMPLE

       There is an example script in the slapd/back-sock/ directory in the OpenLDAP source tree.

FILES

       /etc/ldap/slapd.conf
              default slapd configuration file

SEE ALSO

       slapd.conf(5), slapd-config(5), slapd(8).

AUTHOR

       Brian Candler, with enhancements by Howard Chu