Chapter 30. Managing host groups using the IdM CLI

This chapter introduces host groups in Identity Management (IdM) and describes the following operations to manage host groups and their members in the command-line interface (CLI):

  • Viewing host groups and their members
  • Creating host groups
  • Deleting host groups
  • Adding host group members
  • Removing host group members

30.1. Host groups in IdM

IdM host groups can be used to centralize control over important management tasks, particularly access control.

Definition of host groups

A host group is an entity that contains a set of IdM hosts with common access control rules and other characteristics. For example, you can define host groups based on company departments, physical locations, or access control requirements.

A host group in IdM can include:

  • IdM servers and clients
  • Other IdM host groups

Host groups created by default

By default, the IdM server creates the host group ipaservers for all IdM server hosts.

Direct and indirect group members

Group attributes in IdM apply to both direct and indirect members: when host group B is a member of host group A, all members of host group B are considered indirect members of host group A.

30.2. Viewing IdM host groups using the CLI

This section describes how to view IdM host groups using the command-line interface (CLI).

Prerequisites

Procedure

  1. Find all host groups using the ipa hostgroup-find command.

    $ ipa hostgroup-find
    -------------------
    1 hostgroup matched
    -------------------
      Host-group: ipaservers
      Description: IPA server hosts
    ----------------------------
    Number of entries returned 1
    ----------------------------

    To display all attributes of a host group, add the --all option. For example:

    $ ipa hostgroup-find --all
    -------------------
    1 hostgroup matched
    -------------------
      dn: cn=ipaservers,cn=hostgroups,cn=accounts,dc=idm,dc=local
      Host-group: ipaservers
      Description: IPA server hosts
      Member hosts: xxx.xxx.xxx.xxx
      ipauniqueid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      objectclass: top, groupOfNames, nestedGroup, ipaobject, ipahostgroup
    ----------------------------
    Number of entries returned 1
    ----------------------------

30.3. Creating IdM host groups using the CLI

This section describes how to create IdM host groups using the command-line interface (CLI).

Prerequisites

Procedure

  1. Add a host group using the ipa hostgroup-add command.
    For example, to create an IdM host group named group_name and give it a description:

    $ ipa hostgroup-add --desc 'My new host group' group_name
    ---------------------
    Added hostgroup "group_name"
    ---------------------
      Host-group: group_name
      Description: My new host group
    ---------------------

30.4. Deleting IdM host groups using the CLI

This section describes how to delete IdM host groups using the command-line interface (CLI).

Prerequisites

Procedure

  1. Delete a host group using the ipa hostgroup-del command.
    For example, to delete the IdM host group named group_name:

    $ ipa hostgroup-del group_name
    --------------------------
    Deleted hostgroup "group_name"
    --------------------------
Note

Removing a group does not delete the group members from IdM.

30.5. Adding IdM host group members using the CLI

You can add hosts as well as host groups as members to an IdM host group using a single command.

Prerequisites

  • Administrator privileges for managing IdM or User Administrator role.
  • An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
  • Optional. Use the ipa hostgroup-find command to find hosts and host groups.

Procedure

  1. To add a member to a host group, use the ipa hostgroup-add-member and provide the relevant information. You can specify the type of member to add using these options:

    • Use the --hosts option to add one or more hosts to an IdM host group.
      For example, to add the host named example_member to the group named group_name:

      $ ipa hostgroup-add-member group_name --hosts example_member
      Host-group: group_name
      Description: My host group
      Member hosts: example_member
      -------------------------
      Number of members added 1
      -------------------------
    • Use the --hostgroups option to add one or more host groups to an IdM host group.
      For example, to add the host group named nested_group to the group named group_name:

      $ ipa hostgroup-add-member group_name --hostgroups nested_group
      Host-group: group_name
      Description: My host group
      Member host-groups: nested_group
      -------------------------
      Number of members added 1
      -------------------------
    • You can add multiple hosts and multiple host groups to an IdM host group in one single command using the following syntax:

      $ ipa hostgroup-add-member group_name --hosts={host1,host2} --hostgroups={group1,group2}
Important

When adding a host group as a member of another host group, do not create recursive groups. For example, if Group A is a member of Group B, do not add Group B as a member of Group A. Recursive groups can cause unpredictable behavior.

30.6. Removing IdM host group members using the CLI

You can remove hosts as well as host groups from an IdM host group using a single command.

Prerequisites

  • Administrator privileges for managing IdM or User Administrator role.
  • An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
  • Optional. Use the ipa hostgroup-find command to confirm that the group includes the member you want to remove.

Procedure

  1. To remove a host group member, use the ipa hostgroup-remove-member command and provide the relevant information. You can specify the type of member to remove using these options:

    • Use the --hosts option to remove one or more hosts from an IdM host group.
      For example, to remove the host named example_member from the group named group_name:

      $ ipa hostgroup-remove-member group_name --hosts example_member
      Host-group: group_name
      Description: My host group
      -------------------------
      Number of members removed 1
      -------------------------
    • Use the --hostgroups option to remove one or more host groups from an IdM host group.
      For example, to remove the host group named nested_group from the group named group_name:

      $ ipa hostgroup-remove-member group_name --hostgroups example_member
      Host-group: group_name
      Description: My host group
      -------------------------
      Number of members removed 1
      -------------------------
Note

Removing a group does not delete the group members from IdM.

  • You can remove multiple hosts and multiple host groups from an IdM host group in one single command using the following syntax:

    $ ipa hostgroup-remove-member group_name --hosts={host1,host2} --hostgroups={group1,group2}