Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Using groups in Directory Server

You can add users to groups in Directory Server. Groups are one of the mechanisms to group directory entries, that simplifies management of the user accounts.

When you use a group, Directory Server stores the distinguished name (DN) of the users who are members of this group in a membership attribute of the group entry. This special attribute is defined by the object class you choose when creating a group entry. For details about the group types, see Group types in Directory Server.

Groups are faster than roles. However, for a group to have benefits of a role, you need to enable the MemberOf plug-in. By default, the MemberOf plug-in automatically adds the memberOf attribute to a user entry if this user is a member of the group. As a result, the information about the membership is stored in both the group and user entries. For details about the MemberOf plug-in, see Listing group membership in user entries.

1.1. Group types in Directory Server
Copy link

In Directory Server, you can add members to a static or dynamic group. For more details about definition of each group type, see About groups in Directory Server. A group object class defines a membership attribute, and to add a member to the group, you need to add a value to this membership attribute of the group entry.

The following table lists group object classes and corresponding membership attributes.

Expand
Group typeObject classMembership attribute

Static

groupOfNames

member

groupOfUniqueNames

uniqueMember

Dynamic

groupOfURLs

memberURL

groupOfCertificates

memberCertificate

Object classes that you can use when you create a group:

  • groupOfNames is a simple group. You can add any entry to this group. The member attribute determines the group membership. The member attribute values are distinguished names (DN) of user entries that are members of the group.
  • groupOfUniqueNames lists user DNs as members, however the DNs must be unique. This group prevents self-referential group memberships. The uniqueMember attribute determines the group membership.
  • groupOfURLs uses a list of LDAP URLs to filter and create its membership list. Any dynamic group requires this object class and you can use it in conjunction with groupOfNames and groupOfUniqueNames. The memberURL attribute determines the group membership.
  • groupOfCertificates uses an LDAP filter to search for certificate names to identify group members. Use the groupOfCertificates object class for group-based access control, because you can give special access permissions to this group. The memberCertificateDescription attribute determines the group membership.
Important

If you use an object class of a static group together with one of the dynamic object classes, the group becomes dynamic.

The MemberOf plug-in does not support dynamic groups. Therefore, the plug-in does not add the memberOf attribute to the user entry if the user entry matches the filter of a dynamic group.

1.2. Creating a static group
Copy link

You can create a static group by using the command line or the web console.

Use the dsidm utility to create a static group with the groupOfNames object class. Use the ldapmodify utility to create a static group with the groupOfUniqueNames object class.

The following example creates two static groups in the ou=groups,dc=example,dc=com entry.

Prerequisites

  • The ou=groups,dc=example,dc=com parent entry exists.

Procedure

  • To create cn=simple_group group with the groupOfNames object class, run: 

    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn "simple_group"
Successfully created simple_group

    Note that the dsidm group create command creates groups only in the ou=group sub-entry. If you want to create a group in another entry, use ldapmodify utility.

  • To create cn=unique_members_group group with the groupOfUniqueNames object class, run: 

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
dn: cn=unique_members_group,ou=groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfUniqueNames
cn: unique_members_group
description: A static group with unique members

adding new entry "cn=unique_members_group,ou=groups,dc=example,dc=com"

Verification

  • Use dsidm group list command to list groups with the the groupOfNames object class: 

    # dsidm --basedn "dc=example,dc=com" instance_name group list
simple_group

  • Use dsidm uniquegroup list command to list groups with the unique members: 

    # dsidm --basedn "dc=example,dc=com" instance_name uniquegroup list
unique_members_group

1.2.2. Creating a static group in the LDAP Browser
Copy link

You can use the web console to create a static group. The following example creates a static_group in the ou=groups,dc=example,dc=com parent entry.

Prerequisites

Procedure

  1. Navigate to LDAP Browser menu.
  2. Using the Tree or Table view, expand the parent entry ou=groups,dc=example,dc=com under which you want to create the group.
  3. Click the Options menu (⋮) and select New to open the wizard window.
  4. Select the Create a group and click Next.
  5. Select the Basic Group for the groupe type and click Next.

  6. Add the group name, group description, and select the membership attribute for the group:

    • member for the group with the groupOfNames object class.
    • uniquemember for the group with the groupOfUniqueNames object class.
  7. Click Next.
  8. Optional: Add members to the group and click Next.
  9. Verify the group information, click Create, and Finish.

Verification

  • Expand the newly created group entry in the suffix tree.

1.3. Adding members to static groups
Copy link

You can add a member to a group by using the command line of the web console.

To add a member to a static group use the ldapmodify utility.

Prerequisites

  • The group entry exists.
  • The users entry exist.

