8.3. Automatically Creating Dual Entries

Some clients and integration with Red Hat Directory Server require dual entries. For example, both Posix systems typically have a group for each user. The Directory Server's Managed Entries Plug-in creates a new managed entry, with accurate and specific values for attributes, automatically whenever an appropriate origin entry is created.

8.3.1. About Managed Entries

The basic idea behind the Managed Entries Plug-in is that there are situations when Entry A is created and there should automatically be an Entry B with related attribute values. For example, when a Posix user (posixAccount entry) is created, a corresponding group entry (posixGroup entry) should also be created. An instance of the Managed Entries Plug-in identifies what entry (the origin entry) triggers the plug-in to automatically generate a new entry (the managed entry).
The plug-in works within a defined scope of the directory tree, so only entries within that subtree and that match the given search filter trigger a Managed Entries operation.
Much like configuring a class of service, a managed entry is configured through two entries:
  • A definition entry, that identifies the scope of the plug-in instance and the template to use
  • A template entry, that models what the final managed entry will look like

8.3.1.1. About the Instance Definition Entry

As with the Linked Attributes and DNA Plug-ins, the Managed Entries Plug-in has a container entry in cn=plugins,cn=config, and each unique configuration instance of the plug-in has a definition entry beneath that container.
An instance of the Managed Entries Plug-in defines three things:
  • The search criteria to identify the origin entries (using a search scope and a search filter)
  • The subtree under which to create the managed entries (the new entry location)
  • The template entry to use for the managed entries
Defining Managed Entries

Figure 8.2. Defining Managed Entries

For example: 
dn: cn=Posix User-Group,cn=Managed Entries,cn=plugins,cn=config
objectclass: extensibleObject
cn: Posix User-Group
originScope: ou=people,dc=example,dc=com
originFilter: objectclass=posixAccount
managedBase: ou=groups,dc=example,dc=com
managedTemplate: cn=Posix User-Group Template,ou=Templates,dc=example,dc=com
The origin entry does not have to have any special configuration or settings to create a managed entry; it simply has to be created within the scope of the plug-in and match the given search filter.

8.3.1.2. About the Template Entry

Each instance of the plug-in uses a template entry which defines the managed entry configuration. The template effectively lays out the entry, from the object classes to the entry values.

Note

Since the template is referenced in the definition entry, it can be located anywhere in the directory. However, it is recommended that the template entry be under the replicated suffix so that any other masters in multi-master replication all use the same template for their local instances of the Managed Entries Plug-in.
The concept of a template entry is similar to the templates used in CoS, but there are some important differences. The managed entry template is slightly different than the type of template used for a class of service. For a class of service, the template contains a single attribute with a specific value that is fed into all of the entries which belong to that CoS. Any changes to the class of service are immediately reflected in the associated entries, because the CoS attributes in those entries are virtual attributes, not truly attributes set on the entry.
The template entry for the Managed Entries Plug-in, on the other hand, is not a central entry that supplies values to associated entries. It is a true template — it lays out what is in the entry. The template entry can contain both static attributes (ones with pre-defined values, similar to a CoS) and mapped attributes (attributes that pull their values or parts of values from the origin entry). The template is referenced when the managed entry is created and then any changes are applied to the managed entry only when the origin entry is changed and the template is evaluated again by the plug-in to apply those updates.
Templates, Managed Entries, and Origin Entries

Figure 8.3. Templates, Managed Entries, and Origin Entries

The template can provide a specific value for an attribute in the managed entry by using a static attribute in the template. The template can also use a value that is derived from some attribute in the origin entry, so the value may be different from entry to entry; that is a mapped attribute, because it references the attribute type in the origin entry, not a value.
A mapped value use a combination of token (dynamic values) and static values, but it can only use one token in a mapped attribute. 
dn: cn=Posix User-Group Template,ou=Templates,dc=example,dc=com
objectclass: mepTemplateEntry
cn: Posix User-Group Template
mepRDNAttr: cn
mepStaticAttr: objectclass: posixGroup
mepMappedAttr: cn: $cn Group Entry
mepMappedAttr: gidNumber: $gidNumber
mepMappedAttr: memberUid: $uid
The mapped attributes in the template use tokens, prepended by a dollar sign ($), to pull in values from the origin entry and use it in the managed entry. (If a dollar sign is actually in the managed attribute value, then the dollar sign can be escaped by using two dollar signs in a row.)
A mapped attribute definition can be quoted with curly braces, such as Attr: ${cn}test. Quoting a token value is not required if the token name is not immediately followed by a character that is valid in an attribute name, such as a space or comma. For example, $cn test is acceptable in an attribute definition because a space character immediately follow the attribute name, but $cntest is not valid because the Managed Entries Plug-in attempts to look for an attribute named cntest in the origin entry. Using curly braces identifies the attribute token name.

