Chapter 6. Managing Hosts

Host refers to any physical or virtual system Red Hat Satellite manages. This section shows how to create and configure hosts and host groups using hammer. For web UI equivalents of the following procedures see Managing Hosts.

6.1. Creating a Host Group

A host group is a collection of hosts or host groups. It is recommended to create host groups to hold shared host parameters. Members of the host group inherit these parameters, therefore you do not have to set them individually during host creation. Note that you can nest host groups in a hierarchical manner.

The following command demonstrates a basic set of options for creating a host group:

$ hammer hostgroup create \
--name "hostgroup_name" \
--environment "environment_name" \
--architecture "architecture_name" \
--domain domain_name \
--subnet subnet_name \
--puppet-proxy proxy_name \
--puppet-ca-proxy ca-proxy_name \
--operatingsystem "os_name" \
--partition-table "table_name" \
--medium "medium_name" \
--organization-ids org_ID1,org_ID2... \
--location-ids loc_ID1,loc_ID2...

See hammer hostgroup create --help for the full list of configurable options. There are two settings that cannot be configured during host group creation:

  • An activation key has to be added afterwards using:
$ hammer hostgroup set-parameter \
--hostgroup "hostgroup_name" \
--name "kt_activation_keys" \
--value key_name

Run hammer activation-key list to find the activation key name (see Chapter 4, Managing Activation Keys for details on activation keys).

  • The root password has to be specified when adding a host to the host group.

Example 6.1. Creating Host Groups for Multiple Content Views

The following Bash script creates a host group for each life cycle environment.

OS=$(hammer --output csv os list | awk -F "," "/RedHat ${MAJOR}/ {print \$2;exit}")

hammer lifecycle-environment list --organization "${ORG}" | awk -F "|" '/[[:digit:]]/ {print $2}' | sed s'/ //' | while read LC_ENV
  if [[ ${LC_ENV} == "Library" ]]; then

  LC_ENV_LOWER=$(echo ${LC_ENV} | tr '[[:upper:]' '[[:lower:]]')
  ParentID=$(hammer --output csv hostgroup list --per-page 999 | awk -F"," "(\$3 ~ /^${LC_ENV_LOWER}$/) {print \$1}")

  hammer hostgroup create --name "rhel-${MAJOR}server-${ARCH}" \
    --medium "${ORG}/Library/Red_Hat_Server/Red_Hat_Enterprise_Linux_${MAJOR}_Server_Kickstart_${ARCH}_${MAJOR}
    Server" \
    --parent-id ${ParentID} \
    --architecture "${ARCH}" \
    --operatingsystem "${OS}" \
    --partition-table "${PTABLE_NAME}" \
    --subnet "${DOMAIN}" \
    --domain "${DOMAIN}" \
    --organizations "${ORG}" \
    --locations "${LOCATIONS}" \
    --content-view "cv-os-rhel-${MAJOR}Server" \
    --environment-id $(hammer --output csv environment list --per-page 999 | awk -F "," "/KT_$ {ORG}_${LC_ENV}_cv_os_rhel_${MAJOR}Server/ {print \$1}")

  HgID=$(hammer --output csv hostgroup list --per-page 999 | awk -F"," "(\$3 ~ /^${LC_ENV_LOWER}\/rhel-${MAJOR}server-${ARCH}$/) {print \$1}")

  hammer hostgroup set-parameter \
    --hostgroup-id "${HgID}" \
    --name "kt_activation_keys" \
    --value "act-${LC_ENV_LOWER}-os-rhel-${MAJOR}server-${ARCH}"

6.2. Creating a Host

It is recommended to set general parameters in a host group to reduce the number of required options when creating a host. The following command creates a basic host associated to a host group:

$ hammer host create \
--name "host_name" \
--hostgroup "hostgroup_name" \
--interface="primary=true, \
            provision=true, \
            mac=mac_address, \
            ip=ip_address" \
--organization-id org_ID \
--location-id loc_ID \
--ask-root-password yes

After executing the above command you will be prompted to specify the root password. It is required to specify the host’s IP and MAC address, other properties of the primary network interface can be inherited from the host group or set using the subnet, and domain parameters. You can set additional interfaces using the --interface option, which accepts a list of key-value pairs. For the list of available interface settings, see Table 6.1, “Available Keys for the --interface Option”.

If you decide to create a host without host group membership, specify additional options described in Section 6.1, “Creating a Host Group”. There is a wide range of available host parameters, for details see the output of hammer host create --help. The value of certain parameters depends on the type of compute resource the host is provisioned on, see Table 6.2, “Host Options Specific to Provider” for reference.

Table 6.1. Available Keys for the --interface Option



Defines the interface type, one of Nic::Managed, Nic::BMC, Nic::Bond.

name, identifier

Identification of the interface.

mac, ip, domain (or domain_id), subnet (or subnet_id)

Network settings, domain and subnet identification can be inherited from the host group.

primary, provision, managed, virtual

Accept true or false. Managed hosts needs to have one primary and provisioning interface.

Specific to virtual interfaces



VLAN tag, this attribute has precedence over the subnet VLAN ID.


Identifier of the interface to which the virtual interface belongs, for example eth1.

Specific to bonded interfaces



Bonding mode, one of balance-rr, active-backup, balance-xor, broadcast, 802.3ad, balance-tlb, balance-alb.

Specific to BMC interfaces



BMC provider, set to IPMI.

username, password

BMC access credentials.

Specific to hosts provisioned on Libvirt



Interface type, one of bridge, network.

compute_network or compute_bridge

Specifies interface name, pick one depending on the interface type.


One of virtio, rtl8139, ne2k_pci, pcnet, e1000.

Specific to hosts provisioned on RHEV



Interface name, for example eth0.


Select one of the available networks for a cluster, use UUID from RHEV.

Specific to hosts provisioned on VMware



Type of the network adapter, depends on your version of vSphere.


Network ID form VMware.

Table 6.2. Host Options Specific to Provider


Keys for the --compute-attributes option



flavor_id, image_id, availability_zone, security_group_ids, managed_ip


machine_type, image_id, network, external_ip


cpus, memory, start


flavor_ref, image_ref, tenant_id, security_groups, network


cluster, template, cores, memory, start


cpus, corespersocket, memory_mb, cluster, path, guest_id, scsi_controller_type, hardware_version, start

Keys for the --volume option



poll_name, capacity, format_type


size_gb, storage_domain, bootable


datastore, name, size_gb, thin, eager_zero

Example 6.2. Creating a Host with a Bonded Interface Pair

The following example shows how to create a host with a bonded interface pair. For more information on interface bonding see Configure Network Bonding in the Red Hat Enterprise Linux Networking Guide.

$ hammer host create --name bondtest \
--hostgroup-id 1 \
--ip= \
--mac=52:54:00:14:92:2a \
--subnet-id=1 \
--managed true \
   --interface="identifier=eth1, \
               mac=52:54:00:62:43:06, \
               managed=true, \
               type=Nic::Managed, \
               domain_id=1, \
               subnet_id=1" \
   --interface="identifier=eth2, \
               mac=52:54:00:d3:87:8f, \
               managed=true, \
               type=Nic::Managed, \
               domain_id=1, \
               subnet_id=1" \
   --interface="identifier=bond0, \
               ip=, \
               type=Nic::Bond, \
               mode=active-backup, \
               attached_devices=[eth1,eth2], \
               managed=true, \
               domain_id=1, \
               subnet_id=1" \
--organization-id 1 \
--location-id 1 \
--ask-root-password yes

6.3. Creating a Host Collection

A host collection in Red Hat Satellite is a group of hosts. The following command shows the minimal set of options required to create a host collection:

$ hammer host-collection create \
--organization-label org_label \
--name hc_name

To add hosts to a host collection, issue the following command:

$ hammer host-collection add-host \
--id hc_ID \
--host-ids ch_ID1,ch_ID2...

Run the following command to associate a host collection with an activation key (see Chapter 4, Managing Activation Keys for details on activation keys):

$ hammer activation-key add-host-collection \
--id ak_ID \
--host-collection hc_name

Hosts grouped in the host collection now inherit the configuration from the activation key.

6.4. Running Remote Jobs on Hosts

The remote execution feature enables defining arbitrary commands on the Satellite Server and executing them on remote hosts. Commands are defined in job templates that are similar to provisioning templates. Several job templates are included by default, you can use them or define a custom template for example to manipulate software packages or start a Puppet process on remote hosts. To use this feature in Hammer, install the remote execution CLI module by executing the following command as root:

# yum install tfm-rubygem-hammer_cli_foreman_remote_execution

To list job templates available, issue:

$ hammer job-template list

To create a job template using a template-definition file, use a command as follows:

$ hammer job-template create \
--file "template" \
--name "template_name" \
--provider-type SSH \
--job-category "category_name"

Replace template with the path to the file containing the template definition. Specify a custom category_name or select one of the existing categories (Commands, Katello, Packages, Power, Puppet, or Services). See the output of hammer job-template create --help for information on other available parameters.

To invoke a job with custom parameters, issue:

$ hammer job-invocation create \
--job-template "template_name" \
--inputs key1="value",key2="value",... \
--search-query "query"

Specify the template name you want to use for the remote job. Specify inputs as a comma separated list of key-value pairs. Run hammer job-template info to see what parameters are required by your template. Replace query with the filter expression defining which hosts will be affected (for example "name ~ rex01").

Example 6.3. Starting the httpd Service on Selected Hosts

This example shows how to execute a remote job based on the default Service Action - SSH Default template, that will start the httpd service on hosts that have a name that contains "target".

$ hammer job-invocation create \
--job-template "Service Action - SSH Default" \
--inputs service="httpd",action="start" \
--search-query "name ~ target"

To monitor the job output, issue:

$ hammer job-invocation output \
--id job_ID \
--host host_name

Find the job_ID in the output of hammer job-invocation list. For more information on executing remote commands with hammer, issue hammer job-template --help or hammer job-invocation --help.