FreeIPA
Draft version. Content is hallucinated. Do not use!
directory

Host Group Management

Manage groups of hosts for policy application and delegated administration. Host groups enable centralized configuration of access control rules, sudo policies, and SELinux mappings. Supports nested host group membership, external members, and membership managers for fine-grained control over host organization and policy assignment.

9 commands
directory
groups policy delegation

Overview

Host groups in FreeIPA organize enrolled hosts into logical collections for policy application, access control, and delegated administration. Rather than applying HBAC rules, sudo rules, or other policies to individual hosts, administrators target host groups, enabling consistent policy enforcement across fleets of similar systems. When hosts join or leave groups, policies automatically adjust without requiring rule modifications.

Host groups serve multiple organizational purposes: grouping by function (webservers, databases, load balancers), environment (production, staging, development), location (datacenter-east, office-west), or security classification (dmz, internal, high-security). This flexible grouping enables policy application that mirrors organizational infrastructure topologies and security boundaries.

Host group membership can be direct (individual hosts explicitly added) or nested (host groups containing other host groups). Nested membership enables hierarchical organization where broad parent groups (e.g., “production”) contain more specific subgroups (e.g., “production-web”, “production-db”). HBAC and sudo rule evaluation automatically resolves nested membership, enabling policy targeting of either broad or specific host collections.

Host Group Purposes

Policy Application

Host groups are the primary targeting mechanism for HBAC and sudo rules. Rather than listing individual hosts in each rule, policies reference host groups. As infrastructure scales and hosts are added or removed, policies automatically apply to current group members without rule modifications.

A single host group can be referenced by multiple policies. For example, “webservers” might appear in HBAC rules granting developer access, sudo rules allowing web service restarts, and SELinux user mapping rules setting appropriate security contexts. Changes to webserver group membership instantly affect all associated policies.

Infrastructure Organization

Host groups mirror infrastructure topology, creating organizational structures that reflect actual system purposes. Functional groupings (databases, caches, application servers) enable role-based policy management. Environmental groupings (production, staging, qa) enable environment-specific access controls. Geographic groupings (us-east, eu-west) support location-aware policies.

This organization helps administrators quickly understand infrastructure composition and ensure appropriate policies apply to each system category. Well-organized host groups make policy audits and compliance verification straightforward.

Delegated Administration

Host group membership managers enable delegated administration without granting full group management privileges. Designated users or groups can add or remove hosts from specific host groups but cannot modify group attributes, delete groups, or change other aspects of group configuration.

This delegation pattern supports workflows where infrastructure teams manage their own host group memberships. For example, the web operations team might be designated as membership managers for the “webservers” group, allowing them to add newly provisioned web servers without involving central IT.

Nested Host Groups

Host groups can contain other host groups as members, creating hierarchical organizational structures. Nested membership enables both broad and granular policy targeting while maintaining clear organizational boundaries.

A common nested pattern uses broad parent groups with specific children:

  • production (parent)
    • production-web (child)
    • production-db (child)
    • production-cache (child)

Policies can target the broad “production” group for production-wide access or specific child groups for role-specific access. HBAC and sudo rule evaluation automatically resolves nested membership, treating hosts in child groups as members of parent groups.

Nested groups simplify large-scale organization while enabling policy specificity. Rather than maintaining parallel flat structures for different policy contexts, a single nested hierarchy serves all policy applications.

Circular nesting (group A contains group B, group B contains group A) is prevented by IPA’s validation logic. Attempting to create circular references fails with an error indicating the membership would create a loop.

Membership Managers

Membership managers are users or groups authorized to add or remove hosts from a host group without full administrative privileges. This delegation enables distributed infrastructure management while maintaining security boundaries.

Membership managers can add or remove only host members (and nested host groups); they cannot modify group descriptions, delete groups, or change membership manager assignments. This restricted privilege set enables safe delegation for operational tasks.

Both individual users and user groups can be designated as membership managers. Assigning a user group as membership manager enables any member of that group to manage host group membership, creating flexible delegation hierarchies that adapt as team composition changes.

Membership managers appear in HBAC and sudo rules evaluation, but their manager status doesn’t grant them special access to managed hosts. Membership management is purely administrative; access control is determined by standard HBAC rules.

External Host Support

