Tribblix: manual page: NISLDAPmapping.5

NISLDAPMAPPING(5) File Formats and Configurations NISLDAPMAPPING(5)

NAME

NISLDAPmapping - mapping file used by the NIS server components

SYNOPSIS

/var/yp/NISLDAPmapping

DESCRIPTION

The NISLDAPmapping file specifies the mapping between NIS map entries
and equivalent Directory Information Tree (DIT) entries.

The presence of /var/yp/NISLDAPmapping on a NIS master server causes
that server to obtain NIS data from LDAP. See ypserv(5). If
/var/yp/NISLDAPmapping is present but the connection configuration
file that is defined in /etc/default/ypserv cannot be found, a
warning is logged. See ypserv(8).

NIS slave servers always obtain their data from a NIS master server,
whether or not that server is getting data from LDAP, and ignore the
/var/yp/NISLDAPmapping file.

A simple NISLDAPmapping file is created using inityp2l(8). You can
customize your NISLDAPmapping file as you require.

Each attribute defined below can be specified in
/var/yp/NISLDAPmapping or as an LDAP attribute. If both are
specified, then the attribute in /var/yp/NISLDAPmapping (including
empty values) takes precedence.

A continuation is indicated by a '\' (backslash) in the last
position, immediately before the newline of a line. Characters are
escaped, that is, exempted from special interpretation, when preceded
by a backslash character.

The '#' (hash) character starts a comment. White space is either
ASCII space or a horizontal tab. In general, lines consist of
optional white space, an attribute name, at least one white space
character, and an attribute value.

EXTENDED DESCRIPTION

File Syntax

Repeated fields, with separator characters, are described by the
following syntax:

One or more entries
entry:entry:entry

entry[":"...]

Zero or more entries

[entry":"...]

Attributes

Attributes generally apply to one more more NIS maps. Map names can
be specified either on their own, that is in passwd.byname, in which
case they apply to all domains, or for individual NIS domains, for
example, in passwd.byname,example.sun.uk. Where a map is mentioned in
more than one attribute, both versions are applied. If any parts of
the attributes are in conflict, the domain specific version takes
precedence over the non-domain specific version.

Each domain specific attributes must appear in NISLDAPmapping before
any related non-domain specific attribute. If non-domain specific
attributes appear first, behavior may be unpredictable. Errors are
logged when non-domain specific attributes are found first.

You can associate a group of map names with a databaseId. In effect,
a macro is expanded to the group of names. Use this mechanism where
the same group of names is used in many attributes or where domain
specific map names are used. Then, you can make any changes to the
domain name in one place.

Unless otherwise noted, all elements of the syntaxes below may be
surrounded by white space. Separator characters and white space must
be escaped if they are part of syntactic elements.

The following attributes are recognized.

nisLDAPdomainContext

The context to use for a NIS domain.

The syntax for nisLDAPdomainContext is:

NISDomainName ":" context

The following is an example of the nisLDAPdomainContext
attribute:

domain.one : dc=site, dc=example, dc=com

The mapping file should define the context for each domain before
any other attribute makes use of the NISDomainName specified for
that domain.

nisLDAPyppasswddDomains

Lists the domains for which password changes should be made. NIS
password change requests do not specify the domains in which any
given password should be changed. In traditional NIS this
information is effectively hard coded in the NIS makefile.

The syntax for the nisLDAPyppasswddDomains attribute is:

domainname

If there are multiple domains, use multiple
nisLDAPyppasswddDomain entries with one domainname per entry.

nisLDAPdatabaseIdMapping

Sets up an alias for a group of NIS map names. There is no
default value.

The syntax for the nisLDAPdatabaseIdMapping attribute is:

databaseId ":" ["["indexlist"]"] mapname[" "...]

where

databaseId = Label identifying a (subset of a) NIS
object for mapping purposes.
indexlist = fieldspec[","...]
fieldspec = fieldname "=" fieldvalue
fieldname = The name of a entry field as defined in
nisLDAPnameFields.
fieldvalue = fieldvaluestring | \" fieldvaluestring \"