Procedure

  • To add a member to a static group with the groupOfNames object class, add the user distinguished name (DN) as the value to the member attribute of the group entry: 

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
dn: cn=simple_group,ou=groups,dc=example,dc=com
changetype: modify
add: member
member: uid=jsmith,ou=people,dc=example,dc=com

modifying entry "cn=simple_group,ou=groups,dc=example,dc=com"

    The command adds the uid=jsmith user to the cn=simple_group group.

  • To add a member to a static group with the groupOfUniqueNames object class, add the user distinguished name (DN) as the value to the uniqueMember attribute of the group entry: 

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
dn: cn=unique_members_group,ou=groups,dc=example,dc=com
changetype: modify
add: uniqueMember
uniqueMember: uid=ajonson,ou=people,dc=example,dc=com

modifying entry "cn=unique_members_group,ou=groups,dc=example,dc=com"

    The command adds the uid=ajonson user to the cn=unique_members_group group.

Verification

  • List the members of the group: 

    # ldapsearch -xLL -D "cn=Directory Manager" -W -b dc=example,dc=com "(cn=simple_group)"

dn: cn=simple_group,ou=Groups,dc=example,dc=com
objectClass: top
objectClass: groupOfNames
objectClass: nsMemberOf
cn: simple_group
member: uid=jsmith,ou=people,dc=example,dc=com
member: uid=mtomson,ou=people,dc=example,dc=com

You can add a member to a static group in the web console by using LDAP Browser.

Prerequisites

Procedure

  1. Navigate to LDAP Browser menu.
  2. Using the Tree or Table view, expand the group entry to which you want to add the member. For example. you want to add a member to cn=unique_members_group,ou=groups,dc=example,dc=com.
  3. Click the Options menu (⋮) and select Edit to open the wizard window. The window displays the current members list.
  4. Select Find New Members tab.
  5. Type the part of the uid or cn attribute value of the member in the search bar and press Enter. The Available Members field displays the user distinguished names (DN) that you can add to the group.
  6. Select the member DN and move it to the Chosen Members field by click on the arrow (>).
  7. Click Add Member button.

Verification

  • Expand the cn=unique_members_group,ou=groups,dc=example,dc=com group entry and find the added user in the entry details.

Directory Server supports creating dynamic groups by using only the command line. Use the ldapmodify utility to create a dynamic group with the groupOfURLs and groupOfCertificates object classes.

The following example creates two dynamic groups in the ou=groups,dc=example,dc=com entry.

Prerequisites

  • The ou=groups,dc=example,dc=com parent entry exists.

Procedure

  • To create cn=example_dynamic_group group with the groupOfURLs object class, run: 

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
dn: cn=example_dynamic_group,ou=groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfURLs
cn: example_dynamic_group
description: Example dynamic group for user entries
memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen))

adding new entry "cn=example_dynamic_group,ou=groups,dc=example,dc=com"

    The command creates a dynamic group that filters members with the person object class and the sen substring in the right part of the common name (cn) value.

  • To create cn=example_certificates_group group with the groupOfCertificates object class, run: 

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
dn: cn=example_certificates_group,ou=groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfCertificates
cn: example_certificates_group
description: Example dynamic group for certificate entries
memberCertificateDescription: {ou=people, l=USA, dc=example, dc=com}

adding new entry "cn=example_certificates_group,ou=groups,dc=example,dc=com"

    The command creates a dynamic group that filters members whose certificate subject DNs contain ou=people,l=USA,dc=example,dc=com.

Verification

  • Search for the newly created group with the groupOfURLs object class: 

    # ldapsearch -xLLL -D "cn=Directory Manager" -W -H ldap://server.example.com -b "dc=example,dc=com" "objectClass=groupOfURLs" 1.1 

dn: cn=example_dynamic_group,ou=groups,dc=example,dc=com

  • Search for the newly created group with the groupOfCertificates object class: 

    # ldapsearch -xLLL -D "cn=Directory Manager" -W -H ldap://server.example.com -b "dc=example,dc=com" "objectClass=groupOfCertificates" 1.1 

dn: cn=example_certificates_group,ou=groups,dc=example,dc=com

1.5. Listing group membership in user entries
Copy link

A group defines entries that belong to this group by using the membership attribute. It is easy to look at the group and find its members. For example, a static group with the groupOfNames object class stores distinguished names (DNs) of its members as values of the member attribute. However, you cannot quickly find out what groups a single user belongs to. With groups, a user entry does not contain anything that indicates the user memberships, unlike with roles.

To solve this problem, you can use the MemberOf plug-in. The MemberOf plug-in analyzes the membership attribute in a group entry and automatically writes the memberOf attribute in the user entry that points to the group. By default, the plug-in checks the member attribute in the groups, however, you can use several attributes to support different group types.

