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

   1 .TH LDAPSEARCHPREFS.CONF 5 "20 August 2000" "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 ldapsearchprefs.conf \- configuration file for LDAP search preference routines
   7 .SH SYNOPSIS
   8 ETCDIR/ldapsearchprefs.conf
   9 .SH DESCRIPTION
  10 .LP
  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.
  17 .LP
  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.
  21 .LP
  22 The first non-commment line specifies the version of the template
  23 information and must contain the token
  24 .I Version
  25 followed by an integer version number.  E.g.,
  26 .nf
  27 .ft B
  28     Version 1
  29 .ft
  30 .fi
  31 The current version is
  32 .I 1,
  33 so the above example is always the correct opening line.
  34 .LP
  35 The remainder of the file consists of one or more search preference
  36 configurations.
  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
  40 .I so_objtypeprompt
  41 member of the
  42 .I ldap_searchobj
  43 structure.
  44 E.g.,
  45 .nf
  46 .ft B
  47     "People"
  48 .ft
  49 .fi
  50 specifies a label for a search preference designed to find X.500
  51 entries for People.
  52 .LP
  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
  56 .I so_options
  57 member of the
  58 .I ldap_searchobj
  59 structure and can be tested using the LDAP_IS_SEARCHOBJ_OPTION_SET() macro.
  60 Use "" if no special options are desired.
  61 .LP
  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
  74 ("More Choices").
  75 .LP
  76 For example:
  77 .nf
  78 .ft B
  79     "Search For:"
  80 .ft
  81 .fi
  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
  84 the
  85 .I so_prompt
  86 member of the
  87 .I ldap_searchobj
  88 structure.
  89
  90 .LP
  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:
  94 .nf
  95 .ft B
  96     "(&(objectClass=person)"
  97 .ft
  98 .fi
  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
 102 stored in the
 103 .I so_filterprefix
 104 member of the
 105 .I ldap_searchobj
 106 structure.
 107
 108 .LP
 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.
 111 The line
 112 .nf
 113 .ft B
 114     "xax500-People"
 115 .ft
 116 .fi
 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
 119 stored in the
 120 .I so_filtertag
 121 member of the
 122 .I ldap_searchobj
 123 structure.
 124
 125 .LP
 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:
 128 .nf
 129 .ft B
 130     "title"
 131 .ft
 132 .fi
 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.
 137 .nf
 138 .ft B
 139     "Title:"
 140 .ft
 141 .fi
 142 The above information is stored in the
 143 .I so_defaultselectattr
 144 and
 145 .I so_defaultselecttext
 146 members of the
 147 .I ldap_searchobj
 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).
 151
 152 .LP
 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
 155 more information.
 156
 157 .LP
 158 The next section is a list of "More Choices" search options, terminated by
 159 a line containing only the string "END".  Example:
 160 .nf
 161 .ft B
 162   "Common Name" cn      11111   ""      ""
 163   "Surname"     sn      11111   ""      ""
 164   "Business Phone"      "telephoneNumber"       11101   ""      ""
 165   END
 166 .ft
 167 .fi
 168
 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.
 183
 184 .LP
 185 The next section is a list of search match options, terminated by a
 186 a line containing only the string "END".  Example:
 187 .nf
 188 .ft B
 189   "exactly matches"     "(%a=%v))"
 190   "approximately matches"       "(%a~=%v))"
 191   "starts with" "(%a=%v*))"
 192   "ends with"   "(%a=*%v))"
 193   "contains"    "(%a=*%v*))"
 194   END
 195 .ft
 196 .fi
 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".
 202
 203 .SH EXAMPLE
 204 The following example illustrates one possible configuration of search
 205 preferences for "people".
 206 .LP
 207 .nf
 208 # Version number
 209 Version 1
 210 # Name for this search object
 211 People
 212 # Label to place before text box user types in
 213 "Search For:"
 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
 217 "xax500-People"
 218 # If a search results in > 1 match, retrieve this attribute to help
 219 # user disambiguate the entries...
 220 multilineDescription
 221 # ...and label it with this string:
 222 "Description"
 223 # Search scope to use when searching
 224 subtree
 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  ""  ""
 233 END
 234 # Match types
 235 "exactly matches"               "(%a=%v))"
 236 "approximately matches"         "(%a~=%v))"
 237 "starts with"                   "(%a=%v*))"
 238 "ends with"                     "(%a=*%v))"
 239 "contains"                      "(%a=*%v*))"
 240 END
 241 .fi
 242 .LP
 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".
 245 .SH FILES
 246 ETCDIR/ldapsearchprefs.conf
 247 .SH SEE ALSO
 248 .BR ldap (3).
 249 .BR ldap-searchprefs (3)
 250 .SH ACKNOWLEDGEMENTS
 251 .B      OpenLDAP
 252 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 253 .B      OpenLDAP
 254 is derived from University of Michigan LDAP 3.3 Release.