indexlist is used for those cases where it is necessary to select
a subset of entries from a NIS map. The subset are those NIS
entries that match the indexlist. If there are multiple
specifications indexed for a particular NIS map, they are tried
in the order retrieved until one matches. Note that retrieval
order usually is unspecified for multi-valued LDAP attributes.
Hence, if using indexed specifications when
nisLDAPdatabaseIdMapping is retrieved from LDAP, make sure that
the subset match is unambiguous.

If the fieldvaluestring contains white space or commas, it must
either be surrounded by double quotes, or the special characters
must be escaped. Wildcards are allowed in the fieldvaluestring.
See Wildcards.

To associate the passwd.byname and passwd.byuid maps with the
passwd databaseId:

passwd:passwd.byname passwd.byuid

The passwd and passwd.adjunct databaseIds receive special
handling. In addition to its normal usage, passwd defines which
maps yppasswdd is to update when a passwd is changed. In addition
to its normal usage passwd.adjunct defines which maps yppasswdd
is to update when an adjunct passwd is changed.

You may not alias a single map name to a different name, as the
results are unpredictable.

nisLDAPentryTtl

Establish TTLs for NIS entries derived from LDAP.

The syntax for the nisLDAPentryTtl attribute is:

mapName[" "...]":"
initialTTLlo ":" initialTTLhi ":" runningTTL

where

initialTTLlo
The lower limit for the initial TTL (in seconds)
for data read from LDAP when the ypserv starts.
If the initialTTLhi also is specified, the actual
initialTTL will be randomly selected from the
interval initialTTLlo to initialTTLhi, inclusive.
Leaving the field empty yields the default value
of 1800 seconds.

initialTTLhi
The upper limit for the initial TTL. If left
empty, defaults to 5400 seconds.

runningTTL
The TTL (in seconds) for data retrieved from LDAP
while the ypserv is running. Leave the field
empty to obtain the default value of 3600
seconds.

If there is no specification of TTLs for a particular map, the
default values are used.

If the initialTTLlo and initialTTLhi have the same value, the
effect will be that all data known to the ypserv at startup times
out at the same time. Depending on NIS data lookup patterns, this
could cause spikes in ypserv-to-LDAP traffic. In order to avoid
that, you can specify different initialTTLlo and initialTTLhi
values, and obtain a spread in initial TTLs.

The following is an example of the nisLDAPentryTtl attribute used
to specify that entries in the NIS host maps read from LDAP
should be valid for four hours. When ypserv restarts, the disk
database entries are valid for between two and three hours.

hosts.byname hosts.byaddr:7200:10800:14400

nisLDAPobjectDN

Specifies the connection between a group of NIS maps and the LDAP
directory. This attribute also defines the 'order' of the NIS
maps. When NIS maps are bulk copied to or from the DIT, they are
processed in the same order as related nisLDAPobjectDN attributes
appear in /var/yp/NISLDAPmapping.

The syntax for the nisLDAPobjectDN attribute is:

mapName[" "...] ":" objectDN *( ";" objectDN )

where

objectDN = readObjectSpec [":"[writeObjectSpec]]
readObjectSpec = [baseAndScope [filterAttrValList]]
writeObjectSpec = [baseAndScope [attrValList]]
baseAndScope = [baseDN] ["?" [scope]]
filterAttrValList = ["?" [filter | attrValList]]]
scope = "base" | "one" | "sub"
attrValList = attribute "=" value
*("," attribute "=" value)

The baseDN defaults to the value of the nisLDAPdomainContext
attribute for the accessed domain. If the baseDN ends in a comma,
the nisLDAPdomainContext value is appended.

scope defaults to one. scope has no meaning and is ignored in a
writeObjectSpec.

The filter is an LDAP search filter and has no default value.

The attrValList is a list of attribute and value pairs. There is
no default value.

As a convenience, if an attrValList is specified in a
readObjectSpec, it is converted to a search filter by ANDing
together the attributes and the values. For example, the
attribute and value list:

objectClass=posixAccount,objectClass=shadowAccount

is converted to the filter:

(&(objectClass=posixAccount)\
(objectClass=shadowAccount))

Map entries are mapped by means of the relevant mapping rules in
the nisLDAPnameFields and nisLDAPattributeFromField .