Host groups can include external hosts (non-IPA-enrolled systems) through specific external host references. This limited capability supports hybrid environments where some policy considerations include non-IPA systems.

External host support is constrained as external systems don’t participate in IPA authentication and authorization. External hosts appearing in host groups are visible to policies but may not enforce those policies unless specifically configured with appropriate integration.

Most deployments avoid external host usage, preferring to enroll all managed systems in IPA for consistent policy enforcement. External hosts are primarily used in transitional scenarios or specialized integrations.

Host Group Naming

Host group names should clearly indicate purpose and scope. Common naming conventions include:

  • Function-based: webservers, databases, caches, proxies
  • Environment-based: production, staging, qa, development
  • Location-based: us-east, eu-west, datacenter1
  • Application-based: app1-backend, app1-frontend, app2-workers
  • Security-based: dmz, internal, high-security, pci-scope

Consistent naming conventions improve policy readability and reduce confusion about which hosts belong in which groups. Names should be self-documenting, enabling administrators unfamiliar with specific infrastructure to understand group purposes.

Examples

Basic Host Group Management

Create a new host group:

ipa hostgroup-add webservers --desc="Production web servers"

Create groups for different environments:

ipa hostgroup-add production --desc="Production environment"
ipa hostgroup-add staging --desc="Staging environment"
ipa hostgroup-add development --desc="Development environment"

Delete a host group:

ipa hostgroup-del webservers

Display host group details:

ipa hostgroup-show webservers --all

Search for host groups:

ipa hostgroup-find web

Find host groups a specific host belongs to:

ipa hostgroup-find --hosts=web01.example.com

Adding Host Members

Add a single host to a group:

ipa hostgroup-add-member webservers --hosts=web01.example.com

Add multiple hosts:

ipa hostgroup-add-member webservers --hosts=web01.example.com --hosts=web02.example.com --hosts=web03.example.com

Add multiple hosts using Bash brace expansion:

ipa hostgroup-add-member databases --hosts=db{01,02,03}.example.com

Remove a host from a group:

ipa hostgroup-remove-member webservers --hosts=web02.example.com

Nested Host Groups

Create parent and child groups:

ipa hostgroup-add production --desc="All production systems"
ipa hostgroup-add production-web --desc="Production web servers"
ipa hostgroup-add production-db --desc="Production databases"

Add child groups to parent:

ipa hostgroup-add-member production --hostgroups=production-web
ipa hostgroup-add-member production --hostgroups=production-db

Remove a nested host group:

ipa hostgroup-remove-member production --hostgroups=production-web

Membership Manager Delegation

Designate a user as membership manager:

ipa hostgroup-add-member-manager webservers --users=webops_lead

Designate a group as membership manager:

ipa hostgroup-add-member-manager webservers --groups=webops_team

Add multiple membership managers:

ipa hostgroup-add-member-manager databases --users=dba1 --groups=dba_team

Remove membership manager privileges:

ipa hostgroup-remove-member-manager webservers --users=webops_lead

Complete Organizational Examples

Environment-based organization:

# Create environment groups
ipa hostgroup-add production --desc="Production environment"
ipa hostgroup-add staging --desc="Staging environment"

# Create functional groups within production
ipa hostgroup-add prod-web --desc="Production web tier"
ipa hostgroup-add prod-app --desc="Production application tier"
ipa hostgroup-add prod-db --desc="Production database tier"

# Nest functional groups under environment
ipa hostgroup-add-member production --hostgroups=prod-web --hostgroups=prod-app --hostgroups=prod-db

# Add hosts to functional groups
ipa hostgroup-add-member prod-web --hosts=web{01,02,03}.example.com
ipa hostgroup-add-member prod-app --hosts=app{01,02}.example.com
ipa hostgroup-add-member prod-db --hosts=db{01,02}.example.com

Location-based organization:

# Create location groups
ipa hostgroup-add us-east --desc="US East datacenter"
ipa hostgroup-add eu-west --desc="EU West datacenter"

# Create functional groups
ipa hostgroup-add webservers --desc="All web servers"
ipa hostgroup-add databases --desc="All databases"

# Add location-specific hosts
ipa hostgroup-add-member us-east --hosts=us-web{01,02}.example.com --hosts=us-db01.example.com
ipa hostgroup-add-member eu-west --hosts=eu-web{01,02}.example.com --hosts=eu-db01.example.com

