Chapter 6. Organizing and Grouping Entries

Entries contained within the directory can be grouped in different ways to simplify the management of user accounts. Red Hat Directory Server supports a variety of methods for grouping entries and sharing attributes between entries. To take full advantage of the features offered by roles and class of service, determine the directory topology when planning the directory deployment.

6.1. Using Groups

Groups are a mechanism for associating entries for ease of administration. Groups do not have the flexibility or utility of roles. However, there are certain clients and applications where groups are useful. Groups also offer compatibility with older LDAP clients and directory services.

Note

Managing groups is significantly easier by using the memberOf attribute to identify in user entries to what groups a user belongs. The memberOf attribute is maintained by the Directory Server and updated automatically on entries as group membership changes. See Section 6.1.4, “Listing Group Membership in User Entries” for information on using the memberOf attribute.

6.1.1. Creating Static Groups in the Console

Static groups organize entries by specifying the same group value in the DN attribute of any number of users.

Note

If a user has an entry on a remote Directory Server (for example, in a chained database), different from the Directory Server which has the entry that defines the static group, then use the Referential Integrity plug-in to ensure that deleted user entries are automatically deleted from the static group.
There are some performance and access control considerations with the Referential Integrity plug-in. For more information about using referential integrity with chaining, see Section 2.3.2, “Configuring the Chaining Policy”.
  1. In the Directory Server Console, select the Directory tab.
  2. In the left pane, right-click the entry under which to add a new group, and select New > Group.
    Alternatively, go to the Object menu, and select New > Group.
  3. Click General in the left pane. Type a name for the new group in the Group Name field (the name is required), and enter a description of the new group in the Description field.
  4. Click Members in the left pane. In the right pane, select the Static Group tab. Click Add to add new members to the group.
  5. In the Search drop-down list, select what sort of entries to search for (users, groups, or both) then click Search.
  6. Select the members from the returned entries, and click OK.
  7. Click Languages in the left pane to add language-specific information for the group.
  8. Click OK to create the new group. It appears in the right pane.
To edit a static group, double-click the group entry, and make the changes in the editor window. To view the changes, go to the View menu, and select Refresh.

Note

The Console for managing static groups may not display all possible selections during a search operation if there is no VLV index for users' search. This problem occurs only when the number of users is 1000 or more and there is no VLV index for search. To work around the problem, create a VLV index for the users suffix with the filter (objectclass=person) and scope sub-tree.

6.1.2. Creating Dynamic Groups in the Console

Dynamic groups filter users based on their DN and include them in a single group.
  1. In the Directory Server Console, select the Directory tab.
  2. In the left pane, right-click the entry under which to add a new group, and select New > Group.
    Alternatively, go to the Object menu, and select New > Group.
  3. Click General in the left pane. Type a name for the new group in the Group Name field (the name is required), and enter a description of the new group in the Description field.
  4. Click Members in the left pane. In the right pane, select the Dynamic Group tab. Click Add to create a LDAP URL for querying the database.
  5. Enter an LDAP URL in the text field or select Construct to be guided through the construction of an LDAP URL.
    The results show the current entries (group members) which correspond to the filter.
  6. Click Languages in the left pane to add language-specific information for the group.
  7. Click OK. The new group appears in the right pane.
To edit a dynamic group, double-click the group entry to open the editor window, and make whatever changes to the dynamic group. To view the changes to the group, go to the View menu, and select Refresh.

Note

The Console for managing dynamic groups may not display all possible selections during a search operation if there is no VLV index for users' search. This problem can occur when the number of users is 1000 or more and there is no VLV index for search. To work around the problem, create a VLV index for the users suffix with the filter (objectclass=person) and scope sub-tree.

6.1.3. Creating Groups in the Command Line

