Mapping Syntax

This section describes the syntax of the variables or tokens that you can create in each section of a table definition.

The mapping syntax is described using examples from the nis.mapping file.

Common

The variables defined in the Common section other than the keywords listed in Table 5-1 must follow this syntax:

variable-name=value

Variables defined in the Common section contain static configuration information.

Dynamic

The variables defined in the Dynamic section other than the keywords listed in Table 5-1follow the same syntax as the variables defined in the Common section. However, their values are supplied in the input to the utility (such as dsimport or dsexport) that uses the mapping file during its execution.

Extract

The variables defined in the Extract section define the rules for decomposing input information into smaller units of information, called tokens, that can be directly mapped onto LDAP attributes, or that require simple processing in order to be mapped onto LDAP attributes.

The syntax of a variable that defines a decomposition into tokens is:

VARIABLE => $element1 separator $element2 [separator $elementn...|| ...]

The separator between tokens is the separator expected in the input information. It could be white space, a comma, a colon or any other character. However, one space in the line definition will match any number of spaces or tabs in the actual input information. You can specify several alternatives for the decomposition, by using two pipe symbols (||) to introduce each alternative rule.

The conversion process examines the rules in the order in which they are specified, and applies the first one that matches the information it was given in input.

For example, in nis.mapping, the following definition extracts tokens from a line in the bootparams file:

LINE =>$ipHostNameT $parametersT

The hosts file provides a slightly more complex example:

LINE =>$dummy $ipHostNumberT $ipHostNameT $allIpHostAliasesT*#$descriptionT*||\
	        $dummy $ipHostNumberT $ipHostNameT $allIpHostAliasesT||\
	        $dummy $ipHostNumberT $ipHostNameT

In these examples, the tokens parametersT and allIpHostAliasesT require further processing before they can be mapped onto LDAP attributes. The processing required is defined in the Condense section.

Condense

The Condense section contains variables that define operations on tokens resulting from the Extract section, or any previously defined variable in the table definition.

It simplifies the attribute value definitions given in the Build section.

Variables defined in the Condense section can contain:

• A token specified in the same table section

• A configuration variable specified in the Common section for the same NIS table, or in the Common section that applies to all NIS tables

• A constant expression

• A function: exclude, getrdn, split, instances2string, string2instances, or trim. A variable can contain just one function. If you want to use several functions on the same information, you must create intermediate variables.

Variables in the Condense section can be made up of several alternative rules. The conversion process applies the first rule that matches the input information. The rules must be separated by two pipe symbols, and must all be part of the same expression. For example, the following expression is permitted:

fifi=$parameter1 - $parameter2 || $parameter1 || juju

whereas, the following expression is not:

fifi=$parameter1 - $parameter2
fifi=$parameter1
fifi=juju

You can define any number of variables in the Condense section. The order in which they are listed is important if you create dependencies between them. For instance, you can have:

fifi=$parameter1 - $parameter2 || $parameter1 || juju
riri=$fifi - $parameterA
loulou=$fifi - $parameterB

split Function

The syntax of the split function is as follows:

variableA=split(what, "separator", "add_prefix", "add_suffix", order)

where:

variableA identifies the variable

what identifies the unit of information, variable or parameter, to which the operation applies

separator indicates where to split the information. This value must be specified between quotes because it could contain a space.

add_prefix specifies a prefix to add to each item resulting from the split. This value must be specified between quotes because it could contain a space.

add_suffix specifies a suffix to add to each item resulting from the split. This value must be specified between quotes because it could contain a space.

order specifies the order in which the items resulting from the split are to be presented. The possible values for this parameter are left2right or right2left.

For example, in the nis.mapping file, the following variable definition is used to split an NIS domain name into a sequence of LDAP domain component attributes:

DC_NAMING=split($DOMAIN_NAME, ".", "dc=", ",", left2right)

If the domain name specified is eng.europe.xyz.com, the resulting expression is:

dc=eng, dc=europe, dc=xyz, dc=com.

