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

   1 .TH LDAPSEARCHPREFS.CONF 5 "22 September 1998" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 ldapsearchprefs.conf \- configuration file for LDAP search preference routines
   4 .SH SYNOPSIS
   5 ETCDIR/ldapsearchprefs.conf
   6 .SH DESCRIPTION
   7 .LP
   8 The file ETCDIR/ldapsearchprefs.conf contains information used by
   9 the LDAP search preference routines (see ldap-searchpref(3)).  Blank lines
  10 and lines that have a first character of `#' are treated as comments and
  11 ignored.  Non-comment lines contain one or more tokens.  Tokens are
  12 separated by white space, and double quotes `"' can be used to include
  13 white space inside a token.
  14 .LP
  15 Search preferences are typically used by LDAP-based client programs to
  16 specify what a user may search for, which attributes are searched, and
  17 which options are available to the user.
  18 .LP
  19 The first non-commment line specifies the version of the template
  20 information and must contain the token
  21 .I Version
  22 followed by an integer version number.  E.g.,
  23 .nf
  24 .ft B
  25     Version 1
  26 .ft
  27 .fi
  28 The current version is
  29 .I 1,
  30 so the above example is always the correct opening line.
  31 .LP
  32 The remainder of the file consists of one or more search preference
  33 configurations.
  34 The first line of a search preference is a human-readable name for the
  35 type of object being searched for, e.g. "People" or "Organizations".
  36 This name is stored in the
  37 .I so_objtypeprompt
  38 member of the
  39 .I ldap_searchobj
  40 structure.
  41 E.g.,
  42 .nf
  43 .ft B
  44     "People"
  45 .ft
  46 .fi
  47 specifies a label for a search preference designed to find X.500
  48 entries for People.
  49 .LP
  50 The next line specifies a list of options for this search object.  The
  51 only option currently allowed is "internal" which means that this search
  52 object should not be presented directly to a user.  Options are placed in the
  53 .I so_options
  54 member of the
  55 .I ldap_searchobj
  56 structure and can be tested using the LDAP_IS_SEARCHOBJ_OPTION_SET() macro.
  57 Use "" if no special options are desired.
  58 .LP
  59 The next line specifes a label
  60 to use for "Fewer Choices" (for lack of a better term) searches.  "Fewer
  61 Choices" searches are those where the user's input is fed to the
  62 ldap_filter routines to determine an appropriate filter to use.  This
  63 contrasts with explicitly-constructed LDAP filters, or "More Choices"
  64 searches, where the user can explicitly construct an LDAP filter.  The
  65 "Fewer" and "More Choices" terms derive from the maX.500, waX.500 and
  66 xax500 directory user agents, which offer two configurations of their
  67 "Find Entry" dialogs - one where the user types a search string, and the
  68 client code attempts to find reasonable filter(s) to use in searching
  69 ("Fewer Choices"), and one where the user can select from several pop-up
  70 menus which allow complete specification of the search to be performed
  71 ("More Choices").
  72 .LP
  73 For example:
  74 .nf
  75 .ft B
  76     "Search For:"
  77 .ft
  78 .fi
  79 can be used by LDAP client programs to label the field into which the
  80 user can type a "Fewer Choices" search.  This information is stored in
  81 the
  82 .I so_prompt
  83 member of the
  84 .I ldap_searchobj
  85 structure.
  86
  87 .LP
  88 The next line specifies an LDAP filter prefix to append to all "More Choices"
  89 searched.  This is typically used to limit the types of entries returned
  90 to those containing a specific object class.  For example:
  91 .nf
  92 .ft B
  93     "(&(objectClass=person)"
  94 .ft
  95 .fi
  96 would cause only entries containing the object class "person" to be
  97 returned by a search.  Note that parentheses may be unbalanced here, since
  98 this is a filter prefix, not an entire filter.  This information is
  99 stored in the
 100 .I so_filterprefix
 101 member of the
 102 .I ldap_searchobj
 103 structure.
 104
 105 .LP
 106 The next line is an LDAP filter tag (see ldap-filter(3)) which specifies
 107 the set of LDAP filters to be applied for "Fewer Choices" searching.
 108 The line
 109 .nf
 110 .ft B
 111     "xax500-People"
 112 .ft
 113 .fi
 114 would tell the client program to use the set of LDAP filters from the
 115 ldap filter configuration file tagged "xax500-People".  This information is
 116 stored in the
 117 .I so_filtertag
 118 member of the
 119 .I ldap_searchobj
 120 structure.
 121
 122 .LP
 123 The next line specifies an LDAP attribute to retrieve to help the user
 124 choose when several entries match the search terms specified.  For example:
 125 .nf
 126 .ft B
 127     "title"
 128 .ft
 129 .fi
 130 specifies that if more than one entry matches the search criteria, the
 131 client program should retrieve the "title" attribute that and present
 132 that to the user to allow them to select the appropriate entry.
 133 The next line specifies a label for the above attribute, e.g.
 134 .nf
 135 .ft B
 136     "Title:"
 137 .ft
 138 .fi
 139 The above information is stored in the
 140 .I so_defaultselectattr
 141 and
 142 .I so_defaultselecttext
 143 members of the
 144 .I ldap_searchobj
 145 structure.  Note that these are defaults, and are intended to be overridden
 146 by the sa_selectattr and sa_selecttext fields of the ldap_searchattr
 147 data structure (see below).
 148
 149 .LP
 150 The next line specifies the scope of the LDAP search to be performed.
 151 Acceptable values are subtree, onelevel, and base.  See ldap(3) for
 152 more information.
 153
 154 .LP
 155 The next section is a list of "More Choices" search options, terminated by
 156 a line containing only the string "END".  Example:
 157 .nf
 158 .ft B
 159   "Common Name" cn      11111   ""      ""
 160   "Surname"     sn      11111   ""      ""
 161   "Business Phone"      "telephoneNumber"       11101   ""      ""
 162   END
 163 .ft
 164 .fi
 165
 166 Each line represents one method of searching.  In this example, there
 167 are three ways of searching - by Common Name, by Surname, and by
 168 Business Phone number.  The first field is the text which should be
 169 displayed to user.  The second field is the attribute which will be
 170 searched.  The third field is a bitmap which specifies which of the
 171 match types (discussed below) are permitted for this search type.  A
 172 "1" value in a given bit position indicates that a particular
 173 match type is valid, and a "0" indicates that is it not valid.  The
 174 fourth and fifth fields are, respectively, the select attribute name
 175 (corresponding to the sa_selectattr field of the ldap_searchattr data
 176 structure) and on-screen name for the select attribute (corresponding
 177 to the sa_selecttext field).  These values are intended to override
 178 the so_defaultselectattr and so_defaultselecttext values, described
 179 above.  If blank, the client software should use the default values above.
 180
 181 .LP
 182 The next section is a list of search match options, terminated by a
 183 a line containing only the string "END".  Example:
 184 .nf
 185 .ft B
 186   "exactly matches"     "(%a=%v))"
 187   "approximately matches"       "(%a~=%v))"
 188   "starts with" "(%a=%v*))"
 189   "ends with"   "(%a=*%v))"
 190   "contains"    "(%a=*%v*))"
 191   END
 192 .ft
 193 .fi
 194 In this example, there are five ways of refining the search.  For each method,
 195 there is an LDAP filter suffix which is appended to the ldap filter thus
 196 far constructed.  The routine ldap_build_filter() may be used to construct
 197 the whole filter.  It substitutes the appropriate attribute for "%a" in the
 198 filter, and a value (generally, something the user types) for "%v".
 199
 200 .SH EXAMPLE
 201 The following example illustrates one possible configuration of search
 202 preferences for "people".
 203 .LP
 204 .nf
 205 # Version number
 206 Version 1
 207 # Name for this search object
 208 People
 209 # Label to place before text box user types in
 210 "Search For:"
 211 # Filter prefix to append to all "More Choices" searches
 212 "(&(objectClass=person)"
 213 # Tag to use for "Fewer Choices" searches - from ldapfilter.conf file
 214 "xax500-People"
 215 # If a search results in > 1 match, retrieve this attribute to help
 216 # user disambiguate the entries...
 217 multilineDescription
 218 # ...and label it with this string:
 219 "Description"
 220 # Search scope to use when searching
 221 subtree
 222 # Follows a list of "More Choices" search options.  Format is:
 223 # Label, attribute, select-bitmap, extra attr display name, extra attr ldap name
 224 # If last two are null, "Fewer Choices" name/attributes used
 225 "Common Name"                   cn                 11111  ""  ""
 226 "Surname"                       sn                 11111  ""  ""
 227 "Business Phone"                "telephoneNumber"  11101  ""  ""
 228 "E-Mail Address"                "mail"             11111  ""  ""
 229 "Uniqname"                      "uid"              11111  ""  ""
 230 END
 231 # Match types
 232 "exactly matches"               "(%a=%v))"
 233 "approximately matches"         "(%a~=%v))"
 234 "starts with"                   "(%a=%v*))"
 235 "ends with"                     "(%a=*%v))"
 236 "contains"                      "(%a=*%v*))"
 237 END
 238 .fi
 239 .LP
 240 In this example, the user may search for People.  For "fewer choices" searching,
 241 the tag for the ldap filter config file is "xax500-People".
 242 .SH FILES
 243 ETCDIR/ldapsearchprefs.conf
 244 .SH SEE ALSO
 245 .BR ldap (3).
 246 .BR ldap-searchprefs (3)
 247 .SH ACKNOWLEDGEMENTS
 248 .B      OpenLDAP
 249 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 250 .B      OpenLDAP
 251 is derived from University of Michigan LDAP 3.3 Release.