Automember Rules
Manage automatic group membership assignment based on user and host attributes. Automember rules automatically add users to groups or hosts to host groups when they match defined criteria. Features include inclusive and exclusive rules, default groups, regular expression matching, and support for both user groups and host groups to streamline provisioning and reduce manual group management.
Overview
Automember rules in FreeIPA automatically assign group membership based on attribute matching, eliminating manual group management for entries following predictable patterns. When users or hosts are created with attributes matching automember conditions, they automatically join appropriate groups or host groups without administrator intervention. This automation ensures consistent group membership, reduces provisioning time, and prevents errors from forgotten manual group assignments.
Automember rules use regular expression patterns to match user or host attributes against defined conditions. Each rule targets a specific group or host group, automatically adding new or modified entries whose attributes satisfy the rule’s inclusive conditions and don’t match exclusive conditions. Multiple rules can target the same group, and entries can match multiple rules, enabling flexible automation patterns.
Automember operates at the LDAP directory level through 389 Directory Server’s automembership plugin. When entries are created or modified, the directory server evaluates all applicable automember rules, automatically updating group membership based on current attribute values. This real-time evaluation ensures membership accurately reflects current entry state without manual updates.
Rule Components
Target Groups
Each automember rule is associated with exactly one group (for user rules) or one host group (for host rules). The target group must exist before creating the rule; orphaned rules (referencing non-existent groups) are non-functional and should be cleaned up using automember-find-orphans.
Rules are type-specific: user automember rules target user groups and evaluate user attributes, while hostgroup automember rules target host groups and evaluate host attributes. The --type parameter specifies whether a rule operates on users or hosts.
Multiple rules can target the same group from different attribute conditions, enabling complex membership logic. For example, a “developers” group might have rules matching both department=‘Engineering’ and title=‘Developer’, adding users satisfying either condition.
Inclusive Conditions
Inclusive conditions define patterns that trigger group membership. When an entry’s attribute matches an inclusive condition’s regular expression, the entry is added to the rule’s target group. Inclusive conditions use LDAP attribute names (uid, fqdn, manager, description, etc.) and POSIX extended regular expressions for pattern matching.
Multiple inclusive conditions within a rule create OR logic: matching ANY inclusive condition triggers membership. This enables flexible matching where entries meeting any of several criteria join the group.
Regular expressions must follow POSIX extended regex syntax supported by 389 Directory Server. Anchors (^, $), character classes ([a-z]), quantifiers (*, +, {n,m}), and grouping are all supported.
Exclusive Conditions
Exclusive conditions prevent group membership even when inclusive conditions match. If an entry matches any exclusive condition, it is excluded from the target group regardless of inclusive condition matches. This exception-based logic enables patterns like “all developers except contractors.”
Exclusive conditions override inclusive conditions in all cases. When an entry matches both inclusive and exclusive conditions, the exclusive condition takes precedence and the entry is NOT added to the group.
Exclusive conditions use the same attribute and regex syntax as inclusive conditions. The distinction is behavioral: inclusive adds to group, exclusive prevents addition.
Default Groups
Default groups (configured with automember-default-group-set) serve as fallback destinations for entries matching no automember rules. When a user or host is created and doesn’t match any inclusive automember rules (or matches only exclusive rules), it’s added to the configured default group.
For users, the default group supplements the global default group configured in IPA settings (typically “ipausers”). User entries belong to both the IPA default group and the automember default group if they don’t match specific rules.
For hosts, the default host group provides a destination for uncategorized hosts, useful for ensuring all hosts have some group membership for policy application.
Default groups are optional. If no default is configured, entries matching no rules simply don’t receive automatic group membership.
Rebuilding Membership
The automember-rebuild command retroactively applies automember rules to existing entries. This is necessary when rules are created after entries exist or when rules are modified and existing memberships should reflect new logic.
Rebuild operations re-evaluate all applicable automember rules for specified entries (or all entries of a type), removing memberships created by previous automember logic and applying current rules. Manual group memberships (not created by automember) are preserved during rebuild.
Rebuild can target all users (--type=group), all hosts (--type=hostgroup), or specific entries (--users, --hosts). Targeted rebuilds are faster and less disruptive than full rebuilds, useful when rule changes affect limited entry subsets.
Rebuild operations can be long-running for large directories. Plan rebuilds during maintenance windows and monitor progress through server logs. Incremental rebuilds targeting specific entries are preferred over full rebuilds when possible.
Orphan Rules
Orphan automember rules reference target groups that no longer exist. These rules are non-functional but remain in configuration, potentially causing confusion. Orphans typically result from deleting groups without first deleting their associated automember rules.
The automember-find-orphans command identifies orphaned rules, returning rules whose target groups are missing. The --remove flag automatically deletes orphaned rules, cleaning up defunct configuration.
Regular orphan cleanup maintains configuration hygiene and prevents administrators from being confused by rules that don’t function. Orphan detection should be part of routine maintenance, especially after group reorganization projects.
Attribute Matching
Automember rules can match against any LDAP attribute present in user or host entries. Common attributes for matching include:
User Attributes:
uid: Usernamemanager: Manager’s DNou: Organizational unittitle: Job titledepartmentNumber: Department numberemployeeType: Employee typel: Location/city
Host Attributes:
fqdn: Fully qualified domain namedescription: Host descriptionnshostlocation: Physical locationnshardwareplatform: Hardware platformnsosversion: Operating system version
Custom attributes can also be matched if they’re present in entries. Attribute selection should align with attributes consistently populated during provisioning.
Best Practices
Rule Design
Match stable attributes: Base rules on attributes unlikely to change frequently. Department or role is more stable than manager or temporary project assignments.
Use anchored regexes: Include ^ and $ anchors in patterns to ensure complete matches. ^web.*\.com$ is more precise than web.*com.
Test patterns before deployment: Verify regex patterns match intended entries using test users/hosts before applying to production.
Document rule purposes: Clearly document why each rule exists and what membership it manages. Future administrators will need this context.
Performance Considerations
Limit rule complexity: Excessive automember rules or complex regexes impact directory performance. Keep rules simple and targeted.
Use targeted rebuilds: Rebuild specific entries rather than all entries when possible. Full rebuilds are expensive operations.
Schedule large rebuilds carefully: Plan directory-wide rebuilds during maintenance windows when entry creation/modification is minimal.
Monitor rule evaluation: Track automember plugin performance in directory server logs, optimizing or simplifying rules if performance degrades.
Operational Practices
Create groups before rules: Always create target groups before automember rules. Attempting the reverse creates orphans.
Clean up orphans regularly: Run automember-find-orphans --remove periodically, especially after group reorganizations.
Version control rule configuration: Document automember rules in version control alongside group and policy configurations.
Test rule changes: When modifying rules, test with specific entries before rebuilding all membership.
Pattern Accuracy
Validate regexes thoroughly: Incorrect regexes can cause wrong memberships or miss intended entries. Test patterns against various inputs.
Account for edge cases: Ensure patterns handle unusual but valid values (hyphens in names, special characters, etc.).
Use exclusive rules carefully: Exclusive conditions can create unexpected membership gaps. Document all exclusions clearly.
Review membership after rebuild: After rebuild operations, audit resulting membership to verify it matches expectations.
Integration Planning
Coordinate with provisioning: Ensure user/host provisioning sets attributes that automember rules depend on.
Align with policy structure: Design automember rules that create group memberships useful for HBAC/sudo rules.
Plan for attribute consistency: Automember effectiveness depends on consistent attribute population. Standardize provisioning practices.
Security Considerations
Avoid sensitive attribute matching: Don’t base membership on attributes users can modify (description, some custom fields). Use controlled attributes.
Audit automatic assignments: Regularly review automember-created memberships to ensure they align with intended policy.
Limit default group permissions: Default groups should have minimal privileges since they receive entries by exclusion.
Test security impact: When creating rules affecting security-sensitive groups, verify membership changes don’t grant unintended access.
Integration with Other IPA Components
User and Group Management
Automember rules automatically populate user groups (group-* commands) based on user attributes (user-* commands), eliminating manual group membership management for pattern-following users.
Host and Host Group Management
Automember rules automatically populate host groups (hostgroup-* commands) based on host attributes (host-* commands), ensuring consistent host organization.
HBAC and Sudo Rules
Automember-created group memberships automatically affect HBAC and sudo rule evaluation, enabling policy that dynamically responds to user/host attributes.
Provisioning Workflows
Automember integrates with provisioning automation (Ansible, Puppet, scripts) by automatically handling group assignments when provisioning tools create properly attributed entries.
LDAP Directory
Automember operates through 389 Directory Server’s automembership plugin, evaluating rules during LDAP add/modify operations in real-time.
EXAMPLES
Add the initial group or hostgroup:
ipa hostgroup-add --desc="Web Servers" webservers ipa group-add --desc="Developers" develAdd the initial rule:
ipa automember-add --type=hostgroup webservers ipa automember-add --type=group develAdd a condition to the rule:
ipa automember-add-condition --key=fqdn --type=hostgroup --inclusive-regex=^web[1-9]+\.example\.com webservers ipa automember-add-condition --key=manager --type=group --inclusive-regex=^uid=mscott develAdd an exclusive condition to the rule to prevent auto assignment:
ipa automember-add-condition --key=fqdn --type=hostgroup --exclusive-regex=^web5\.example\.com webserversAdd a host:
ipa host-add web1.example.comAdd a user:
ipa user-add --first=Tim --last=User --password tuser1 --manager=mscottVerify automembership:
ipa hostgroup-show webservers Host-group: webservers Description: Web Servers Member hosts: web1.example.com ipa group-show devel Group name: devel Description: Developers GID: 1004200000 Member users: tuserRemove a condition from the rule:
ipa automember-remove-condition --key=fqdn --type=hostgroup --inclusive-regex=^web[1-9]+\.example\.com webserversModify the automember rule:
ipa automember-modSet the default (fallback) target group:
ipa automember-default-group-set --default-group=webservers --type=hostgroup ipa automember-default-group-set --default-group=ipausers --type=groupRemove the default (fallback) target group:
ipa automember-default-group-remove --type=hostgroup ipa automember-default-group-remove --type=groupShow the default (fallback) target group:
ipa automember-default-group-show --type=hostgroup ipa automember-default-group-show --type=groupFind all of the automember rules:
ipa automember-findFind all of the orphan automember rules:
ipa automember-find-orphans --type=hostgroupFind all of the orphan automember rules and remove them:
ipa automember-find-orphans --type=hostgroup --removeDisplay a automember rule:
ipa automember-show --type=hostgroup webservers ipa automember-show --type=group develDelete an automember rule:
ipa automember-del --type=hostgroup webservers ipa automember-del --type=group develRebuild membership for all users:
ipa automember-rebuild --type=groupRebuild membership for all hosts:
ipa automember-rebuild --type=hostgroupRebuild membership for specified users:
ipa automember-rebuild --users=tuser1 --users=tuser2Rebuild membership for specified hosts:
ipa automember-rebuild --hosts=web1.example.com --hosts=web2.example.com
Commands
Command Description
automember-add Add an automember rule.
automember-add-condition Add conditions to an automember rule.
automember-default-group-remove Remove default (fallback) group for all unmatched entries.
automember-default-group-set Set default (fallback) group for all unmatched entries.
automember-default-group-show Display information about the default (fallback) automember groups.
automember-del Delete an automember rule.
automember-find Search for automember rules.
automember-find-orphans Search for orphan automember rules. The command might need to be run as
automember-mod Modify an automember rule.
automember-rebuild Rebuild auto membership.
automember-remove-condition Remove conditions from an automember rule.
automember-show Display information about an automember rule.
automember-add
Usage:
ipa [global-options] automember-add AUTOMEMBER-RULE [options]
Add an automember rule.
Arguments
Argument Required Description
AUTOMEMBER-RULE yes Automember Rule
Options
Option Description
--desc DESC A description of this auto member rule
--setattr SETATTR Set an attribute to a name/value pair. Format is
attr=value.
--addattr ADDATTR Add an attribute/value pair. Format is
attr=value. The attribute
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
automember-add-condition
Usage:
ipa [global-options] automember-add-condition AUTOMEMBER-RULE [options]
Add conditions to an automember rule.
Arguments
Argument Required Description
AUTOMEMBER-RULE yes Automember Rule
Options
Option Description
--desc DESC A description of this auto member rule
--inclusive-regex INCLUSIVE-REGEX Inclusive Regex
--exclusive-regex EXCLUSIVE-REGEX Exclusive Regex
--key KEY Attribute to filter via regex. For example fqdn
for a host, or manager for a user
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
automember-default-group-remove
Usage:
ipa [global-options] automember-default-group-remove [options]
Remove default (fallback) group for all unmatched entries.
Options
Option Description
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
automember-default-group-set
Usage: ipa [global-options] automember-default-group-set [options]
Set default (fallback) group for all unmatched entries.
Options
Option Description
--default-group DEFAULT-GROUP Default (fallback) group for entries to land
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
automember-default-group-show
Usage:
ipa [global-options] automember-default-group-show [options]
Display information about the default (fallback) automember groups.
Options
Option Description
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
automember-del
Usage:
ipa [global-options] automember-del AUTOMEMBER-RULE [options]
Delete an automember rule.
Arguments
Argument Required Description
AUTOMEMBER-RULE yes Automember Rule
Options
Option Description
--type TYPE Grouping to which the rule applies
automember-find
Usage: ipa [global-options] automember-find [CRITERIA] [options]
Search for automember rules.
Arguments
Argument Required Description
CRITERIA no A string searched in all relevant object
attributes
Options
Option Description
--desc DESC A description of this auto member rule
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
--pkey-only Results should contain primary key attribute only
(“automember-rule”)
automember-find-orphans
Usage:
ipa [global-options] automember-find-orphans [CRITERIA] [options]
Search for orphan automember rules. The command might need to be run as
a privileged user user to get all orphan rules.Arguments
Argument Required Description
CRITERIA no A string searched in all relevant object
attributes
Options
Option Description
--desc DESC A description of this auto member rule
--type TYPE Grouping to which the rule applies
--remove Remove orphan automember rules
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
--pkey-only Results should contain primary key attribute only
(“automember-rule”)
automember-mod
Usage:
ipa [global-options] automember-mod AUTOMEMBER-RULE [options]
Modify an automember rule.
Arguments
Argument Required Description
AUTOMEMBER-RULE yes Automember Rule
Options
Option Description
--desc DESC A description of this auto member rule
--setattr SETATTR Set an attribute to a name/value pair. Format is
attr=value.
--addattr ADDATTR Add an attribute/value pair. Format is
attr=value. The attribute
--delattr DELATTR Delete an attribute/value pair. The option will
be evaluated
--rights Display the access rights of this entry (requires
—all). See ipa man page for details.
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
automember-rebuild
Usage: ipa [global-options] automember-rebuild [options]
Rebuild auto membership.
Options
Option Description
--type TYPE Grouping to which the rule applies
--users USERS Rebuild membership for specified users
--hosts HOSTS Rebuild membership for specified hosts
--no-wait Don’t wait for rebuilding membership
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
automember-remove-condition
Usage:
ipa [global-options] automember-remove-condition AUTOMEMBER-RULE [options]
Remove conditions from an automember rule.
Arguments
Argument Required Description
AUTOMEMBER-RULE yes Automember Rule
Options
Option Description
--desc DESC A description of this auto member rule
--inclusive-regex INCLUSIVE-REGEX Inclusive Regex
--exclusive-regex EXCLUSIVE-REGEX Exclusive Regex
--key KEY Attribute to filter via regex. For example fqdn
for a host, or manager for a user
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.
--raw Print entries as stored on the server. Only
affects output format.
automember-show
Usage:
ipa [global-options] automember-show AUTOMEMBER-RULE [options]
Display information about an automember rule.
Arguments
Argument Required Description
AUTOMEMBER-RULE yes Automember Rule
Options
Option Description
--type TYPE Grouping to which the rule applies
--all Retrieve and print all attributes from the
server. Affects command output.