If a writeObjectSpec is omitted, the effect is one of the
following:

o If there is no trailing colon after the
readObjectSpec, then there is no write at all.

o If there is a colon after the readObjectSpec, then
writeObjectSpec equals readObjectSpec.
The following is an example of a nisLDAPobjectDN attribute
declaration that gets the hosts.byaddr map entries from the
ou=Hosts container under the default search base and writes to
the same place.

hosts.byaddr:ou=Hosts,?one?objectClass=ipHost:

The following is an example of a nisLDAPobjectDN attribute
declaration that obtains passwd map entries from the ou=People
containers under the default search base, and also from
dc=another,dc=domain.

passwd:ou=People,?one?\
objectClass=shadowAccount,\
objectClass=posixAccount:;\
ou=People,dc=another,dc=domain,?one?\
objectClass=shadowAccount,\
objectClass=posixAccount

nisLDAPnameFields

Specifies the content of entries in a NIS map and how they should
be broken into named fields. nisLDAPnameFields is required
because NIS maps do not store information in named fields.

The syntax for the nisLDAPnameFields attribute is as follows:

"nisLDAPnameFields" mapName ":" "(" matchspec "," fieldNames ")"
fieldName = nameOrArrayName[","...]
nameOrArrayName = Name of field or 'array' of repeated fields.
matchspec = \" formatString \"

formatString may contain a list of %s and %a elements each of
which represents a single named field or a list of repeated
fields. A %a field is interpreted as an IPv4 address or an IPv6
address in preferred format. If an IPv6 address in non preferred
format is found, then it is converted and a warning is logged.

Where there are a list of repeated fields, the entire list is
stored as one entry. The fields are broken up into individual
entries, based on the internal separator, at a latter stage.
Other characters represent separators which must be present. Any
separator, including whitespace, specified by the formatString,
may be surrounded by a number of whitespace and tab characters.
The whitespace and tab characters are ignored.

Regardless of the content of this entry some fieldNames are
reserved:

rf_key
The DBM key value.

rf_ipkey
The DBM key value handled as an IP address. See
the discussion of %a fields.

rf_comment
Everything following the first occurrence of a
symbol. rf_comment is defined by
nisLDAPcommentChar.

rf_domain
The name of the domain in which the current NIS
operation is being carried out.

rf_searchipkey
The rf_searchkey value handled as an IP
address. See the discussion of %a fields above.

rf_searchkey
See the description under
nisLDAPattributeFromField below.

For example, the rpc.bynumber map has the format:

name number alias[" "...]

The NIS to LDAP system is instructed to break it into a name, a
number, and an array of alias field by the following entry in the
mapping file:

nisLDAPnameFields rpc.bynumber : \
"%s %s %s", name,number,aliases)

nisLDAPsplitFields

Defines how a field, or list of fields, named by
nisLDAPnameFields is split into subfields. The original field is
compared with each line of this attribute until one matches. When
a match is found named subfields are generated. In latter
operations subfield names can be used in the same way as other
field names.

The syntax for the nisLDAPsplitFields attribute is as follows:

"nisLDAPsplitFields" fieldName ":" splitSpec[","...]
splitSpec = "(" matchspec "," subFieldNames ")"
fieldName = Name of a field from nisLDAPnameFields
subFieldNames = subFieldname[","...]
matchspec = \" formatString \"

The netgroup memberTriples can have format (host, user, domain)
or groupname. The format is specified by the attribute:

nisLDAPsplitField memberTriple: \
("(%s,%s,%s)", host, user, domain) , \
("%s", group)

Later operations can then use field names host, user, domain,
group or memberTriple. Because lines are processed in order, if
host, user and domain are found, group will not be generated.

Several maps and databaseIds may contain fields that are to be
split in the same way. As a consequence, the names of fields to
be split must be unique across all maps and databaseIds.

Only one level of splitting is supported. That is, a subfield
cannot be split into further subfields.

nisLDAPrepeatedFieldSeparators

Where there is a list of repeated, splittable fields,
nisLDAPrepeatedFieldSeparators specifies which characters
separate instances of the splittable field.

The syntax for the nisLDAPrepeatedFieldSeparators attribute is as
follows:

