/var/yp/NISLDAPmapping

The NISLDAPmapping file specifies the mapping between NIS map entries and equivalent Directory Information Tree (DIT) entries. The syntax of this file is based on the equivalent NIS+ to LDAP mapping file, NIS+LDAPmapping(4).

The presence of /var/yp/NISLDAPmapping on a NIS master server causes that server to obtain NIS data from LDAP. See ypserv(4). 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(1M).

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(1M). You can customize your NISLDAPmapping file as you require.

Each attribute defined below can be specified in/var/yp/NISLDAPmappingLDAP 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 '\e' (backslash) in the last position, immediately before the newline of a line. Characters are escaped, that is, exempted from special interpretation, when preceeded 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.

Repeated fields, with separator characters, are described by the following syntax: One or more entries

entry[":"...]

[entry":"...]

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

NISDomainName ":" context

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

domainname

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

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 | \e" fieldvaluestring \e"

passwd:passwd.byname passwd.byuid

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

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

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

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

objectClass=posixAccount,objectClass=shadowAccount

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

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

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

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

name number alias[" "...]

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

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

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

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

nisLDAPrepeatedFieldSeparators netIdEntry: ""

nisLDAPcommentChar mapname : '*'

nisLDAPcommentChar mapname : ''

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

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

addr=ipHostNumber

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

ipHostNumber=addr

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]

field | "(" field ")"

attribute | "(" attribute ")"

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

The repository specification in a namespec defaults is as follows:

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

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 ommision 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 mean time, 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.

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

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.

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, ":")

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, \e
myAliases = ("%s ", (cn) - yp:myName, " ")

then the following assignments are carried out:

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

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)

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.

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, ",")

See attributes(5) for descriptions of the following attributes:

inityp2l(1M), makedbm(1M), ypserv(1M), ber_printf(3LDAP), sprintf(3C), sscanf(3C), NIS+LDAPmapping(4), ypserv(4), attributes(5)

System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP)