Host-group Commands
In large managed environments with many hosts, you can assign hosts into host groups for easier management. For more information about host groups, see Host-Group Management.
The All Hosts group is a special host group that always contains all the hosts in the managed environment. Commands that change host group memberships cannot be used on the All Hosts group. Additionally, the All Hosts group cannot be deleted.
add-hosts-to-group
Syntax:
ssh-mgr-client [global_options] add-hosts-to-group (-d <data> | -f <file>) \
(-F <filter> | -i <id>) [-B] [-T <timeout>]
The command adds hosts to existing host groups. You must specify the host groups to which the hosts are to be added, and the hosts that are to be added.
Select a host by providing its ID (-i). Alternatively, you can select multiple hosts using filters (-F). The filters work with similar attributes as the list-hosts command (see list-hosts).
The target host group is to be specified as data (-d). If the name of the host group is unique in the system, you may specify the host-group name. Otherwise, you must specify the host-group path (use forward slashes to separate host groups along the path).
Required data:
hostgroup
The name of the host group, or the host-group path.
The following example adds all the Linux hosts to the host group Example Host Group 01:
$ ssh-mgr-client add-hosts-to-group -d 'hostgroup=Example Host Group 01' -F "os=linux"
Adding hosts to the host group Child Group 011, which is a child group to Example Host Group 01:
$ ssh-mgr-client add-hosts-to-group -d \
'hostgroup=Example Host Group 01/Child Group 011' -F "os=linux"
clear-host-membership
Syntax:
ssh-mgr-client clear-host-membership [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>]
This command removes the selected host(s) from all the host groups (except from the All Hosts group).
Select a host by specifying its ID (-i). Alternatively, you can select multiple hosts using filters (-F). For
filtering, you can use similar attributes as the list-hosts command (see list-hosts).
For example, to remove all host-group memberships from the Linux hosts in your managed environment:
$ ssh-mgr-client clear-host-membership -F "os=linux"
count-host-groups
Syntax:
ssh-mgr-client count-host-groups [options] [-F <filter>] [-vvv] [-U <url>]
Counts the host groups in the Key Manager system.
You can use filters (-F) to count only those host groups that match the given filters. For filtering, you can
use similar attributes as the list-host-groups command (see list-host-groups).
Example:
$ ssh-mgr-client count-host-groups
19
Example for counting host groups that match to certain criteria:
$ ssh-mgr-client count-host-groups -F name="Database*"
3
create-host-group
Syntax:
ssh-mgr-client create-host-group -d <data> [options] [-vvv] [-U <url>]
Add new host groups to the Key Manager system.
Specify the information about the new host group using the following data attributes:
Required data:
name
The free-text name for the host group.
Optional data:
description
The free-text description of the group.
parent
The name of the parent host group. When specified, the host group is added as a subgroup of the parent host group. When left unspecified, the host group is added as a top-level host group.
For example, adding a top-level host group that has the name DB Group and the description Database servers:
$ ssh-mgr-client create-host-group -d name='DB Group',description='Database servers'
As another example, to add a similar host group as a subgroup to the Linux host group:
$ ssh-mgr-client create-host-group -d \
name='DB Group',description='Database servers',parent='Linux'
delete-host-group
Syntax:
ssh-mgr-client delete-host-group -i <id> [options] [-vvv] [-U <url>] [-B]
Deletes a host group from the Key Manager system. The host group must be identified using its id. The
host group must be empty before it can be deleted using the command.
The following example command deletes host group 16:
$ ssh-mgr-client delete-host-group -i 16
It is not possible to delete non-empty host groups, or host groups with non-empty subgroups. You must
first empty the relevant host groups using the empty-host-group command:
$ ssh-mgr-client empty-host-group -i 16
$ ssh-mgr-client delete-host-group -i 16
For more information about emptying host groups with the empty-host-group command, see
empty-host-group.
empty-host-group
Syntax:
ssh-mgr-client empty-host-group [options] (-F <filter> | -i <id>) [-vvv] [-U <url>]
Removes all the hosts from the selected host groups.
You can select one host group by providing its ID (-i). The id value of host groups can be displayed using
the list-host-groups command (described in list-host-groups). Alternatively, you can use filters (-F)
to select those host groups that match the given filters. For filtering, you can use similar attributes as the
list-host-groups command (see list-host-groups).
The attributes that can be used for filtering are similar to those used with the list-host-groups
command (list-host-groups).
For example, to remove all the hosts from host group 11:
$ ssh-mgr-client empty-host-group -d id=11
As another example, to remove all hosts from the host groups that include test in their name:
$ ssh-mgr-client empty-host-group -F "name=*test*"
list-host-groups
Syntax:
ssh-mgr-client list-host-groups [options] [-F <filter>] [-vvv] [-U <url>] \
[-o <format>] [-C <columns>] [-H] [-O <sort-order>] [-S <start-from>] \
[-M <max-results>] [-E <delim>] [-B]
The default command lists all the host groups. The columns shown by default are name, hostcount,
description, and id:
$ ssh-mgr-client list-host-groups
All Hosts,120,Hostgroup always containin all hosts,1
Example Host Group,8,,2
Linux Hosts,80,Group for Linux hosts,3
...
The following columns can be used for filtering (-F) and output formatting (-C):
description
Description of the Host group
host_count
Number of hosts in the group. Only usable for output formatting (-C).
host_group_parent_id
Internal PrivX Key Manager id for Parent group
host_id
Internal PKM ID of a group member host. Only usable for filtering (-F).
hostgroup
Name of the host group
hostname
Name of a group member host. Only usable for filtering (-F).
hosts_in_hierarchy_count
Number of hosts in the group and subgroups. Only usable for output formatting (-C).
id
Internal PrivX Key Manager id for host group
level
Hierarchy level of the host group. Only usable for output formatting (-C).
priority
Priority of the host group. Only usable for output formatting (-C).
tree_id
Host group hierarchy tree id. NOTE: Creating host groups may change existing values.
As an example, to list all the host groups, the name of which starts with Host.
$ ssh-mgr-client list-host-groups -F "hostgroup=Host*"
modify-host-group
Syntax:
ssh-mgr-client modify-host-group [options] \
(-I <id-filter> | -i <id>) -d <data> [-vvv] [-U <url>]
Modify the selected host group.
Select the host group using its ID (-i) or using matching ID filters (-I). For ID filtering, you can use the
same attributes that are available for the list-host-groups command (described in list-host-groups).
Example for setting host-group priority:
$ ssh-mgr-client modify-host-group -I hostgorup="Example_Group" \
-d priority=8
Host-group priority can be removed by specifying a value of 0:
$ ssh-mgr-client modify-host-group -I hostgorup="Example_Group" \
-d priority=0
remove-hosts-from-group
Syntax:
ssh-mgr-client [-v] [-U <url>] [-B] remove-hosts-from-group \
(-F <filter> | -i <id>) (-d <data> | -f <file>)
Required data:
hostgroup
The ID of the host group from which hosts are to be removed.
The id value of host groups can be displayed using the list-host-groups command (described in list-host-groups).
The following example removes all the Linux hosts from the hostgroup that has the id value of 12.
$ ssh-mgr-client remove-hosts-from-group -d hostgroup=12 -F "os=linux"
show-host-group
Syntax:
ssh-mgr-client [-v] [-U <url>] [-o <format>] [-C <columns>] show-host-group -i <id>
Displays the host group with the given ID. For output formatting, you can use similar attributes as the
list-host-groups command (see list-host-groups).
Example:
$ ssh-mgr-client show-host-group -i 3