SupportConsoleDevelopersStart a trialContact

Chapter 8. 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.

8.1. Using Groups

Similar to the operating system, you can add users to groups in Directory Server. Groups work the other way around as roles. If you are using roles, the DN of the assigned role is stored in the nsRoleDN attribute in the user object. If you use groups, then the DN of the users who are members of this group are stored in member attributes in the group object. If you enabled the memberOf plug-in, then the groups the user is a member of, are additionally stored in memberOf attribute in the user object. With this plug-in enabled, groups additionally have the benefit of roles, that you can list the group memberships of a user, similar as when using roles. Additionally, groups are faster than roles.
For further details about using the memberOf plug-in, see Section 8.1.4, “Listing Group Membership in User Entries”.

8.1.1. The Different Types of Groups

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 10 Configuration, Command, and File Reference. The type of group in this case refers to the type of defining member attribute it has:
  • groupOfNames (recommended) 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.
The following table shows the default attributes for groups:
Table 8.1. Dynamic and Static Group Schema
Type of Group Group Object Classes Member Attributes
Static groupOfNames [a] member
groupOfUniqueNames [a] uniqueMember
Dynamic groupOfURLs memberURL
groupOfCertificates memberCertificate
[a] If this object class is used together with one of the dynamic object classes, the group becomes dynamic.
The following two examples show a static and a dynamic group entry:

Example 8.1. A Static Group Entry

A static group entry lists the specific members of the group. For example: 
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

Example 8.2. A Dynamic Group Entry

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. For example: 
objectClass: top
objectClass: groupOfUniqueNames
objectClass: groupOfURLs
cn: dynamic group
description: Example dynamic group.
memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))

Note

The memberOf plug-in does not support dynamically generated group memberships. If you set the memberURL attribute instead of listing the group members in an attribute, the memberOf plug-in does not add the memberOf attribute to the user objects that match the filter.

8.1.2. Creating a Static Group

Directory Server only supports creating static groups using the command line.

8.1.2.1. Creating a Static Group Using the Command Line

This section describes how to create the different types of static groups using the command line.
For details about the different static groups, see Section 8.1.1, “The Different Types of Groups”.

Creating a Static Group with the groupOfNames Object Class

The dsidm utility creates static groups in the cn=Groups entry in the specified base DN.
For example, to create the static example_group group with the groupOfNames object class in the cn=Groups,dc=example,dc=com entry 
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn "example_group"

Creating a Static Group with the groupOfUniqueNames Object Class

To create a static group with the groupOfUniqueNames object class, use the ldapmodify utility to add the entry.
For example, to create the static example_group group with the groupOfUniqueNames object class in the cn=Groups,dc=example,dc=com entry: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example_group,cn=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfUniqueNames
cn: example_group
description: Example static group with unique members

8.1.3. Creating a Dynamic Group

Directory Server only supports creating dynamic groups using the command line.

8.1.3.1. Creating a Dynamic Group Using the Command Line

This section describes how to create the different types of dynamic groups using the command line.
For details about the different dynamic groups, see Section 8.1.1, “The Different Types of Groups”.

Creating a Dynamic Group with the groupOfURLs Object Class

For example, to create the dynamic example_group group with the groupOfURLs object class in the cn=Groups,dc=example,dc=com entry: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example_group,cn=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfURLs
cn: example_group
description: Example dynamic group for user entries
memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))

Creating a Dynamic Group with the groupOfCertificates Object Class

For example, to create the dynamic example_group group with the groupOfCertificates object class in the cn=Groups,dc=example,dc=com entry: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example_group,cn=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfURLs
cn: example_group
description: Example dynamic group for certificate entries
memberCertificate: ...

8.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 multiple 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.

8.1.4.1. Considerations When Using the memberOf Plug-in

This section describes important considerations when you want to use the memberOf plug-in.
Using the memberOf Plug-in in a Replication Topology
There are two approaches to manage the memberOf attribute in a replication topology:
Using the memberOf plug-in With Distributed Databases
As described in Section 2.2.1, “Creating Databases”, you can store sub-trees of your directory in individual databases. By default, the memberOf plug-in only updates user entries which are stored within the same database as the group. To enable the plug-in to also update users in different databases as the group, you must set the memberOfAllBackends parameter to on. See Section 8.1.4.5.2, “Configuring the MemberOf Plug-in on Each Server Using the Web Console”.

8.1.4.2. Required Object Classes by the memberOf Plug-In

The memberOf plug-in By default, the memberOf plug-in will add the MemberOf object class to objects to provide the memberOf attribute. This object class is safe to add to any object for this purpose, and no further action is required to enable this plug-in to operate correctly. Alternatively, you can create user objects that contain the inetUser or inetAdmin, object class. Both object classes support the memberOf attribute as well.
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

8.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 8.3, “Default MemberOf Plug-in Entry”.