Creating both static and dynamic groups from the command line is a similar process. A group entry contains the group name, the type of group, and a members attribute.
There are several different options for the type of group; these are described in more detail in the Red Hat Directory Server 9 Configuration, Command, and File Reference. The type of group in this case refers to the type of defining member attribute it has:
  • groupOfNames is a simple group, that allows any entry to be added. The attribute used to determine members for this is member.
  • groupOfUniqueNames, like groupOfNames, simply lists user DNs as members, but the members must be unique. This prevents users being added more than once as a group member, which is one way of preventing self-referential group memberships. The attribute used to determine members for this is uniqueMember.
  • groupOfURLs uses a list of LDAP URLs to filter and generate its membership list. This object class is required for any dynamic group and can be used in conjunction with groupOfNames and groupOfUniqueNames.
  • groupOfCertificates is similar to groupOfURLs in that it uses an LDAP filter to search for and identify certificates (or, really, certificate names) to identify group members. This is useful for group-based access control, since the group can be given special access permissions. The attribute used to determine members for this is memberCertificate.
Table 6.1, “Dynamic and Static Group Schema” lists the default attributes for groups as they are created from the command line.

Table 6.1. Dynamic and Static Group Schema

Type of Group Group Object Classes Member Attributes
Static groupOfUniqueNames uniqueMember
Dynamic
groupOfUniqueNames
groupOfURLs
 memberURL
A static group entry lists the specific members of the group. For example: 
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=static group,ou=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfUniqueNames
cn: static group
description: Example static group.
uniqueMember: uid=mwhite,ou=People,dc=example,dc=com
uniqueMember: uid=awhite,ou=People,dc=example,dc=com
A dynamic group uses at least one LDAP URL to identify entries belonging to the group and can specify multiple LDAP URLs or, if used with another group object class like groupOfUniqueNames, can explicitly list some group members along with the dynamic LDAP URL. 
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=dynamic group,ou=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfUniqueNames
objectClass: groupOfURLs
cn: dynamic group
description: Example dynamic group.
memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))

6.1.4. Listing Group Membership in User Entries

The entries which belong to a group are defined, in some way, in the group entry itself. This makes it very easy to look at a group and see its members and to manage group membership centrally. However, there is no good way to find out what groups a single user belongs to. There is nothing in a user entry which indicates its memberships, as there are with roles.
The MemberOf Plug-in correlates group membership lists to the corresponding user entries.
The MemberOf Plug-in analyzes the member attribute in a group entry and automatically writes a corresponding memberOf attribute in the member's entry. (By default, this checks the member attribute, but mutiple attribute instances can be used to support multiple different group types.)
As membership changes, the plug-in updates the memberOf attributes on the user entries. The MemberOf Plug-in provides a way to view the groups to which a user belongs simply by looking at the entry, including nested group membership. It can be very difficult to backtrack memberships through nested groups, but the MemberOf Plug-in shows memberships for all groups, direct and indirect.
The MemberOf Plug-in manages member attributes for static groups, not dynamic groups or circular groups.

6.1.4.1. Directory Topology Considerations with the MemberOf Plug-in

memberOf and Multi-Master Replication

The memberOf attributes for user entries should not be replicated in multi-master environments. Make sure that the memberOf attribute is excluded from replication in the replication agreement. (Fractional replication is described in Section 11.1.7, “Replicating a Subset of Attributes with Fractional Replication”.)

Each server must maintain its own MemberOf Plug-in independently. To make sure that the memberOf attributes for entries are the same across servers, simply configure the MemberOf Plug-in the same on all servers.
With single-master replication, it is perfectly safe to replicate memberOf attributes. Configure the MemberOf Plug-in for the supplier, then replicate the memberOf attributes to the consumers.
memberOf and Distributed Databases

It is possible, as outlined in Section 2.2.1, “Creating Databases”, to distribute suffixes and directory data across different databases.

By default, the MemberOf Plug-in only looks for potential members for users who are in the same database as the group. If users are stored in a different database than the group, then the user entries will not be updated with memberOf attributes because the plug-in cannot ascertain the relationship between them.
The plug-in can be configured to search across all databases by enabling the memberOfAllBackends in the plug-in configuration.

6.1.4.2. Required Object Classes by the memberOf Plug-In

To enable the memberOf plug-in to add the memberOf attribute, the user entry must contain the inetUser or inetAdmin object class to support this attribute. If you configure the memberOf plug-in to use a different attribute, make sure that the user entry contains an object class that supports this attribute.
To configure nested groups, the group must use the extensibleObject object class.

Note

If directory entries do not contain an object class that supports the required attributes, operations fail with the following error: 
LDAP: error code 65 - Object Class Violation

