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

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