external/bsd/openldap/man/slapd-perl.5

   1 .TH SLAPD-PERL 5 "2008/07/16" "OpenLDAP 2.4.11"
   2 .\" $OpenLDAP: pkg/ldap/doc/man/man5/slapd-perl.5,v 1.7 2005/07/04 04:57:11 hallvard Exp $
   3 .SH NAME
   4 slapd-perl \- Perl backend to slapd
   5 .SH SYNOPSIS
   6 /etc/openldap/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     # process unknown config file lines,
  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 with unknown
 124 .BR slapd.conf (5)
 125 configuration file lines.
 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 .SH EXAMPLE
 163 There is an example Perl module `SampleLDAP' in the slapd/back-perl/
 164 directory in the OpenLDAP source tree.
 165 .SH ACCESS CONTROL
 166 The
 167 .B passwd
 168 backend does not honor any of the access control semantics described in
 169 .BR slapd.access (5);
 170 all access control is delegated to the underlying PERL scripting.
 171 Only
 172 .B read (=r)
 173 access to the
 174 .B entry
 175 pseudo-attribute and to the other attribute values of the entries
 176 returned by the
 177 .B search
 178 operation is honored, which is performed by the frontend.
 179 .SH WARNING
 180 The interface of this backend to the perl module MAY change.
 181 Any suggestions would greatly be appreciated.
 182 .SH FILES
 183 .TP
 184 /etc/openldap/slapd.conf
 185 default slapd configuration file
 186 .SH SEE ALSO
 187 .BR slapd.conf (5),
 188 .BR slapd (8),
 189 .BR perl (1).