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

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