6.1.4.3. The MemberOf Plug-in Syntax

The MemberOf Plug-in instance defines two attributes, one for the group member attribute to poll (memberOfGroupAttr) and the other for the attribute to create and manage in the member's user entry (memberOfAttr).
The memberOfGroupAttr attribute is multi-valued. Because different types of groups use different member attributes, using multiple memberOfGroupAttr attributes allows the plug-in to manage multiple types of groups.
The plug-in instance also gives the plug-in path and function to identify the MemberOf Plug-in and contains a state setting to enable the plug-in, both of which are required for all plug-ins. The default MemberOf Plug-in is shown in Example 6.1, “Default MemberOf Plug-in Entry” and the different parameters are described in Table 6.2, “MemberOf Syntax”.

Example 6.1. Default MemberOf Plug-in Entry

 dn: cn=MemberOf Plugin,cn=plugins,cn=config
 objectClass: top
 objectClass: nsSlapdPlugin
 objectClass: extensibleObject
 cn: MemberOf Plugin  
 nsslapd-pluginPath: libmemberof-plugin  
 nsslapd-pluginInitfunc: memberof_postop_init  
 nsslapd-pluginType: postoperation
 nsslapd-pluginEnabled: on  
 nsslapd-plugin-depends-on-type: database
 memberOfGroupAttr: member  
 memberOfGroupAttr: uniqueMember  
 memberOfAttr: memberOf  
 memberOfAllBackends: on  
 nsslapd-pluginId: memberOf
 nsslapd-pluginVersion: 9.0.4
 nsslapd-pluginVendor: Red Hat, Inc.
 nsslapd-pluginDescription: memberOf plugin

Table 6.2. MemberOf Syntax

Plug-in Attribute Description
cn Gives a unique name for the plug-in instance.
memberOfGroupAttr Gives the attribute in the group entry to poll to identify member DNs. By default, this is the member attribute, but it can be any attribute used to identify group members, such as uniqueMember. This is a multi-valued attribute, so if multiple types of groups will be used with the MemberOf Plug-in, multiple member type attributes can be set.
memberOfAttr Gives the attribute for the plug-in to create and manage on the user entry. By default, this is the memberOf attribute.
memberOfAllBackends Sets whether the plug-in should evaluate user entries only within the local suffix (off) or whether it should evaluate all configured databases (on).
memberOfEntryScope Sets on which suffixes the plug-in works on. If not set, the plug-in works on all suffixes.
memberOfEntryScopeExcludeSubtree Sets what suffixes the plug-in excludes.
nsslapd-pluginEnabled Sets whether the plug-in instance is enabled (active) or disabled. The default MemberOf Plug-in instance is disabled by default.
nsslapd-pluginPath Gives the name of the specific plug-in to load. This must be libmemberof-plugin.
nsslapd-pluginInitfunc Gives the name of the function to call to initialize the plug-in. This must be memberof_postop_init.

Note

To maintain backwards compatibility with older versions of Directory Server, which only allowed a single member attribute (by default, member), it may be necessary to include the member group attribute or whatever previous member attribute was used, in addition any new member attributes used in the plug-in configuration. 
 memberOfGroupAttr: member  
 memberOfGroupAttr: uniqueMember  
See Example 6.1, “Default MemberOf Plug-in Entry”.

6.1.4.4. Configuring an Instance of the MemberOf Plug-in

The attributes defined in the MemberOf Plug-in can be changed, depending on the types of groups used in the directory.
6.1.4.4.1. Editing the MemberOf Plug-in from the Console
  1. Select the Configuration tab, and expand to the Plugins folder.
  2. Scroll to the Memberof Plugin entry.
  3. Make sure that the plug-in is enabled. This is disabled by default.
  4. Click the Advanced button to open the Advanced Properties Editor.
  5. The memberOfGroupAttr attribute sets the attribute in the group entry which the server uses to identify member entries; this attribute can be used multiple times for different group/member types. The memberOfAttr attribute sets the attribute which the plug-in creates and manages on user entries.
  6. Save the changes.
  7. Restart the server to update the plug-in. For example, open the Tasks tab and click the Restart server task.
