1.lf 1 stdin
2.TH SLAPD-PERL 5 "2020/04/28" "OpenLDAP 2.4.50"
3.\" $OpenLDAP$
4.SH NAME
5slapd\-perl \- Perl backend to slapd
6.SH SYNOPSIS
7/etc/openldap/slapd.conf
8.SH DESCRIPTION
9The Perl backend to
10.BR slapd (8)
11works by embedding a
12.BR perl (1)
13interpreter into
14.BR slapd (8).
15Any perl database section of the configuration file
16.BR slapd.conf (5)
17must then specify what Perl module to use.
18.B Slapd
19then creates a new Perl object that handles all the requests for that
20particular instance of the backend.
21.LP
22You will need to create a method for each one of the
23following actions:
24.LP
25.nf
26  * new        # creates a new object,
27  * search     # performs the ldap search,
28  * compare    # does a compare,
29  * modify     # modifies an entry,
30  * add        # adds an entry to backend,
31  * modrdn     # modifies an entry's rdn,
32  * delete     # deletes an ldap entry,
33  * config     # module-specific config directives,
34  * init       # called after backend is initialized.
35.fi
36.LP
37Unless otherwise specified, the methods return the result code
38which will be returned to the client.  Unimplemented actions
39can just return unwillingToPerform (53).
40.TP
41.B new
42This method is called when the configuration file encounters a 
43.B perlmod
44line.
45The module in that line is then effectively `use'd into the perl
46interpreter, then the \fBnew\fR method is called to create a new
47object.
48Note that multiple instances of that object may be instantiated, as
49with any perl object.
50.\" .LP
51The
52.B new
53method receives the class name as argument.
54.TP
55.B search
56This method is called when a search request comes from a client.
57It arguments are as follows:
58.nf
59  * object reference
60  * base DN
61  * scope
62  * alias dereferencing policy
63  * size limit
64  * time limit
65  * filter string
66  * attributes only flag (1 for yes)
67  * list of attributes to return (may be empty)
68.fi
69.LP
70Return value: (resultcode, ldif-entry, ldif-entry, ...)
71.TP
72.B compare
73This method is called when a compare request comes from a client.
74Its arguments are as follows.
75.nf
76  * object reference
77  * dn
78  * attribute assertion string
79.fi
80.LP
81.TP
82.B modify
83This method is called when a modify request comes from a client.
84Its arguments are as follows.
85.nf
86  * object reference
87  * dn
88  * a list formatted as follows
89    ({ "ADD" | "DELETE" | "REPLACE" },
90     attributetype, value...)...
91.fi
92.LP
93.TP
94.B add
95This method is called when a add request comes from a client.
96Its arguments are as follows.
97.nf
98  * object reference
99  * entry in string format
100.fi
101.LP
102.TP
103.B modrdn
104This method is called when a modrdn request comes from a client.
105Its arguments are as follows.
106.nf
107  * object reference
108  * dn
109  * new rdn
110  * delete old dn flag (1 means yes)
111.fi
112.LP
113.TP
114.B delete
115This method is called when a delete request comes from a client.
116Its arguments are as follows.
117.nf
118  * object reference
119  * dn
120.fi
121.LP
122.TP
123.B config
124This method is called once for each perlModuleConfig line in the
125.BR slapd.conf (5)
126configuration file.
127Its arguments are as follows.
128.nf
129  * object reference
130  * array of arguments on line
131.fi
132.LP
133Return value: nonzero if this is not a valid option.
134.TP
135.B init
136This method is called after backend is initialized.
137Its argument is as follows.
138.nf
139  * object reference
140.fi
141.LP
142Return value: nonzero if initialization failed.
143.SH CONFIGURATION
144These
145.B slapd.conf
146options apply to the PERL backend database.
147That is, they must follow a "database perl" line and come before any
148subsequent "backend" or "database" lines.
149Other database options are described in the
150.BR slapd.conf (5)
151manual page.
152.TP
153.B perlModulePath /path/to/libs
154Add the path to the @INC variable.
155.TP
156.B perlModule ModName
157`Use' the module name ModName from ModName.pm
158.TP
159.B filterSearchResults
160Search results are candidates that need to be filtered (with the
161filter in the search request), rather than search results to be
162returned directly to the client.
163.TP
164.B perlModuleConfig <arguments>
165Invoke the module's config method with the given arguments.
166.SH EXAMPLE
167There is an example Perl module `SampleLDAP' in the slapd/back\-perl/
168directory in the OpenLDAP source tree.
169.SH ACCESS CONTROL
170The
171.B perl
172backend does not honor any of the access control semantics described in
173.BR slapd.access (5);
174all access control is delegated to the underlying PERL scripting.
175Only
176.B read (=r)
177access to the
178.B entry
179pseudo-attribute and to the other attribute values of the entries
180returned by the
181.B search
182operation is honored, which is performed by the frontend.
183.SH WARNING
184The interface of this backend to the perl module MAY change.
185Any suggestions would greatly be appreciated.
186
187Note: in previous versions, any unrecognized lines in the slapd.conf
188file were passed to the perl module's config method. This behavior is
189deprecated (but still allowed for backward compatibility), and the
190perlModuleConfig directive should instead be used to invoke the
191module's config method. This compatibility feature will be removed at
192some future date.
193.SH FILES
194.TP
195/etc/openldap/slapd.conf
196default slapd configuration file
197.SH SEE ALSO
198.BR slapd.conf (5),
199.BR slapd (8),
200.BR perl (1).
201