1SLAPD-SOCK(5)                 File Formats Manual                SLAPD-SOCK(5)
2
3
4

NAME

6       slapd-sock - Socket backend/overlay to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

12       The  Socket  backend  to  slapd(8)  uses  an external program to handle
13       queries, similarly to slapd-shell(5).  However, in this case the exter‐
14       nal program listens on a Unix domain socket.  This makes it possible to
15       have a pool of processes, which persist between requests.  This  allows
16       multithreaded  operation and a higher level of efficiency. The external
17       program must have been started independently; slapd(8) itself will  not
18       start it.
19
20       This  module  may also be used as an overlay on top of some other data‐
21       base.  Use as an overlay allows external actions to be triggered in re‐
22       sponse to operations on the main database.
23

CONFIGURATION

25       These  slapd.conf options apply to the SOCK backend database.  That is,
26       they must follow a "database sock" line and come before any  subsequent
27       "backend" or "database" lines.  Other database options are described in
28       the slapd.conf(5) manual page.
29
30       Alternatively, to use this module as an overlay, these directives  must
31       follow an "overlay sock" line within an existing database definition.
32
33       extensions [ binddn | peername | ssf | connid ]*
34              Enables  the sending of additional meta-attributes with each re‐
35              quest.
36              binddn: <bound DN>
37              peername: IP=<address>:<port>
38              ssf: <SSF value>
39              connid: <connection ID>
40
41       socketpath <pathname>
42              Gives the path to a Unix domain socket  to  which  the  commands
43              will be sent and from which replies are received.
44
45              When  used  as  an  overlay, these additional directives are de‐
46              fined:
47
48       sockops   [ bind | unbind | search | compare | modify | modrdn | add  |
49       delete | extended ]*
50              Specify which request types to send to the external program. The
51              default is empty (no requests are sent).
52
53       sockresps [ result | search ]*
54              Specify which response types to send to  the  external  program.
55              "result"  sends just the results of an operation. "search" sends
56              all entries that the database returned for a search request. The
57              default is empty (no responses are sent).
58
59       sockdnpat <regexp>
60              Specify  DN patterns for which the overlay will act. Only opera‐
61              tions on DNs matching the specified regular expression  will  be
62              processed. The default is empty (all DNs are processed).
63
64

PROTOCOL

