Hammer CLI Guide

Almost all actions that can be performed via the management UI can also be performed via the "Hammer command line interface" (Hammer CLI).

During the installation of orcharhino the Hammer CLI is installed and configured. Like orcharhino itself, the functionality of Hammer CLI can be extended by plugins.

This guide uses orcharhino specific terminology. If you are new to orcharhino or unsure about certain terms, have a look at our glossary.

Installation

The Hammer CLI is usually installed automatically during the installation of orcharhino. If this is not the case, or if you want to install the Hammer CLI on a separate host, you can do this with the following command:

yum install tfm-rubygem-hammer_cli_katello

As already mentioned, additional Hammer CLI plugins can be installed. Use yum search hammer_cli to search for additional plugins.

Below is a list of other interesting Hammer CLI plugins:

Plugin Package

Ansible

tfm-rubygem-hammer_cli_foreman_ansible

Boot Disk

tfm-rubygem-hammer_cli_foreman_bootdisk

Discovery

tfm-rubygem-hammer_cli_foreman_discovery

OpenSCAP

tfm-rubygem-hammer_cli_foreman_openscap

Remote Execution

tfm-rubygem-hammer_cli_foreman_remote_execution

Salt

tfm-rubygem-hammer_cli_foreman_salt

SCC Manager

tfm-rubygem-hammer_cli_foreman_scc_manager

During the installation of orcharhino, a default configuration is stored in /etc/hammer/ and /etc/hammer/cli.modules.d/.

Hammer CLI searches for a configuration in the following directories:

  • /etc/hammer/

  • ~/.hammer/

/etc/hammer/ (and ~/.hammer/) contains the generic configuration and /etc/hammer/cli.modules.d/ (and ~/.hammer/cli.modules.d/) contains a plugin-specific configuration.

The path to the configuration file can also be set by -c CONFIG_FILE while using the Hammer CLI.

Authentication

For the use of Hammer CLI commands an authentication to orcharhino is necessary. This can be done using the "admin" user or any other orcharhino user so long as the user has the appropriate permissions.

Authentication can either be done individually for each command or can also be specified in the configuration. During the orcharhino installation the authentication for the system root user is stored in ~/.hammer/cli.modules.d/foreman.yml.

If the authentication is necessary for another system user or is configured on a different host using Hammer CLI, create ~/.hammer/cli_config.yml with the following contents:

:foreman:
  # Credentials. You'll be asked for the interactively if you leave them blank here
  :username: 'admin'
  :password: 'admin'

  # Check API documentation cache status on each request
  :refresh_cache: false

  # API request timeout in seconds, set -1 for infinity
  :request_timeout: 120

  # Specify the orcharhino host. If unset (or commented out), localhost is used.
  #:host: 'https://orcharhino.example.com'

Usage

With Hammer you can control orcharhino almost completely via the CLI. Many different commands are available for this purpose. As already mentioned, the functionality can be extended by hammer plugins. Documenting all commands at this point would go far beyond the scope of this documentation.

Therefore this documentation describes the general use of Hammer. A list of all available commands can be retrieved via hammer -h.

For each command and subcommand the list of options and available subcommands can be shown with -h, e.g. hammer os -h and hammer os create -h.

Hammer Shell

Hammer offers an interactive shell that can be used to execute multiple commands one after the other. This can be useful for testing purposes, before packing the commands into a shell script, which controls the Hammer commands. To exit the Hammer Shell you have to enter "exit" or "CTRL+D".

Output Format

Normally Hammer displays the generated output in tabular form. This can be controlled with the parameter --output <format>. Formats supported by orcharhino are base, table, silent, csv, yaml, and json. A shorter form of the output format of CSV data (comma separated values) can be controlled via the hammer option --csv.

With the option --no-headers you can suppress the output of the headings. If you want to write the output directly to a file, you can use the --output-file <output file> option.

Example: Create the list of hosts configured in orcharhino in CSV format without headings in the file host_list.csv.

hammer --csv --no-headers --output-file host_list.csv host list

Examples

Target of the first example is to add a Operating System "SLES15". First of all, we use hammer os create -h to show which options are necessary to create the OS.

Afterwards, we use the following construct to create the OS:

# hammer os create --name "SLES15" --family "Suse" --major "15" --description "SLES 15"
Operating system created.

Create some global parameters in a loop:

# for var in sles10:false sles11:true sles12:true sles15:false; do \
    name=$(echo $var | cut -f1 -d:); \
    value=$(echo $var | cut -f2 -d:); \
    hammer global-parameter set --name $name --value $value; \
  done
Created parameter [sles10] with value [false].
Created parameter [sles11] with value [true].
Created parameter [sles12] with value [true].
Created parameter [sles15] with value [false].

The aim of the second example is to deploy multiple hosts using a .csv file, and the following multi_host_deploy.sh bash script:

#!/bin/bash

while IFS=, read -r host_name host_group organization location
do
  hammer host create \
    --name "${host_name}" \
    --hostgroup "${host_group}" \
    --organization "${organization}" \
    --location "${location}"
  hammer host start --name "${host_name}.example.com"
done < hosts.csv

We can then define an arbitrary number of hosts by setting the host_name, host_group, organization and location parameters using the hosts.csv file, as follows:

# cat hosts.csv
host1,CentOS 7,My_Organization,My_Location_A
host2,SLES 15,My_Organization,My_Location_B

We can then deploy all hosts at once by running the multi_host_deploy.sh shell script as follows:

# ./multi_host_deploy.sh