summaryrefslogtreecommitdiffstats
path: root/doc/man/man5/slapd-sock.5
blob: eb7034a1b8c04d8b6934f7a8fb7152e724f0aa5c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
.TH SLAPD-SOCK 5 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" Copyright 2007-2022 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 that 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 high 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 uses 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
.B sockresps
includes
.BR result
or
.BR search ,
the overlay will also send any response messages to the external program (also
see KNOWN LIMITATIONS). These will appear as an extended RESULT message or an
ENTRY message respectively, both are defined below and the program is not
expected to respond to these.

The extended 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.

If
.B sockresps
is configured,
.B sock
overlay does not consider
.B sockops
nor
.B sockdnpat
to decide which responses are passed onto the external program, instead, all
responses are currently passed on.

.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