"nisLDAPrepeatedFieldSeparators" fieldName \"sepChar[...]\"
sepChar = A separator character.

The default value is space or tab. If repeated splittable fields
are adjacent, that is, there is no separating character, then the
following should be specified:

nisLDAPrepeatedFieldSeparators netIdEntry: ""

nisLDAPcommentChar

Specifies which character represents the start of the special
comment field in a given NIS map. If this attribute is not
present then the default comment character # is used.

To specify that a map uses an asterisk to mark the start of
comments.

nisLDAPcommentChar mapname : '*'

If a map cannot contain comments, then the following attribute
should be specified.

nisLDAPcommentChar mapname : ''

nisLDAPmapFlags

Indicates if YP_INTERDOMAIN or YP_SECURE entries should be
created in a map. Using nisLDAPmapFlags is equivalent to running
makedbm(8) with the -b or the -s option. When a map is created
from the contents of the DIT, the mapping file attribute is the
only source for the YP_INTERDOMAIN or YP_SECURE entries.

The syntax for the nisLDAPmapFlags attribute is as follows:

"nisLDAPmapFlags" mapname ":" ["b"]["s"]

By default neither entry is created.

nisLDAPfieldFromAttribute

Specifies how a NIS entries field values are derived from LDAP
attribute values.

The syntax for the nisLDAPfieldFromAttribute attribute is as
follows:

mapName ":" fieldattrspec *("," fieldattrspec)

The format of fieldattrspec is shown below at Field and Attribute
Conversion Syntax.

To map by direct copy and assignment the value of the
ipHostNumber attribute to the addr named field, for example:

addr=ipHostNumber

Formats for the named field and attribute conversion syntax are
discussed below, including examples of complex attribute to field
conversions.

nisLDAPattributeFromField

Specifies how an LDAP attribute value is derived from a NIS
entry field value.

The syntax for the nisLDAPattributeFromField attribute is as
follows:

mapName ":" fieldattrspec *("," fieldattrspec )

The format of fieldattrspec is shown below at Field and Attribute
Conversion Syntax.

As a special case, if the dn attribute value derived from a
fieldattrspec ends in a comma (","), the domains context from
nisLDAPdomainContext is appended.

Use the following example to map the value of the addr field to
the ipHostNumber attribute by direct copy and assignment:

ipHostNumber=addr

All relevant attributes, including the dn, must be specified.

For every map it must be possible to rapidly find a DIT entry
based on its key. There are some maps for which a NIS to LDAP
mapping for the key is not desirable, so a key mapping cannot be
specified. In these cases a mapping that uses the reserved
rf_searchkey must be specified. Mappings that use this field name
are ignored when information is mapped into the DIT.

Field and Attribute Conversion Syntax

The general format of a fieldattrspec is:

fieldattrspec = lhs "=" rhs
lhs = lval | namespeclist
rhs = rval | [namespec]
namespeclist = namespec | "(" namespec *("," namespec) ")"

The lval and rval syntax are defined below at Values. The format of a
namespec is:

namespec

["ldap:"] attrspec [searchTriple] | ["yp:"] fieldname
[mapspec]

fieldname

field | "(" field ")"

attrspec

attribute | "(" attribute ")"

searchTriple

":" [baseDN] ["?" [scope] ["?" [filter]]]

baseDN
Base DN for search

filter
LDAP search filter

mapspec
Map name

The repository specification in a namespec defaults is as follows:

o For assignments to a field:

on the LHS
yp

on the RHS
ldap

NIS field values on the RHS are those that exist before the NIS
entry is modified.

o For assignments to an attribute:

on the LHS
ldap

on the RHS
yp

Attribute values on the RHS are those that exist before the LDAP
entry is modified.

When the field or attribute name is enclosed in parenthesis, it
denotes a list of field or attribute values. For attributes, the
meaning is the list of all attributes of that name, and the
interpretation depends on the context. See the discussion at Values.
The list specification is ignored when a searchTriple or mapspec is
supplied.

For fields, the fieldname syntax is used to map multiple attribute
instances to multiple NIS entries.

