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