6.1.4.4.2. Editing the MemberOf Plug-in from the Command Line
  1. Enable the MemberOf Plug-in. 
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=MemberOf Plugin,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
-
  2. Set the attribute to use for the group member entry attribute. The default attribute is member, which can be changed using the replace command, or, since the memberOfGroupAttr attribute is multi-valued, additional member types can be added to the definition. For example: 
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=MemberOf Plugin,cn=plugins,cn=config
changetype: modify
add: memberOfGroupAttr
memberOfGroupAttr: uniqueMember

add: memberOfGroupAttr
memberOfGroupAttr: customMember-
  3. Set the attribute to set on the user entries to show group membership. For example: 
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=MemberOf Plugin,cn=plugins,cn=config
changetype: modify
replace: memberOfAttr
memberOfAttr: memberOf
-
  4. Optional. If the deployment uses distributed databases, then enable the memberOfAllBackends attribute to search through all databases, not just the local one, for user entries. 
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=MemberOf Plugin,cn=plugins,cn=config
changetype: modify
replace: memberOfAllBackends
memberOfAllBackends: on
-
  5. Restart the Directory Server to load the modified new plug-in instance. 
    service dirsrv restart instance_name

6.1.4.5. Setting the Scope of the MemberOf Plug-in

If you configured several back ends or multiple-nested suffixes, you can use the memberOfEntryScope and memberOfEntryScopeExcludeSubtree parameters to set what suffixes the MemberOf plug-in works on.
If you add a user to a group, the MemberOf plug-in only adds the memberOf attribute to the group if both the user and the group are in the plug-in's scope. For example, to configure the MemberOf plug-in to work on all entries in dc=example,dc=com, but to exclude entries in ou=private,dc=example,dc=com, set: 
memberOfEntryScope: dc=example,dc=com
memberOfEntryScopeExcludeSubtree: ou=private,dc=example,dc=com
If you moved a user entry out of the scope set in the memberOfEntryScope parameter:
  • The membership attribute, such as member, is updated in the group entry to remove the user DN value.
  • The memberOf attribute is updated in the user entry to remove the group DN value.

Note

The value set in the memberOfEntryScopeExcludeSubtree parameter has a higher priority than values set in memberOfEntryScope. If the scopes set in both parameters overlap, the MemberOf plug-in only works on the non-overlapping directory entries.

6.1.4.6. Synchronizing memberOf Values

The MemberOf Plug-in automatically manages the memberOf attribute on group member entries, based on the configuration in the group entry itself. However, the memberOf attribute can be edited on a user entry directly (which is improper) or new entries can be imported or replicated over to the server that have a memberOf attribute already set. These situations create inconsistencies between the memberOf configuration managed by the server plug-in and the actual memberships defined for an entry.
Directory Server has a memberOf repair task which manually runs the plug-in to make sure the appropriate memberOf attributes are set on entries. There are three ways to trigger this task:
  • In the Directory Server Console
  • Using the fixup-memberof.pl script
  • Running a cn=memberof task,cn=tasks,cn=config tasks entry

Note

The memberOf regeneration tasks are run locally, even if the entries themselves are replicated. This means that the memberOf attributes for the entries on other servers are not updated until the updated entry is replicated.
6.1.4.6.1. Initializing and Regenerating memberOf Attributes Using fixup-memberof.pl
The fixup-memberof.pl script launches a special task to regenerate all of the memberOf attributes on user entries based on the defined member attributes in the group entries. This is a clean-up task which synchronizes the membership defined in group entries and the corresponding user entries and overwrites any accidental or improper edits on the user entries.
  1. Open the tool directory for the Directory Server instance, /usr/lib/dirsrv/slapd-instance_name/.
  2. Run the script, binding as the Directory Manager. 
    ./fixup-memberof.pl -D "cn=Directory Manager" -w password