Example 8.3. 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: X.Y.Z
 nsslapd-pluginVendor: Red Hat, Inc.
 nsslapd-pluginDescription: memberOf plugin
For details about the parameters used in the example and other parameters you can set, see the MemberOf Plug-in Attributes section in the Red Hat Directory Server Command, Configuration, and File Reference.

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  

8.1.4.4. Enabling the MemberOf Plug-in

This section describes how to enable the MemberOf plug-in.
8.1.4.4.1. Enabling the MemberOf Plug-in Using the Command Line
Enable the MemberOf plug-in using the command line:
  1. Use the dsconf utility to enable the plug-in: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof enable
  2. Restart the instance: 
    # dsctl instance_name restart
8.1.4.4.2. Enabling the MemberOf Plug-in Using the Web Console
Enable the MemberOf plug-in using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the MemberOf plug-in.
  5. Change the status to ON to enable the plug-in.
  6. Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.

8.1.4.5. Configuring the MemberOf Plug-in on Each Server

If you do not want to replicate the configuration of the MemberOf plug-in, configure the plug-in manually on each server.
8.1.4.5.1. Configuring the MemberOf Plug-in on Each Server Using the Command Line
To configure the MemberOf plug-in using the command line:
  1. Enable the plug-in. See Section 8.1.4.4.1, “Enabling the MemberOf Plug-in Using the Command Line”.
  2. To retrieve members of a group from a different attribute than member, which is the default, set the memberOfGroupAttr parameter to the respective attribute name.
    For example, to read group members from uniqueMember attributes, replace the current value of memberOfGroupAttr:
    1. Optionally, display the attribute that is currently configured: 
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof show
...
memberofgroupattr: member
...
      The command displays that currently only the member attribute is configured to retrieve members of a group.
    2. Remove all attributes from the configuration that currently set: 
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --groupattr delete
Successfully changed the cn=MemberOf Plugin,cn=plugins,cn=config

      Note

      It is not possible to remove a specific group attribute.
    3. Add the uniqueMember attribute to the configuration: 
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --groupattr uniqueMember
successfully added memberOfGroupAttr value "uniqueMember"
      To set multiple attributes, pass them all to the --groupattr parameter. For example: 
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --groupattr member uniqueMember ...
  3. By default, the MemberOf plug-in adds the memberOf attribute to user entries. To use a different attribute, set the name of the attribute in the memberOfAttr parameter.
    For example, to add the customMemberOf attribute to user records, replace the current value of memberOfAttr:
    1. Optionally, display the attribute that is currently configured: 
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof show
...
memberofattr: memberOf
...
    2. Configure the MemberOf plug-in to add the customMemberOf attribute to user entries: 
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --attr customMemberOf
memberOfAttr set to "customMemberOf"

      Note

      You can only set this parameter to an attribute that supports DN syntax.
  4. In an environment that uses distributed databases, you can configure the plug-in to search user entries in all databases instead of only the local database: 
    dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --allbackends on
memberOfAllBackends enabled successfully
  5. Restart the instance: 
    # dsctl instance_name restart
8.1.4.5.2. Configuring the MemberOf Plug-in on Each Server Using the Web Console
To configure the MemberOf plug-in using the command line:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the memberOf plug-in.
  5. Change the status to ON to enable the plug-in.
  6. Fill the fields to configure the plug-in. For example, to configure that the plug-in adds the customMemberOf attribute to user entries if the uniqueMember attribute is added to a group:
  7. Click Save.
  8. Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.

8.1.4.6. Using the MemberOf Plug-in Shared Configuration

By default, the configuration of the MemberOf plug-in is stored on each server. Using the shared configuration feature of the plug-in, the configuration can be stored outside of the cn=config suffix and replicated. Administrators can use the same settings without configuring the plug-in manually on each server.
  1. Enable the plug-in. See Section 8.1.4.4, “Enabling the MemberOf Plug-in”.
  2. Add the shared configuration entry for the MemberOf plug-in. For example: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof config-entry add "cn=shared_MemberOf_config,dc=example,dc=com" --groupattr "member" --attr "memberOf"
    This automatically enables the shared configuration entry on the server on which you ran the command.
  3. Restart the instance: 
    # dsctl instance_name restart
  4. On all other servers in the replication topology that should use the shared configuration, enable the shared configuration:
    1. Enable the plug-in. See Section 8.1.4.4, “Enabling the MemberOf Plug-in”.
    2. Set the DN that stores the shared configuration. For example: 
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --config-entry cn=shared_MemberOf_config,dc=example,dc=com
    3. Restart the instance: 
      # dsctl instance_name restart

Important

After enabling the shared configuration, the plug-in ignores all parameters set in the cn=MemberOf Plugin,cn=plugins,cn=config plug-in entry and only uses settings from the shared configuration entry.

