1 .TH LDAPSEARCHPREFS.CONF 5 "22 September 1998" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
4 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
6 ldapsearchprefs.conf \- configuration file for LDAP search preference routines
8 ETCDIR/ldapsearchprefs.conf
11 The file ETCDIR/ldapsearchprefs.conf contains information used by
12 the LDAP search preference routines (see ldap-searchpref(3)). Blank lines
13 and lines that have a first character of `#' are treated as comments and
14 ignored. Non-comment lines contain one or more tokens. Tokens are
15 separated by white space, and double quotes `"' can be used to include
16 white space inside a token.
18 Search preferences are typically used by LDAP-based client programs to
19 specify what a user may search for, which attributes are searched, and
20 which options are available to the user.
22 The first non-commment line specifies the version of the template
23 information and must contain the token
25 followed by an integer version number. E.g.,
31 The current version is
33 so the above example is always the correct opening line.
35 The remainder of the file consists of one or more search preference
37 The first line of a search preference is a human-readable name for the
38 type of object being searched for, e.g. "People" or "Organizations".
39 This name is stored in the
50 specifies a label for a search preference designed to find X.500
53 The next line specifies a list of options for this search object. The
54 only option currently allowed is "internal" which means that this search
55 object should not be presented directly to a user. Options are placed in the
59 structure and can be tested using the LDAP_IS_SEARCHOBJ_OPTION_SET() macro.
60 Use "" if no special options are desired.
62 The next line specifes a label
63 to use for "Fewer Choices" (for lack of a better term) searches. "Fewer
64 Choices" searches are those where the user's input is fed to the
65 ldap_filter routines to determine an appropriate filter to use. This
66 contrasts with explicitly-constructed LDAP filters, or "More Choices"
67 searches, where the user can explicitly construct an LDAP filter. The
68 "Fewer" and "More Choices" terms derive from the maX.500, waX.500 and
69 xax500 directory user agents, which offer two configurations of their
70 "Find Entry" dialogs - one where the user types a search string, and the
71 client code attempts to find reasonable filter(s) to use in searching
72 ("Fewer Choices"), and one where the user can select from several pop-up
73 menus which allow complete specification of the search to be performed
82 can be used by LDAP client programs to label the field into which the
83 user can type a "Fewer Choices" search. This information is stored in
91 The next line specifies an LDAP filter prefix to append to all "More Choices"
92 searched. This is typically used to limit the types of entries returned
93 to those containing a specific object class. For example:
96 "(&(objectClass=person)"
99 would cause only entries containing the object class "person" to be
100 returned by a search. Note that parentheses may be unbalanced here, since
101 this is a filter prefix, not an entire filter. This information is
109 The next line is an LDAP filter tag (see ldap-filter(3)) which specifies
110 the set of LDAP filters to be applied for "Fewer Choices" searching.
117 would tell the client program to use the set of LDAP filters from the
118 ldap filter configuration file tagged "xax500-People". This information is
126 The next line specifies an LDAP attribute to retrieve to help the user
127 choose when several entries match the search terms specified. For example:
133 specifies that if more than one entry matches the search criteria, the
134 client program should retrieve the "title" attribute that and present
135 that to the user to allow them to select the appropriate entry.
136 The next line specifies a label for the above attribute, e.g.
142 The above information is stored in the
143 .I so_defaultselectattr
145 .I so_defaultselecttext
148 structure. Note that these are defaults, and are intended to be overridden
149 by the sa_selectattr and sa_selecttext fields of the ldap_searchattr
150 data structure (see below).
153 The next line specifies the scope of the LDAP search to be performed.
154 Acceptable values are subtree, onelevel, and base. See ldap(3) for
158 The next section is a list of "More Choices" search options, terminated by
159 a line containing only the string "END". Example:
162 "Common Name" cn 11111 "" ""
163 "Surname" sn 11111 "" ""
164 "Business Phone" "telephoneNumber" 11101 "" ""
169 Each line represents one method of searching. In this example, there
170 are three ways of searching - by Common Name, by Surname, and by
171 Business Phone number. The first field is the text which should be
172 displayed to user. The second field is the attribute which will be
173 searched. The third field is a bitmap which specifies which of the
174 match types (discussed below) are permitted for this search type. A
175 "1" value in a given bit position indicates that a particular
176 match type is valid, and a "0" indicates that is it not valid. The
177 fourth and fifth fields are, respectively, the select attribute name
178 (corresponding to the sa_selectattr field of the ldap_searchattr data
179 structure) and on-screen name for the select attribute (corresponding
180 to the sa_selecttext field). These values are intended to override
181 the so_defaultselectattr and so_defaultselecttext values, described
182 above. If blank, the client software should use the default values above.
185 The next section is a list of search match options, terminated by a
186 a line containing only the string "END". Example:
189 "exactly matches" "(%a=%v))"
190 "approximately matches" "(%a~=%v))"
191 "starts with" "(%a=%v*))"
192 "ends with" "(%a=*%v))"
193 "contains" "(%a=*%v*))"
197 In this example, there are five ways of refining the search. For each method,
198 there is an LDAP filter suffix which is appended to the ldap filter thus
199 far constructed. The routine ldap_build_filter() may be used to construct
200 the whole filter. It substitutes the appropriate attribute for "%a" in the
201 filter, and a value (generally, something the user types) for "%v".
204 The following example illustrates one possible configuration of search
205 preferences for "people".
210 # Name for this search object
212 # Label to place before text box user types in
214 # Filter prefix to append to all "More Choices" searches
215 "(&(objectClass=person)"
216 # Tag to use for "Fewer Choices" searches - from ldapfilter.conf file
218 # If a search results in > 1 match, retrieve this attribute to help
219 # user disambiguate the entries...
221 # ...and label it with this string:
223 # Search scope to use when searching
225 # Follows a list of "More Choices" search options. Format is:
226 # Label, attribute, select-bitmap, extra attr display name, extra attr ldap name
227 # If last two are null, "Fewer Choices" name/attributes used
228 "Common Name" cn 11111 "" ""
229 "Surname" sn 11111 "" ""
230 "Business Phone" "telephoneNumber" 11101 "" ""
231 "E-Mail Address" "mail" 11111 "" ""
232 "Uniqname" "uid" 11111 "" ""
235 "exactly matches" "(%a=%v))"
236 "approximately matches" "(%a~=%v))"
237 "starts with" "(%a=%v*))"
238 "ends with" "(%a=*%v))"
239 "contains" "(%a=*%v*))"
243 In this example, the user may search for People. For "fewer choices" searching,
244 the tag for the ldap filter config file is "xax500-People".
246 ETCDIR/ldapsearchprefs.conf
249 .BR ldap-searchprefs (3)
252 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
254 is derived from University of Michigan LDAP 3.3 Release.