The searchTriple can be used to specify an attribute from a location
other than the read or write target. The defaultvalues are as
follows:

baseDN
If baseDN is omitted, the default is the current objectDN.
If the baseDN ends in a comma, the context of the domain is
appended from nisLDAPdomainContext .

scope
one

filter
Empty

Similarly, the mapspec can be used to specify a field value from a
NIS map other than the one implicitly indicated by the mapName. If
searchTriple or mapspec is explicitly specified in a namespec, the
retrieval or assignment, whether from or to LDAP or NIS, is performed
without checking if read and write are enabled for the LDAP container
or NIS map.

The omission of the namespec in an rhs is only allowed if the lhs is
one or more attributes. The effect is to delete the specified
attribute(s). In all other situations, an omitted namespec means that
the rule is ignored.

The filter can be a value. See Values. For example, to find the
ipHostNumberthat uses the cn, you specify the following in the filter
field:

ldap:ipHostNumber:?one?("cn=%s", (cname, "%s.*"))

In order to remove ambiguity, the unmodified value of a single field
or attribute must be specified as the following when used in the
filter field.

("%s", namespec)

If the filter is not specified, the scope will be base, and the
baseDN is assumed to be the DN of the entry that contains the
attribute to be retrieved or modified. To use previously existing
field or attribute values in the mapping rules requires a lookup to
find those values. Obviously, this adds to the time required to
perform the modification. Also, there is a window between the time
when a value is retrieved and then slightly later stored back. If the
values have changed in the meantime, the change may be overwritten.

When fieldattrspecs are grouped into rule sets, in the value of a
nisLDAPfieldFromAttribute or nisLDAPattributeFromField attribute, the
evaluation of the fieldattrspecs proceed in the listed order.
However, evaluation may be done in parallel for multiple
fieldattrspecs. If there is an error when evaluating a certain
fieldattrspec, including retrieval or assignment of entry or field
values, the extent to which the other fieldattrspec rules are
evaluated is unspecified.

Wildcards

Where wildcard support is available, it is of the following limited
form:

*
Matches any number of characters

[x]
Matches the character x

[x-y]
Matches any character in the range x to y, inclusive

Combinations such as [a-cA-C0123] are also allowed, which would match
any one of a, b, c, A, B, C, 0, 1, 2, or 3.

Substring Extraction

substringextract = "(" namespec "," matchspec ")"
name = field or attribute name
matchspec =

The matchspec is a string like the sscanf(3C) format string, except
that there may be at most one format specifier, a single %s. The
output value of the substringextract is the substring that matches
the location of the %s.

If there is no %s in the formatstring, it must instead be a single
character, which is assumed to be a field separator for the namespec.
The output values are the field values. Wild cards are supported. If
there is no match, the output value is the empty string, " ".

For example, if the fieldcname has the value user.some.domain.name.,
the value of the expression:

(cname, "%s.*")

is user, which can be used to extract the user name from a NIS
principal name.

Similarly, use this expression to extract the third of the colon-
separated fields of the shadow field:

(shadow, "*:*:%s:*")

This form can be used to extract all of the shadow fields. However, a
simpler way to specify that special case is:

(shadow, ":")

Values

lval = "(" formatspec "," namespec *("," namespec) ")"
rval = "(" formatspec ["," namelist ["," elide] ] ")"

namelist = name_or_sse *( "," name_or_sse)
name_or_sse = namespec | removespec | substringextract
removespec = list_or_name "-" namespec
list_or_name = "(" namespec ")" | namespec
formatspec =
formatstring = A string combining text and % field specifications
elide =
singlechar = Any character

The syntax above is used to produce rval values that incorporate
field or attribute values, in a manner like sprintf(3C), or to
perform assignments to lval like sscanf(3C). One important
restriction is that the format specifications,% plus a single
character, use the designations from ber_printf(3LDAP). Thus, while
%s is used to extract a string value, %i causes BER conversion from
an integer. Formats other than %s, for instance, %i, are only
meaningfully defined in simple format strings without any other text.

The following ber_printf() format characters are recognized:

b i n o s

If there are too few format specifiers, the format string may be
repeated as needed.

When used as an lval, there is a combination of pattern matching and
assignment, possibly to multiple fields or attributes.

