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

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