When you add or delete a member of a group, the plug-in updates the memberOf attributes in the user entries. With the MemberOf plug-in, you can do a simple search against a specific user entry to find all groups that the user is a member of. The MemberOf Plug-in shows direct and indirect memberships for all groups.

Important

The MemberOf plug-in manages membership attributes only for static groups.

When using the MemberOf plug-in, consider the following:

  • The MemberOf plug-in in a replication topology

    In a replication topology, you can manage the MemberOf plug-in in two ways:

    • Enable the MemberOf plug-in on all supplier and consumer servers in the topology. In this case, you must exclude the memberOf attribute of user entries from replication in all replication agreements.

    • Enable the MemberOf plug-in only on all supplier servers in the topology. To do this:

      • You must disable replication of the memberOf attribute to all write-enabled suppliers in the replication agreement.
      • You must enable replication of the memberOf attribute to all consumer replicas in their replication agreement.
      • You must disable the MemberOf plug-in on consumer replicas.

  • The MemberOf plug-in with distributed databases

    As described in Creating and maintaining databases, you can store sub-trees of your directory in separate databases. By default, the MemberOf plug-in only updates user entries that are stored within the same database as the group. To update users across all databases, you must set the memberOfAllBackends parameter to on. For more details about setting the memberOfAllBackends parameter, see Configuring the MemberOf plug-in on each server using the web console.

By default, the MemberOf plug-in adds the nsMemberOf object class to user entries to provide the memberOf attribute. The nsMemberOf object class is sufficient for the plug-in to work correctly.

Alternatively, you can create user entries that contain the inetUser,inetAdmin, inetOrgPerson object class. These object classes support the memberOf 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 required attributes operations fail with the following error: 

LDAP: error code 65 - Object Class Violation

1.5.3. The MemberOf plug-in syntax
Copy link

When configuring the MemberOf plug-in, you set the main two attributes:

  • memberOfGroupAttr. Defines which membership attribute to poll from the group entry. The memberOfGroupAttr attribute is multi-valued. Therefore, the plug-in can manage multiple types of groups. By default, the plug-in polls the member attribute.
  • memberOfAttr. Defines which membership attribute to create and manage in the member’s user entry. By default, the plug-in adds the memberOf attribute to the user entry.

In addition, the plug-in syntax provides the plug-in path, function to identify the MemberOf plug-in, the plug-in state, and other configuration parameters.

The following example shows the default MemberOf plug-in entry configuration: 

dn: cn=MemberOf Plugin,cn=plugins,cn=config
cn: MemberOf Plugin
memberofallbackends: off
memberofattr: memberOf
memberofentryscope: dc=example,dc=com
memberofgroupattr: member
memberofskipnested: off
nsslapd-plugin-depends-on-type: database
nsslapd-pluginDescription: memberof plugin
nsslapd-pluginEnabled: off
nsslapd-pluginId: memberof
nsslapd-pluginInitfunc: memberof_postop_init
nsslapd-pluginPath: libmemberof-plugin
nsslapd-pluginType: betxnpostoperation
nsslapd-pluginVendor: 389 Project
nsslapd-pluginVersion: 2.4.5
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject

For details about the parameters in the example and other parameters you can set, see MemberOf plug-in section in the "Configuration and schema reference" documentation.

1.5.4. Enabling the MemberOf plug-in
Copy link

You can enable the MemberOf plug-in by using the command line or the web console.

Use the dsconf utility to enable the MemberOf plug-in.

Procedure

  1. Enable the plug-in: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof enable

  2. Restart the instance: 

    # dsctl instance_name restart

Verification

  • View the plug-in configuration details: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof show

dn: cn=MemberOf Plugin,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
...

You can use the web console to enable the MemberOf plug-in.

Prerequisites

Procedure

  1. Navigate to the Plugins menu.
  2. Select the MemberOf plug-in in the list of plug-ins.
  3. Change the status to ON to enable the plug-in.
  4. Restart the instance. For instructions for restarting the instance, see Starting and stopping a Directory Server instance by using the web console.

If you do not want to replicate the configuration of the MemberOf plug-in, configure the plug-in manually on each server by using the command line or the web console.

By default, the MemberOf plug-in reads the member membership attribute from the group entries and adds the memberOf attribute to the user entries. However, you can configure the plug-in to read other membership attribute from the group, add another attribute to the user entry, skip nested groups, work on all databases and other settings.

For example, you want the MemberOf plug-in to do the following:

  • Read uniqueMember attribute from group entries to identify membership.
  • Skip nested groups.
  • Search for user entries in all databases.