The fixup-memberof.pl command is described in more detail in the Configuration and Command-Line Tool Reference.
6.1.4.6.2. Initializing and Regenerating memberOf Attributes Using ldapmodify
Regenerating memberOf attributes is one of the tasks which can be managed through a special task configuration entry. Task entries occur under the cn=tasks configuration entry in the dse.ldif file, so it is also possible to initiate a task by adding the entry using ldapmodify. As soon as the task is complete, the entry is removed from the directory.
The fixup-memberof.pl script creates a special task entry in a Directory Server instance which regenerates the memberOf attributes.
To initiate a memberOf fixup task, add an entry under the cn=memberof task, cn=tasks,cn=config entry. The only required attribute is the cn for the specific task. 
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example memberOf,cn=memberof task,cn=tasks,cn=config
changetype: add
cn:example memberOf
As soon as the task is completed, the entry is deleted from the dse.ldif configuration, so it is possible to reuse the same task entry continually.
The cn=memberof task configuration is described in more detail in the Configuration and Command-Line Tool Reference.

6.1.5. Automatically Adding Entries to Specified Groups

Group management can be a critical factor for managing directory data, especially for clients which use Directory Server data and organization or which use groups to apply functionality to entries. Groups make it easier to apply policies consistently and reliably across the directory. Password policies, access control lists, and other rules can all be based on group membership.
Being able to assign new entries to groups, automatically, at the time that an account is created ensures that the appropriate policies and functionality are immediately applied to those entries — without requiring administrator intervention.
Dynamic groups are one method of creating groups and assigning members automatically because any matching entry is automatically included in the group. For applying Directory Server policies and settings, this is sufficient. However, LDAP applications and clients commonly need a static and explicit list of group members in order to perform whatever operation is required. And all of the members in static groups have to be manually added to those groups.
The static group itself cannot search for members like a dynamic group, but there is a way to allow a static group to have members added to it automatically — the Auto Membership Plug-in.
Automembership essentially allows a static group to act like a dynamic group, at least for adding new members to the group. Different automembership definitions create searches that are automatically run on all new directory entries. The automembership rules search for and identify matching entries — much like the dynamic search filters — and then explicitly add those entries as members to the static group.

Note

Automembership assignments are only made automatically when an entry is added to the Directory Server.
For existing entries or entries who are edited to match an automember group rule, there is a fix-up task which can be run that updates the group membership.
The Auto Membership Plug-in can target any type of object stored in the directory: users, machines and network devices, customer data, or other assets.

Note

The Auto Membership Plug-in adds a new entry to an existing group based on defined criteria. It does not create a group for the new entry.
To create a corresponding group entry when a new entry of a certain type is created, use the Managed Entries Plug-in. This is covered in Section 6.3, “Automatically Creating Dual Entries”.

6.1.5.1. Looking at the Structure of an Automembership Rule

The Auto Membership Plug-in itself is a container entry in cn=plugins,cn=config. Group assignments are defined through child entries.
6.1.5.1.1. The Automembership Configuration Entry
Automembership assignments are created through a main definition entry, a child of the Auto Membership Plug-in entry. Each definition entry defines three elements:
  • An LDAP search to identify entries, including both a search scope and a search filter (autoMemberScope and autoMemberFilter)
  • A default group to which to add the member entries (autoMemberDefaultGroup)
  • The member entry format, which is the attribute in the group entry, such as member, and the attribute value, such as dn (autoMemberGroupingAttr)
The definition is the basic configuration for an automember rule. It identifies all of the required information: what a matching member entry looks like and a group for that member to belong to.
For example, this definition assigns all Windows users to the cn=windows-users group: 
dn: cn=Windows Users,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
autoMemberScope: ou=People,dc=example,dc=com
autoMemberFilter: objectclass=ntUser
autoMemberDefaultGroup: cn=windows-group,cn=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn
The attributes for the definition entry are listed in Table 6.3, “Automember Definition Attributes”.

Table 6.3. Automember Definition Attributes

