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