git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-tcl.5

   1 .TH SLAPD-TCL 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .SH NAME
   4 slapd-tcl \- Tcl backend to slapd
   5 .SH SYNOPSIS
   6 ETCDIR/slapd.conf
   7 .SH DESCRIPTION
   8 The Tcl backend to
   9 .BR slapd (8)
  10 works by embedding a
  11 .BR Tcl (3tcl)
  12 interpreter into
  13 .BR slapd (8).
  14 Any tcl database section of the configuration file
  15 .BR slapd.conf (5)
  16 must then specify what Tcl script to use.
  17 .LP
  18 This backend is experimental.
  19 .SH WARNING
  20 .B "This backend's calling conventions have changed since OpenLDAP 2.0."
  21 Previously, the 2nd argument to the procs was a message ID.
  22 Now they are an "operation ID" string.
  23 Also, proc abandon now gets a new
  24 .B abandonid
  25 argument.
  26 .SH CONFIGURATION
  27 These
  28 .B slapd.conf
  29 options apply to the TCL backend database.
  30 That is, they must follow a "database tcl" line and come before any
  31 subsequent "backend" or "database" lines.
  32 Other database options are described in the
  33 .BR slapd.conf (5)
  34 manual page.
  35 .TP
  36 .B scriptpath      <filename.tcl>
  37 The full path to the tcl script used for this database.
  38 .LP
  39 .B search   <proc>
  40 .br
  41 .B add      <proc>
  42 .br
  43 .B delete   <proc>
  44 .br
  45 .B modify   <proc>
  46 .br
  47 .B bind     <proc>
  48 .br
  49 .B unbind   <proc>
  50 .br
  51 .B modrdn   <proc>
  52 .br
  53 .B compare  <proc>
  54 .br
  55 .B abandon  <proc>
  56 .RS
  57 The procs for each ldap function.
  58 They refer to the tcl procs in the `scriptpath' script that handles them.
  59 .RE
  60 .TP
  61 .B tclrealm <interpreter name>
  62 This is one of the biggest pluses of using the tcl backend.
  63 The realm lets you group several databases to the same interpreter.
  64 This basically means they share the same global variables and proc space.
  65 So global variables, as well as all the procs, are callable between databases.
  66 If no tclrealm is specified, it is put into the "default" realm.
  67 .SH Variables passed to the procs
  68 .TP
  69 .B abandon { action opid suffix abandonid }
  70 .nf
  71 action    - Always equal to ABANDON.
  72 opid      - The opid of this ldap operation.
  73 suffix    - List of suffix(es) associated with the
  74             call.  Each one is an entry in a tcl
  75             formatted list (surrounded by {}'s).
  76 abandonid - The opid of the operation to abandon.
  77 .fi
  78 .TP
  79 .B add "{ action opid suffix entry }"
  80 .nf
  81 action - Always equal to ADD.
  82 opid   - The opid of this ldap operation.
  83 suffix - List of suffix(es), as above.
  84 entry  - Full entry to add. Each "type: val" is
  85          an element in a tcl formatted list.
  86 .fi
  87 .TP
  88 .B bind "{ action opid suffix dn method cred_len cred }"
  89 .nf
  90 action   - Always equal to BIND.
  91 opid     - The opid of this ldap operation.
  92 suffix   - List of suffix(es), as above.
  93 dn       - DN being bound to.
  94 method   - One of the ldap authentication methods.
  95 cred_len - Length of cred.
  96 cred     - Credentials being used to authenticate,
  97            according to RFC.  If this value is empty,
  98            then it should be considered an anonymous
  99            bind (??)
 100 .fi
 101 .TP
 102 .B compare "{ action opid suffix dn ava_type ava_value }"
 103 .nf
 104 action    - Always equal to COMPARE.
 105 opid      - The opid of this ldap operation.
 106 suffix    - List of suffix(es), as above.
 107 dn        - DN for compare.
 108 ava_type  - Type for comparison.
 109 ava_value - Value to compare.
 110 .fi
 111 .TP
 112 .B delete "{ action opid suffix dn }"
 113 .nf
 114 action    - Always equal to DELETE.
 115 opid      - The opid of this ldap operation.
 116 suffix    - List of suffix(es), as above.
 117 dn        - DN to delete.
 118 .fi
 119 .TP
 120 .B modify "{ action opid suffix dn mods }"
 121 .nf
 122 action - Always equal to MODIFY.
 123 opid   - The opid of this ldap operation.
 124 suffix - List of suffix(es), as above.
 125 dn     - DN to modify.
 126 mods   - Tcl list of modifications.
 127          The list is formatted in this way:
 128
 129          {
 130            { {op: type} {type: val} }
 131            { {op: type} {type: val} {type: val} }
 132            ...
 133          }
 134
 135          Newlines are not present in the actual var,
 136          they are present here for clarification.
 137          "op" is the type of modification
 138          (ADD, DELETE, REPLACE).
 139 .fi
 140 .TP
 141 .B modrdn "{ action opid suffix dn newrdn deleteoldrdn }"
 142 .nf
 143 action - Always equal to MODRDN.
 144 opid   - The opid of this ldap operation.
 145 suffix - List of suffix(es), as above.
 146 dn     - DN whose RDN is being renamed.
 147 newrdn - New RDN.
 148 deleteoldrdn - Boolean stating whether or not the
 149          old RDN should be removed after being renamed.
 150 .fi
 151 .TP
 152 .B
 153 search { action opid suffix base scope deref \
 154 sizelimit timelimit filterstr attrsonly attrlist }
 155 .nf
 156 action    - Always equal to SEARCH.
 157 opid      - The opid of this ldap operation.
 158 suffix    - List of suffix(es), as above.
 159 base      - Base for this search.
 160 scope     - Scope of search, ( 0 | 1 | 2 ).
 161 deref     - Alias dereferencing ( 0 | 1 | 2 | 3 ).
 162 sizelimit - Maximum number of entries to return.
 163 timelimit - Time limit for search.
 164 filterstr - Filter string as sent by the requester.
 165 attrsonly - Boolean for whether to list only the
 166             attributes, and not values as well.
 167 attrlist  - Tcl list if to retrieve.
 168 .fi
 169 .TP
 170 .B unbind "{ action opid suffix dn }"
 171 .nf
 172 action - Always equal to UNBIND.
 173 opid   - The opid of this ldap operation.
 174 suffix - List of suffix(es), as above.
 175 dn     - DN to unbind.
 176 .fi
 177 .LP
 178 An
 179 .I opid
 180 (operation ID) is a "connection ID/message ID" string identifying an
 181 operation.
 182 .LP
 183 .SH Return Method and Syntax
 184 There are only 2 return types.
 185 All procs must return a result to show status of the operation.
 186 The result is in this form:
 187 .LP
 188 .RS
 189 .nf
 190 { RESULT {code: <integer>} {matched: <partialdn>}
 191   {info: <string>} {} }
 192 .fi
 193 .RE
 194 .LP
 195 This is best accomplished with this type of tcl code
 196 .LP
 197 .RS
 198 .nf
 199   lappend ret_val "RESULT"
 200   lappend ret_val "code: 0"
 201   lappend ret_val ""
 202   return $ret_val
 203 .fi
 204 .RE
 205 .LP
 206 The final empty string (item in list) is necessary to point to the end
 207 of list.
 208 The `code', `matched', and `info' values are not necessary, and
 209 default values are given if not specified.
 210 The `code' value is usually an LDAP error in decimal notation from
 211 ldap.h.
 212 The `info', may be sent back to the client, depending on the
 213 function.
 214 In the bind proc, LDAP uses the value of `code' to indicate whether or
 215 not the authentication is acceptable.
 216 .LP
 217 The other type of return is for searches.
 218 It is similar format to the shell backend return (as is most of the
 219 syntax here).
 220 Its format follows:
 221 .LP
 222 .RS
 223 .nf
 224 {dn: o=Company, c=US} {attr: val} {objectclass: val} {}
 225 {dn: o=CompanyB, c=US} {attr: val} {objectclass: val} {}
 226 .fi
 227 .RE
 228 .LP
 229 Again, newlines are for visual purposes here.
 230 Also note the {} marking the end of the entry (same effect as a
 231 newline in ldif format).
 232 Here is some example code again, showing a full search proc example.
 233 .LP
 234 .RS
 235 .nf
 236 # Note that `args' lets you lump all possible args
 237 # into one var, used here for simplicity of example
 238 proc ldap:search { args } {
 239   # ...perform some operations...
 240
 241   lappend ret_val "dn: $rdn,$base"
 242   lappend ret_val "objectclass: $objcl"
 243   lappend ret_val "sn: $rdn"
 244   lappend ret_val "mail: $email"
 245   lappend ret_val ""
 246   # Now setup the result
 247   lappend ret_val "RESULT"
 248   lappend ret_val "code: 0"
 249   lappend ret_val ""
 250   return $ret_val
 251 }
 252 .fi
 253 .RE
 254 .LP
 255 NOTE: Newlines in the return value is acceptable in search entries
 256 (i.e. when returning base64 encoded binary entries).
 257 .LP
 258 .SH Builtin Commands and Variables
 259 .TP
 260 .B ldap:debug <msg>
 261 Allows you to send debug messages through OpenLDAP's native debugging
 262 system, this is sent as a LDAP_DEBUG_ANY and will be logged.
 263 Useful for debugging scripts or logging bind failures.
 264 .SH FILES
 265 .TP
 266 ETCDIR/slapd.conf
 267 default slapd configuration file
 268 .SH SEE ALSO
 269 .BR slapd.conf (5),
 270 .BR slapd (8),
 271 .BR Tcl (3tcl).