ldapsearchprefs.conf - configuration file for LDAP search
preference routines
SYNOPSIS
/etc/openldap/ldapsearchprefs.conf
DESCRIPTION
The file /etc/openldap/ldapsearchprefs.conf contains
information used by the LDAP search preference routines
(see ldap-searchpref(3)). Blank lines and lines that have
a first character of `#' are treated as comments and
ignored. Non-comment lines contain one or more tokens.
Tokens are separated by white space, and double quotes `"'
can be used to include white space inside a token.
Search preferences are typically used by LDAP-based client
programs to specify what a user may search for, which
attributes are searched, and which options are available
to the user.
The first non-commment line specifies the version of the
template information and must contain the token Version
followed by an integer version number. E.g.,
Version 1
The current version is 1, so the above example is always
the correct opening line.
The remainder of the file consists of one or more search
preference configurations. The first line of a search
preference is a human-readable name for the type of object
being searched for, e.g. "People" or "Organizations".
This name is stored in the so_objtypeprompt member of the
ldap_searchobj structure. E.g.,
"People"
specifies a label for a search preference designed to find
X.500 entries for People.
The next line specifies a list of options for this search
object. The only option currently allowed is "internal"
which means that this search object should not be pre
sented directly to a user. Options are placed in the
so_options member of the ldap_searchobj structure and can
be tested using the LDAP_IS_SEARCHOBJ_OPTION_SET() macro.
Use "" if no special options are desired.
The next line specifes a label to use for "Fewer Choices"
(for lack of a better term) searches. "Fewer Choices"
searches are those where the user's input is fed to the
ldap_filter routines to determine an appropriate filter to
use. This contrasts with explicitly-constructed LDAP fil
ters, or "More Choices" searches, where the user can
explicitly construct an LDAP filter. The "Fewer" and
"More Choices" terms derive from the maX.500, waX.500 and
tions of their "Find Entry" dialogs - one where the user
types a search string, and the client code attempts to
find reasonable filter(s) to use in searching ("Fewer
Choices"), and one where the user can select from several
pop-up menus which allow complete specification of the
search to be performed ("More Choices").
For example:
"Search For:"
can be used by LDAP client programs to label the field
into which the user can type a "Fewer Choices" search.
This information is stored in the so_prompt member of the
ldap_searchobj structure.
The next line specifies an LDAP filter prefix to append to
all "More Choices" searched. This is typically used to
limit the types of entries returned to those containing a
specific object class. For example:
"(&(objectClass=person)"
would cause only entries containing the object class "per
son" to be returned by a search. Note that parentheses
may be unbalanced here, since this is a filter prefix, not
an entire filter. This information is stored in the
so_filterprefix member of the ldap_searchobj structure.
The next line is an LDAP filter tag (see ldap-filter(3))
which specifies the set of LDAP filters to be applied for
"Fewer Choices" searching. The line
"xax500-People"
would tell the client program to use the set of LDAP fil
ters from the ldap filter configuration file tagged
"xax500-People". This information is stored in the
so_filtertag member of the ldap_searchobj structure.
The next line specifies an LDAP attribute to retrieve to
help the user choose when several entries match the search
terms specified. For example:
"title"
specifies that if more than one entry matches the search
criteria, the client program should retrieve the "title"
attribute that and present that to the user to allow them
to select the appropriate entry. The next line specifies
a label for the above attribute, e.g.
"Title:"
The above information is stored in the so_defaultselec
tattr and so_defaultselecttext members of the
ldap_searchobj structure. Note that these are defaults,
and are intended to be overridden by the sa_selectattr and
sa_selecttext fields of the ldap_searchattr data structure
(see below).
performed. Acceptable values are subtree, onelevel, and
base. See ldap(3) for more information.
The next section is a list of "More Choices" search
options, terminated by a line containing only the string
"END". Example:
"Common Name" cn 11111 "" ""
"Surname" sn 11111 "" ""
"Business Phone" "telephoneNumber" 11101 "" ""
END
Each line represents one method of searching. In this
example, there are three ways of searching - by Common
Name, by Surname, and by Business Phone number. The first
field is the text which should be displayed to user. The
second field is the attribute which will be searched. The
third field is a bitmap which specifies which of the match
types (discussed below) are permitted for this search
type. A "1" value in a given bit position indicates that
a particular match type is valid, and a "0" indicates that
is it not valid. The fourth and fifth fields are, respec
tively, the select attribute name (corresponding to the
sa_selectattr field of the ldap_searchattr data structure)
and on-screen name for the select attribute (corresponding
to the sa_selecttext field). These values are intended to
override the so_defaultselectattr and so_defaultselecttext
values, described above. If blank, the client software
should use the default values above.
The next section is a list of search match options, termi
nated by a a line containing only the string "END". Exam
ple:
"exactly matches" "(%a=%v))"
"approximately matches" "(%a~=%v))"
"starts with" "(%a=%v*))"
"ends with" "(%a=*%v))"
"contains" "(%a=*%v*))"
END
In this example, there are five ways of refining the
search. For each method, there is an LDAP filter suffix
which is appended to the ldap filter thus far constructed.
The routine ldap_build_filter() may be used to construct
the whole filter. It substitutes the appropriate
attribute for "%a" in the filter, and a value (generally,
something the user types) for "%v".
EXAMPLE
The following example illustrates one possible configura
tion of search preferences for "people".
Version 1
# Name for this search object
People
# Label to place before text box user types in
"Search For:"
# Filter prefix to append to all "More Choices" searches
"(&(objectClass=person)"
# Tag to use for "Fewer Choices" searches - from ldapfilter.conf file
"xax500-People"
# If a search results in > 1 match, retrieve this attribute to help
# user disambiguate the entries...
multilineDescription
# ...and label it with this string:
"Description"
# Search scope to use when searching
subtree
# Follows a list of "More Choices" search options. Format is:
# Label, attribute, select-bitmap, extra attr display name, extra attr ldap name
# If last two are null, "Fewer Choices" name/attributes used
"Common Name" cn 11111 "" ""
"Surname" sn 11111 "" ""
"Business Phone" "telephoneNumber" 11101 "" ""
"E-Mail Address" "mail" 11111 "" ""
"Uniqname" "uid" 11111 "" ""
END
# Match types
"exactly matches" "(%a=%v))"
"approximately matches" "(%a~=%v))"
"starts with" "(%a=%v*))"
"ends with" "(%a=*%v))"
"contains" "(%a=*%v*))"
END
In this example, the user may search for People. For
"fewer choices" searching, the tag for the ldap filter
config file is "xax500-People".
FILES
/etc/openldap/ldapsearchprefs.conf
SEE ALSO
ldap(3). ldap-searchprefs(3)
ACKNOWLEDGEMENTS
OpenLDAP is developed and maintained by The OpenLDAP Pro
ject (http://www.openldap.org/). OpenLDAP is derived from
University of Michigan LDAP 3.3 Release.
Man(1) output converted with
man2html