Appendix A Mapping Syntax and Semantics

This chapter describes the mapping syntax and semantics used in the nis.mapping file and the radius.mapping file. The mapping syntax and semantics are designed to provide maximum flexibility so that you can easily:

• Import information from any text file into the directory
• Adapt or create the mapping for a proprietary table in your NIS environment

Front-end name

     Common

     Table

             Common

             Dynamic

             Export

                     Extract

                     Condense

                     Build

             Import

                     Extract

                     Condense

                     Build

...

The content and meaning of each section is described in "Mapping Semantics" . The syntactic rules for each section are described in "Mapping Syntax" .

Front-end name indicates the name of the service. All the information that follows that name describes the mapping of service-specific information to LDAP object classes and attributes.

The first Common section immediately following the front-end name gives configuration information that applies to the front-end or service. It contains mandatory configuration variables that are required in the translation process, and optional configuration variables that are stored in the same file for convenience.

The Table section provides a mapping definition for a particular type of information. The mapping definition determines the object class of all entries created using that particular definition. Each table definition is composed of the following sections:

• Common
• Dynamic (mandatory)
• Export
• Import

Each section contains keywords and definitions used in the import or export process. Table  A.1 provides a list of mapping keywords, the sections in which they can occur, and their purpose.

In any section, you can create variables or tokens, that is, private definitions, by using the following format:

tokenT=token definition

Your private definitions can use the syntax and functions described in "Condense" .

Table A.1 Summary of Mapping File Keywords

The Common section contains definitions of variables that apply to all the entries created using that table definition but not to the entire service or front-end. For example, the Common section typically contains the subtree under which the entries are created. The subtree is specified using the BASE_DN keyword.

BASE_DN

The BASE_DN keyword specifies the subtree under which the entries are to be created. The dsimport utility looks for this parameter in several places, in the following order:

• Command line of dsimport, option -V
• Dynamic section
• Common section for the Table
• Common section for the Front-End (at the beginning of the mapping file)

The MAP_NAME keyword specifies the name of the NIS map corresponding to the table definition. This keyword is used to create administrative entries for the NIS service. The directory server maintains these entries automatically.

This keyword is used also to create the subtree for the NIS entries that are created by using the generic mapping definition.

The MAP_NAME keyword is specific to the NIS service.

PRIVATE_OBJECTCLASSES

The PRIVATE_OBJECTCLASSES keyword specifies an object class when the object class and attributes derived from a table definition do not make up a complete entry. This keyword is necessary for maintaining directory entries that are created from several table definitions. This can be the case when several table definitions each create an auxiliary object class and its associated attributes.

For example, in the NIS environment, network hosts can have entries in at least three files: /etc/bootparams, /etc/ethers, /etc/hosts. However, each host has just one entry in the LDAP directory, with the three auxiliary object classes bootableDevice, ieee802Device, and ipHost. If the entry for the host is deleted in one of these files, the corresponding entry in the LDAP directory must not be deleted but simply updated by removing the appropriate auxiliary object class, and any attributes specific to that object class.

Dynamic Section

The Dynamic section contains equations that make it possible to dynamically build the filters required to locate relevant information.

LINE

The LINE keyword is necessary to define how the input information must be dynamically decomposed to provide the elements required in the MATCH_FILTER and ALL_FILTER definitions.

The syntax of the LINE keyword is given in "Extract" .

MATCH_FILTER

The MATCH_FILTER keyword specifies a filter that is used by the dsimport utility to check whether an entry already exists in the database before creating it. If it exists, the dsimport utility will check whether it needs to be modified.

The MATCH_FILTER keyword is also used by the directory server to respond to commands such as ypmatch.

ALL_FILTER

The ALL_FILTER keyword specifies a filter that is used by the dsexport command to regenerate the file from which the directory entries were originally created. This filter is necessary even if you do not intend to export information from the directory to regenerate the source file for that information.

The ALL_FILTER keyword is used by the directory server to retrieve from the directory all entries that belong to a given NIS table.

The ALL_FILTER keyword is also used by the directory server to respond to commands such as ypcat.

DC_NAMING

The DC_NAMING keyword defines the mechanism applied to convert a domain name of the form airius.com to an LDAP data store suffix or subtree of the form dc=airius, dc=com. This is useful if the naming structure that you use in your directory is a domain component (dc) structure.

Export Section

The Export section provides the method for regenerating a source file from LDAP directory entries. This section is optional. When it exists, it must contain the keyword LINE. The LINE keyword in the Export section must reflect the format of a line in the original source file.

The Export section contains the following subsections:

• Condense
This optional subsection contains variable definitions that can be used in the Build subsection to build the parameters required to generate LINE.
• Build
Contains at least the output LINE definition.

Import Section

The Import section provides the method for translating a line in an input file into an LDAP directory entry. This section must contain a LINE keyword that defines how a line in the input file can be decomposed into elements that can be described by LDAP attributes. It must also contain the list of LDAP attributes that are created from a line in the input file.

The Import section contains the following subsections:

• Extract
Contains the LINE definition with the notation described in "Extract" .
• Condense
Contains variable definitions that can be used in the Build subsection to generate LDAP attributes and attribute values.
• Build
Provides a list of LDAP attributes, including the object class, and defines the rules for constructing the value of each LDAP attribute from the variables in the Condense section or from the parameters in the Extract section

Common

The variables defined in the Common section other than the keywords listed in Table  A.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  A.1 follow 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.

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(string, "separator", "add_prefix", "add_suffix", order)

Where:

variableA identifies the variable

string 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.airius.com, the resulting expression is:

dc=eng, dc=europe, dc=airius, 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. 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(instance, "separator")

Where:

variableA identifies the variable

instance is a discrete element of variableA

separator marks the separation between the elements of the variable. 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()

Note. 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.

Note. 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.

Note. 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

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