Prerequisites

Procedure

  1. Optionally: Display the MemberOf plug-in configuration to see which membership attribute the plug-in currently reads from groups entries: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof show

...
memberofgroupattr: member
...

    The plug-in currently reads the member attribute from the group entry to retrieve members.

  2. Set the uniqueMember attribute as the value to the memberOfGroupAttr parameter in the plug-in configuration: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --groupattr uniqueMember

    The memberOfGroupAttr parameter is multi-valued and you can set several values by passing them all to the --groupattr parameter. For example: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --groupattr member uniqueMember

  3. In an environment that uses distributed databases, 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

    The command sets the memberOfAllBackends parameter.

  4. Configure the plug-in to skip nested groups: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --skipnested on

    The command sets the memberOfSkipNested parameter.

  5. Optional: By default, the plug-in adds nsMemberOf object class to user entries if the user entries do not have the object class that allows the memberOf attribute. To configure the plug-in to add the inetUser object class to the user entries instead of nsMemberOf, run: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --autoaddoc inetUser

    The command sets the memberOfAutoAddOC parameter.

  6. Restart the instance: 

    # dsctl instance_name restart

Verification

  • View the MemberOf plug-in configuration: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof show
dn: cn=MemberOf Plugin,cn=plugins,cn=config
cn: MemberOf Plugin
memberofallbackends: on
memberofattr: memberOf
memberofautoaddoc: inetuser
memberofentryscope: dc=example,dc=com
memberofgroupattr: uniqueMember
memberofskipnested: on
...
nsslapd-pluginEnabled: on
...

By default, the MemberOf plug-in reads the member membership attribute from the group entries and adds the memberOf attribute to the user entries. However, you can configure the plug-in to read other membership attribute from the group, skip nested groups, work on all databases and other settings by using the web console.

For example, you want the MemberOf plug-in to do the following:

  • Read member and uniqueMember attributes from group entries to identify membership.
  • Set the scope of the plug-in to dc=example,dc=com.
  • Skip nested groups.
  • Search for user entries in all databases.

Prerequisites

Procedure

  1. Navigate to LDAP Browser menu.
  2. Select the MemberOf plug-in from the plug-ins list.
  3. Add the uniqueMember attribute to the Group Attribute field.

  4. Set the scope of the plug-in to dc=example,dc=com:

    1. Enter dc=example,dc=com to the Subtree Scope field.

    2. Click Create "dc=example,dc=com" in the drop-down list.

      configuring the memberof 1

  5. Optional: Set a subtree to exclude. For example, you do not want the plug-in to work on the ou=private,dc=example,dc=com subtree:

    1. Enter ou=private,dc=example,dc=com to the Exclude Subtree field.
    2. Click Create "ou=private,dc=example,dc=com" in the drop-down list.
  6. Check All Backends to configure the plug-in to search user entries in all databases instead of only the local database.
  7. Check Skip Nested to configure the plug-in to skip nested groups.
  8. Click Save Config.

By default, each server stores its own configuration of the MemberOf plug-in. With the shared configuration of the plug-in, you can use the same settings without configuring the plug-in manually on each server. Directory Server stores the shared configuration outside of the cn=config suffix and replicates it.

For example, you want to store the plug-in shared configuration in the cn=shared_MemberOf_config,dc=example,dc=com entry.

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.

Prerequisites

Procedure

  1. Enable the shared configuration entry on a server: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof config-entry add "cn=shared_MemberOf_config,dc=example,dc=com" --attr memberOf --groupattr member

Successfully created the cn=shared_MemberOf_config,dc=example,dc=com
MemberOf attribute nsslapd-pluginConfigArea (config-entry) was set in the main plugin config

    The command sets nsslapd-pluginConfigArea attribute value to cn=shared_MemberOf_config,dc=example,dc=com.

  2. Restart the instance: 

    # dsctl instance_name restart

  3. Enable the shared configuration on other servers in the replication topology that should use the shared configuration:

    1. Set the distinguished name (DN) of the configuration entry that stores the shared configuration: 

      # dsconf -D "cn=Directory Manager" ldap://server2.example.com plugin memberof set --config-entry cn=shared_MemberOf_config,dc=example,dc=com

    2. Restart the instance: 

      # dsctl instance_name restart

Verification

  1. Check that the MemberOf plug-in uses the shared configuration: 

    # dsconf -D "cn=Directory Manager" ldap://server1.example.com plugin memberof show

dn: cn=MemberOf Plugin,cn=plugins,cn=config
cn: MemberOf Plugin
...
nsslapd-pluginConfigArea: cn=shared_MemberOf_config,dc=example,dc=com
...

  2. Optional: Check the shared configuration settings: 

    # dsconf -D "cn=Directory Manager" ldap://server1.example.com plugin memberof config-entry show "cn=shared_MemberOf_config,dc=example,dc=com"

