Chapter 43. Managing host groups using the IdM CLI
Learn more about how to manage host groups and their members in the command-line interface (CLI) by using the following operations:
- Viewing host groups and their members
- Creating host groups
- Deleting host groups
- Adding host group members
- Removing host group members
- Adding host group member managers
- Removing host group member managers
43.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.
43.2. Viewing IdM host groups using the CLI
Follow this procedure to view IdM host groups using the command-line interface (CLI).
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.
Procedure
Find all host groups using the
ipa hostgroup-findcommand.$ 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
--alloption. 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 ----------------------------
43.3. Creating IdM host groups using the CLI
Follow this procedure to create IdM host groups using the command-line interface (CLI).
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.
Procedure
Add a host group using the
ipa hostgroup-addcommand.
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 ---------------------
43.4. Deleting IdM host groups using the CLI
Follow this procedure to delete IdM host groups using the command-line interface (CLI).
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.
Procedure
Delete a host group using the
ipa hostgroup-delcommand.
For example, to delete the IdM host group named group_name:$ ipa hostgroup-del group_name -------------------------- Deleted hostgroup "group_name" --------------------------
Removing a group does not delete the group members from IdM.
43.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-findcommand to find hosts and host groups.
Procedure
To add a member to a host group, use the
ipa hostgroup-add-memberand provide the relevant information. You can specify the type of member to add using these options:
Use the
--hostsoption 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
--hostgroupsoption 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}
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.
43.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-findcommand to confirm that the group includes the member you want to remove.
Procedure
To remove a host group member, use the
ipa hostgroup-remove-membercommand and provide the relevant information. You can specify the type of member to remove using these options:
Use the
--hostsoption 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
--hostgroupsoption 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 -------------------------
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}
43.7. Adding IdM host group member managers using the CLI
You can add hosts as well as host groups as member managers to an IdM host group using a single command. Member managers can add hosts or host groups to IdM host groups but cannot change the attributes of a host group.
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.
- You must have the name of the host or host group you are adding as member managers and the name of the host group you want them to manage.
Procedure
-
Optional: Use the
ipa hostgroup-findcommand to find hosts and host groups. To add a member manager to a host group, use the
ipa hostgroup-add-member-manager.For example, to add the user named example_member as a member manager to the group named group_name:
$ ipa hostgroup-add-member-manager group_name --user example_member Host-group: group_name Member hosts: server.idm.example.com Member host-groups: project_admins Member of netgroups: group_name Membership managed by users: example_member ------------------------- Number of members added 1 -------------------------
Use the
--groupsoption to add one or more host groups as a member manager to an IdM host group.For example, to add the host group named admin_group as a member manager to the group named group_name:
$ ipa hostgroup-add-member-manager group_name --groups admin_group Host-group: group_name Member hosts: server.idm.example.com Member host-groups: project_admins Member of netgroups: group_name Membership managed by groups: admin_group Membership managed by users: example_member ------------------------- Number of members added 1 -------------------------
After you add a member manager to a host group, the update may take some time to spread to all clients in your Identity Management environment.
Verification
Using the
ipa group-showcommand to verify the host user and host group were added as member managers.$ ipa hostgroup-show group_name Host-group: group_name Member hosts: server.idm.example.com Member host-groups: project_admins Membership managed by groups: admin_group Membership managed by users: example_member
Additional resources
-
See
ipa hostgroup-add-member-manager --helpfor more details. -
See
ipa hostgroup-show --helpfor more details.
43.8. Removing IdM host group member managers using the CLI
You can remove hosts as well as host groups as member managers from an IdM host group using a single command. Member managers can remove hosts group member managers from IdM host groups but cannot change the attributes of a host group.
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.
- You must have the name of the existing member manager host group you are removing and the name of the host group they are managing.
Procedure
-
Optional: Use the
ipa hostgroup-findcommand to find hosts and host groups. To remove a member manager from a host group, use the
ipa hostgroup-remove-member-managercommand.For example, to remove the user named example_member as a member manager from the group named group_name:
$ ipa hostgroup-remove-member-manager group_name --user example_member Host-group: group_name Member hosts: server.idm.example.com Member host-groups: project_admins Member of netgroups: group_name Membership managed by groups: nested_group --------------------------- Number of members removed 1 ---------------------------
Use the
--groupsoption to remove one or more host groups as a member manager from an IdM host group.For example, to remove the host group named nested_group as a member manager from the group named group_name:
$ ipa hostgroup-remove-member-manager group_name --groups nested_group Host-group: group_name Member hosts: server.idm.example.com Member host-groups: project_admins Member of netgroups: group_name --------------------------- Number of members removed 1 ---------------------------
After you remove a member manager from a host group, the update may take some time to spread to all clients in your Identity Management environment.
Verification
Use the
ipa group-showcommand to verify that the host user and host group were removed as member managers.$ ipa hostgroup-show group_name Host-group: group_name Member hosts: server.idm.example.com Member host-groups: project_admins
Additional resources
-
See
ipa hostgroup-remove-member-manager --helpfor more details. -
See
ipa hostgroup-show --helpfor more details.
