From: Howard Chu <hyc@openldap.org>
Date: Fri, 7 Sep 2007 12:27:33 +0000 (+0000)
Subject: back-sock by Brian Candler (B.Candler@pobox.com) ITS#4094 (untested)
X-Git-Tag: OPENLDAP_REL_ENG_2_4_9~20^2~677
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=c8c6cba5fc6dd475570a8c8cda09ce267d442879;p=openldap

back-sock by Brian Candler (B.Candler@pobox.com) ITS#4094 (untested)
---

diff --git a/doc/man/man5/slapd-sock.5 b/doc/man/man5/slapd-sock.5
new file mode 100644
index 0000000000..d0d3472c50
--- /dev/null
+++ b/doc/man/man5/slapd-sock.5
@@ -0,0 +1,251 @@
+.TH SLAPD-SOCK 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 2007 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.\" $OpenLDAP$
+.SH NAME
+slapd-sock \- Socket backend to slapd
+.SH SYNOPSIS
+ETCDIR/slapd.conf
+.SH DESCRIPTION
+The Socket backend to
+.BR slapd (8)
+uses an external program to handle queries, similarly to
+.BR slapd-shell (5).
+However, in this case the external program 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 higher level of
+efficiency. The external program must have been started independently;
+.BR slapd (8)
+itself will not start it.
+.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.
+.TP
+.B extensions      [ binddn | peername | ssf ]*
+Enables the sending of additional meta-attributes with each request.
+.nf
+binddn: <bound DN>
+peername: IP=<address>:<port>
+ssf: <SSF value>
+.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.
+.SH PROTOCOL
+The protocol is essentially the same as
+.BR slapd-shell (5)
+with the addition of 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
+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.
+.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 read (=r)
+access (FIXME: wouldn't 
+.B compare (=c)
+be a more appropriate choice?)
+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.
+
+.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 (8).
+.SH AUTHOR
+Brian Candler
diff --git a/servers/slapd/back-sock/Makefile.in b/servers/slapd/back-sock/Makefile.in
new file mode 100644
index 0000000000..7ca24bf9f9
--- /dev/null
+++ b/servers/slapd/back-sock/Makefile.in
@@ -0,0 +1,47 @@
+# Makefile.in for back-sock
+# $OpenLDAP$
+## This work is part of OpenLDAP Software <http://www.openldap.org/>.
+##
+## Copyright 2007 The OpenLDAP Foundation.
+## All rights reserved.
+##
+## Redistribution and use in source and binary forms, with or without
+## modification, are permitted only as authorized by the OpenLDAP
+## Public License.
+##
+## A copy of this license is available in the file LICENSE in the
+## top-level directory of the distribution or, alternatively, at
+## <http://www.OpenLDAP.org/license.html>.
+##
+## ACKNOWLEDGEMENTS:
+## This work was initially developed by Brian Candler for inclusion
+## in OpenLDAP Software.
+
+SRCS	= init.c config.c opensock.c search.c bind.c unbind.c add.c \
+		delete.c modify.c modrdn.c compare.c result.c
+OBJS	= init.lo config.lo opensock.lo search.lo bind.lo unbind.lo add.lo \
+		delete.lo modify.lo modrdn.lo compare.lo result.lo
+
+LDAP_INCDIR= ../../../include       
+LDAP_LIBDIR= ../../../libraries
+
+BUILD_OPT = "--enable-sock"
+BUILD_MOD = @BUILD_SOCK@
+
+mod_DEFS = -DSLAPD_IMPORT
+MOD_DEFS = $(@BUILD_SOCK@_DEFS)
+
+shared_LDAP_LIBS = $(LDAP_LIBLDAP_R_LA) $(LDAP_LIBLBER_LA)
+NT_LINK_LIBS = -L.. -lslapd $(@BUILD_LIBS_DYNAMIC@_LDAP_LIBS)
+UNIX_LINK_LIBS = $(@BUILD_LIBS_DYNAMIC@_LDAP_LIBS)
+
+LIBBASE = back_sock
+
+XINCPATH = -I.. -I$(srcdir)/..
+XDEFS = $(MODULES_CPPFLAGS)
+
+all-local-lib:	../.backend
+
+../.backend: lib$(LIBBASE).a
+	@touch $@
+