1.lf 1 stdin
2.TH SLAPD-SHELL 5 "2020/04/28" "OpenLDAP 2.4.50"
3.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved.
4.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
5.\" $OpenLDAP$
6.SH NAME
7slapd\-shell \- Shell backend to slapd
8.SH SYNOPSIS
9/etc/openldap/slapd.conf
10.SH DESCRIPTION
11The Shell backend to
12.BR slapd (8)
13executes external programs to implement operations, and is designed to
14make it easy to tie an existing database to the
15.B slapd
16front-end.
17.LP
18This backend is primarily intended to be used in prototypes.
19.SH WARNING
20The
21.B abandon
22shell command has been removed since OpenLDAP 2.1.
23.SH CONFIGURATION
24These
25.B slapd.conf
26options apply to the SHELL backend database.
27That is, they must follow a "database shell" line and come before any
28subsequent "backend" or "database" lines.
29Other database options are described in the
30.BR slapd.conf (5)
31manual page.
32.LP
33These options specify the pathname and arguments of the program to
34execute in response to the given LDAP operation.
35Each option is followed by the input lines that the program receives:
36.TP
37.B add      <pathname> <argument>...
38.nf
39ADD
40msgid: <message id>
41<repeat { "suffix:" <database suffix DN> }>
42<entry in LDIF format>
43.fi
44.TP
45.B bind     <pathname> <argument>...
46.nf
47BIND
48msgid: <message id>
49<repeat { "suffix:" <database suffix DN> }>
50dn: <DN>
51method: <method number>
52credlen: <length of <credentials>>
53cred: <credentials>
54.fi
55.TP
56.B compare  <pathname> <argument>...
57.nf
58COMPARE
59msgid: <message id>
60<repeat { "suffix:" <database suffix DN> }>
61dn: <DN>
62<attribute>: <value>
63.fi
64.TP
65.B delete   <pathname> <argument>...
66.nf
67DELETE
68msgid: <message id>
69<repeat { "suffix:" <database suffix DN> }>
70dn: <DN>
71.fi
72.TP
73.B modify   <pathname> <argument>...
74.nf
75MODIFY
76msgid: <message id>
77<repeat { "suffix:" <database suffix DN> }>
78dn: <DN>
79<repeat {
80    <"add"/"delete"/"replace">: <attribute>
81    <repeat { <attribute>: <value> }>
82    \-
83}>
84.fi
85.TP
86.B modrdn   <pathname> <argument>...
87.nf
88MODRDN
89msgid: <message id>
90<repeat { "suffix:" <database suffix DN> }>
91dn: <DN>
92newrdn: <new RDN>
93deleteoldrdn: <0 or 1>
94<if new superior is specified: "newSuperior: <DN>">
95.fi
96.TP
97.B search   <pathname> <argument>...
98.nf
99SEARCH
100msgid: <message id>
101<repeat { "suffix:" <database suffix DN> }>
102base: <base DN>
103scope: <0-2, see ldap.h>
104deref: <0-3, see ldap.h>
105sizelimit: <size limit>
106timelimit: <time limit>
107filter: <filter>
108attrsonly: <0 or 1>
109attrs: <"all" or space-separated attribute list>
110.fi
111.TP
112.B unbind   <pathname> <argument>...
113.nf
114UNBIND
115msgid: <message id>
116<repeat { "suffix:" <database suffix DN> }>
117dn: <bound DN>
118.fi
119.LP
120Note that you need only supply configuration lines for those commands you
121want the backend to handle.
122Operations for which a command is not supplied will be refused with an
123"unwilling to perform" error.
124.LP
125The \fBsearch\fP command should output the entries in LDIF format,
126each entry followed by a blank line, and after these the RESULT below.
127.LP
128All commands except \fBunbind\fP should then output:
129.RS
130.nf
131RESULT
132code: <integer>
133matched: <matched DN>
134info: <text>
135.fi
136.RE
137where only the RESULT line is mandatory.
138Lines starting with `#' or `DEBUG:' are ignored.
139.SH ACCESS CONTROL
140The
141.B shell
142backend does not honor all ACL semantics as described in
143.BR slapd.access (5).
144In general, access to objects is checked by using a dummy object
145that contains only the DN, so access rules that rely on the contents
146of the object are not honored.
147In detail:
148.LP
149The
150.B add
151operation does not require
152.B write (=w)
153access to the 
154.B children
155pseudo-attribute of the parent entry.
156.LP
157The
158.B bind
159operation requires 
160.B auth (=x)
161access to the 
162.B entry
163pseudo-attribute of the entry whose identity is being assessed;
164.B auth (=x)
165access to the credentials is not checked, but rather delegated 
166to the underlying shell script.
167.LP
168The
169.B compare
170operation requires 
171.B read (=r)
172access (FIXME: wouldn't 
173.B compare (=c)
174be a more appropriate choice?)
175to the 
176.B entry
177pseudo-attribute
178of the object whose value is being asserted;
179.B compare (=c)
180access to the attribute whose value is being asserted is not checked.
181.LP
182The
183.B delete
184operation does not require
185.B write (=w)
186access to the 
187.B children
188pseudo-attribute of the parent entry.
189.LP
190The
191.B modify
192operation requires
193.B write (=w)
194access to the 
195.B entry 
196pseudo-attribute;
197.B write (=w)
198access to the specific attributes that are modified is not checked.
199.LP
200The
201.B modrdn
202operation does not require
203.B write (=w)
204access to the 
205.B children
206pseudo-attribute of the parent entry, nor to that of the new parent,
207if different;
208.B write (=w)
209access to the distinguished values of the naming attributes
210is not checked.
211.LP
212The
213.B search 
214operation does not require
215.B search (=s)
216access to the 
217.B entry
218pseudo_attribute of the searchBase;
219.B search (=s)
220access to the attributes and values used in the filter is not checked.
221
222.SH EXAMPLE
223There is an example search script in the slapd/back\-shell/ directory
224in the OpenLDAP source tree.
225.SH LIMITATIONS
226The shell backend does not support threaded environments.
227When using the shell backend, 
228.BR slapd (8)
229should be built
230.IR \-\-without\-threads .
231.SH FILES
232.TP
233/etc/openldap/slapd.conf
234default slapd configuration file
235.SH SEE ALSO
236.BR slapd.conf (5),
237.BR slapd (8),
238.BR sh (1).
239