Attribute Description
autoMemberDefinition (required object class) Identifies the entry as an automember definition. This entry must be a child of the Auto Membership Plug-in, cn=Auto Membership Plugin,cn=plugins,cn=config.
autoMemberScope Sets the subtree DN to search for entries. This is the search base.
autoMemberFilter Sets a standard LDAP search filter to use to search for matching entries. Examples of search filters are in Section 10.4, “LDAP Search Filters”.
autoMemberDefaultGroup Sets a default or fallback group to add the entry to as a member.
If the definition does not use any regular expression conditions, then this is the primary group to which entries are added. If the automember definition does have defined regular expression conditions, then an entry is added to those specified groups first, and the autoMemberDefaultGroup group is used as a fallback for entries which match the autoMemberFilter but do not match a regular expression.
autoMemberGroupingAttr Sets the name of the member attribute in the group entry and the attribute in the object entry that supplies the member attribute value.
This structures how the Auto Membership Plug-in adds a member to the group, depending on the group configuration. For example, for a groupOfUniqueNames user group, each member is added as a uniqueMember attribute. The value of uniqueMember is the DN of the user entry. In essence, each group member is identified by the attribute-value pair of uniqueMember: user_entry_DN. The member entry format, then, is uniqueMember:dn.
6.1.5.1.2. Additional Regular Expression Entries
For something like a users group, where more than likely all matching entries should be added as members, a simple definition is sufficient. However, there can be instances where entries that match the LDAP search filter should be added to different groups, depending on the value of some other attribute. For example, machines may need to be added to different groups depending on their IP address or physical location; users may need to be in different groups depending on their employee ID number.
The automember definition can use regular expressions to provide additional conditions on what entries to include or exclude from a group, and then a new, specific group to add those selected entries to.
For example, an automember definition sets all machines to be added to a generic host group.

Example 6.2. Automember Definition for a Host Group

dn: cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
cn: Hostgroups
autoMemberScope: dc=example,dc=com
autoMemberFilter: objectclass=ipHost
autoMemberDefaultGroup: cn=systems,cn=hostgroups,ou=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn
A regular expression rule is added so that any machine with a fully-qualified domain name within a given range is added to a web server group.

Example 6.3. Regular Expression Condition for a Web Server Group

dn: cn=webservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group for webservers
cn: webservers
autoMemberTargetGroup: cn=webservers,cn=hostgroups,dc=example,dc=com
autoMemberInclusiveRegex: fqdn=^www\.web[0-9]+\.example\.com
So, any host machine added with a fully-qualified domain name that matches the expression ^www\.web[0-9]+\.example\.com, such as www.web1.example.com, is added to the cn=webservers group, defined for that exact regular expression. Any other machine entry, which matches the LDAP filter objectclass=ipHost but with a different type of fully-qualified domain name, is added to the general host group, cn=systems, defined in the main definition entry.
The group in the definition, then, is a fallback for entries which match the general definition, but do not meet the conditions in the regular expression rule.
Regular expression rules are child entries of the automember definition.
Regular Expression Conditions

Figure 6.1. Regular Expression Conditions

Each rule can include multiple inclusion and exclusion expressions. (Exclusions are evaluated first.) If an entry matches any inclusion rule, it is added to the group.
There can be only one target group given for the regular expression rule.

Table 6.4. Regular Expression Condition Attributes

Attribute Description
autoMemberRegexRule (required object class) Identifies the entry as a regular expression rule. This entry must be a child of an automember definition (objectclass: autoMemberDefinition).
autoMemberInclusiveRegex Sets a regular expression to use to identify entries to include. Only matching entries are added to the group. Multiple regular expressions could be used, and if an entry matches any one of those expressions, it is included in the group.
The format of the expression is a Perl-compatible regular expression (PCRE). For more information on PCRE patterns, see the pcresyntax(3) man page.
This is a multi-valued attribute.
autoMemberExclusiveRegex Sets a regular expression to use to identify entries to exclude. If an entry matches the exclusion condition, then it is not included in the group. Multiple regular expressions could be used, and if an entry matches any one of those expressions, it is excluded in the group.
The format of the expression is a Perl-compatible regular expression (PCRE). For more information on PCRE patterns, see the pcresyntax(3) man page.
This is a multi-valued attribute.

Note

Exclude conditions are evaluated first and take precedence over include conditions.
autoMemberTargetGroup Sets which group to add the entry to as a member, if it meets the regular expression conditions.

6.1.5.2. Examples of Automembership Rules

Automembership rules are usually going to applied to users and to machines (although they can be applied to any type of entry). There are a handful of examples that may be useful in planning automembership rules:
  • Different host groups based on IP address
  • Windows user groups
  • Different user groups based on employee ID

Example 6.4. Host Groups by IP Address