dn: cn=shared_MemberOf_config,dc=example,dc=com
cn: shared_MemberOf_config
memberofattr: memberOf
memberofgroupattr: member
objectClass: top
objectClass: extensibleObject

1.5.7. Setting the scope of the MemberOf plug-in
Copy link

If you configured several backends 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, the following procedure configures 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.

Prerequisites

Procedure

  1. Set the scope value for the MemberOf plug-in to dc=example,dc=com: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --scope "dc=example,dc=com"

  2. Exclude entries in ou=private,dc=example,dc=com: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --exclude "ou=private,dc=example,com"

    If you moved a user entry out of the scope by using the --scope DN parameter:

    • The MemberOf plug-in updates the membership attribute, such as member, in the group entry to remove the user DN value.

    • The MemberOf plug-in updates the memberOf attribute 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.

For details about setting the scope for the MemberOf plug-in, see Configuring the MemberOf plug-in on each server using the web console.

The MemberOf plug-in automatically manages memberOf attributes in group member entries based on the configuration in the group entry. However, you need to run the fixup task in the following situations to avoid inconsistency between the memberOf configuration that the server plug-in manages and the actual memberships defined in user entries:

  • You added group members to a group before you enabled the MemberOf plug-in.
  • You manually edited the memberOf attribute in a user entry.
  • You imported or replicated new user entries to the server that already have the memberOf attribute.

Note that you can run the fixup tasks only locally. In a replication environment, Directory Server updates the memberOf attribute for entries on other servers after Directory Server replicates the updated entries.

Prerequisites

Procedure

  • For example, to update the memberOf values in dc=example,dc=com entry and subentries, run: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof fixup "dc=example,dc=com"
Attempting to add task entry...
Successfully added task entry

    By default, the fixup task updates memberOf values in all entries that contain the inetUser, inetAdmin, or nsMemberOf object class.

    If you want the fixup task to also work on entries that contain other object classes, use -f filter option: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof fixup -f "(|(objectclass=inetuser)(objectclass=inetadmin)(objectclass=nsmemberof)(objectclass=nsmemberof)(objectclass=inetOrgPerson))" "dc=example,dc=com"

    This fixup task updates memberOf values in all entries that contain the inetUser, inetAdmin, nsMemberOf, or inetOrgPerson object class.

With groups, Directory Server can apply policies consistently and reliably across the directory because password policies, access controls, and other rules can all be based on group membership. Assigning new entries to groups automatically at the time when the entry are created or modified ensures that Directory Server applies the appropriate policies and functionality to these entries.

Dynamic groups are one method of assigning members automatically because Directory Server includes any matching entries in the group based of the dynamic group filter. This is sufficient for applying Directory Server policies and settings. However, LDAP applications and clients commonly need a static and explicit list of group members to perform the required operation. You must manually add all members of static groups to these groups.

With the Auto Membership plugin, a static group can search for members like a dynamic group. When you enable the Auto Membership plugin, Directory Server automatically searches for and identifies matching entries and then explicitly adds these entries as members to the static group.

The Auto Membership plugin can target any type of an entry stored in the directory: users, machines and network devices, customer data, or other entries.

Note

The Auto Membership plugin 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 plugin.

1.6.1. Auto Membership plugin syntax overview
Copy link

The Auto Membership plugin is the cn=Auto Membership Plugin,cn=plugins,cn=config container entry. You define group assignments by creating the following configuration entries:

Auto Membership definition entry
The definition entry is the plugin main configuration entry. The definition entry contains the LDAP search base and filter to identify entries and a default group to add them to. The definition entry is the child entry of cn=Auto Membership Plugin,cn=plugins,cn=config.
Auto Membership regular expression entries
Regular expression entries are optional children of the definition entry. These entries define additional conditions for assigning a new or modified entry to a group.

1.6.1.1. Auto Membership definition entry
Copy link

The Auto Membership definition entry is a child of cn=Auto Membership Plugin,cn=plugins,cn=config with the autoMemberDefinition object class. Each plugin configuration requires a separate definition entry, where you define the following basic settings:

  • The required autoMemberDefinition object class that identifies the entry as the definition entry of the plugin.
  • autoMemberDefaultGroup that sets a default group to add the member entries to.
  • autoMemberFilter that sets an LDAP filter to identify entries.
  • autoMemberGroupingAttr that sets the member entry format that consists of the attribute in the group entry, such as member, and the attribute value, such as dn.
  • autoMemberScope that sets a directory subtree, where to search for entries.

