1 '\" te
2 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH NISLDAPMAPPING 4 "Feb 25, 2017"
7 .SH NAME
8 NISLDAPmapping \- mapping file used by the NIS server components
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/var/yp/NISLDAPmapping\fR
13 .fi
14
15 .SH DESCRIPTION
16 .LP
17 The \fBNISLDAPmapping\fR file specifies the mapping between NIS map entries and
18 equivalent Directory Information Tree (DIT) entries.
19 .sp
20 .LP
21 The presence of \fB/var/yp/NISLDAPmapping\fR on a NIS master server causes that
22 server to obtain NIS data from LDAP. See \fBypserv\fR(4). If
23 \fB/var/yp/NISLDAPmapping\fR is present but the connection configuration file
24 that is defined in \fB/etc/default/ypserv\fR cannot be found, a warning is
25 logged. See \fBypserv\fR(1M).
26 .sp
27 .LP
28 NIS slave servers always obtain their data from a NIS master server, whether or
29 not that server is getting data from LDAP, and ignore the
30 \fB/var/yp/NISLDAPmapping\fR file.
31 .sp
32 .LP
33 A simple \fBNISLDAPmapping\fR file is created using \fBinityp2l\fR(1M). You can
34 customize your \fBNISLDAPmapping\fR file as you require.
35 .sp
36 .LP
37 Each attribute defined below can be specified
38 in\fB/var/yp/NISLDAPmappingLDAP\fR or as an LDAP attribute. If both are
39 specified, then the attribute in \fB/var/yp/NISLDAPmapping\fR (including empty
40 values) takes precedence.
41 .sp
42 .LP
43 A continuation is indicated by a '\e' (backslash) in the last position,
44 immediately before the newline of a line. Characters are escaped, that is,
45 exempted from special interpretation, when preceded by a backslash character.
46 .sp
47 .LP
48 The '#' (hash) character starts a comment. White space is either ASCII space or
49 a horizontal tab. In general, lines consist of optional white space, an
50 attribute name, at least one white space character, and an attribute value.
51 .SH EXTENDED DESCRIPTION
52 .SS "File Syntax"
53 .LP
54 Repeated fields, with separator characters, are described by the following
55 syntax:
56 .sp
57 .ne 2
58 .na
59 \fBOne or more entries\fR
60 .ad
61 .RS 24n
62 entry:entry:entry
63 .sp
64 .in +2
65 .nf
66 entry[":"...]
67 .fi
68 .in -2
69
70 .RE
71
72 .sp
73 .ne 2
74 .na
75 \fBZero or more entries\fR
76 .ad
77 .RS 24n
78 .sp
79 .in +2
80 .nf
81 [entry":"...]
82 .fi
83 .in -2
84
85 .RE
86
87 .SS "Attributes"
88 .LP
89 Attributes generally apply to one more more NIS maps. Map names can be
90 specified either on their own,that is in \fBpasswd.byname\fR, in which case
91 they apply to all domains, or for individual NIS domains, for example, in
92 \fBpasswd.byname,example.sun.uk\fR. Where a map is mentioned in more than one
93 attribute, both versions are applied. If any parts of the attributes are in
94 conflict, the domain specific version takes precedence over the non-domain
95 specific version.
96 .sp
97 .LP
98 Each domain specific attributes must appear in \fBNISLDAPmapping\fR before any
99 related non-domain specific attribute. If non-domain specific attributes appear
100 first, behavior may be unpredictable. Errors are logged when non-domain
101 specific attributes are found first.
102 .sp
103 .LP
104 You can associate a group of map names with a \fBdatabaseId\fR. In effect, a
105 macro is expanded to the group of names. Use this mechanism where the same
106 group of names is used in many attributes or where domain specific map names
107 are used. Then, you can make any changes to the domain name in one place.
108 .sp
109 .LP
110 Unless otherwise noted, all elements of the syntaxes below may be surrounded by
111 white space. Separator characters and white space must be escaped if they are
112 part of syntactic elements.
113 .sp
114 .LP
115 The following attributes are recognized.
116 .sp
117 .ne 2
118 .na
119 \fB\fBnisLDAPdomainContext\fR\fR
120 .ad
121 .sp .6
122 .RS 4n
123 The context to use for a NIS domain.
124 .sp
125 The syntax for \fBnisLDAPdomainContext\fR is:
126 .sp
127 .in +2
128 .nf
129 NISDomainName ":" context
130 .fi
131 .in -2
132
133 The following is an example of the \fBnisLDAPdomainContext\fR attribute:
134 .sp
135 .in +2
136 .nf
137 domain.one : dc=site, dc=company, dc=com
138 .fi
139 .in -2
140
141 The mapping file should define the context for each domain before any other
142 attribute makes use of the \fBNISDomainName\fR specified for that domain.
143 .RE
144
145 .sp
146 .ne 2
147 .na
148 \fB\fBnisLDAPyppasswddDomains\fR\fR
149 .ad
150 .sp .6
151 .RS 4n
152 Lists the domains for which password changes should be made. NIS password
153 change requests do not specify the domains in which any given password should
154 be changed. In traditional NIS this information is effectively hard coded in
155 the NIS makefile.
156 .sp
157 The syntax for the \fBnisLDAPyppasswddDomains\fR attribute is:
158 .sp
159 .in +2
160 .nf
161 domainname
162 .fi
163 .in -2
164
165 If there are multiple domains, use multiple \fBnisLDAPyppasswddDomain\fR
166 entries with one domainname per entry.
167 .RE
168
169 .sp
170 .ne 2
171 .na
172 \fB\fBnisLDAPdatabaseIdMapping\fR\fR
173 .ad
174 .sp .6
175 .RS 4n
176 Sets up an alias for a group of NIS map names. There is no default value.
177 .sp
178 The syntax for the \fBnisLDAPdatabaseIdMapping\fR attribute is:
179 .sp
180 .in +2
181 .nf
182 databaseId ":" ["["indexlist"]"] mapname[" "...]
183 .fi
184 .in -2
185
186 where
187 .sp
188 .in +2
189 .nf
190 databaseId = Label identifying a (subset of a) NIS
191 object for mapping purposes.
192 indexlist = fieldspec[","...]
193 fieldspec = fieldname "=" fieldvalue
194 fieldname = The name of a entry field as defined in
195 nisLDAPnameFields.
196 fieldvalue = fieldvaluestring | \e" fieldvaluestring \e"
197 .fi
198 .in -2
199
200 \fBindexlist\fR is used for those cases where it is necessary to select a
201 subset of entries from a NIS map. The subset are those NIS entries that match
202 the \fBindexlist\fR. If there are multiple specifications indexed for a
203 particular NIS map, they are tried in the order retrieved until one matches.
204 Note that retrieval order usually is unspecified for multi-valued LDAP
205 attributes. Hence, if using indexed specifications when
206 \fBnisLDAPdatabaseIdMapping\fR is retrieved from LDAP, make sure that the
207 subset match is unambiguous.
208 .sp
209 If the \fBfieldvaluestring\fR contains white space or commas, it must either be
210 surrounded by double quotes, or the special characters must be escaped.
211 Wildcards are allowed in the \fBfieldvaluestring\fR. See Wildcards
212 .sp
213 To associate the \fBpasswd.byname\fR and \fBpasswd.byuid\fR maps with the
214 \fBpasswd databaseId\fR:
215 .sp
216 .in +2
217 .nf
218 passwd:passwd.byname passwd.byuid
219 .fi
220 .in -2
221
222 The \fBpasswd\fR and \fBpasswd.adjunct\fR \fBdatabaseIds\fR receive special
223 handling. In addition to its normal usage, \fBpasswd\fR defines which maps
224 \fByppasswdd\fR is to update when a \fBpasswd\fR is changed. In addition to its
225 normal usage \fBpasswd.adjunct\fR defines which maps \fByppasswdd\fR is to
226 update when an adjunct \fBpasswd\fR is changed.
227 .sp
228 You may not alias a single map name to a different name, as the results are
229 unpredictable.
230 .RE
231
232 .sp
233 .ne 2
234 .na
235 \fB\fBnisLDAPentryTtl\fR\fR
236 .ad
237 .sp .6
238 .RS 4n
239 Establish TTLs for NIS entries derived from LDAP.
240 .sp
241 The syntax for the \fBnisLDAPentryTtl\fR attribute is:
242 .sp
243 .in +2
244 .nf
245 mapName[" "...]":"
246 initialTTLlo ":" initialTTLhi ":" runningTTL
247 .fi
248 .in -2
249
250 where
251 .sp
252 .ne 2
253 .na
254 \fB\fBinitialTTLlo\fR\fR
255 .ad
256 .RS 16n
257 The lower limit for the initial \fBTTL\fR (in seconds) for data read from LDAP
258 when the \fBypserv\fR starts. If the \fBinitialTTLhi\fR also is specified, the
259 actual \fBinitialTTL\fR will be randomly selected from the interval
260 \fBinitialTTLlo\fR to \fBinitialTTLhi\fR , inclusive. Leaving the field empty
261 yields the default value of 1800 seconds.
262 .RE
263
264 .sp
265 .ne 2
266 .na
267 \fB\fBinitialTTLhi\fR\fR
268 .ad
269 .RS 16n
270 The upper limit for the initial TTL. If left empty, defaults to 5400.
271 .RE
272
273 .sp
274 .ne 2
275 .na
276 \fB\fBrunningTTL\fR\fR
277 .ad
278 .RS 16n
279 The TTL (in seconds) for data retrieved from LDAP while the ypserv is running.
280 Leave the field empty to obtain the default value of 3600 seconds.
281 .RE
282
283 If there is no specification of \fBTTL\fRs for a particular map, the default
284 values are used.
285 .sp
286 If the \fBinitialTTLlo\fR and \fBinitialTTLhi\fR have the same value, the
287 effect will be that all data known to the \fBypserv\fR at startup times out at
288 the same time. Depending on NIS data lookup patterns, this could cause spikes
289 in ypserv-to-LDAP traffic. In order to avoid that, you can specify different
290 \fBinitialTTLlo\fR and \fBinitialTTLhi\fR values, and obtain a spread in
291 initial TTLs.
292 .sp
293 The following is an example of the \fBnisLDAPentryTtl\fR attribute used to
294 specify that entries in the NIS host maps read from LDAP should be valid for
295 four hours. When \fBypserv\fR restarts, the disk database entries are valid for
296 between two and three hours.
297 .sp
298 .in +2
299 .nf
300 hosts.byname hosts.byaddr:7200:10800:14400
301 .fi
302 .in -2
303
304 .RE
305
306 .sp
307 .ne 2
308 .na
309 \fB\fBnisLDAPobjectDN\fR\fR
310 .ad
311 .sp .6
312 .RS 4n
313 Specifies the connection between a group of NIS maps and the LDAP directory.
314 This attribute also defines the 'order' of the NIS maps. When NIS maps are bulk
315 copied to or from the DIT, they are processed in the same order as related
316 \fBnisLDAPobjectDN\fR attributes appear in \fB/var/yp/NISLDAPmapping.\fR
317 .sp
318 The syntax for the \fBnisLDAPobjectDN\fR\ attribute is:
319 .sp
320 .in +2
321 .nf
322 mapName[" "...] ":" objectDN *( ";" objectDN )
323 .fi
324 .in -2
325
326 where
327 .sp
328 .in +2
329 .nf
330 objectDN = readObjectSpec [":"[writeObjectSpec]]
331 readObjectSpec = [baseAndScope [filterAttrValList]]
332 writeObjectSpec = [baseAndScope [attrValList]]
333 baseAndScope = [baseDN] ["?" [scope]]
334 filterAttrValList = ["?" [filter | attrValList]]]
335 scope = "base" | "one" | "sub"
336 attrValList = attribute "=" value
337 *("," attribute "=" value)
338 .fi
339 .in -2
340
341 The \fBbaseDN\fR defaults to the value of the \fBnisLDAPdomainContext\fR
342 attribute for the accessed domain. If the \fBbaseDN\fR ends in a comma, the
343 \fBnisLDAPdomainContext\fR value is appended.
344 .sp
345 \fBscope\fR defaults to one. \fBscope\fR has no meaning and is ignored in a
346 \fBwriteObjectSpec\fR.
347 .sp
348 The \fBfilter\fR is an LDAP search filter and has no default value.
349 .sp
350 The \fBattrValList\fR is a list of attribute and value pairs. There is no
351 default value.
352 .sp
353 As a convenience, if an \fBattrValList\fR is specified in a
354 \fBreadObjectSpec\fR, it is converted to a search filter by ANDing together the
355 attributes and the values. For example, the attribute and value list:
356 .sp
357 .in +2
358 .nf
359 objectClass=posixAccount,objectClass=shadowAccount
360 .fi
361 .in -2
362
363 is converted to the filter:
364 .sp
365 .in +2
366 .nf
367 (&(objectClass=posixAccount)\e
368 (objectClass=shadowAccount))
369 .fi
370 .in -2
371
372 Map entries are mapped by means of the relevant mapping rules in the
373 \fBnisLDAPnameFields\fR and \fBnisLDAPattributeFromField\fR .
374 .sp
375 If a \fBwriteObjectSpec\fR is omitted, the effect is one of the following:
376 .RS +4
377 .TP
378 .ie t \(bu
379 .el o
380 If there is no trailing colon after the \fBreadObjectSpec\fR, then there is no
381 write at all.
382 .RE
383 .RS +4
384 .TP
385 .ie t \(bu
386 .el o
387 If there is a colon after the \fBreadObjectSpec\fR, then \fBwriteObjectSpec\fR
388 equals \fBreadObjectSpec\fR.
389 .RE
390 The following is an example of a \fBnisLDAPobjectDN\fR attribute declaration
391 that gets the \fBhosts.byaddr\fR map entries from the \fBou=Hosts\fR container
392 under the default search base and writes to the same place.
393 .sp
394 .in +2
395 .nf
396 hosts.byaddr:ou=Hosts,?one?objectClass=ipHost:
397 .fi
398 .in -2
399
400 The following is an example of a \fBnisLDAPobjectDN\fR attribute declaration
401 that obtains \fBpasswd\fR map entries from the \fBou=People\fR containers under
402 the default search base, and also from \fBdc=another,dc=domain\fR.
403 .sp
404 .in +2
405 .nf
406 passwd:ou=People,?one?\e
407 objectClass=shadowAccount,\e
408 objectClass=posixAccount:;\e
409 ou=People,dc=another,dc=domain,?one?\e
410 objectClass=shadowAccount,\e
411 objectClass=posixAccount
412 .fi
413 .in -2
414
415 .RE
416
417 .sp
418 .ne 2
419 .na
420 \fB\fBnisLDAPnameFields\fR\fR
421 .ad
422 .sp .6
423 .RS 4n
424 Specifies the content of entries in a NIS map and how they should be broken
425 into named fields. \fBnisLDAPnameFields\fR is required because NIS
426 maps do not store information in named fields.
427 .sp
428 The syntax for the \fBnisLDAPnameFields\fR attribute is as follows:
429 .sp
430 .in +2
431 .nf
432 "nisLDAPnameFields" mapName ":" "(" matchspec "," fieldNames ")"
433 fieldName = nameOrArrayName[","...]
434 nameOrArrayName = Name of field or 'array' of repeated fields.
435 matchspec = \e" formatString \e"
436 .fi
437 .in -2
438
439 \fBformatString\fR may contains a list of \fB%s\fR and \fB%a\fR elements each
440 of which represents a single named field or a list of repeated fields. A
441 \fB%a\fR field is interpreted as an IPv4 address or an IPv6 address in
442 preferred format. If an IPv6 address in non preferred format is found, then it
443 is converted and a warning is logged.
444 .sp
445 Where there are a list of repeated fields, the entire list is stored as one
446 entry. The fields are broken up into individual entries, based on the internal
447 separator, at a latter stage. Other characters represent separators which must
448 be present. Any separator, including whitespace, specified by the
449 \fBformatString\fR, may be surrounded by a number of whitespace and tab
450 characters. The whitespace and tab characters are ignored.
451 .sp
452 Regardless of the content of this entry some \fBfieldNames\fR are reserved:
453 .sp
454 .ne 2
455 .na
456 \fB\fBrf_key\fR\fR
457 .ad
458 .RS 18n
459 The DBM key value
460 .RE
461
462 .sp
463 .ne 2
464 .na
465 \fB\fBrf_ipkey\fR\fR
466 .ad
467 .RS 18n
468 The DBM key value handled as an IP address. See the discussion of \fB%a\fR
469 fields.
470 .RE
471
472 .sp
473 .ne 2
474 .na
475 \fB\fBrf_comment\fR\fR
476 .ad
477 .RS 18n
478 Everything following the first occurrence of a symbol. \fBrf_comment\fR is
479 defined by \fBnisLDAPcommentChar\fR.
480 .RE
481
482 .sp
483 .ne 2
484 .na
485 \fB\fBrf_domain\fR\fR
486 .ad
487 .RS 18n
488 The name of the domain in which the current NIS operation is being carried out.
489 .RE
490
491 .sp
492 .ne 2
493 .na
494 \fB\fBrf_searchipkey\fR\fR
495 .ad
496 .RS 18n
497 The \fBrf_searchkey\fR value handled as an IP address. See the discussion of
498 \fB%a\fR fields above.
499 .RE
500
501 .sp
502 .ne 2
503 .na
504 \fB\fBrf_searchkey\fR\fR
505 .ad
506 .RS 18n
507 See the description under \fBnisLDAPattributeFromField\fR below.
508 .RE
509
510 For example, the \fBrpc.bynumber\fR map has the format:
511 .sp
512 .in +2
513 .nf
514 name number alias[" "...]
515 .fi
516 .in -2
517
518 The NIS to LDAP system is instructed to break it into a name, a number, and an
519 array of alias field by the following entry in the mapping file:
520 .sp
521 .in +2
522 .nf
523 nisLDAPnameFields rpc.bynumber : \e
524 "%s %s %s", name,number,aliases)
525 .fi
526 .in -2
527
528 .RE
529
530 .sp
531 .ne 2
532 .na
533 \fB\fBnisLDAPsplitFields\fR\fR
534 .ad
535 .sp .6
536 .RS 4n
537 Defines how a field, or list of fields, named by \fBnisLDAPnameFields\fR is
538 split into subfields. The original field is compared with each line of this
539 attribute until one matches. When a match is found named subfields are
540 generated. In latter operations subfield names can be used in the same way as
541 other field names.
542 .sp
543 The syntax for the \fBnisLDAPsplitFields\fR attribute is as follows:
544 .sp
545 .in +2
546 .nf
547 "nisLDAPsplitFields" fieldName ":" splitSpec[","...]
548 splitSpec = "(" matchspec "," subFieldNames ")"
549 fieldName = Name of a field from nisLDAPnameFields
550 subFieldNames = subFieldname[","...]
551 matchspec = \e" formatString \e"
552 .fi
553 .in -2
554
555 The netgroup \fBmemberTriples\fR can have format \fB(host, user, domain)\fR or
556 \fBgroupname\fR. The format is specified by the attribute:
557 .sp
558 .in +2
559 .nf
560 nisLDAPsplitField memberTriple: \e
561 ("(%s,%s,%s)", host, user, domain) , \e
562 ("%s", group)
563 .fi
564 .in -2
565
566 Later operations can then use field names \fBhost\fR, \fBuser\fR, \fBdomain\fR,
567 \fBgroup\fR or \fBmemberTriple\fR. Because lines are processed in order, if
568 \fBhost\fR, \fBuser\fR and \fBdomain\fR are found, \fBgroup\fR will not be
569 generated.
570 .sp
571 Several maps and databaseIds may contain fields that are to be split in the
572 same way. As a consequence, the names of fields to be split must be unique
573 across all maps and databaseIds.
574 .sp
575 Only one level of splitting is supported. That is, a subfield cannot be split
576 into further subfields.
577 .RE
578
579 .sp
580 .ne 2
581 .na
582 \fB\fBnisLDAPrepeatedFieldSeparators\fR\fR
583 .ad
584 .sp .6
585 .RS 4n
586 Where there is a list of repeated, splittable fields,
587 \fBnisLDAPrepeatedFieldSeparators\fR specifies which characters separate
588 instances of the splittable field.
589 .sp
590 The syntax for the \fBnisLDAPrepeatedFieldSeparators\fR attribute is as
591 follows:
592 .sp
593 .in +2
594 .nf
595 "nisLDAPrepeatedFieldSeparators" fieldName \e"sepChar[...]\e"
596 sepChar = A separator character.
597 .fi
598 .in -2
599
600 The default value is space or tab. If repeated splittable fields are adjacent,
601 that is, there is no separating character, then the following should be
602 specified:
603 .sp
604 .in +2
605 .nf
606 nisLDAPrepeatedFieldSeparators netIdEntry: ""
607 .fi
608 .in -2
609
610 .RE
611
612 .sp
613 .ne 2
614 .na
615 \fB\fBnisLDAPcommentChar\fR\fR
616 .ad
617 .sp .6
618 .RS 4n
619 Specifies which character represents the start of the special comment field in
620 a given NIS map. If this attribute is not present then the default comment
621 character \fB#\fR is used.
622 .sp
623 To specify that a map uses a asterix to mark the start of comments.
624 .sp
625 .in +2
626 .nf
627 nisLDAPcommentChar mapname : '*'
628 .fi
629 .in -2
630
631 If a map cannot contain comments, then the following attribute should be
632 specified.
633 .sp
634 .in +2
635 .nf
636 nisLDAPcommentChar mapname : ''
637 .fi
638 .in -2
639
640 .RE
641
642 .sp
643 .ne 2
644 .na
645 \fB\fBnisLDAPmapFlags\fR\fR
646 .ad
647 .sp .6
648 .RS 4n
649 Indicates if \fBYP_INTERDOMAIN\fR or \fBYP_SECURE\fR entries should be created
650 in a map. Using \fBnisLDAPmapFlags\fR is equivalent to running
651 \fBmakedbm\fR(1M) with the \fB-b\fR or the \fB-s\fR option. When a map is
652 created from the contents of the DIT, the mapping file attribute is the only
653 source for the \fBYP_INTERDOMAIN\fR or \fBYP_SECURE\fR entries.
654 .sp
655 The syntax for the \fBnisLDAPmapFlags\fR attribute is as follows:
656 .sp
657 .in +2
658 .nf
659 "nisLDAPmapFlags" mapname ":" ["b"]["s"]
660 .fi
661 .in -2
662
663 By default neither entry is created.
664 .RE
665
666 .sp
667 .ne 2
668 .na
669 \fB\fBnisLDAPfieldFromAttribute\fR\fR
670 .ad
671 .sp .6
672 .RS 4n
673 Specifies how a NIS entries field values are derived from LDAP attribute
674 values.
675 .sp
676 The syntax for the \fBnisLDAPfieldFromAttribute\fR attribute is as follows:
677 .sp
678 .in +2
679 .nf
680 mapName ":" fieldattrspec *("," fieldattrspec)
681 .fi
682 .in -2
683
684 The format of \fBfieldattrspec\fR is shown below at Field and Attribute
685 Conversion Syntax.
686 .sp
687 To map by direct copy and assignment the value of the \fBipHostNumber\fR
688 attribute to the \fBaddr\fR named field, for example:
689 .sp
690 .in +2
691 .nf
692 addr=ipHostNumber
693 .fi
694 .in -2
695
696 Formats for the named field and attribute conversion syntax are discussed
697 below, including examples of complex attribute to field conversions.
698 .RE
699
700 .sp
701 .ne 2
702 .na
703 \fB\fBnisLDAPattributeFromField\fR\fR
704 .ad
705 .sp .6
706 .RS 4n
707 Specifies how an LDAP attribute value is derived from a NIS entriy field
708 value.
709 .sp
710 The syntax for the \fBnisLDAPattributeFromField\fR attribute is as follows:
711 .sp
712 .in +2
713 .nf
714 mapName ":" fieldattrspec *("," fieldattrspec )
715 .fi
716 .in -2
717
718 The format of \fBfieldattrspec\fR is shown below at Field and Attribute
719 Conversion Syntax.
720 .sp
721 As a special case, if the \fBdn\fR attribute value derived from a
722 \fBfieldattrspec\fR ends in a comma ("\fB,\fR"), the domains context from
723 \fBnisLDAPdomainContext\fR is appended.
724 .sp
725 Use the following example to map the value of the \fBaddr\fR field to the
726 \fBipHostNumber\fR attribute by direct copy and assignment:
727 .sp
728 .in +2
729 .nf
730 ipHostNumber=addr
731 .fi
732 .in -2
733
734 All relevant attributes, including the \fBdn\fR, must be specified.
735 .sp
736 For every map it must be possible to rapidly find a DIT entry based on its key.
737 There are some maps for which a NIS to LDAP mapping for the key is not
738 desirable, so a key mapping cannot be specified. In these cases a mapping that
739 uses the reserved \fBrf_searchkey\fR must be specified. Mappings that use this
740 field name are ignored when information is mapped into the DIT.
741 .RE
742
743 .SS "Field and Attribute Conversion Syntax"
744 .LP
745 The general format of a \fBfieldattrspec\fR is:
746 .sp
747 .in +2
748 .nf
749 fieldattrspec = lhs "=" rhs
750 lhs = lval | namespeclist
751 rhs = rval | [namespec]
752 namespeclist = namespec | "(" namespec *("," namespec) ")"
753 .fi
754 .in -2
755
756 .sp
757 .LP
758 The \fBlval\fR and \fBrval\fR syntax are defined below at Values. The format of
759 a \fBnamespec\fR is:
760 .sp
761 .ne 2
762 .na
763 \fB\fBnamespec\fR\fR
764 .ad
765 .RS 16n
766 .sp
767 .in +2
768 .nf
769 ["ldap:"] attrspec [searchTriple] | ["yp:"] fieldname
770 [mapspec]
771 .fi
772 .in -2
773
774 .RE
775
776 .sp
777 .ne 2
778 .na
779 \fB\fBfieldname\fR\fR
780 .ad
781 .RS 16n
782 .sp
783 .in +2
784 .nf
785 field | "(" field ")"
786 .fi
787 .in -2
788
789 .RE
790
791 .sp
792 .ne 2
793 .na
794 \fB\fBattrspec\fR\fR
795 .ad
796 .RS 16n
797 .sp
798 .in +2
799 .nf
800 attribute | "(" attribute ")"
801 .fi
802 .in -2
803
804 .RE
805
806 .sp
807 .ne 2
808 .na
809 \fB\fBsearchTriple\fR\fR
810 .ad
811 .RS 16n
812 .sp
813 .in +2
814 .nf
815 ":" [baseDN] ["?" [scope] ["?" [filter]]]
816 .fi
817 .in -2
818
819 .RE
820
821 .sp
822 .ne 2
823 .na
824 \fB\fBbaseDN\fR\fR
825 .ad
826 .RS 16n
827 Base DN for search
828 .RE
829
830 .sp
831 .ne 2
832 .na
833 \fB\fBfilter\fR\fR
834 .ad
835 .RS 16n
836 LDAP search filter
837 .RE
838
839 .sp
840 .ne 2
841 .na
842 \fB\fBmapspec\fR\fR
843 .ad
844 .RS 16n
845 Map name
846 .RE
847
848 .sp
849 .LP
850 The repository specification in a \fBnamespec\fR defaults is as follows:
851 .RS +4
852 .TP
853 .ie t \(bu
854 .el o
855 For assignments to a field:
856 .RS
857
858 .sp
859 .ne 2
860 .na
861 \fBon the \fBLHS\fR\fR
862 .ad
863 .RS 14n
864 yp
865 .RE
866
867 .sp
868 .ne 2
869 .na
870 \fBon the \fBRHS\fR\fR
871 .ad
872 .RS 14n
873 ldap
874 .RE
875
876 .RE
877
878 NIS field values on the \fBRHS\fR are those that exist before the NIS entry is
879 modified.
880 .RE
881 .RS +4
882 .TP
883 .ie t \(bu
884 .el o
885 For assignments to an attribute:
886 .RS
887
888 .sp
889 .ne 2
890 .na
891 \fBon the \fBLHS\fR\fR
892 .ad
893 .RS 14n
894 ldap
895 .RE
896
897 .sp
898 .ne 2
899 .na
900 \fBon the \fBRHS\fR\fR
901 .ad
902 .RS 14n
903 yp
904 .RE
905
906 .RE
907
908 Attribute values on the \fBRHS\fR are those that exist before the LDAP entry is
909 modified.
910 .RE
911 .sp
912 .LP
913 When the field or attribute name is enclosed in parenthesis, it denotes a list
914 of field or attribute values. For attributes, the meaning is the list of all
915 attributes of that name, and the interpretation depends on the context. See the
916 discussion at Values. The list specification is ignored when a
917 \fBsearchTriple\fR or \fBmapspec\fR is supplied.
918 .sp
919 .LP
920 For fields, the \fBfieldname\fR syntax is used to map multiple attribute
921 instances to multiple NIS entries.
922 .sp
923 .LP
924 The \fBsearchTriple\fR can be used to specify an attribute from a location
925 other than the read or write target. The defaultvalues are as follows:
926 .sp
927 .ne 2
928 .na
929 \fB\fBbaseDN\fR\fR
930 .ad
931 .RS 10n
932 If \fBbaseDN\fR is omitted, the default is the current \fBobjectDN\fR. If the
933 \fBbaseDN\fR ends in a comma, the context of the domain is appended from
934 \fBnisLDAPdomainContext\fR .
935 .RE
936
937 .sp
938 .ne 2
939 .na
940 \fB\fBscope\fR\fR
941 .ad
942 .RS 10n
943 one
944 .RE
945
946 .sp
947 .ne 2
948 .na
949 \fB\fBfilter\fR\fR
950 .ad
951 .RS 10n
952 Empty
953 .RE
954
955 .sp
956 .LP
957 Similarly, the \fBmapspec\fR can be used to specify a field value from a NIS
958 map other than the one implicitly indicated by the \fBmapName\fR. If
959 \fBsearchTriple\fR or \fBmapspec\fR is explicitly specified in a
960 \fBnamespec\fR, the retrieval or assignment, whether from or to LDAP or NIS, is
961 performed without checking if read and write are enabled for the LDAP container
962 or NIS map.
963 .sp
964 .LP
965 The omission of the \fBnamespec\fR in an \fBrhs\fR is only allowed if the
966 \fBlhs\fR is one or more attributes. The effect is to delete the specified
967 attribute(s). In all other situations, an omitted \fBnamespec\fR means that the
968 rule is ignored.
969 .sp
970 .LP
971 The \fBfilter\fR can be a value. See Values. For example, to find the
972 \fBipHostNumber\fRthat uses the \fBcn\fR, you specify the following in the
973 \fBfilter\fR field:
974 .sp
975 .in +2
976 .nf
977 ldap:ipHostNumber:?one?("cn=%s", (cname, "%s.*"))
978 .fi
979 .in -2
980
981 .sp
982 .LP
983 In order to remove ambiguity, the unmodified value of a single field or
984 attribute must be specified as the following when used in the \fBfilter\fR
985 field.
986 .sp
987 .in +2
988 .nf
989 ("%s", namespec)
990 .fi
991 .in -2
992
993 .sp
994 .LP
995 If the \fBfilter\fR is not specified, the scope will be base, and the
996 \fBbaseDN\fR is assumed to be the \fBDN\fR of the entry that contains the
997 attribute to be retrieved or modified. To use previously existing field or
998 attribute values in the mapping rules requires a lookup to find those values.
999 Obviously, this adds to the time required to perform the modification. Also,
1000 there is a window between the time when a value is retrieved and then slightly
1001 later stored back. If the values have changed in the mean time, the change may
1002 be overwritten.
1003 .sp
1004 .LP
1005 When \fBfieldattrspecs\fR are grouped into rule sets, in the value of a
1006 \fBnisLDAPfieldFromAttribute\fR or \fBnisLDAPattributeFromField\fR attribute,
1007 the evaluation of the \fBfieldattrspecs\fR proceed in the listed order.
1008 However, evaluation may be done in parallel for multiple \fBfieldattrspecs\fR.
1009 If there is an error when evaluating a certain \fBfieldattrspec\fR, including
1010 retrieval or assignment of entry or field values, the extent to which the other
1011 \fBfieldattrspec\fR rules are evaluated is unspecified.
1012 .SS "Wildcards"
1013 .LP
1014 Where wildcard support is available, it is of the following limited form:
1015 .sp
1016 .ne 2
1017 .na
1018 \fB\fB*\fR\fR
1019 .ad
1020 .RS 9n
1021 Matches any number of characters
1022 .RE
1023
1024 .sp
1025 .ne 2
1026 .na
1027 \fB\fB[x]\fR\fR
1028 .ad
1029 .RS 9n
1030 Matches the character x
1031 .RE
1032
1033 .sp
1034 .ne 2
1035 .na
1036 \fB\fB[x-y]\fR\fR
1037 .ad
1038 .RS 9n
1039 Matches any character in the range x to y, inclusive
1040 .RE
1041
1042 .sp
1043 .LP
1044 Combinations such as \fB[a-cA-C0123]\fR are also allowed, which would match any
1045 one of a, b, c, A, B, C, 0, 1, 2, or 3.
1046 .SS "Substring Extraction"
1047 .in +2
1048 .nf
1049 substringextract = "(" namespec "," matchspec ")"
1050 name = field or attribute name
1051 matchspec =
1052 .fi
1053 .in -2
1054
1055 .sp
1056 .LP
1057 The \fBmatchspec\fR is a string like the \fBsscanf\fR(3C) format string, except
1058 that there may be at most one format specifier, a single \fB%s\fR. The output
1059 value of the \fBsubstringextract\fR is the substring that matches the location
1060 of the \fB%s\fR.
1061 .sp
1062 .LP
1063 If there is no \fB%s\fR in the formatstring, it must instead be a single
1064 character, which is assumed to be a field separator for the \fBnamespec\fR. The
1065 output values are the field values. Wild cards are supported. If there is no
1066 match, the output value is the empty string, " ".
1067 .sp
1068 .LP
1069 For example, if the \fBfieldcname\fR has the value
1070 \fBuser.some.domain.name.\fR, the value of the expression:
1071 .sp
1072 .in +2
1073 .nf
1074 (cname, "%s.*")
1075 .fi
1076 .in -2
1077
1078 .sp
1079 .LP
1080 is \fBuser\fR, which can be used to extract the user name from a NIS principal
1081 name.
1082 .sp
1083 .LP
1084 Similarly, use this expression to extract the third of the colon-separated
1085 fields of the shadow field:
1086 .sp
1087 .in +2
1088 .nf
1089 (shadow, "*:*:%s:*")
1090 .fi
1091 .in -2
1092
1093 .sp
1094 .LP
1095 This form can be used to extract all of the shadow fields. However, a simpler
1096 way to specify that special case is:
1097 .sp
1098 .in +2
1099 .nf
1100 (shadow, ":")
1101 .fi
1102 .in -2
1103
1104 .SS "Values"
1105 .in +2
1106 .nf
1107 lval = "(" formatspec "," namespec *("," namespec) ")"
1108 rval = "(" formatspec ["," namelist ["," elide] ] ")"
1109
1110 namelist = name_or_sse *( "," name_or_sse)
1111 name_or_sse = namespec | removespec | substringextract
1112 removespec = list_or_name "-" namespec
1113 list_or_name = "(" namespec ")" | namespec
1114 formatspec =
1115 formatstring = A string combining text and % field specifications
1116 elide =
1117 singlechar = Any character
1118 .fi
1119 .in -2
1120
1121 .sp
1122 .LP
1123 The syntax above is used to produce \fBrval\fR values that incorporate field or
1124 attribute values, in a manner like \fBsprintf\fR(3C), or to perform assignments
1125 to \fBlval\fR like \fBsscanf\fR(3C). One important restriction is that the
1126 format specifications,\fB%\fR plus a single character, use the designations
1127 from \fBber_printf\fR(3LDAP). Thus, while \fB%s\fR is used to extract a string
1128 value, \fB%i\fR causes BER conversion from an integer. Formats other than
1129 \fB%s\fR, for instance, \fB%i\fR, are only meaningfully defined in simple
1130 format strings without any other text.
1131 .sp
1132 .LP
1133 The following \fBber_printf()\fR format characters are recognized:
1134 .sp
1135 .in +2
1136 .nf
1137 b i n o s
1138 .fi
1139 .in -2
1140
1141 .sp
1142 .LP
1143 If there are too few format specifiers, the format string may be repeated as
1144 needed.
1145 .sp
1146 .LP
1147 When used as an \fBlval\fR, there is a combination of pattern matching and
1148 assignment, possibly to multiple fields or attributes.
1149 .sp
1150 .LP
1151 In an assignment to an attribute, if the value of the \fBaddr\fR field is
1152 \fB1.2.3.4\fR, the \fBrval\fR:
1153 .sp
1154 .in +2
1155 .nf
1156 ("ipNetworkNumber=%s,", addr)
1157 .fi
1158 .in -2
1159
1160 .sp
1161 .LP
1162 produces the value \fBipNetworkNumber=1.2.3.4,\fR, while:
1163 .sp
1164 .in +2
1165 .nf
1166 ("(%s,%s,%s)", host, user, domain)
1167 .fi
1168 .in -2
1169
1170 .sp
1171 .LP
1172 results in:
1173 .sp
1174 .in +2
1175 .nf
1176 (assuming host="xyzzy", user="-", domain="x.y.z")
1177 "(xyzzy,-,x.y.z)"
1178 .fi
1179 .in -2
1180
1181 .sp
1182 .LP
1183 The elide character feature is used with attribute lists. So:
1184 .sp
1185 .in +2
1186 .nf
1187 ("%s,", (mgrprfc822mailmember), ",")
1188 .fi
1189 .in -2
1190
1191 .sp
1192 .LP
1193 concatenates all \fBmgrprfc822mailmember\fR values into one comma-separated
1194 string, and then elides the final trailing comma. Thus, for
1195 .sp
1196 .in +2
1197 .nf
1198 mgrprfc822mailmember=usera
1199 mgrprfc822mailmember=userb
1200 mgrprfc822mailmember=userc
1201 .fi
1202 .in -2
1203
1204 .sp
1205 .LP
1206 the value would be:
1207 .sp
1208 .in +2
1209 .nf
1210 usera,userb,userc
1211 .fi
1212 .in -2
1213
1214 .sp
1215 .LP
1216 As a special case, to combine an \fBLHS\fR extraction with an \fBRHS\fR
1217 implicit list creates multiple entries and values. So
1218 .sp
1219 .in +2
1220 .nf
1221 ("(%s,%s,%s)", host, user, domain)=(nisNetgroupTriple)
1222 .fi
1223 .in -2
1224
1225 .sp
1226 .LP
1227 creates one NIS entry for each \fBnisNetgroupTriple\fR value.
1228 .sp
1229 .LP
1230 The \fB\&'removespec'\fR form is used to exclude previously assigned fields
1231 values from a list. So, if an LDAP entry contains:
1232 .sp
1233 .in +2
1234 .nf
1235 name: foo
1236 cn: foo
1237 cn: foo1
1238 cn: foo2
1239 .fi
1240 .in -2
1241
1242 .sp
1243 .LP
1244 and the mapping file specifies :
1245 .sp
1246 .in +2
1247 .nf
1248 myName = name, \e
1249 myAliases = ("%s ", (cn) - yp:myName, " ")
1250 .fi
1251 .in -2
1252
1253 .sp
1254 .LP
1255 then the following assignments are carried out:
1256 .RS +4
1257 .TP
1258 1.
1259 Assign value \fBfoo\fR to \fBmyName\fR
1260 .RE
1261 .RS +4
1262 .TP
1263 2.
1264 Assign value \fBfoo foo1 foo2\fR to \fBmyAliases\fR
1265 .RE
1266 .RS +4
1267 .TP
1268 3.
1269 Remove value of \fBmyName\fR from value \fBmyAliases\fR
1270 .RE
1271 .sp
1272 .LP
1273 This results in the field values \fBmyName\fR is set to \fBfoo\fR, and
1274 \fBmyAliases\fR is set to \fBfoo1 foo2\fR.
1275 .SS "Assignments"
1276 .LP
1277 The assignment syntax, also found at Field and Attribute Conversion Syntax, is
1278 as follows:
1279 .sp
1280 .in +2
1281 .nf
1282 fieldattrspec = lhs "=" rhs
1283 lhs = lval | namespeclist
1284 rhs = rval | namespec
1285 namespeclist = namespec | "(" namespec *("," namespec) ")"
1286 .fi
1287 .in -2
1288
1289 .sp
1290 .LP
1291 The general form of a simple assignment, which is a one-to-one mapping of field
1292 to attribute, is:
1293 .sp
1294 .in +2
1295 .nf
1296 ("%s", fieldname)=("%s", attrname)
1297 .fi
1298 .in -2
1299
1300 .sp
1301 .LP
1302 As a convenient shorthand, this can also be written as:
1303 .sp
1304 .in +2
1305 .nf
1306 fieldname=attrname
1307 .fi
1308 .in -2
1309
1310 .sp
1311 .LP
1312 A list specification, which is a name enclosed in parenthesis, can be used to
1313 make many-to-many assignments. The expression:
1314 .sp
1315 .in +2
1316 .nf
1317 (fieldname)=(attrname)
1318 .fi
1319 .in -2
1320
1321 .sp
1322 .LP
1323 where there are multiple instances of \fBattrname\fR, creates one NIS entry for
1324 each such instance, differentiated by their \fBfieldname\fR values. The
1325 following combinations of lists are allowed, but they are not particularly
1326 useful:
1327 .sp
1328 .ne 2
1329 .na
1330 \fB\fB(attrname)=(fieldname)\fR\fR
1331 .ad
1332 .RS 26n
1333 Equivalent to \fBattrname=fieldname\fR
1334 .RE
1335
1336 .sp
1337 .ne 2
1338 .na
1339 \fB\fBattrname=(fieldname)\fR\fR
1340 .ad
1341 .RS 26n
1342 Equivalent to \fBattrname=fieldname\fR
1343 .RE
1344
1345 .sp
1346 .ne 2
1347 .na
1348 \fB\fB(fieldname)=attrname\fR\fR
1349 .ad
1350 .RS 26n
1351 Equivalent to \fBfieldname=attrname\fR
1352 .RE
1353
1354 .sp
1355 .ne 2
1356 .na
1357 \fB\fBfieldname=(attrname)\fR\fR
1358 .ad
1359 .RS 26n
1360 Equivalent to \fBfieldname=attrname\fR
1361 .RE
1362
1363 .sp
1364 .LP
1365 If a multi-valued \fBRHS\fR is assigned to a single-valued \fBLHS\fR, the
1366 \fBLHS\fR value will be the first of the \fBRHS\fR values. If the \fBRHS\fR is
1367 an attribute list, the first attribute is the first one returned by the LDAP
1368 server when queried. Otherwise, the definition of "first"is implementation
1369 dependent.
1370 .sp
1371 .LP
1372 Finally, the \fBLHS\fR can be an explicit list of fields or attributes, such
1373 as:
1374 .sp
1375 .in +2
1376 .nf
1377 (name1,name2,name3)
1378 .fi
1379 .in -2
1380
1381 .sp
1382 .LP
1383 If the \fBRHS\fR is single-valued, this assigns the \fBRHS\fR value to all
1384 entities in the list. If the \fBRHS\fR is multi-valued, the first value is
1385 assigned to the first entity of the list, the second value to the second
1386 entity, and so on. Excess values or entities are silently ignored.
1387 .SH EXAMPLES
1388 .LP
1389 \fBExample 1 \fRAssigning an Attribute Value to a Field
1390 .sp
1391 .LP
1392 The following example illustrates how to assign the value of the
1393 \fBipHostNumber\fR attribute to the \fBaddr\fR field
1394
1395 .sp
1396 .in +2
1397 .nf
1398 addr=ipHostNumber
1399 .fi
1400 .in -2
1401
1402 .LP
1403 \fBExample 2 \fRCreating Multiple NIS Entries from Multi-Valued LDAP Attributes
1404 .sp
1405 .LP
1406 An LDAP entry with:
1407
1408 .sp
1409 .in +2
1410 .nf
1411 cn=name1
1412 cn=name2
1413 cn=name3
1414 .fi
1415 .in -2
1416
1417 .sp
1418 .LP
1419 and the following assignments:
1420
1421 .sp
1422 .in +2
1423 .nf
1424 cname=cn
1425 (name)=(cn)
1426 .fi
1427 .in -2
1428
1429 .sp
1430 .LP
1431 creates three NIS entries. Other attributes and fields are omitted for clarity.
1432
1433 .sp
1434 .in +2
1435 .nf
1436 cname=name1, name=name1
1437 cname=name1, name=name2
1438 cname=name1, name=name3
1439 .fi
1440 .in -2
1441
1442 .LP
1443 \fBExample 3 \fRAssigning String Constants
1444 .sp
1445 .LP
1446 The following expression sets the \fBpasswd\fR field to x:
1447
1448 .sp
1449 .in +2
1450 .nf
1451 passwd=("x")
1452 .fi
1453 .in -2
1454
1455 .LP
1456 \fBExample 4 \fRSplitting Field Values to Multi-Valued Attributes
1457 .sp
1458 .LP
1459 The \fBexpansion\fR field contains a comma-separated list of alias member
1460 names. In the following example, the expression assigns each member name to an
1461 instance of \fBmgrprfc822mailmember\fR:
1462
1463 .sp
1464 .in +2
1465 .nf
1466 (mgrprfc822mailmember)=(expansion, ",")
1467 .fi
1468 .in -2
1469
1470 .SH FILES
1471 .ne 2
1472 .na
1473 \fB\fB/var/yp/NISLDAPmapping\fR\fR
1474 .ad
1475 .RS 26n
1476 Mapping file used by the NIS server components
1477 .RE
1478
1479 .SH ATTRIBUTES
1480 .LP
1481 See \fBattributes\fR(5) for descriptions of the following attributes:
1482 .sp
1483
1484 .sp
1485 .TS
1486 box;
1487 c | c
1488 l | l .
1489 ATTRIBUTE TYPE ATTRIBUTE VALUE
1490 _
1491 Interface Stability Obsolete
1492 .TE
1493
1494 .SH SEE ALSO
1495 .LP
1496 \fBinityp2l\fR(1M), \fBmakedbm\fR(1M), \fBypserv\fR(1M),
1497 \fBber_printf\fR(3LDAP), \fBsprintf\fR(3C), \fBsscanf\fR(3C),
1498 \fBypserv\fR(4), \fBattributes\fR(5)
1499 .sp
1500 .LP
1501 \fISystem Administration Guide: Naming and Directory Services (DNS, NIS, and
1502 LDAP)\fR