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=company, 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.
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 contains 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 a asterix 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(1M) 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 entriy 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
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 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.
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.