8.1.4.7. 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: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --scope "dc=example,com"
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --exclude "dc=group,dc=example,com"
If you moved a user entry out of the scope by using the --scope DN 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 --exclude parameter has a higher priority than values set in --scope. If the scopes set in both parameters overlap, the MemberOf plug-in only works on the non-overlapping directory entries.

8.1.4.8. Regenerating memberOf Values

The MemberOf plug-in automatically manages memberOf attributes on group member entries, based on the configuration in the group entry itself. However, the memberOf attribute can be manually edited in a user entry or new entries can be imported or replicated 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 in an entry.
For example, to regenerate the memberOf values in dc=example,dc=com entry and subentries: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof fixup -f "(|(objectclass=inetuser)(objectclass=inetadmin)(objectclass=nsmemberof))" "dc=example,dc=com"
Attempting to add task entry...
Successfully added task entry
The -f filter option is optional. Use the filter to regenerate the memberOf attributes in user entries matching the filter. If you do not specify a filter, the tasks regenerates the attributes in all entries containing the inetUser, inetAdmin, or nsMemberOf object class.

Note

Regeneration tasks run locally, even if the entries themselves are replicated. This means that memberOf attributes for entries on other servers are not updated until the updated entry is replicated.

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

By default, the autoMemberProcessModifyOps parameter in the cn=Auto Membership Plugin,cn=plugins,cn=config entry is set to on. With this setting, the Automembership plug-in also updates group memberships when an administrator moves a user to a different group by editing a user entry.
If you set autoMemberProcessModifyOps to off, Directory Server invokes the plug-in only when you add a group entry to the user, and you must manually run a fix-up task to update 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 member 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 8.3, “Automatically Creating Dual Entries”.

8.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.
8.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 users with the object class set to ntUser 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
For details about the attributes used in the example and other attributes you can set in this entry, see the cn=Auto Membership Plugin,cn=plugins,cn=config entry description in the Red Hat Directory Server Configuration, Command, and File Reference.
8.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 8.4. 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,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 8.5. 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 8.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 8.2. 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.

8.1.5.2. Configuring Auto Membership Definitions

To use the Auto Membership plug-in, create definitions for the plug-in.
8.1.5.2.1. Configuring Auto Membership Definitions Using the Command Line
To create Auto Membership definitions using the command line:
  1. Enable the Auto Membership plug-in: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember enable
Enabled Auto Membership Plugin
  2. Create a Auto Membership definition. For example: 
    #  dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember definition definition_name add --default-group "cn=windows-group,cn=groups,dc=example,dc=com" --scope "ou=People,dc=example,dc=com" --filter "objectclass=ntUser" --grouping-attr "member:dn"
Automember definition created successfully!
  3. Optionally, you can set further parameters in an Auto Membership definition, for example, to use regular expressions to identify entries to include.Use the ldapmodify utility to add or update these parameters in the cn=definition_name,cn=Auto Membership Plugin,cn=plugins,cn=config entry. For parameters you can set, see cn=Auto Membership Plugin,cn=plugins,cn=config entry description in the Red Hat Directory Server Configuration, Command, and File Reference.
  4. Restart the instance: 
    # dsctl instance_name restart
8.1.5.2.2. Configuring Auto Membership Definitions Using the Web Console
To create Auto Membership definitions using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the Auto Membership plug-in.
  5. Change the status to ON to enable the plug-in.
  6. Click Add Definition.
  7. Fill the fields. For example:
  8. Optionally, add a regular expression filter.
  9. Click Save.
  10. Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.

8.1.5.3. Updating Existing Entries to apply Auto Membership Definitions

By default, the autoMemberProcessModifyOps parameter in the cn=Auto Membership Plugin,cn=plugins,cn=config entry is enabled. With this setting, the Automembership plug-in also updates group memberships when an administrator moves a user to a different group by editing a user entry. However, if you set autoMemberProcessModifyOps to off, you must manually run a fix-up task when you added new entries to the directory or changed existing entries.
To create the task entry: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember fixup -f "filter" -s scope
When the task is completed, the entry is removed from the directory configuration.

8.1.5.4. 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 8.6. Host Groups by IP Address

The automember rule first defines the scope and target of the rule. The example in Section 8.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 8.7. Windows User Group

The basic users group shown in Section 8.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 synchronized 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 8.8. 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 8.6, “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

8.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. 
# ldapadd -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, using ldapmodify: 
# ldapadd -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

8.1.5.6. Canceling the Auto Membership Plug-in Task

The Auto Membership plug-in task can generate high CPU usage on the server if the Directory Server has complex configuration (large groups, complex rules and interaction with other plugins). To prevent the performance issues, you can cancel the Auto Membership plug-in task.

Procedure

  • To cancel the Auto Membership plug-in task enter: 
    # dsconf server.example.com plugin automember abort-fixup

Verification

  • To see the list of all Auto Membership plug-in tasks, including canceled tasks, enter: 
    # dsconf server.example.com plugin automember fixup-status
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.