Using the Hammer CLI tool

Red Hat Satellite 6.18

Administer Satellite or develop custom scripts by using Hammer, the Satellite command-line tool

Abstract

This document describes how to use the Hammer CLI tool to configure and manage Red Hat Satellite.

Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. Let us know how we can improve it.

Use the Create Issue form in Red Hat Jira to provide your feedback. The Jira issue is created in the Red Hat Satellite Jira project, where you can track its progress.

Procedure

  1. Log in to Content from id.atlassian.com is not included.Atlassian Jira.
  2. Click the following link: Content from redhat.atlassian.net is not included.Create Issue.
  3. Complete the Summary, Description, and Reporter fields. In the Description field, include the documentation URL, chapter or section number, and a detailed description of the issue. Do not modify any other fields in the form.
  4. Click Create.

Chapter 1. Introduction to Hammer

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

Additional resources

1.1. Hammer compared to Satellite web UI

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

1.2. Satellite API compared to Hammer CLI

Hammer serves as a human-friendly interface to Satellite 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

Chapter 2. Installing standalone Hammer

You can install Hammer on a host running RHEL that has no Satellite Server installed, and use it to connect from the host to a remote Satellite.

Prerequisites

  • Ensure that you register the host to Satellite Server or Capsule Server.

  • Ensure that the following repositories are enabled and synchronized on Satellite Server:

    • rhel-9-for-x86_64-baseos-rpms
    • rhel-9-for-x86_64-appstream-rpms
    • satellite-utils-6.18-for-rhel-9-x86_64-rpms

Procedure

  1. Enable the required repositories on the host.

  2. Install Hammer CLI: 

    # dnf install satellite-cli

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

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

Additional resources

Chapter 3. Hammer authentication

Hammer requires Satellite 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 Satellite 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 Satellite Server. If you change your credentials on Satellite 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 Satellite 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 Satellite 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

Chapter 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 Chapter 3, 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'

Chapter 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.

Chapter 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

Chapter 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

Chapter 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
       }
                   ]
}'

Chapter 9. Troubleshooting Satellite by using Hammer

You can use the hammer ping command to check the status of core Satellite services. Together with the satellite-maintain service status command, this can help you to diagnose and troubleshoot Satellite 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

Chapter 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 Satellite Server by using either CLI commands or shell script automation. Run hammer full-help on Satellite to view the complete Hammer CLI help.

10.1. General information

Review essential information for using Hammer CLI in Red Hat Satellite. 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 Chapter 3, 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 Red Hat Satellite by using Hammer CLI commands.

SubcommandDescription and tasks

organization

Create an organization: 

hammer organization create \
--name org_name

List organizations: 

hammer organization list

location

See the options for organization

subscriptionorganization-specific

Upload a subscription manifest: 

hammer subscription upload \
--file path

repository-setorganization-specific

Enable a repository: 

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

repositoryorganization-specific

Synchronize a repository: 

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

Create a custom 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 custom 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 Red Hat Satellite by using Hammer CLI commands.

SubcommandDescription and tasks

lifecycle-environmentorganization-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-vieworganization-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 Red Hat Satellite by using Hammer CLI commands.

SubcommandDescription and tasks

domain

Create a domain: 

hammer domain create \
--name domain_name

subnetorganization-specificlocation-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-resourceorganization-specificlocation-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 Red Hat Satellite by using Hammer CLI commands.

SubcommandDescription and tasks

activation-keyorganization-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 Red Hat Satellite by using Hammer CLI commands.

SubcommandDescription and tasks

userorganization-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 Red Hat Satellite by using Hammer CLI commands.

SubcommandDescription 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 Red Hat Satellite by using Hammer CLI commands.

SubcommandDescription and tasks

hostgrouporganization-specificlocation-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

hostorganization-specificlocation-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 Red Hat Satellite by using Hammer CLI commands.

SubcommandDescription and tasks

task

List all tasks: 

hammer task list

Monitor progress of a running task: 

hammer task progress \
--id task_ID

Legal Notice

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.