# Add to functional groups regardless of location
ipa hostgroup-add-member webservers --hosts=us-web{01,02}.example.com --hosts=eu-web{01,02}.example.com

Best Practices

Group Organization

Mirror infrastructure topology: Organize host groups to reflect actual infrastructure organization. This makes policy application intuitive and auditing straightforward.

Use nested groups for hierarchy: Create parent groups for broad categories with specific child groups. This enables both broad and granular policy targeting.

Avoid excessive nesting: Limit nesting depth to 2-3 levels. Deep hierarchies become difficult to understand and troubleshoot.

Group by stable characteristics: Group hosts by enduring attributes (function, environment) rather than transient ones (current workload, temporary projects).

Naming Conventions

Establish consistent naming: Use consistent prefixes or suffixes for related groups (prod-web, staging-web, dev-web).

Make names self-documenting: Names should clearly indicate purpose without requiring external documentation.

Avoid ambiguous names: Don’t use names like “group1” or “servers”. Descriptive names improve policy clarity.

Use lowercase and hyphens: Follow convention of lowercase names with hyphens for multi-word names (web-servers, high-security).

Membership Management

Automate with automember rules: Use automember rules to automatically populate host groups based on host attributes. This reduces manual maintenance.

Audit membership regularly: Periodically review host group membership to ensure hosts are in appropriate groups.

Document group purposes: Maintain clear documentation explaining what each host group represents and which policies reference it.

Clean up obsolete groups: Delete or disable host groups that are no longer used. Stale groups clutter the directory.

Delegation

Delegate membership management carefully: Membership managers have significant control over policy application. Grant this privilege judiciously.

Use group-based delegation: Prefer delegating to user groups rather than individuals. This enables delegation that adapts to team composition.

Document delegation relationships: Maintain records of which users/groups can manage which host groups.

Monitor delegated changes: Track membership changes made by membership managers to detect errors or inappropriate modifications.

Policy Integration

Design groups with policies in mind: Create host groups that align with HBAC and sudo rule requirements.

Avoid over-segmentation: Don’t create excessive host groups for minor variations. Overly granular groups complicate policy management.

Use descriptive groups in rules: When creating HBAC/sudo rules, host group names should clearly indicate which hosts are affected.

Test policy changes: Before modifying host group membership affecting production systems, test policy impact in staging environments.

Operational Practices

Coordinate with provisioning: Ensure host provisioning processes add new hosts to appropriate groups automatically.

Plan for group changes: When reorganizing host groups, plan migration carefully to avoid unintended policy gaps.

Maintain inventory documentation: Track which hosts belong to which groups and why, especially for complex infrastructures.

Monitor membership churn: Excessive membership changes may indicate infrastructure instability or misconfigured automation.

Integration with Other IPA Components

Host Management

Hosts (host-* commands) are the members of host groups. Host enrollment and lifecycle management directly impacts host group membership.

HBAC Rules

HBAC rules (hbacrule-* commands) reference host groups to define which hosts access control policies apply to. Host group membership changes immediately affect HBAC evaluation.

Sudo Rules

Sudo rules (sudorule-* commands) reference host groups to specify where sudo privileges apply. Hosts joining or leaving groups affects sudo policy application.

Automember Rules

Automember rules (automember-* commands) can automatically populate host group membership based on host attributes, reducing manual group management overhead.

SELinux User Mapping

SELinux user mapping rules can reference host groups to apply security context policies to specific sets of hosts.

RBAC (Roles, Privileges, Permissions)

Host group management privileges can be delegated through roles, enabling distributed administration of group membership and structure.

Commands

Command Description

hostgroup-add Add a new hostgroup.

hostgroup-add-member Add members to a hostgroup.

hostgroup-add-member-manager Add users that can manage members of this hostgroup.

hostgroup-del Delete a hostgroup.

hostgroup-find Search for hostgroups.

hostgroup-mod Modify a hostgroup.

hostgroup-remove-member Remove members from a hostgroup.

hostgroup-remove-member-manager Remove users that can manage members of this hostgroup.

hostgroup-show Display information about a hostgroup.

hostgroup-add

Usage: ipa [global-options] hostgroup-add HOSTGROUP-NAME [options]

Add a new hostgroup.

Arguments

Argument Required Description

