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

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