The automember rule first defines the scope and target of the rule. The example in Section 6.1.5.1.2, “Additional Regular Expression Entries” uses the configuration group to define the fallback group and a regular expression entry to sort out matching entries.
The scope is used to find all host entries. The plug-in then iterates through the regular expression entries. If an entry matches an inclusive regular expression, then it is added to that host group. If it does not match any group, it is added to the default group.
The actual plug-in configuration entries are configured like this, for the definition entry and two regular expression entries to filter hosts into a web servers group or a mail servers group. 
configuration entry
dn: cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
cn: Hostgroups
autoMemberScope: dc=example,dc=com
autoMemberFilter: objectclass=bootableDevice
autoMemberDefaultGroup: cn=orphans,cn=hostgroups,dc=example,dc=com
autoMemberGroupingAttr: member:dn

regex entry #1
dn: cn=webservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group placement for webservers
cn: webservers
autoMemberTargetGroup: cn=webservers,cn=hostgroups,dc=example,dc=com
autoMemberInclusiveRegex: fqdn=^www[0-9]+\.example\.com
autoMemberInclusiveRegex: fqdn=^web[0-9]+\.example\.com
autoMemberExclusiveRegex: fqdn=^www13\.example\.com
autoMemberExclusiveRegex: fqdn=^web13\.example\.com

regex entry #2
dn: cn=mailservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group placement for mailservers
cn: mailservers
autoMemberTargetGroup: cn=mailservers,cn=hostgroups,dc=example,dc=com
autoMemberInclusiveRegex: fqdn=^mail[0-9]+\.example\.com
autoMemberInclusiveRegex: fqdn=^smtp[0-9]+\.example\.com
autoMemberExclusiveRegex: fqdn=^mail13\.example\.com
autoMemberExclusiveRegex: fqdn=^smtp13\.example\.com

Example 6.5. Windows User Group

The basic users group shown in Section 6.1.5.1.1, “The Automembership Configuration Entry” uses the posixAccount attribute to identify all new users. All new users created within Directory Server are created with the posixAccount attribute, so that is a safe catch-all for new Directory Server users. However, when user accounts are synced over from the Windows domain to the Directory Server, the Windows user accounts are created without the posixAccount attribute.
Windows users are identified by the ntUser attribute. The basic, all-users group rule can be modified to target Windows users specifically, which can then be added to the default all-users group or to a Windows-specific group. 
dn: cn=Windows Users,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
autoMemberScope: dc=example,dc=com
autoMemberFilter: objectclass=ntUser
autoMemberDefaultGroup: cn=Windows Users,cn=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn

Example 6.6. User Groups by Employee Type

The Auto Membership Plug-in can work on custom attributes, which can be useful for entries which are managed by other applications. For example, a human resources application may create and then reference users based on the employee type, in a custom employeeType attribute.
Much like Example 6.4, “Host Groups by IP Address”, the user type rule uses two regular expression filters to sort full time and temporary employees, only this example uses an explicit value rather than a true regular expression. For other attributes, it may be more appropriate to use a regular expression, like basing the filter on an employee ID number range. 
configuration entry
dn: cn=Employee groups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
cn: Hostgroups
autoMemberScope: ou=employees,ou=people,dc=example,dc=com
autoMemberFilter: objectclass=inetorgperson
autoMemberDefaultGroup: cn=general,cn=employee groups,ou=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn

regex entry #1
dn: cn=full time,cn=Employee groups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group for full time employees
cn: full time
autoMemberTargetGroup: cn=full time,cn=employee groups,ou=groups,dc=example,dc=com
autoMemberInclusiveRegex: employeeType=full

regex entry #2
dn: cn=temporary,cn=Employee groups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group placement for interns, contractors, and seasonal employees
cn: temporary
autoMemberTargetGroup: cn=temporary,cn=employee groups,ou=groups,dc=example,dc=com
autoMemberInclusiveRegex: employeeType=intern
autoMemberInclusiveRegex: employeeType=contractor
autoMemberInclusiveRegex: employeeType=seasonal

