usr/src/man/man4/ldapsearchprefs.conf.4

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 1997, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH LDAPSEARCHPREFS.CONF 4 "Jul 9, 2003"
   8 .SH NAME
   9 ldapsearchprefs.conf \- configuration file for LDAP search preference routines
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB/etc/opt/SUNWconn/ldap/current/ldapsearchprefs.conf\fR
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The \fBldapsearchprefs.conf\fR file contains information used by LDAP when
  20 searching the directory. Blank lines and lines that start with a hash ('#')
  21 character are treated as comments and ignored. Non-comment lines contain one or
  22 more tokens. Tokens are separated by white space, and double quotes can be used
  23 to include white space inside a token.
  24 .sp
  25 .LP
  26 Search preferences are typically used by LDAP-based client programs to specify
  27 what a user may search for, which attributes are searched, and which options
  28 are available to the user.
  29 .sp
  30 .LP
  31 The first non-commment line specifies the version of the template information
  32 and must contain the token \fBVersion\fR followed by an integer version number.
  33 For example:
  34 .sp
  35 .in +2
  36 .nf
  37 Version 1
  38 .fi
  39 .in -2
  40 .sp
  41
  42 .sp
  43 .LP
  44 The current version is \fI1,\fR so the above example is always the correct
  45 opening line.
  46 .sp
  47 .LP
  48 The remainder of the file consists of one or more search preference
  49 configurations. The first line of a search preference is a human-readable name
  50 for the type of object being searched for, for example \fBPeople\fR or
  51 \fBOrganizations\fR. This name is stored in the \fIso_objtypeprompt\fR member
  52 of the \fBldap_searchobj\fR structure (see \fBldap_searchprefs\fR(3LDAP)). For
  53 example:
  54 .sp
  55 .in +2
  56 .nf
  57 People
  58 .fi
  59 .in -2
  60 .sp
  61
  62 .sp
  63 .LP
  64 specifies a label for a search preference designed to find X.500 entries for
  65 people.
  66 .sp
  67 .LP
  68 The next line specifies a list of options for this search object. The only
  69 option currently allowed is "internal" which means that this search object
  70 should not be presented directly to a user. Options are placed in the
  71 \fIso_options\fR member of the \fIldap_searchobj\fR structure and can be tested
  72 using the \fBLDAP_IS_SEARCHOBJ_OPTION_SET()\fR macro. Use "" if no special
  73 options are required.
  74 .sp
  75 .LP
  76 The next line specifes a label to use for "Fewer Choices" searches. "Fewer
  77 Choices" searches are those where the user's input is fed to the ldap_filter
  78 routines to determine an appropriate filter to use. This contrasts with
  79 explicitly-constructed LDAP filters, or "More Choices" searches, where the user
  80 can explicitly construct an LDAP filter.
  81 .sp
  82 .LP
  83 For example:
  84 .sp
  85 .in +2
  86 .nf
  87 "Search For:"
  88 .fi
  89 .in -2
  90 .sp
  91
  92 .sp
  93 .LP
  94 can be used by LDAP client programs to label the field into which the user can
  95 type a "Fewer Choices" search.
  96 .sp
  97 .LP
  98 The next line specifies an LDAP filter prefix to append to all "More Choices"
  99 searched. This is typically used to limit the types of entries returned to
 100 those containing a specific object class. For example:
 101 .sp
 102 .in +2
 103 .nf
 104 "(&(objectClass=person)"
 105 .fi
 106 .in -2
 107 .sp
 108
 109 .sp
 110 .LP
 111 would cause only entries containing the object class \fIperson\fR to be
 112 returned by a search. Note that parentheses may be unbalanced here, since this
 113 is a filter prefix, not an entire filter.
 114 .sp
 115 .LP
 116 The next line is an LDAP filter tag which specifies the set of LDAP filters to
 117 be applied for "Fewer Choices" searching. The line
 118 .sp
 119 .in +2
 120 .nf
 121 \fB"x500-People"\fR
 122 .fi
 123 .in -2
 124 .sp
 125
 126 .sp
 127 .LP
 128 would tell the client program to use the set of LDAP filters from the ldap
 129 filter configuration file tagged "x500-People".
 130 .sp
 131 .LP
 132 The next line specifies an LDAP attribute to retrieve to help the user choose
 133 when several entries match the search terms specified. For example:
 134 .sp
 135 .in +2
 136 .nf
 137 "title"
 138 .fi
 139 .in -2
 140 .sp
 141
 142 .sp
 143 .LP
 144 specifies that if more than one entry matches the search criteria, the client
 145 program should retrieve the \fBtitle\fR attribute that and present that to the
 146 user to allow them to select the appropriate entry. The next line specifies a
 147 label for the above attribute, for example,
 148 .sp
 149 .in +2
 150 .nf
 151 "Title:"
 152 .fi
 153 .in -2
 154 .sp
 155
 156 .sp
 157 .LP
 158 Note that the values defined so far in the file are defaults, and are intended
 159 to be overridden by the specific search options that follow.
 160 .sp
 161 .LP
 162 The next line specifies the scope of the LDAP search to be performed.
 163 Acceptable values are subtree, onelevel, and base.
 164 .sp
 165 .LP
 166 The next section is a list of "More Choices" search options, terminated by a
 167 line containing only the string \fBEND\fR. For example:
 168 .sp
 169 .in +2
 170 .nf
 171 "Common Name"   cn      11111   ""      ""
 172 "Surname"       sn      11111   ""      ""
 173 "Business Phone"        "telephoneNumber"       11101   ""      ""
 174 END
 175 .fi
 176 .in -2
 177 .sp
 178
 179 .sp
 180 .LP
 181  Each line represents one method of searching. In this example, there are three
 182 ways of searching - by Common Name, by Surname, and by Business Phone number.
 183 The first field is the text which should be displayed to user. The second field
 184 is the attribute which will be searched. The third field is a bitmap which
 185 specifies which of the match types are permitted for this search type. A "1"
 186 value in a given bit position indicates that a particular match type is valid,
 187 and a "0" indicates that is it not valid. The fourth and fifth fields are,
 188 respectively, the select attribute name and on-screen name for the selected
 189 attribute. These values are intended to override the defaults defined above. If
 190 no specific values are specified, the client software uses the default values
 191 above.
 192 .sp
 193 .LP
 194 The next section is a list of search match options, terminated by a a line
 195 containing only the string \fBEND\fR. Example:
 196 .sp
 197 .in +2
 198 .nf
 199 "exactly matches"       "(%a=%v))"
 200 "approximately matches" "(%a~=%v))"
 201 "starts with"   "(%a=%v*))"
 202 "ends with"     "(%a=*%v))"
 203 "contains"      "(%a=*%v*))"
 204 END
 205 .fi
 206 .in -2
 207 .sp
 208
 209 .sp
 210 .LP
 211 In this example, there are five ways of refining the search. For each method,
 212 there is an LDAP filter suffix which is appended to the ldap filter.
 213 .SH EXAMPLES
 214 .LP
 215 \fBExample 1 \fRA Sample Configuration Using Search Preference for "people"
 216 .sp
 217 .LP
 218 The following example illustrates one possible configuration of search
 219 preferences for "people".
 220
 221 .sp
 222 .in +2
 223 .nf
 224 # Version number
 225 Version 1
 226 # Name for this search object
 227 People
 228 # Label to place before text box user types in
 229 "Search For:"
 230 # Filter prefix to append to all "More Choices" searches
 231 "(&(objectClass=person)"
 232 # Tag to use for "Fewer Choices" searches - from ldapfilter.conf file
 233 "x500-People"
 234 # If a search results in > 1 match, retrieve this attribute to help
 235 # user distinguish between the entries...
 236 multilineDescription
 237 # ...and label it with this string:
 238 "Description"
 239 # Search scope to use when searching
 240 subtree
 241 # Follows a list of "More Choices" search options. Format is:
 242 # Label, attribute, select-bitmap, extra attr display name, extra attr ldap name
 243 # If last two are null, "Fewer Choices" name/attributes used
 244 "Common Name"                   cn                 11111  ""  ""
 245 "Surname"                       sn                 11111  ""  ""
 246 "Business Phone"                "telephoneNumber"  11101  ""  ""
 247 "E-Mail Address"                "mail"             11111  ""  ""
 248 "Uniqname"                      "uid"              11111  ""  ""
 249 END
 250 # Match types
 251 "exactly matches"               "(%a=%v))"
 252 "approximately matches"         "(%a~=%v))"
 253 "starts with"                   "(%a=%v*))"
 254 "ends with"                     "(%a=*%v))"
 255 "contains"                      "(%a=*%v*))"
 256 END
 257 .fi
 258 .in -2
 259
 260 .sp
 261 .LP
 262 In this example, the user may search for People. For "fewer choices" searching,
 263 the tag for the \fBldapfilter.conf\fR(4) file is "x500-People".
 264 .SH ATTRIBUTES
 265 .sp
 266 .LP
 267 See \fBattributes\fR(5) for a description of the following attributes:
 268 .sp
 269
 270 .sp
 271 .TS
 272 box;
 273 c | c
 274 l | l .
 275 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 276 Stability Level Evolving
 277 .TE
 278
 279 .SH SEE ALSO
 280 .sp
 281 .LP
 282 \fBldap_searchprefs\fR(3LDAP) , \fBattributes\fR(5)