1. Introduction to Hammer

Hammer is a powerful command-line tool provided with Foreman. You can use Hammer to configure and manage a Foreman server either through CLI commands or automation in shell scripts. Hammer also provides an interactive shell.

Additional resources

1.1. Hammer compared to Foreman web UI

Hammer provides faster interaction with Foreman than the Foreman web UI through shell features, scripting capabilities, and tool integration.

1.2. Foreman API compared to Hammer CLI

Hammer serves as a human-friendly interface to Foreman API. Use Hammer for interactive tasks and testing API calls, but use the API directly for better performance when executing many commands in scripts.

For example, to test responses to API calls before applying them in a script, use the --debug option to inspect API calls that Hammer issues: hammer --debug organization list.

In the background, each Hammer command first establishes a binding to the API, then sends a request. This can have performance implications when executing a large number of Hammer commands in sequence. In contrast, a script communicating directly with the API establishes the binding only once.

Additional resources

1.3. Getting help with Hammer CLI

Use the --help flag with Hammer CLI commands to view the built-in help documentation.

View the full list of hammer options and subcommands by executing:

$ hammer --help

Use --help to inspect any subcommand, for example:

$ hammer organization --help

You can search the help output using grep, or redirect it to a text viewer, for example:

$ hammer | less

2. Installing standalone Hammer

You can install Hammer on a host running Enterprise Linux that has no Foreman server installed, and use it to connect from the host to a remote Foreman.

Prerequisites

  • Ensure that the CA certificate of Foreman server is deployed to the truststore on the host.

Procedure

  1. Enable the required repositories on the host.

    # dnf install https://yum.theforeman.org/releases/nightly/el9/x86_64/foreman-release.rpm

  2. Install Hammer CLI:

    # dnf install foreman-cli

  3. Set the :host: entry in the /etc/hammer/cli.modules.d/foreman.yml file to the Foreman URL:

    :host: 'https://foreman.example.com'

3. Hammer authentication

Hammer requires Foreman credentials for authentication. You can authenticate using sessions, configuration files, or command-line options depending on whether you run commands manually or automatically.

3.1. Authenticating Hammer using a configuration file

Store Hammer credentials in the configuration file to automate tasks without interactive prompts. This method is recommended for running Hammer commands from scripts or cron jobs.

Important

If you ran the Foreman installation with --foreman-initial-admin-username and --foreman-initial-admin-password options, credentials you entered are stored in the ~/.hammer/cli.modules.d/foreman.yml configuration file on Foreman server. If you change your credentials on Foreman server, you must update the configuration file manually. The installer does not overwrite the configuration file.
Procedure

  • Add your credentials to the ~/.hammer/cli.modules.d/foreman.yml configuration file:

    :foreman:
 :username: 'username'
 :password: 'password'

    Use only spaces for indentation in Hammer configuration files, do not use tabs.

3.2. Authenticating Hammer using CLI options

If you do not have your Foreman credentials saved in the ~/.hammer/cli.modules.d/foreman.yml configuration file, Hammer prompts you for them each time you enter a command.

Note

Examples in this guide assume that you have saved credentials in the configuration file or are using a Hammer authentication session.
Procedure

  • Specify your credentials when executing a command as follows:

    $ hammer -u username -p password subcommands

3.3. Authenticating Hammer using sessions

The Hammer authentication session is a cache that stores your credentials, and you have to provide them only once, at the beginning of the session. This method is suited to running several Hammer commands in succession, for example a script containing Hammer commands.

Prerequisites

  • You have enabled sessions by adding :use_sessions: true to the ~/.hammer/cli.modules.d/foreman.yml file:

    :foreman:
 :use_sessions: true

    Note that if you enable sessions, credentials stored in the configuration file will be ignored.

  • Optional: You can change the length of a session, for example, to 30 minutes:

    $ hammer settings set \
--name idle_timeout \
--value 30

    The default length is 60 minutes.

Procedure

  • Start a session:

    $ hammer auth login

    You are prompted for your Foreman credentials, and logged in. You will not be prompted for the credentials again until your session expires.