66       The  protocol  is essentially the same as slapd-shell(5) with the addi‐
67       tion of a newline to terminate the command  parameters.  The  following
68       commands are sent:
69              ADD
70              msgid: <message id>
71              <repeat { "suffix:" <database suffix DN> }>
72              <entry in LDIF format>
73              <blank line>
74
75              BIND
76              msgid: <message id>
77              <repeat { "suffix:" <database suffix DN> }>
78              dn: <DN>
79              method: <method number>
80              credlen: <length of <credentials>>
81              cred: <credentials>
82              <blank line>
83
84              COMPARE
85              msgid: <message id>
86              <repeat { "suffix:" <database suffix DN> }>
87              dn: <DN>
88              <attribute>: <value>
89              <blank line>
90
91              DELETE
92              msgid: <message id>
93              <repeat { "suffix:" <database suffix DN> }>
94              dn: <DN>
95              <blank line>
96
97              EXTENDED
98              msgid: <message id>
99              <repeat { "suffix:" <database suffix DN> }>
100              oid: <OID>
101              value: <base64-value>
102              <blank line>
103
104              MODIFY
105              msgid: <message id>
106              <repeat { "suffix:" <database suffix DN> }>
107              dn: <DN>
108              <repeat {
109                  <"add"/"delete"/"replace">: <attribute>
110                  <repeat { <attribute>: <value> }>
111                  -
112              }>
113              <blank line>
114
115              MODRDN
116              msgid: <message id>
117              <repeat { "suffix:" <database suffix DN> }>
118              dn: <DN>
119              newrdn: <new RDN>
120              deleteoldrdn: <0 or 1>
121              <if new superior is specified: "newSuperior: <DN>">
122              <blank line>
123
124              SEARCH
125              msgid: <message id>
126              <repeat { "suffix:" <database suffix DN> }>
127              base: <base DN>
128              scope: <0-2, see ldap.h>
129              deref: <0-3, see ldap.h>
130              sizelimit: <size limit>
131              timelimit: <time limit>
132              filter: <filter>
133              attrsonly: <0 or 1>
134              attrs: <"all" or space-separated attribute list>
135              <blank line>
136
137              UNBIND
138              msgid: <message id>
139              <repeat { "suffix:" <database suffix DN> }>
140              <blank line>
141
142       The commands - except unbind - should output:
143              RESULT
144              code: <integer>
145              matched: <matched DN>
146              info: <text>
147       where  only RESULT is mandatory, and then close the socket.  The search
148       RESULT should be preceded by the entries in  LDIF  format,  each  entry
149       followed  by a blank line.  Lines starting with `#' or `DEBUG:' are ig‐
150       nored.
151
152       When used as an overlay, the external program should return a  CONTINUE
153       response  if  request processing should continue normally, or a regular
154       RESULT response if the external program wishes to bypass the underlying
155       database.
156
157       If  the overlay is configured to send response messages to the external
158       program, they will appear as an extended RESULT message or as an  ENTRY
159       message, defined below. The RESULT message is similar to the one above,
160       but also includes the msgid and any configured extensions:
161              RESULT
162              msgid: <message id>
163              code: <integer>
164              matched: <matched DN>
165              info: <text>
166              <blank line>
167
168       Typically both the msgid and the connid will be needed to match  a  re‐
169       sult message to a request. The ENTRY message has the form
170              ENTRY
171              msgid: <message id>
172              <entry in LDIF format>
173              <blank line>
174
175

KNOWN LIMITATIONS

177       The  sock  backend  does not process extended operation results from an
178       external program.
179
180

ACCESS CONTROL

182       The sock backend does not honor  all  ACL  semantics  as  described  in
183       slapd.access(5).   In  general, access to objects is checked by using a
184       dummy object that contains only the DN, so access rules  that  rely  on
185       the contents of the object are not honored.  In detail:
186
187       The  add  operation  does not require write (=w) access to the children
188       pseudo-attribute of the parent entry.
189
190       The bind operation requires auth (=x) access to the entry pseudo-attri‐
191       bute of the entry whose identity is being assessed; auth (=x) access to
192       the credentials is not checked, but rather delegated to the  underlying
193       program.
194
195       The compare operation requires compare (=c) access to the entry pseudo-
196       attribute of the object whose value is being asserted; compare (=c) ac‐
197       cess to the attribute whose value is being asserted is not checked.
198
199       The delete operation does not require write (=w) access to the children
200       pseudo-attribute of the parent entry.
201
202       The modify operation requires write (=w) access to the entry pseudo-at‐
203       tribute; write (=w) access to the specific attributes that are modified
204       is not checked.
205
206       The modrdn operation does not require write (=w) access to the children
207       pseudo-attribute of the parent entry, nor to that of the new parent, if
208       different; write (=w) access to the distinguished values of the  naming
209       attributes is not checked.
210
211       The  search  operation does not require search (=s) access to the entry
212       pseudo_attribute of the searchBase;  search  (=s)  access  to  the  at‐
213       tributes and values used in the filter is not checked.
214
215       The extended operation does not require any access special rights.  The
216       external program has to implement any sort of access control.
217
218

EXAMPLE

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

FILES

224       /etc/openldap/slapd.conf
225              default slapd configuration file
226

SEE ALSO

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

AUTHOR

231       Brian Candler, with enhancements by Howard Chu
232
233
234
235OpenLDAP                          2021/06/03                     SLAPD-SOCK(5)
Impressum