git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-sock.5

   1 .TH SLAPD-SOCK 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 2007-2018 The OpenLDAP Foundation All Rights Reserved.
   3 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   4 .\" $OpenLDAP$
   5 .SH NAME
   6 slapd\-sock \- Socket backend/overlay to slapd
   7 .SH SYNOPSIS
   8 ETCDIR/slapd.conf
   9 .SH DESCRIPTION
  10 The Socket backend to
  11 .BR slapd (8)
  12 uses an external program to handle queries, similarly to
  13 .BR slapd\-shell (5).
  14 However, in this case the external program listens on a Unix domain socket.
  15 This makes it possible to have a pool of processes, which persist between
  16 requests. This allows multithreaded operation and a higher level of
  17 efficiency. The external program must have been started independently;
  18 .BR slapd (8)
  19 itself will not start it.
  20
  21 This module may also be used as an overlay on top of some other database.
  22 Use as an overlay allows external actions to be triggered in response to
  23 operations on the main database.
  24 .SH CONFIGURATION
  25 These
  26 .B slapd.conf
  27 options apply to the SOCK backend database.
  28 That is, they must follow a "database sock" line and come before any
  29 subsequent "backend" or "database" lines.
  30 Other database options are described in the
  31 .BR slapd.conf (5)
  32 manual page.
  33
  34 Alternatively, to use this module as an overlay, these directives must
  35 follow an "overlay sock" line within an existing database definition.
  36 .TP
  37 .B extensions      [ binddn | peername | ssf | connid ]*
  38 Enables the sending of additional meta-attributes with each request.
  39 .nf
  40 binddn: <bound DN>
  41 peername: IP=<address>:<port>
  42 ssf: <SSF value>
  43 connid: <connection ID>
  44 .fi
  45 .TP
  46 .B socketpath      <pathname>
  47 Gives the path to a Unix domain socket to which the commands will
  48 be sent and from which replies are received.
  49
  50 When used as an overlay, these additional directives are defined:
  51 .TP
  52 .B sockops      [ bind | unbind | search | compare | modify | modrdn | add | delete | extended ]*
  53 Specify which request types to send to the external program. The default is
  54 empty (no requests are sent).
  55 .TP
  56 .B sockresps       [ result | search ]*
  57 Specify which response types to send to the external program. "result"
  58 sends just the results of an operation. "search" sends all entries that
  59 the database returned for a search request. The default is empty
  60 (no responses are sent).
  61 .TP
  62 .B sockdnpat    <regexp>
  63 Specify DN patterns for which the overlay will act. Only operations on
  64 DNs matching the specified regular expression will be processed. The default
  65 is empty (all DNs are processed).
  66
  67 .SH PROTOCOL
  68 The protocol is essentially the same as
  69 .BR slapd\-shell (5)
  70 with the addition of a newline to terminate the command parameters. The
  71 following commands are sent:
  72 .RS
  73 .nf
  74 ADD
  75 msgid: <message id>
  76 <repeat { "suffix:" <database suffix DN> }>
  77 <entry in LDIF format>
  78 <blank line>
  79 .fi
  80 .RE
  81 .PP
  82 .RS
  83 .nf
  84 BIND
  85 msgid: <message id>
  86 <repeat { "suffix:" <database suffix DN> }>
  87 dn: <DN>
  88 method: <method number>
  89 credlen: <length of <credentials>>
  90 cred: <credentials>
  91 <blank line>
  92 .fi
  93 .RE
  94 .PP
  95 .RS
  96 .nf
  97 COMPARE
  98 msgid: <message id>
  99 <repeat { "suffix:" <database suffix DN> }>
 100 dn: <DN>
 101 <attribute>: <value>
 102 <blank line>
 103 .fi
 104 .RE
 105 .PP
 106 .RS
 107 .nf
 108 DELETE
 109 msgid: <message id>
 110 <repeat { "suffix:" <database suffix DN> }>
 111 dn: <DN>
 112 <blank line>
 113 .fi
 114 .RE
 115 .PP
 116 .RS
 117 .nf
 118 EXTENDED
 119 msgid: <message id>
 120 <repeat { "suffix:" <database suffix DN> }>
 121 oid: <OID>
 122 value: <base64-value>
 123 <blank line>
 124 .fi
 125 .RE
 126 .PP
 127 .RS
 128 .nf
 129 MODIFY
 130 msgid: <message id>
 131 <repeat { "suffix:" <database suffix DN> }>
 132 dn: <DN>
 133 <repeat {
 134     <"add"/"delete"/"replace">: <attribute>
 135     <repeat { <attribute>: <value> }>
 136     \-
 137 }>
 138 <blank line>
 139 .fi
 140 .RE
 141 .PP
 142 .RS
 143 .nf
 144 MODRDN
 145 msgid: <message id>
 146 <repeat { "suffix:" <database suffix DN> }>
 147 dn: <DN>
 148 newrdn: <new RDN>
 149 deleteoldrdn: <0 or 1>
 150 <if new superior is specified: "newSuperior: <DN>">
 151 <blank line>
 152 .fi
 153 .RE
 154 .PP
 155 .RS
 156 .nf
 157 SEARCH
 158 msgid: <message id>
 159 <repeat { "suffix:" <database suffix DN> }>
 160 base: <base DN>
 161 scope: <0-2, see ldap.h>
 162 deref: <0-3, see ldap.h>
 163 sizelimit: <size limit>
 164 timelimit: <time limit>
 165 filter: <filter>
 166 attrsonly: <0 or 1>
 167 attrs: <"all" or space-separated attribute list>
 168 <blank line>
 169 .fi
 170 .RE
 171 .PP
 172 .RS
 173 .nf
 174 UNBIND
 175 msgid: <message id>
 176 <repeat { "suffix:" <database suffix DN> }>
 177 <blank line>
 178 .fi
 179 .RE
 180 .LP
 181 The commands - except \fBunbind\fP - should output:
 182 .RS
 183 .nf
 184 RESULT
 185 code: <integer>
 186 matched: <matched DN>
 187 info: <text>
 188 .fi
 189 .RE
 190 where only RESULT is mandatory, and then close the socket.
 191 The \fBsearch\fP RESULT should be preceded by the entries in LDIF
 192 format, each entry followed by a blank line.
 193 Lines starting with `#' or `DEBUG:' are ignored.
 194
 195 When used as an overlay, the external program should return a
 196 CONTINUE response if request processing should continue normally, or
 197 a regular RESULT response if the external program wishes to bypass the
 198 underlying database.
 199
 200 If the overlay is configured to send response messages to the external
 201 program, they will appear as an extended RESULT message or as an
 202 ENTRY message, defined below. The RESULT message is similar to
 203 the one above, but also includes the msgid and any configured
 204 extensions:
 205 .RS
 206 .nf
 207 RESULT
 208 msgid: <message id>
 209 code: <integer>
 210 matched: <matched DN>
 211 info: <text>
 212 <blank line>
 213 .fi
 214 .RE
 215
 216 Typically both the msgid and the connid will be needed to match
 217 a result message to a request. The ENTRY message has the form
 218 .RS
 219 .nf
 220 ENTRY
 221 msgid: <message id>
 222 <entry in LDIF format>
 223 <blank line>
 224 .fi
 225 .RE
 226
 227 .SH KNOWN LIMITATIONS
 228 The
 229 .B sock
 230 backend does not process extended operation results from an external program.
 231
 232 .SH ACCESS CONTROL
 233 The
 234 .B sock
 235 backend does not honor all ACL semantics as described in
 236 .BR slapd.access (5).
 237 In general, access to objects is checked by using a dummy object
 238 that contains only the DN, so access rules that rely on the contents
 239 of the object are not honored.
 240 In detail:
 241 .LP
 242 The
 243 .B add
 244 operation does not require
 245 .B write (=w)
 246 access to the
 247 .B children
 248 pseudo-attribute of the parent entry.
 249 .LP
 250 The
 251 .B bind
 252 operation requires
 253 .B auth (=x)
 254 access to the
 255 .B entry
 256 pseudo-attribute of the entry whose identity is being assessed;
 257 .B auth (=x)
 258 access to the credentials is not checked, but rather delegated
 259 to the underlying program.
 260 .LP
 261 The
 262 .B compare
 263 operation requires
 264 .B compare (=c)
 265 access to the
 266 .B entry
 267 pseudo-attribute
 268 of the object whose value is being asserted;
 269 .B compare (=c)
 270 access to the attribute whose value is being asserted is not checked.
 271 .LP
 272 The
 273 .B delete
 274 operation does not require
 275 .B write (=w)
 276 access to the
 277 .B children
 278 pseudo-attribute of the parent entry.
 279 .LP
 280 The
 281 .B modify
 282 operation requires
 283 .B write (=w)
 284 access to the
 285 .B entry
 286 pseudo-attribute;
 287 .B write (=w)
 288 access to the specific attributes that are modified is not checked.
 289 .LP
 290 The
 291 .B modrdn
 292 operation does not require
 293 .B write (=w)
 294 access to the
 295 .B children
 296 pseudo-attribute of the parent entry, nor to that of the new parent,
 297 if different;
 298 .B write (=w)
 299 access to the distinguished values of the naming attributes
 300 is not checked.
 301 .LP
 302 The
 303 .B search
 304 operation does not require
 305 .B search (=s)
 306 access to the
 307 .B entry
 308 pseudo_attribute of the searchBase;
 309 .B search (=s)
 310 access to the attributes and values used in the filter is not checked.
 311 .LP
 312 The
 313 .B extended
 314 operation does not require any access special rights.
 315 The external program has to implement any sort of access control.
 316
 317 .SH EXAMPLE
 318 There is an example script in the slapd/back\-sock/ directory
 319 in the OpenLDAP source tree.
 320 .SH FILES
 321 .TP
 322 ETCDIR/slapd.conf
 323 default slapd configuration file
 324 .SH SEE ALSO
 325 .BR slapd.conf (5),
 326 .BR slapd\-config (5),
 327 .BR slapd (8).
 328 .SH AUTHOR
 329 Brian Candler, with enhancements by Howard Chu