Verification

  • View the current status of the session:

    $ hammer auth status
Next steps

  • End the session:

    $ hammer auth logout

4. Hammer configuration option

You can customize Hammer behavior by modifying global configuration in /etc/hammer/ or user-specific settings in ~/.hammer/, including log levels, output formatting, and CLI module settings.

The default location for global Hammer configuration is:

  • /etc/hammer/cli_config.yml for general Hammer settings

  • /etc/hammer/cli.modules.d/ for CLI module configuration files

You can set user specific directives for Hammer (in ~/.hammer/cli_config.yml) as well as for CLI modules (in respective .yml files under ~/.hammer/cli.modules.d/).

To see the order in which configuration files are loaded, as well as versions of loaded modules, use:

$ hammer -d --version
Note

Loading configuration for many CLI modules can slow down the execution of Hammer commands. In such a case, consider disabling CLI modules that are not regularly used.

Apart from saving credentials as described in Hammer authentication, you can set several other options in the ~/.hammer/ configuration directory. For example, you can change the default log level and set log rotation with the following directives in ~/.hammer/cli_config.yml. These directives affect only the current user and are not applied globally.

:log_level: 'warning'
:log_size: 5 #in MB

Similarly, you can configure user interface settings. For example, set the number of entries displayed per request in the Hammer output by changing the following line:

:per_page: 30

This setting is an equivalent of the --per-page Hammer option.

4.1. Setting a default organization and location context

Set a default organization and location context for Hammer to simplify commands and avoid repeatedly specifying the --organization and --location options. This is useful when you primarily manage a single organization.

Procedure

  1. Set a default organization:

    $ hammer defaults add --param-name organization \
--param-value "Your_Organization"

    You can find the name of your organization with the hammer organization list command.

  2. Optional: Set a default location:

    $ hammer defaults add --param-name location \
--param-value "Your_Location"

    You can find the name of your location with the hammer location list command.

Verification

  1. Review the currently specified default settings:

    $ hammer defaults list

4.2. Increasing the logging level for Hammer

Increase Hammer logging to debug to capture detailed CLI activity when troubleshooting command-line errors or API responses.

Hammer writes logs to ~/.hammer/log/hammer.log.

Procedure

  • In /etc/hammer/cli_config.yml, set the :log_level: option to debug:

    :log_level: 'debug'

5. Using interactive Hammer shell

You can issue Hammer commands through an interactive shell.

In the shell, you can enter sub-commands directly without typing hammer, which can be useful for testing commands before using them in a script.

Procedure

  • Start the shell:

    $ hammer shell
Next steps

  • To exit the shell, type exit or press Ctrl + D.

6. Formatting Hammer output

Change the Hammer output format to simplify processing by other tools and applications. Hammer supports table, base, YAML, CSV, JSON, and silent output formats.

Procedure

  • Set the output format with the --output option:

    $ hammer --output output_format organization list

  • Define a custom separator for the CSV format:

    $ hammer --csv --csv-separator ";" organization list

7. Hiding header output from Hammer commands

When you use any Hammer command, you have the option of hiding headers from the output. If you want to pipe or use the output in custom scripts, hiding the output is useful.

Procedure

  • Add the --no-headers option to any Hammer command to hide the header output:

    $ hammer --no-headers command

8. Using JSON for complex parameters

Use JSON format to pass complex parameters with multiple nested values to Hammer commands.

An example of JSON formatted content appears below:

$ hammer compute-profile values create --compute-profile-id 22 --compute-resource-id 1 --compute-attributes=
'{
"cpus": 2,
"corespersocket": 2,
"memory_mb": 4096,
"firmware": "efi",
"resource_pool": "Resources",
"cluster": "Example_Cluster",
"guest_id": "rhel8",
"path": "/Datacenters/EXAMPLE/vm/",
"hardware_version": "Default",
"memoryHotAddEnabled": 0,
"cpuHotAddEnabled": 0,
"add_cdrom": 0,
"boot_order": [
               "disk",
               "network"
              ],