In an assignment to an attribute, if the value of the addr field is
1.2.3.4, the rval:

("ipNetworkNumber=%s,", addr)

produces the value ipNetworkNumber=1.2.3.4,, while:

("(%s,%s,%s)", host, user, domain)

results in:

(assuming host="xyzzy", user="-", domain="x.y.z")
"(xyzzy,-,x.y.z)"

The elide character feature is used with attribute lists. So:

("%s,", (mgrprfc822mailmember), ",")

concatenates all mgrprfc822mailmember values into one comma-separated
string, and then elides the final trailing comma. Thus, for

mgrprfc822mailmember=usera
mgrprfc822mailmember=userb
mgrprfc822mailmember=userc

the value would be:

usera,userb,userc

As a special case, to combine an LHS extraction with an RHS implicit
list creates multiple entries and values. So

("(%s,%s,%s)", host, user, domain)=(nisNetgroupTriple)

creates one NIS entry for each nisNetgroupTriple value.

The 'removespec' form is used to exclude previously assigned fields
values from a list. So, if an LDAP entry contains:

name: foo
cn: foo
cn: foo1
cn: foo2

and the mapping file specifies :

myName = name, \
myAliases = ("%s ", (cn) - yp:myName, " ")

then the following assignments are carried out:

1. Assign value foo to myName

2. Assign value foo foo1 foo2 to myAliases

3. Remove value of myName from value myAliases

This results in the field values myName is set to foo, and myAliases
is set to foo1 foo2.

Assignments

The assignment syntax, also found at Field and Attribute Conversion
Syntax, is as follows:

fieldattrspec = lhs "=" rhs
lhs = lval | namespeclist
rhs = rval | namespec
namespeclist = namespec | "(" namespec *("," namespec) ")"

The general form of a simple assignment, which is a one-to-one
mapping of field to attribute, is:

("%s", fieldname)=("%s", attrname)

As a convenient shorthand, this can also be written as:

fieldname=attrname

A list specification, which is a name enclosed in parenthesis, can be
used to make many-to-many assignments. The expression:

(fieldname)=(attrname)

where there are multiple instances of attrname, creates one NIS entry
for each such instance, differentiated by their fieldname values. The
following combinations of lists are allowed, but they are not
particularly useful:

(attrname)=(fieldname)
Equivalent to attrname=fieldname

attrname=(fieldname)
Equivalent to attrname=fieldname

(fieldname)=attrname
Equivalent to fieldname=attrname

fieldname=(attrname)
Equivalent to fieldname=attrname

If a multi-valued RHS is assigned to a single-valued LHS, the LHS
value will be the first of the RHS values. If the RHS is an attribute
list, the first attribute is the first one returned by the LDAP
server when queried. Otherwise, the definition of "first" is
implementation dependent.

Finally, the LHS can be an explicit list of fields or attributes,
such as:

(name1,name2,name3)

If the RHS is single-valued, this assigns the RHS value to all
entities in the list. If the RHS is multi-valued, the first value is
assigned to the first entity of the list, the second value to the
second entity, and so on. Excess values or entities are silently
ignored.

EXAMPLES

Example 1: Assigning an Attribute Value to a Field

The following example illustrates how to assign the value of the
ipHostNumber attribute to the addr field

addr=ipHostNumber

Example 2: Creating Multiple NIS Entries from Multi-Valued LDAP

Attributes

An LDAP entry with:

cn=name1
cn=name2
cn=name3

and the following assignments:

cname=cn
(name)=(cn)

creates three NIS entries. Other attributes and fields are omitted
for clarity.

cname=name1, name=name1
cname=name1, name=name2
cname=name1, name=name3

Example 3: Assigning String Constants

The following expression sets the passwd field to x:

passwd=("x")

Example 4: Splitting Field Values to Multi-Valued Attributes

The expansion field contains a comma-separated list of alias member
names. In the following example, the expression assigns each member
name to an instance of mgrprfc822mailmember:

(mgrprfc822mailmember)=(expansion, ",")

FILES

/var/yp/NISLDAPmapping
Mapping file used by the NIS server
components

ATTRIBUTES