HOSTGROUP-NAME yes Name of host-group

Options

Option Description

--desc DESC A description of this host-group

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

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

hostgroup-add-member

Usage: ipa [global-options] hostgroup-add-member HOSTGROUP-NAME [options]

Add members to a hostgroup.

Arguments

Argument Required Description

HOSTGROUP-NAME yes Name of host-group

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--hosts HOSTS hosts to add

--hostgroups HOSTGROUPS host groups to add

hostgroup-add-member-manager

Usage: ipa [global-options] hostgroup-add-member-manager HOSTGROUP-NAME [options]

Add users that can manage members of this hostgroup.

Arguments

Argument Required Description

HOSTGROUP-NAME yes Name of host-group

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to add

--groups GROUPS groups to add

hostgroup-del

Usage: ipa [global-options] hostgroup-del HOSTGROUP-NAME [options]

Delete a hostgroup.

Arguments

Argument Required Description

HOSTGROUP-NAME yes Name of host-group

Options

Option Description

--continue Continuous mode: Don’t stop on errors.

hostgroup-find

Usage: ipa [global-options] hostgroup-find [CRITERIA] [options]

Search for hostgroups.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option Description

--hostgroup-name HOSTGROUP-NAME Name of host-group

--desc DESC A description of this host-group

--timelimit TIMELIMIT Time limit of search in seconds (0 is unlimited)

--sizelimit SIZELIMIT Maximum number of entries returned (0 is unlimited)

--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 (“hostgroup-name”)

--hosts HOSTS Search for host groups with these member hosts.

--no-hosts NO-HOSTS Search for host groups without these member hosts.

--hostgroups HOSTGROUPS Search for host groups with these member host groups.

--no-hostgroups NO-HOSTGROUPS Search for host groups without these member host groups.

--in-hostgroups IN-HOSTGROUPS Search for host groups with these member of host groups.

--not-in-hostgroups NOT-IN-HOSTGROUPS Search for host groups without these member of host groups.

--in-netgroups IN-NETGROUPS Search for host groups with these member of netgroups.

--not-in-netgroups NOT-IN-NETGROUPS Search for host groups without these member of netgroups.

--in-hbacrules IN-HBACRULES Search for host groups with these member of HBAC rules.

--not-in-hbacrules NOT-IN-HBACRULES Search for host groups without these member of HBAC rules.

--in-sudorules IN-SUDORULES Search for host groups with these member of sudo rules.

--not-in-sudorules NOT-IN-SUDORULES Search for host groups without these member of sudo rules.

--membermanager-users MEMBERMANAGER-USERS Search for host groups with these group membership managed by users.

--not-membermanager-users NOT-MEMBERMANAGER-USERS Search for host groups without these group membership managed by users.

--membermanager-groups MEMBERMANAGER-GROUPS Search for host groups with these group membership managed by groups.

--not-membermanager-groups NOT-MEMBERMANAGER-GROUPS Search for host groups without these group membership managed by groups.

hostgroup-mod

Usage: ipa [global-options] hostgroup-mod HOSTGROUP-NAME [options]

Modify a hostgroup.

Arguments

Argument Required Description

HOSTGROUP-NAME yes Name of host-group

Options

Option Description

--desc DESC A description of this host-group

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

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--rename RENAME Rename the host group object

hostgroup-remove-member

Usage: ipa [global-options] hostgroup-remove-member HOSTGROUP-NAME [options]

Remove members from a hostgroup.

Arguments

Argument Required Description

HOSTGROUP-NAME yes Name of host-group

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--hosts HOSTS hosts to remove

--hostgroups HOSTGROUPS host groups to remove

hostgroup-remove-member-manager

Usage: ipa [global-options] hostgroup-remove-member-manager HOSTGROUP-NAME [options]

Remove users that can manage members of this hostgroup.

Arguments

Argument Required Description

HOSTGROUP-NAME yes Name of host-group

Options

Option Description

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to remove

--groups GROUPS groups to remove

hostgroup-show

Usage: ipa [global-options] hostgroup-show HOSTGROUP-NAME [options]

Display information about a hostgroup.

Arguments

Argument Required Description

HOSTGROUP-NAME yes Name of host-group

Options

Option Description

--rights Display the access rights of this entry (requires —all). See ipa man page for details.

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

Related Topics

host hbacrule sudorule