git.sur5r.net Git - openldap/blob - doc/man/man5/ldapfilter.conf.5

   1 .TH LDAPFILTER.CONF 5 "22 September 1998" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 ldapfilter.conf \- configuration file for LDAP get filter routines
   4 .SH SYNOPSIS
   5 ETCDIR/ldapfilter.conf
   6 .SH DESCRIPTION
   7 .LP
   8 The file
   9 .B ETCDIR/ldapfilter.conf
  10 contains information used by
  11 the LDAP get filter routines (see
  12 .BR ldap-getfilter (3)).
  13 Blank lines and
  14 lines that have a first character of `#' are treated as comments and
  15 ignored.  The configuration information consists of lines that contain
  16 one, two, three, four, or five tokens.  Tokens are separated
  17 by white space, and double quotes `"' can be used to include white space
  18 inside a token.
  19 .LP
  20 The file consists of a sequence of one or more filter sets.  A filter
  21 set begins with a line containing a single token called a
  22 .I tag.
  23 The
  24 .I tag
  25 is used in the
  26 .BR ldap_getfirstfilter (3)
  27 call to select the filter set.
  28 .LP
  29 The filter set consists of a sequence of one or more filter lists.  The
  30 first line in a filter list must contain four or five tokens: the
  31 .I value pattern,
  32 the
  33 .I delimiter list,
  34 a
  35 .I filter template,
  36 a
  37 .I match description,
  38 and an optional
  39 .I search scope.
  40 The
  41 .I value pattern
  42 is a regular expression that is matched against the
  43 .B value
  44 passed to the
  45 .BR ldap_getfirstfilter (3)
  46 call to select the filter list.
  47 .LP
  48 The
  49 .I delimiter list
  50 is a list of characters (in the form of a single string) that are used to
  51 break the
  52 .B value
  53 into distinct words.
  54 .LP
  55 The
  56 .I filter template
  57 is used to construct an LDAP filter (it is described further below)
  58 .LP
  59 The
  60 .I match description
  61 is returned to the called along with a filter as a piece of text that can
  62 be used to describe the sort of LDAP search that took place.  It should
  63 correctly compete both of the following phrases:
  64 "One
  65 .I match description
  66 match was found for..."
  67 and
  68 "Three
  69 .I match description
  70 matches were found for...."
  71 .LP
  72 The
  73 .I search scope
  74 is optional, and should be one of "base", "onelevel", or "subtree".  If
  75 .I search scope
  76 is not provided, the default is "subtree".
  77 .LP
  78 The remaining lines of the filter list should contain two or three tokens,
  79 a
  80 .I filter template,
  81 a
  82 .I match description
  83 and an optional
  84 .I search scope
  85 (as described above).
  86 .LP
  87 The
  88 .I filter template
  89 is similar in concept to a printf(3) style format
  90 string.  Everything is taken literally except for the character
  91 sequences:
  92 .nf
  93 .ft I
  94     %v
  95     %v$
  96     %vN
  97     %vM-N
  98     %vN-
  99 .ft
 100 .fi
 101 A plain
 102 .I %v
 103 means to substitute the entire
 104 .B value
 105 string in place of the
 106 .I %v.
 107 .I %v$
 108 means substitute the last word in this spot.
 109 A
 110 .I %vN,
 111 where N is a single digit 1-9, means substitute word N in this spot.
 112 Words are number from left to right within the value starting at 1.
 113 A
 114 .I %vM-N,
 115 where M and N are both single digits 1-9, means substitute the indicated
 116 sequence of words.
 117 A
 118 .I %vN-,
 119 where N is again a single digit 1-9, means substitute word N through the
 120 last word in
 121 .B value.
 122 .SH EXAMPLE
 123 The following ldap filter configuration file contains two filter sets
 124 .RB ( finger
 125 and
 126 .B go500gw
 127 .BR onelevel ),
 128 each of which contains four filter lists.
 129 .LP
 130 .nf
 131   # ldap filter file
 132   #
 133   finger
 134     "="                " "     "%v"                    "arbitrary filter"
 135
 136     "[0-9][0-9\-]*"    " "     "(telephoneNumber=*%v)" "phone number"
 137
 138     "@"                " "     "(mail=%v)"             "email address"
 139
 140     "^.[. _].*"       ". _"   "(cn=%v1* %v2-)"        "first initial"
 141
 142     ".*[. _].$"        ". _"   "(cn=%v1-*)"            "last initial"
 143
 144     "[. _]"            ". _"   "(|(sn=%v1-)(cn=%v1-))"        "exact"
 145                                "(|(sn~=%v1-)(cn~=%v1-))"      "approximate"
 146
 147     ".*"               ". "    "(|(cn=%v1)(sn=%v1)(uid=%v1))" "exact"
 148                                "(|(cn~=%v1)(sn~=%v1))"        "approximate"
 149
 150   "go500gw onelevel"
 151     "^..$"  " "   "(|(o=%v)(c=%v)(l=%v)(co=%v))"       "exact" "onelevel"
 152                   "(|(o~=%v)(c~=%v)(l~=%v)(co~=%v))"   "approximate" "onelevel"
 153
 154     " "     " "   "(|(o=%v)(l=%v)(co=%v)"       "exact"        "onelevel"
 155                   "(|(o~=%v)(l~=%v)(co~=%v)"    "approximate"  "onelevel"
 156
 157     "\."    " "   "(associatedDomain=%v)"       "exact"        "onelevel"
 158
 159     ".*"    " "   "(|(o=%v)(l=%v)(co=%v)"       "exact"        "onelevel"
 160                   "(|(o~=%v)(l~=%v)(co~=%v)"    "approximate"  "onelevel"
 161 .fi
 162 .LP
 163 The call
 164 .ft B
 165 ldap_getfirstfilter( lfdp, "finger", "m.smith" );
 166 .ft
 167 will return an LDAPFiltInfo structure with the
 168 .B lfi_filter
 169 member containing the string
 170 .I (cn=m* smith)
 171 with the
 172 .B lfi_desc
 173 member containing the string
 174 .I first initial,
 175 and
 176 .B lfi_scope
 177 containing the value LDAP_SCOPE_SUBTREE.
 178 .LP
 179 The call
 180 .ft B
 181 ldap_getfirstfilter( lfdp, "go500gw onelevel", "umich" );
 182 .ft
 183 will return an LDAPFiltInfo structure with the
 184 .B lfi_filter
 185 member containing the string
 186 .I (|(o=umich)(l=umich)(co=umich)
 187 with the
 188 .B lfi_desc
 189 member containing the string
 190 .I exact,
 191 and
 192 .B lfi_scope
 193 containing the value LDAP_SCOPE_ONELEVEL.
 194 .SH FILES
 195 ETCDIR/ldapfilter.conf
 196 .SH SEE ALSO
 197 .BR ldap (3),
 198 .BR ldap_getfilter (3)
 199 .SH ACKNOWLEDGEMENTS
 200 .B      OpenLDAP
 201 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 202 .B      OpenLDAP
 203 is derived from University of Michigan LDAP 3.3 Release.