For details about other Auto Membership plugin configuration attributes, see Auto Membership plugin attributes description in the RHDS 13 Configuration and schema reference documentation

The definition entry identifies a matching member entry and a group for that member. For example, the following cn=hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config definition entry assigns all host entries with the objectclass=ipHost object class to the cn=servers 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=servers,cn=hostgroups,dc=example,dc=com
autoMemberGroupingAttr: member:dn

Write a short introductory paragraph that provides an overview of the module.

The contents of a concept module give the user descriptions and explanations needed to understand and use a product.

  • Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
  • Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
  • Avoid including action items. Action items belong in procedure modules. However, in some cases a concept or reference can include suggested actions when those actions are simple, are highly dependent on the context of the module, and have no place in any procedure module. In such cases, ensure that the heading of the concept or reference remains a noun phrase and not a gerund.

To assign new or modified entries to groups automatically, you need to create a definition entry for the Auto Membership plugin under cn=Auto Membership Plugin,cn=plugins,cn=config. To apply additional conditions on new or modified entries, you must add regular expression entries to the definition entry.

For example, you want the Auto Membership plugin to do the following tasks:

  • Add new or modified host entries to the cn=servers group.
  • Filter web servers and add them to the separate cn=webservers group.
  • Filter mail servers and add them to the separate cn=mailservers group.

Prerequisites

  • You have root permissions.
  • Group entries exist in your directory. Note that the plugin does not create a group for the new entry.

Procedure

  1. Optional: Enable the Auto Membership plugin: 

    # dsconf <instance_name> plugin automember enable

    By default, the plugin is enabled.

  2. Create the Auto Membership definition entry with an LDAP filter to identify host entries, a default cn=servers group, and the member entry format: 

    # dsconf <instance_name> plugin automember definition "Hostgroups definition" add --default-group "cn=servers,cn=hostgroups,ou=groups,dc=example,dc=com" --scope "dc=example,dc=com" --filter "objectclass=ipHost" --grouping-attr "member:dn"
     
    Successfully created the cn=Hostgroups definition,cn=Auto Membership Plugin,cn=plugins,cn=config

  3. Optional: Add regular expression entries to filter web and mail servers:

    1. To identify web servers from rest of hosts and add them to the separate cn=webservers group, enter: 

      # dsconf <instace_name> plugin automember definition "Hostgroups definition" regex "webservers" add --target-group "cn=webservers,cn=hostgroups,dc=example,dc=com" --inclusive "fqdn=^www\.web[0-9]+\.example\.com" --exclusive "fqdn=^web13\.example\.com"
       
      Successfully created the cn=webservers,cn=Hostgroups definition,cn=Auto Membership Plugin,cn=plugins,cn=config

      With these conditions, Directory Server adds any host machine with a fully-qualified domain name that matches the ^www\.web[0-9]+\.example\.com expression, such as www.web1.example.com, to the cn=webservers group. However, Directory Server adds the www.web13.example.com host to the default cn=servers,cn=Host Groups,ou=groups,dc=example,dc=com group as well as other host entries that match the objectclass=ipHost filter.

      Note that Directory Server evaluates exclude conditions first.

    2. To identify mail servers within the rest of hosts and add them to the separate cn=mailservers group, enter: 

      # dsconf <instace_name> plugin automember definition "Hostgroups definition" regex "mailservers" add --target-group "cn=mailservers,cn=hostgroups,dc=example,dc=com" --inclusive "fqdn=^www\.mail[0-9]+\.example\.com" 
      Successfully created the cn=mailservers,cn=Hostgroups definition,cn=Auto Membership Plugin,cn=plugins,cn=config

  4. Optional: By default, Directory Server updates the group memberships when you add a group entry to an entry or when you move an entry to a different group by editing the entry. If you want the plugin to ignore the entry modification, set the autoMemberProcessModifyOps attribute to off in the definition entry configuration: 

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
     
    dn: cn=Hostgroups definition,cn=Auto Membership Plugin,cn=plugins,cn=config
changetype: modify
add: autoMemberProcessModifyOps
autoMemberProcessModifyOps: off

Verification

  1. Display the Auto Membership definition entry configuration: 

    # dsconf <instance_name> plugin automember definition "Hostgroups definition" show
     
    dn: cn=Hostgroups definition,cn=Auto Membership Plugin,cn=plugins,cn=config
autoMemberDefaultGroup: cn=servers,cn=Host Groups,ou=groups,dc=example,dc=com
autoMemberFilter: objectclass=ipHost
autoMemberGroupingAttr: member:dn
autoMemberScope: dc=example,dc=com
cn: Hostgroups definition
objectClass: top
objectClass: autoMemberDefinition

  2. Display the Auto Membership regular expression entries: 

    # dsconf <instace_name> plugin automember definition "Hostgroups definition" regex "webservers" show
     
    dn: cn=webservers,cn=Hostgroups definition,cn=Auto Membership Plugin,cn=plugins,cn=config