"scsi_controllers":[
      {
       "type":  "ParaVirtualSCSIController",
       "key":1000
       },
      {
        "type":  "ParaVirtualSCSIController",
        "key":1001
       }
                   ]
}'

9. Troubleshooting Foreman by using Hammer

You can use the hammer ping command to check the status of core Foreman services. Together with the foreman-maintain service status command, this can help you to diagnose and troubleshoot Foreman issues.

If all services are running as expected, the output looks as follows:

$ hammer ping
database:
    Status:          ok
    Server Response: Duration: 0ms
cache:
    servers:
     1) Status:          ok
        Server Response: Duration: 1ms
candlepin:
    Status:          ok
    Server Response: Duration: 17ms
candlepin_auth:
    Status:          ok
    Server Response: Duration: 14ms
candlepin_events:
    Status:          ok
    message:         4 Processed, 0 Failed
    Server Response: Duration: 0ms
katello_events:
    Status:          ok
    message:         5 Processed, 0 Failed
    Server Response: Duration: 0ms
pulp3:
    Status:          ok
    Server Response: Duration: 5083ms
pulp3_content:
    Status:          ok
    Server Response: Duration: 5051ms
foreman_tasks:
    Status:          ok
    Server Response: Duration: 2ms

10. Hammer cheat sheet

You can use the examples in the cheat sheet as templates for common Hammer CLI tasks to configure and manage a Foreman server by using either CLI commands or shell script automation. Run hammer full-help on Foreman to view the complete Hammer CLI help.

10.1. General information

Review essential information for using Hammer CLI in Foreman. There are certain options that apply to all commands, such as authentication and getting help.

Authentication in examples

This cheat sheet assumes saved credentials in ~/.hammer/cli_config.yml. For more information, see Hammer authentication.

--help

Displays Hammer commands and options. You can append it after a subcommand to get more information.

organization-specific

The command requires you to specify an organization. You can append --organization My_Organization to the command or set a default organization:

hammer defaults add \
--param-name organization_id \
--param-value org_ID
location-specific

The command requires you to specify a location. You can append --location My_Location to the command or set a default location:

hammer defaults add \
--param-name location_id \
--param-value loc_ID

10.2. Organizations, locations, and repositories

You can manage organizations, locations, and repositories in Foreman by using Hammer CLI commands.

Subcommand Description and tasks

organization

Create an organization:

hammer organization create \
--name org_name

List organizations:

hammer organization list

location

See the options for organization

subscription organization-specific

Upload a subscription manifest:

hammer subscription upload \
--file path

repository-set organization-specific

Enable a repository:

hammer repository-set enable \
--product prod_name \
--basearch base_arch \
--releasever rel_v \
--name repo_name

repository organization-specific

Synchronize a repository:

hammer repository synchronize \
--product prod_name \
--name repo_name

Create a repository:

hammer repository create \
--product prod_name \
--content-type cont_type \
--publish-via-http true \
--url repo_url \
--name repo_name

Upload content to a repository:

hammer repository upload-content \
--product prod_name \
--id repo_id \
--path path_to_dir

10.3. Content life cycles

You can manage content views in lifecycle environments in Foreman by using Hammer CLI commands.

Subcommand Description and tasks

lifecycle-environment organization-specific

Create a life cycle environment:

hammer lifecycle-environment create \
--name env_name
--description env_desc
--prior prior_env_name

List life cycle environments:

hammer lifecycle-environment list

content-view organization-specific

Create a content view:

hammer content-view create \
--name cv_n \
--repository-ids repo_ID1,... \
--description cv_description

Add repositories to a content view:

hammer content-view add-repository \
--name cv_n \
--repository-id repo_ID

Add Puppet modules to a content view:

hammer content-view puppet-module add \
--content-view cv_n \
--name module_name

Publishing a content view:

hammer content-view publish \
--id cv_ID

Promoting a content view:

hammer content-view version promote \
--content-view cv_n \
--to-lifecycle-environment env_name

Incremental update of a content view:

hammer content-view version incremental-update \
--content-view-version-id cv_ID \
--packages pkg_n1,... \
--lifecycle-environment-ids env_ID1,...