6.1.5.3. Creating Automembership Definitions

  1. If necessary, enable the Auto Membership Plug-in. 
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=Auto Membership Plugin,cn=plugins,cn=config
changetype: replace
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
-
  2. Create the new plug-in instance below the cn=Auto Membership Plugin,cn=plugins,cn=config container entry. This entry must belong to the autoMemberDefinition object class. 
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=Example Automember Definition,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
    The required attributes for the definition are listed in Table 6.3, “Automember Definition Attributes”.
  3. Set the scope and filter for the definition. This is used for the initial search for matching entries.
    For example, for new entries added to the ou=People subtree and containing the ntUser attribute: 
    autoMemberScope: ou=People,dc=example,dc=com
autoMemberFilter: objectclass=ntUser
  4. Set the group to which to add matching entries (as the default or fallback group) and the format of the member entries for that group type. 
    autoMemberDefaultGroup: cn=windows-group,cn=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn
  5. Optional. Create inclusive or exclusive regular expression filters and set a group to use for entries matching those filters.
    The attributes for the regular expression condition are listed in Table 6.4, “Regular Expression Condition Attributes”.
    Regular expression conditions are added as children of the automember definition. These conditions must belong to the autoMemberRegexRule object class. 
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=Example Regex,cn=Example Automember Definition,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
    Then add the target group name and any inclusive or exclusive regular expressions. Both include and exclude conditions can be used, and multiple expressions of both types can be used. 
    autoMemberTargetGroup: cn=webservers,cn=hostgroups,dc=example,dc=com
autoMemberInclusiveRegex: fqdn=^www\.web[0-9]+\.example\.com
    If a new entry matches a regular expression condition, it is added to that group instead of the default group set in the automember definition.
  6. Restart the Directory Server to load the modified new plug-in instance. 
    service dirsrv restart instance_name

6.1.5.4. Updating Existing Entries for Automembership Definitions

The Auto Member Plug-in only runs when new entries are added to the directory. The plug-in ignores existing entries or entries which are edited to match an automembership rule.
There is a directory task operation which can be run to check existing entries against automembership rules and then update group membership accordingly. This task (cn=automember rebuild membership) requires three elements to run, based on LDAP search parameters to identify which existing entries to process:
  • The search filter
  • The search scope
  • The base DN from which to begin the search
The specific task run also needs a name.
The task entry can be created using ldapmodify; when the task completes, the entry is automatically removed. For example: 
[root@server ~]# ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=my rebuild task, cn=automember rebuild membership,cn=tasks,cn=config
objectClass: top
objectClass: extensibleObject
cn: my rebuild task
basedn: dc=example,dc=com
filter: (uid=*)
scope: sub

6.1.5.5. Testing Automembership Definitions

Because each instance of the Auto Member Plug-in is a set of related-but-separate entries for the definition and regular expression, it can be difficult to see exactly how users are going to be mapped to groups. This becomes even more difficult when there are multiple rules which target different subsets of users.
There are two dry-run tasks which can be useful to determine whether all of the different Auto Member Plug-in definitions are assigning groups properly as designed.
Testing with Existing Entries

cn=automember export updates runs against existing entries in the directory and exports the results of what users would have been added to what groups, based on the rules. This is useful for testing existing rules against existing users to see how your real deployment are performing.

This task requires the same information as the cn=automember rebuild membership task — the base DN to search, search filter, and search scope — and has an additional parameter to specify an export LDIF file to record the proposed entry updates. 
[root@server ~]# ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=test export, cn=automember export updates,cn=tasks,cn=config
objectClass: top
objectClass: extensibleObject
cn: test export
basedn: dc=example,dc=com
filter: (uid=*)
scope: sub
ldif: /tmp/automember-updates.ldif
Testing with an Import LDIF

cn=automember map updates takes an import LDIF of new users and then runs the new users against the current automembership rules. This can be very useful for testing a new rule, before applying it to (real) new or existing user entries.

This is called a map task because it maps or relates changes for proposed new entries to the existing rules.
This task only requires two attributes: the location of the input LDIF (which must contain at least some user entries) and an output LDIF file to which to write the proposed entry updates. Both the input and output LDIF files are absolute paths on the local machine.
For example: 
[root@server ~]# ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=test mapping, cn=automember map updates,cn=tasks,cn=config
objectClass: top
objectClass: extensibleObject
cn: test mapping
ldif_in: /tmp/entries.ldif
ldif_out: /tmp/automember-updates.ldif