string2instances Function

The string2instances function breaks down a specified string into instances. The syntax for this operation is:

variableA=string2instances("string", "separator")

where:

variableA identifies the variable

string identifies the unit of information, variable or parameter, to which the operation applies. This value must be specified between quotes because it could contain a space.

separator indicates where to split the information into instances. This value must be specified between quotes because it could contain a space.

For example, in nis.mapping, the following definition in the Condense section of the bootparams file breaks down a string of parameters into separate instances:

bootParameterT=string2instances($parametersT," ")

The string2instances function is also used to specify the inheritance tree for an object class. For example, if the object class of an entry created using a particular mapping definition is organizationalPerson, the Condense section of the mapping definition must contain the line:

objectClassT=string2instances("top person organizationalPerson", " ")

instances2string Function

The instances2string function combines several instances into a single string. The syntax for this operation is:

variableA=instances2string(what, "separator")

where:

variableA identifies the variable

what is a variable that has a number of instances

separator marks the separation between the elements of the string. This value must be specified between quotes because it could be a space.

For example, you could use the following variable to find the list of names and alias names for a given machine:

NameList=instances2string($cn, " ")

If the cn attribute has the values camembert, Cam, Bertie, the resulting string would be:

camembert Cam Bertie

trim Function

The trim function removes any unnecessary white space surrounding a parameter. The syntax for the trim operation is:

variableA=trim(parameter)

where:

variableA identifies the variable

parameter is the item from which white space must be removed

For example, if you decompose an alias list into its constituent members, you could define the following variables:

aliasMember=string2instances($aliasList, ",")
trimAliasMember=trim($aliasMember)

Each aliasMember parameter resulting from the string2instances operation is processed to remove any white spaces.

getrdn Function

The getrdn function returns the naming attribute of an entry, that is the attribute used in the entry's RDN. The syntax for the getrdn operation is:

variableA=getrdn()

The getrdn function can only be used in variables in the Condense section.

For example, the cn attribute of a machine has the values camembert, Cam, Bertie, but the actual system name of the machine, used in the RDN is camembert. For example, you could create the following variable:

HostName=getrdn()

The getrdn function returns the name camembert.

The getrdn function is case-sensitive.

exclude Function

The exclude function removes a value from a list or a string. The syntax for this operation is:

variableA=exclude(string, exclude-value, "separator")

where:

variableA identifies the variable

string identifies the list or string

exclude-value is the value to exclude

separator marks the separation between the elements of the list or string. This value must be specified between quotes because it could be a space.

For example, to obtain the list of aliases for a machine, you need to exclude the canonical name from the list of names. You could create the following variables:

NameList=instances2string($cn, " ")
HostName=getrdn()
HostAliases=exclude(NameList, HostName, " ")

In nis.mapping, the Condense section of the hosts mapping definition contains:

ipHostAliasesLineT=exclude($allIpHostAliasesT,$ipHostNameT, " ")

This definition excludes the ipHostName from the list of alias names for the host.

Build

The Build subsection contains a list of LDAP attributes and the definitions of their values. It must contain at least all mandatory attributes for an object class, and the DN. If the DN definition is missing from the Build section, the entries cannot be created in the directory.

You do not need to specify a DN definition in the Build sections of the radius.mapping file because this file is not used to import entries into the directory.

Attribute value definitions can be made up of:

• A variable or keyword specified in any of the sections of the table definition

• A configuration variable specified in the Common section that applies to all the tables in the Front-End section

• A constant expression

• A concatenation of any of the above

The syntax of an LDAP attribute and its associated value definition in the Build section is as follows:

LDAPattribute=attributeValueDefinition

For example, if you wanted to create an entry for a mail alias, and use the LDAP attribute rfc822mailMember to store the names of alias members, your mapping would contain the following definitions:

Condense:
	aliasMember=string2instances($aliasList, ",")
	trimAliasMember=trim($aliasMember)
...
Build:
	rfc822mailMember=$trimAliasMember
...