autoMemberExclusiveRegex: fqdn=^web13\.example\.com
autoMemberInclusiveRegex: fqdn=^www\.web[0-9]+\.example\.com
autoMemberTargetGroup: cn=webservers,cn=hostgroups,dc=example,dc=com
cn: webservers
objectClass: top
objectClass: autoMemberRegexRule
     
    # dsconf <instace_name> plugin automember definition "Hostgroups definition" regex "mailservers" show
     
    dn: cn=mailservers,cn=Hostgroups definition,cn=Auto Membership Plugin,cn=plugins,cn=config
autoMemberInclusiveRegex: fqdn=^www\.mail[0-9]+\.example\.com
autoMemberTargetGroup: cn=mailservers,cn=hostgroups,dc=example,dc=com
cn: mailservers
objectClass: top
objectClass: autoMemberRegexRule

To assign new entries to groups automatically, create Auto Membership definition entries for the plugin. To apply additional conditions on new or modified entries, you must add regular expression entries to the definition entry.

For example, you want the Auto Membership plugin to do the following tasks:

  • Add new or modified host entries with ipHost object class to the cn=servers group.
  • Filter web servers and add them to the separate cn=webservers group. At the same time, some web servers must go to the default cn=servers group.

Prerequisites

Procedure

  1. Select the Directory Server instance.
  2. Open the Plugins menu and select the Auto Membership plugin from the list of plugins.
  3. Click Add Definition button to add a new plugin configuration.

  4. On the Add Auto Membership Plugin Definition Entry pop-up window, set:

    • Definition Name as Hostgroups definition
    • Subtree scope as dc=example,dc=com
    • Entry Filter as objectclass=ipHost
    • Grouping Attribute as member:dn

    • Default Group as cn=servers,cn=hostgroups,ou=groups,dc=example,dc=com

      For the detailed description of the plugin definition entry configuration attributes, see Auto Membership definition entry.

  5. Optional: Click Add Regex to add regular expression entries to filter web servers. On the Manage Auto Membership Plugin Regex Entry pop-up window, set the following:

    • Regex Name as webservers
    • Exclusive Regex as fqdn=^web13\.example\.com
    • Inclusive Regex as fqdn=^www\.web[0-9]+\.example\.com

    • Target Group as cn=webservers,cn=hostgroups,dc=example,dc=com

      For the detailed description of the regular expression configuration attributes, see Auto Membership regular expression entries.

  6. Click Save to save the regular expression entry configuration.
  7. Optional: Add other regular expression entries.

  8. Click Add Definition to save the Auto Membership plugin configuration including regular expression entries.

    When you save the configuration, Directory Server creates the definition entry with its child regular expression entries under cn=Auto Membership Plugin,cn=plugins,cn=config. If a host entry matches the fqdn=^www\.web[0-9]+\.example\.com filter, it goes to the separate cn=webservers,cn=hostgroups,dc=example,dc=com. If a web server entry matches the fqdn=^web13\.example\.com filter, it goes to the default cn=servers,cn=hostgroups,ou=groups,dc=example,dc=com group as well as other host entries that match the objectclass=ipHost filter.

1.6.4. Examples of Auto Membership plugin rules
Copy link

In most cases, Auto Membership rules are applied to users and machines. Lean about the most common examples of Auto Membership rules you can configure for your directory:

  • Different host groups based on IP address
  • Different user groups based on employee ID
  • Windows user groups

Host groups by IP address

The following example plugin configuration divides your hosts into three groups:

  • web servers
  • mail servers
  • other servers

First, you create an Auto Membership definition entry that defines the scope and target of the Auto Membership rule. Directory Server uses the scope to find all host entries. 

Auto Membership definition 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=otherhosts,cn=hostgroups,dc=example,dc=com
autoMemberGroupingAttr: member:dn

Then you create regular expression entries that are children of the Auto Membership definition entry: 

Child regular expression entry #1
dn: cn=webservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group for web servers
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

Child regular expression entry #2
dn: cn=mailservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group for mail servers
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

The plugin iterates through the child regular expression entries and, if a host entry matches an inclusive regular expression, Directory Server adds the entry to the host group defined in this regular expression entry. If the host entry does not match any group, Directory Server adds it to the default group set in autoMemberDefaultGroup of the parent definition entry.

Different user groups based on employee ID

The Auto Membership plugin can work with custom attributes. For example, a human resources application can create and then reference users based on the employee type in a custom employeeType attribute.