10.4. Provisioning environments

You can prepare provisioning infrastructure in Foreman by using Hammer CLI commands.

Subcommand Description and tasks

domain

Create a domain:

hammer domain create \
--name domain_name

subnet organization-specific location-specific

Add a subnet:

hammer subnet create \
--name subnet_name \
--organization-ids org_ID1,... \
--location-ids loc_ID1,... \
--domain-ids dom_ID1,... \
--boot-mode boot_mode \
--network network_address \
--mask netmask --ipam ipam

compute-resource organization-specific location-specific

Create a compute resource:

hammer compute-resource create \
--name cr_name \
--organization-ids org_ID1,... \
--location-ids loc_ID1,... \
--provider provider_name

medium

Add an installation medium:

hammer medium create \
--name med_name \
--path path_to_medium

partition-table

Add a partition table:

hammer partition-table create \
--name tab_name \
--path path_to_file \
--os-family os_family

template

Add a provisioning template:

hammer template create \
--name tmp_name \
--file path_to_template

os

Add an operating system:

hammer os create \
--name os_name \
--version version_num

10.5. Activation keys

You can create activation keys and add subscriptions in Foreman by using Hammer CLI commands.

Subcommand Description and tasks

activation-key organization-specific

Create an activation key:

hammer activation-key create \
--name ak_name \
--content-view cv_n \
--lifecycle-environment lc_name

Add a subscription to the activation key:

hammer activation-key add-subscription \
--id ak_ID \
--subscription-id sub_ID

10.6. Users and permissions

You can manage users, user groups, roles, and filters in Foreman by using Hammer CLI commands.

Subcommand Description and tasks

user organization-specific

Create a user:

hammer user create \
--login user_name \
--mail user_mail \
--auth-source-id 1 \
--organization-ids org_ID1,org_ID2,...

Add a role to a user:

hammer user add-role \
--id user_id \
--role role_name

user-group

Create a user group:

hammer user-group create \
--name ug_name

Add a role to a user group:

hammer user-group add-role \
--id ug_id \
--role role_name

role

Create a role:

hammer role create \
--name role_name

filter

Create a filter and add it to a role:

hammer filter create \
--role role_name \
--permission-ids perm_ID1,perm_ID2,...

10.7. Errata

You can manage security updates and patches in Foreman by using Hammer CLI commands.

Subcommand Description and tasks

erratum

List errata:

hammer erratum list

Find erratum by CVE:

hammer erratum list --cve CVE

Inspect erratum:

hammer erratum info --id err_ID

host

List errata applicable to a host:

hammer host errata list \
--host host_name

Apply errata to a host:

hammer host errata apply \
--host host_name \
--errata-ids err_ID1,err_ID2,...

10.8. Hosts

You can manage hosts, host groups, and remote job execution in Foreman by using Hammer CLI commands.

Subcommand Description and tasks

hostgroup organization-specific location-specific

Create a host group:

hammer hostgroup create \
--name hg_name \
--puppet-environment env_name \
--architecture arch_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,... \
--location-ids loc_ID1,...

Add an activation key to a host group:

hammer hostgroup set-parameter \
--hostgroup "hg_name" \
--name "kt_activation_keys" \
--value key_name

host organization-specific location-specific

Create a host (inheriting parameters from a host group):

hammer host create \
--name host_name \
--hostgroup hg_name \
--interface="primary=true, \
mac=mac_addr, ip=ip_addr, \
provision=true" \
--organization-id org_ID \
--location-id loc_ID \
--ask-root-password yes

Remove the host from host group:

hammer host update --name host_name --hostgroup NIL

job-template

Add a job template for remote execution:

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

job-invocation

Start a remote job:

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

Monitor the remote job:

hammer job-invocation output \
--id job_id --host host_name

10.9. Tasks

You can list tasks and monitor their progress in Foreman by using Hammer CLI commands.

Subcommand Description and tasks

task

List all tasks:

hammer task list

Monitor progress of a running task:

hammer task progress \
--id task_ID
Pre-release version Report issue