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

   1 .TH SLAPD-SOCK 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 2007-2016 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 ]*
  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 MODIFY
 119 msgid: <message id>
 120 <repeat { "suffix:" <database suffix DN> }>
 121 dn: <DN>
 122 <repeat {
 123     <"add"/"delete"/"replace">: <attribute>
 124     <repeat { <attribute>: <value> }>
 125     \-
 126 }>
 127 <blank line>
 128 .fi
 129 .RE
 130 .PP
 131 .RS
 132 .nf
 133 MODRDN
 134 msgid: <message id>
 135 <repeat { "suffix:" <database suffix DN> }>
 136 dn: <DN>
 137 newrdn: <new RDN>
 138 deleteoldrdn: <0 or 1>
 139 <if new superior is specified: "newSuperior: <DN>">
 140 <blank line>
 141 .fi
 142 .RE
 143 .PP
 144 .RS
 145 .nf
 146 SEARCH
 147 msgid: <message id>
 148 <repeat { "suffix:" <database suffix DN> }>
 149 base: <base DN>
 150 scope: <0-2, see ldap.h>
 151 deref: <0-3, see ldap.h>
 152 sizelimit: <size limit>
 153 timelimit: <time limit>
 154 filter: <filter>
 155 attrsonly: <0 or 1>
 156 attrs: <"all" or space-separated attribute list>
 157 <blank line>
 158 .fi
 159 .RE
 160 .PP
 161 .RS
 162 .nf
 163 UNBIND
 164 msgid: <message id>
 165 <repeat { "suffix:" <database suffix DN> }>
 166 <blank line>
 167 .fi
 168 .RE
 169 .LP
 170 The commands - except \fBunbind\fP - should output:
 171 .RS
 172 .nf
 173 RESULT
 174 code: <integer>
 175 matched: <matched DN>
 176 info: <text>
 177 .fi
 178 .RE
 179 where only RESULT is mandatory, and then close the socket.
 180 The \fBsearch\fP RESULT should be preceded by the entries in LDIF
 181 format, each entry followed by a blank line.
 182 Lines starting with `#' or `DEBUG:' are ignored.
 183
 184 When used as an overlay, the external program should return a
 185 CONTINUE response if request processing should continue normally, or
 186 a regular RESULT response if the external program wishes to bypass the
 187 underlying database.
 188
 189 If the overlay is configured to send response messages to the external
 190 program, they will appear as an extended RESULT message or as an
 191 ENTRY message, defined below. The RESULT message is similar to
 192 the one above, but also includes the msgid and any configured
 193 extensions:
 194 .RS
 195 .nf
 196 RESULT
 197 msgid: <message id>
 198 code: <integer>
 199 matched: <matched DN>
 200 info: <text>
 201 <blank line>
 202 .fi
 203 .RE
 204
 205 Typically both the msgid and the connid will be needed to match
 206 a result message to a request. The ENTRY message has the form
 207 .RS
 208 .nf
 209 ENTRY
 210 msgid: <message id>
 211 <entry in LDIF format>
 212 <blank line>
 213 .fi
 214 .RE
 215
 216 .SH ACCESS CONTROL
 217 The
 218 .B sock
 219 backend does not honor all ACL semantics as described in
 220 .BR slapd.access (5).
 221 In general, access to objects is checked by using a dummy object
 222 that contains only the DN, so access rules that rely on the contents
 223 of the object are not honored.
 224 In detail:
 225 .LP
 226 The
 227 .B add
 228 operation does not require
 229 .B write (=w)
 230 access to the
 231 .B children
 232 pseudo-attribute of the parent entry.
 233 .LP
 234 The
 235 .B bind
 236 operation requires
 237 .B auth (=x)
 238 access to the
 239 .B entry
 240 pseudo-attribute of the entry whose identity is being assessed;
 241 .B auth (=x)
 242 access to the credentials is not checked, but rather delegated
 243 to the underlying program.
 244 .LP
 245 The
 246 .B compare
 247 operation requires
 248 .B compare (=c)
 249 access to the
 250 .B entry
 251 pseudo-attribute
 252 of the object whose value is being asserted;
 253 .B compare (=c)
 254 access to the attribute whose value is being asserted is not checked.
 255 .LP
 256 The
 257 .B delete
 258 operation does not require
 259 .B write (=w)
 260 access to the
 261 .B children
 262 pseudo-attribute of the parent entry.
 263 .LP
 264 The
 265 .B modify
 266 operation requires
 267 .B write (=w)
 268 access to the
 269 .B entry
 270 pseudo-attribute;
 271 .B write (=w)
 272 access to the specific attributes that are modified is not checked.
 273 .LP
 274 The
 275 .B modrdn
 276 operation does not require
 277 .B write (=w)
 278 access to the
 279 .B children
 280 pseudo-attribute of the parent entry, nor to that of the new parent,
 281 if different;
 282 .B write (=w)
 283 access to the distinguished values of the naming attributes
 284 is not checked.
 285 .LP
 286 The
 287 .B search
 288 operation does not require
 289 .B search (=s)
 290 access to the
 291 .B entry
 292 pseudo_attribute of the searchBase;
 293 .B search (=s)
 294 access to the attributes and values used in the filter is not checked.
 295
 296 .SH EXAMPLE
 297 There is an example script in the slapd/back\-sock/ directory
 298 in the OpenLDAP source tree.
 299 .SH FILES
 300 .TP
 301 ETCDIR/slapd.conf
 302 default slapd configuration file
 303 .SH SEE ALSO
 304 .BR slapd.conf (5),
 305 .BR slapd\-config (5),
 306 .BR slapd (8).
 307 .SH AUTHOR
 308 Brian Candler, with enhancements by Howard Chu