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