Note

Make sure that the values given for static and mapped attributes comply with the required attribute syntax.

8.3.1.3. Entry Attributes Written by the Managed Entries Plug-in

Both the origin entry and the managed entry have special managed entries attributes which indicate that they are being managed by an instance of the Managed Entries Plug-in. For the origin entry, the plug-in adds links to associated managed entries. 
dn: uid=jsmith,ou=people,dc=example,dc=com
objectclass: mepOriginEntry
objectclass: posixAccount
...
sn: Smith
mail: jsmith@example.com
mepManagedEntry: cn=jsmith Posix Group,ou=groups,dc=example,dc=com
On the managed entry, the plug-in adds attributes that point back to the origin entry, in addition to the attributes defined in the template. 
dn: cn=jsmith Posix Group,ou=groups,dc=example,dc=com
objectclass: mepManagedEntry
objectclass: posixGroup
...
mepManagedBy: uid=jsmith,ou=people,dc=example,dc=com
Using special attributes to indicate managed and origin entries makes it easy to identify the related entries and to assess changes made by the Managed Entries Plug-in.

8.3.1.4. Managed Entries Plug-in and Directory Server Operations

The Managed Entries Plug-in has some impact on how the Directory Server carries out common operations, like add and delete operations.

Table 8.3. Managed Entries Plug-in and Directory Server Operations

Operation Effect by the Managed Entries Plug-in
Add With every add operation, the server checks to see if the new entry is within the scope of any Managed Entries Plug-in instance. If it meets the criteria for an origin entry, then a managed entry is created and managed entry-related attributes are added to both the origin and managed entry.
Modify
If an origin entry is modified, it triggers the plug-in to update the managed entry. Changing a template entry, however, does not update the managed entry automatically. Any changes to the template entry are not reflected in the managed entry until after the next time the origin entry is modified.
The mapped managed attributes within a managed entry cannot be modified manually, only by the Managed Entry Plug-in. Other attributes in the managed entry (including static attributes added by the Managed Entry Plug-in) can be modified manually.
Delete If an origin entry is deleted, then the Managed Entries Plug-in will also delete any managed entry associated with that entry. There are some limits on what entries can be deleted.
  • A template entry cannot be deleted if it is currently referenced by a plug-in instance definition.
  • A managed entry cannot be deleted except by the Managed Entries Plug-in.
Rename If an origin entry is renamed, then plug-in updates the corresponding managed entry. If the entry is moved out of the plug-in scope, then the managed entry is deleted, while if an entry is moved into the plug-in scope, it is treated like an add operation and a new managed entry is created. As with delete operations, there are limits on what entries can be renamed or moved.
  • A configuration definition entry cannot be moved out of the Managed Entries Plug-in container entry. If the entry is removed, that plug-in instance is inactivated.
  • If an entry is moved into the Managed Entries Plug-in container entry, then it is validated and treated as an active configuration definition.
  • A template entry cannot be renamed or moved if it is currently referenced by a plug-in instance definition.
  • A managed entry cannot be renamed or moved except by the Managed Entries Plug-in.
Replication The Managed Entries Plug-in operations are not initiated by replication updates. If an add or modify operation for an entry in the plug-in scope is replicated to another replica, that operation does not trigger the Managed Entries Plug-in instance on the replica to create or update an entry. The only way for updates for managed entries to be replicated is to replicate the final managed entry over to the replica.

8.3.2. Creating the Managed Entries Template Entry

The first entry to create is the template entry. The template entry must contain all of the configuration required for the generated, managed entry. This is done by setting the attribute-value assertions in static and mapped attributes in the template: 
mepStaticAttr: attribute: specific_value
mepMappedAttr: attribute: $token_value
The static attributes set an explicit value; mapped attributes pull some value from the originating entry is used to supply the given attribute. The values of these attributes will be tokens in the form attribute: $attr. As long as the syntax of the expanded token of the attribute does not violate the required attribute syntax, then other terms and strings can be used in the attribute. For example: 
mepMappedAttr: cn: Managed Group for $cn
There are some syntax rules that must be followed for the managed entries:
  • A mapped value use a combination of token (dynamic values) and static values, but it can only use one token per mapped attribute.
  • The mapped attributes in the template use tokens, prepended by a dollar sign ($), to pull in values from the origin entry and use it in the managed entry. (If a dollar sign is actually in the managed attribute value, then the dollar sign can be escaped by using two dollar signs in a row.)
  • A mapped attribute definition can be quoted with curly braces, such as Attr: ${cn}test. Quoting a token value is not required if the token name is not immediately followed by a character that is valid in an attribute name, such as a space or comma. For example, $cn test is acceptable in an attribute definition because a space character immediately follow the attribute name, but $cntest is not valid because the Managed Entries Plug-in attempts to look for an attribute named cntest in the origin entry. Using curly braces identifies the attribute token name.
  • Make sure that the values given for static and mapped attributes comply with the required attribute syntax.