For this purpose, you create automembership rule that uses two regular expression filters to sort full time and temporary employees. However, the following example uses an explicit value rather than a true regular expression. For other attributes, use a regular expression, like basing the filter on an employee ID number range. 

Auto Membership definition entry
dn: cn=Employee groups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
cn: Employee groups
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

Child regular expression 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

Child regular expression 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

Windows User Group

By default, Directory Server creates new users with the posixAccount attribute. However, when user accounts are synchronized over from the Windows domain to Directory Server, the Windows user accounts contain the ntUser attribute instead.

You can create an automembership rule to target only Windows users: 

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

By default, Directory Server invokes the Auto Membership plugin to add and modify operations even when you move a user to a different group by editing the user entry. However, if you tuned off such behavior by setting autoMemberProcessModifyOps to off in the cn=<definition_entry_name>,cn=Auto Membership Plugin,cn=plugins,cn=config configuration entry, you must manually update the membership after you added new entries to the directory or changed existing ones. To do so, you can run a fixup task.

Prerequisites

  • You have root permissions.
  • You enabled the Auto Membership plugin.
  • The autoMemberProcessModifyOps plugin attribute is set to off.

Procedure

  1. Create the fixup task entry: 

    # dsconf <instance_name> plugin automember fixup "dc=example,dc=com" -f "objectclass=inetorgperson" -s sub --timeout 5

    The following command initiate the fixup task for people entries under dc=example,dc=com with the timeout of 5 seconds.

    For more details about other options, run the dsconf <instance_name> plugin automember fixup -h command.

Verification

  • Display the list of all Auto Membership fixup tasks: 

    # dsconf <instance_name> plugin automember fixup-status
     
    Found 1 fix-up task

[1] Task: cn=automember_rebuild_2025-09-19T09:59:10.628240,cn=automember rebuild membership,cn=tasks,cn=config
--------------------------------------------------------------------------------
 - Base DN:       dc=example,dc=com
 - Filter:        objectclass=inetorgperson
 - Status:        Automember rebuild task finished. Processed (109087) entries in 3 seconds
 - Started:       Fri Sep 19 14:59:10 2025 (20250919135910Z)
 - Ended:         Fri Sep 19 14:59:13 2025 (20250919135910Z)
 - Elapsed Time:  0:00:03
 - Exit Code:     0

Each instance of the Auto Member plugin is a set of related-but-separate entries like the definition entry and regular expression entries. It can be difficult to determine how exactly Directory Server will map users groups. This becomes even more difficult when you configured multiple rules which target different subsets of users.

You can run two dry-run tasks to determine if different Auto Membership plugin definitions assign groups properly as designed:

  • The cn=automember export updates task that uses existing entries
  • The cn=automember map updates task that uses import LDIF file with the new users

To determine if Directory Server assigns users to groups properly after configuring Auto Membership definition entry, you can run the cn=automember export updates task against existing entries. By doing so, you can test configured rules against existing users to see how your real deployment performs.

Prerequisites

  • You have root permissions.
  • You enabled the Auto Membership plugin.

Procedure

  1. Create the instance of the cn=automember export updates task: 

    # ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x

  2. Enter task parameters, such as the base DN to search, search filter, search scope, and an export LDIF file to record the proposed entry updates: 

    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

    In this example, Directory Server runs the Auto Membership plugin configuration against all user entries (uid=*) under the dc=example,dc=com subtree and writes the result to the /tmp/automember-updates.ldif file.

To determine if Directory Server assigns users to groups properly after configuring Auto Membership definition entry, you can run the cn=automember map updates task against new or test entries from an LDIF file. By doing so, you can test a new rule before applying it to real new or existing user entries.

Prerequisites

  • You have root permissions.
  • You enabled the Auto Membership plugin.

Procedure

  1. Create the instance of the cn=automember map updates task: 

    # ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x

  2. Enter task parameters, such as the base DN to search, search filter, search scope, and an export LDIF file to record the proposed entry updates: 

    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

    In this example, Directory Server runs the Auto Membership plugin configuration against user entries from the /tmp/entries.ldif file and writes the result to the /tmp/automember-updates.ldif file.

1.6.7. Canceling the Auto Membership plugin task
Copy link

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

Prerequisites

  • You have root permissions.
  • You enabled the Auto Membership plugin.

Procedure

  • To cancel the Auto Membership plugin task enter: 

    # dsconf <instance_name> plugin automember abort-fixup

Verification

  • To see the list of all Auto Membership fixup tasks, including canceled tasks, enter: 

    # dsconf <instance_name> 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. Explore our recent updates.

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.

Theme

© 2026 Red HatBack to top