Note

Make sure that the values given for static and mapped attributes comply with the required attribute syntax. For example, if one of the mapped attributes is gidNumber, then the mapped value should be an integer.

Table 8.4. Attributes for the Managed Entry Template

Attribute Description
mepTemplateEntry (object class) Identifies the entry as a template.
cn Gives the common name of the entry.
mepMappedAttr Contains an attribute-token pair that the plug-in uses to create an attribute in the managed entry with a value taken from the originating entry.
mepRDNAttr Specifies which attribute to use as the naming attribute in the managed entry. The attribute used as the RDN must be a mapped attribute for the configuration to be valid.
mepStaticAttr Contains an attribute-value pair that will be used, with that specified value, in the managed entry.
To create a template entry:
Use the dsconf plugin managed-entries template add command to add the template entry. For example: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin managed-entries template "cn=Posix User Template,ou=templates,dc=example,dc=com" add --rdn-attr "cn" --static-attr "objectclass: posixGroup" --mapped-attr "cn: $cn Group Entry" "gidNumber: $gidNumber" "memberUid: $uid"

8.3.3. Creating the Managed Entries Instance Definition

Once the template entry is created, then it is possible to create a definition entry that points to that template. The definition entry is an instance of the Managed Entries Plug-in.

Note

When the definition is created, the server checks to see if the specified template entry exists. If the template does not exist, then the server returns a warning that the definition configuration is invalid.
The definition entry must define the parameters to recognize the potential origin entry and the information to create the managed entry. The attributes available for the plug-in instance are listed in Table 8.5, “Attributes for the Managed Entries Definition Entry”.

Table 8.5. Attributes for the Managed Entries Definition Entry

Attribute Name Description
originFilter The search filter to use to search for and identify the entries within the subtree which require a managed entry. The syntax is the same as a regular search filter.
originScope The base subtree which contains the potential origin entries for the plug-in to monitor.
managedTemplate Identifies the template entry to use to create the managed entry. This entry can be located anywhere in the directory tree.
managedBase The subtree under which to create the managed entries.

Note

The Managed Entries Plug-in is enabled by default. If this plug-in is disabled, then re-enable it as described in Section 1.10.3, “Enabling and Disabling Plug-ins”.
To create an instance:
  1. Create the new plug-in instance below the cn=Managed Entries,cn=plugins,cn=config container entry. For example: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin managed-entries config "cn=instance,cn=Managed Entries,cn=plugins,cn=config" add --scope="ou=people,dc=example,dc=com" --filter="objectclass=posixAccount" --managed-base="ou=groups,dc=example,dc=com" --managed-template="cn=Posix User-Group Template,ou=Templates,dc=example,dc=com"
    This command sets the scope and filter for the origin entry search, the location of the new managed entries, and the template entry to use.
  2. If the Directory Server is not configured to enable dynamic plug-ins, restart the server to load the modified new plug-in instance: 
    # dsctl instance_name restart

8.3.4. Putting Managed Entries Plug-in Configuration in a Replicated Database

As Section 8.3.1, “About Managed Entries” highlights, different instances of the Managed Entries Plug-in are created as children beneath the container plug-in entry in cn=plugins,cn=com. (This is common for plug-ins which allow multiple instances.) The drawback to this is that the configuration entries in cn=plugins,cn=com are not replicated, so the configuration has to be re-created on each Directory Server instance.
The Managed Entries Plug-in entry allows the nsslapd-pluginConfigArea attribute. This attribute to another container entry, in the main database area, which contains the plug-in instance entries. This container entry can be in a replicated database, which allows the plug-in configuration to be replicated.
  1. Create a container entry. For example, to create an entry that points back to the container entry, enter: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin managed-entries set --config-area="cn=managed entries container,ou=containers,dc=example,dc=com"
  2. Move or create the definition (Section 8.3.3, “Creating the Managed Entries Instance Definition”) and template (Section 8.3.2, “Creating the Managed Entries Template Entry”) entries under the new container entry.