Using the Hammer CLI tool

Red Hat Satellite 6.17

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

Red Hat Satellite Documentation Team

satellite-doc-list@redhat.com

Legal Notice

Abstract

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

Providing feedback on Red Hat documentation
Copy link

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

Log in to Atlassian Jira.
Click the following link: Create Issue.
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.
Click Create.

Chapter 1. Introduction to Hammer
Copy link

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.

1.1. Hammer compared to Satellite web UI
Copy link

Compared to navigating the Satellite web UI, using Hammer can result in much faster interaction with the Satellite Server, as common shell features such as environment variables and aliases are at your disposal. You can also incorporate Hammer commands into reusable scripts for automating tasks of various complexity. Output from Hammer commands can be redirected to other tools, which allows for integration with your existing environment. You can issue Hammer commands directly on the base operating system running Red Hat Satellite.

Access to base operating system on Satellite Server is required to issue Hammer commands, which can limit the number of potential users compared to the Satellite web UI. Although the parity between Hammer and the Satellite web UI is almost complete, the Satellite web UI has development priority and can be ahead especially for newly introduced features.

1.2. Hammer compared to Satellite API
Copy link

For many tasks, both Hammer and Satellite API are equally applicable. Hammer can be used as a human friendly interface to Satellite API, for example to test responses to API calls before applying them in a script (use the -d option to inspect API calls issued by Hammer, for example hammer -d organization list). Changes in the API are automatically reflected in Hammer, while scripts using the API directly have to be updated manually.

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.

For more information, see the Using the Satellite REST API.

1.3. Getting help
Copy link

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
Copy link

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.17-for-rhel-9-x86_64-rpms

Procedure

Enable the required repositories on the host.
Install Hammer CLI:
```
# dnf install satellite-cli
```
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

Enabling repositories on hosts in Managing hosts
Registering hosts by using global registration in Managing hosts
Synchronizing Repositories in Managing content

Chapter 3. Hammer authentication
Copy link

A Satellite user must prove their identity to Red Hat Satellite when entering hammer commands. Hammer commands can be run manually or automatically. In either case, hammer requires Satellite credentials for authentication. There are three methods of hammer authentication:

Hammer authentication session
Storing credentials in the hammer configuration file
Providing credentials with each hammer command

The hammer configuration file method is recommended when running commands automatically. For example, running Satellite maintenance commands from a cron job. When running commands manually, Red Hat recommends using the hammer authentication session and providing credentials with each command.

3.1. Authenticating Hammer using a configuration file
Copy link

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, and hammer does not prompt for your credentials.

You can also add your credentials to the ~/.hammer/cli.modules.d/foreman.yml configuration file manually:

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

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

Important

If you change your credentials on Satellite Server, you must update the configuration file manually. The installer does not overwrite the configuration file.

3.2. Authenticating Hammer using CLI options
Copy link

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. You can specify your credentials when executing a command as follows:

$ hammer -u username -p password subcommands

Note

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

3.3. Authenticating Hammer using sessions
Copy link

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. In this scenario, you enter your Satellite credentials once, and the script runs as expected. By using the hammer authentication session, you avoid storing your credentials in the script itself and in the ~/.hammer/cli.modules.d/foreman.yml hammer configuration file.

See the instructions on how to use the sessions:

To enable sessions, add :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.
To start a session, enter the following command:
```
$ 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.
The default length of a session is 60 minutes. You can change the time to suit your preference. For example, to change it to 30 minutes, enter the following command:
```
$ hammer settings set --name idle_timeout --value 30
Setting [idle_timeout] updated to [30]
```
To see the current status of the session, enter the following command:
```
$ hammer auth status
```
To end the session, enter the following command:
```
$ hammer auth logout
```

Chapter 4. Configuring Hammer
Copy link

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
Copy link

Many hammer commands are organization specific. You can set a default organization and location for hammer commands so that you do not have to specify them every time with the --organization and --location options.

Specifying a default organization is useful when you mostly manage a single organization, as it makes your commands shorter. However, when you switch to a different organization, you must use hammer with the --organization option to specify it.

Procedure

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

Review the currently specified default settings:
```
$ hammer defaults list
```

4.2. Increasing the logging level for Hammer
Copy link

You can find the log in ~/.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
Copy link

You can issue hammer commands through an interactive shell. Start the shell:

$ hammer 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. To exit the shell, type exit or press Ctrl + D.

Chapter 6. Formatting Hammer output
Copy link

You can modify the default formatting of the output of hammer commands to simplify the processing of this output by other command line tools and applications. For example, to list organizations in a CSV format with a custom separator (in this case a semicolon), use the following command:

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

Output in CSV format is useful for example when you need to parse IDs and use them in a for loop.

Several other formatting options are available with the --output option:

$ hammer --output output_format organization list

Replace output_format with one of:

table – generates output in the form of a human readable table (default).
base – generates output in the form of key-value pairs.
yaml – generates output in the YAML format.
csv – generates output in the Comma Separated Values format. To define a custom separator, use the --csv and --csv-separator options instead.
json – generates output in the JavaScript Object Notation format.
silent – suppresses the output.

Chapter 7. Hiding header output from Hammer commands
Copy link

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.

To hide the header output, add the --no-headers option to any hammer command.

Chapter 8. Using JSON for complex parameters
Copy link

JSON is the preferred way to describe complex parameters.

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
Copy link

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
Copy link

Hammer is a command-line tool provided with Red Hat Satellite 6. You can use Hammer 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
Copy link

Expand

Subcommand	Description and tasks
`--help`	Display hammer commands and options, append after a subcommand to get more information
org	The setting is organization-specific, append `--organization org_name`, or set default organization with: `hammer defaults add \ --param-name organization_id \ --param-value org_ID`
loc	The setting is location-specific, append `--location loc_name`, or set default location with: `hammer defaults add \ --param-name location_id \ --param-value loc_ID`

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

10.2. Organizations, locations, and repositories
Copy link

Expand

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` org	Upload a subscription manifest: `hammer subscription upload \ --file path`
`repository-set` org	Enable a repository: `hammer repository-set enable \ --product prod_name \ --basearch base_arch \ --releasever rel_v \ --name repo_name`
`repository` org	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
Copy link

Expand

Subcommand Description and tasks

Subcommand	Description and tasks
`lifecycle-environment` org	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` org	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,...`

lifecycle-environment
org

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
org

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
Copy link

Expand

Subcommand	Description and tasks
`domain`	Create a domain: `hammer domain create \ --name domain_name`
`subnet` org loc	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` org loc	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
Copy link

Expand

Subcommand Description and tasks

Subcommand	Description and tasks
`activation-key` org	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`

activation-key
org

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
Copy link

Expand

Subcommand	Description and tasks
`user` org	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
Copy link

Expand

Subcommand Description and tasks

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,...`

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
Copy link

Expand

Subcommand	Description and tasks
`hostgroup` org loc	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` org loc	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
Copy link

Expand

Subcommand	Description and tasks
`task`	List all tasks: `hammer task list Monitor progress of a running task: hammer task progress \ --id task_ID`

Chapter 11. Hammer reference
Copy link

You can review the usage of Hammer statements.

This reference is up to date with the versions of Hammer components released for Satellite 6.17.

Legal Notice
Copy link

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.

Using the Hammer CLI tool

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

Red Hat Satellite Documentation Team

Providing feedback on Red Hat documentationCopy linkLink copied to clipboard!

Chapter 1. Introduction to HammerCopy linkLink copied to clipboard!

1.1. Hammer compared to Satellite web UICopy linkLink copied to clipboard!

1.2. Hammer compared to Satellite APICopy linkLink copied to clipboard!

1.3. Getting helpCopy linkLink copied to clipboard!

Chapter 2. Installing standalone HammerCopy linkLink copied to clipboard!

Chapter 3. Hammer authenticationCopy linkLink copied to clipboard!

3.1. Authenticating Hammer using a configuration fileCopy linkLink copied to clipboard!

3.2. Authenticating Hammer using CLI optionsCopy linkLink copied to clipboard!

3.3. Authenticating Hammer using sessionsCopy linkLink copied to clipboard!

Chapter 4. Configuring HammerCopy linkLink copied to clipboard!

4.1. Setting a default organization and location contextCopy linkLink copied to clipboard!

4.2. Increasing the logging level for HammerCopy linkLink copied to clipboard!

Chapter 5. Using interactive Hammer shellCopy linkLink copied to clipboard!

Chapter 6. Formatting Hammer outputCopy linkLink copied to clipboard!

Chapter 7. Hiding header output from Hammer commandsCopy linkLink copied to clipboard!

Chapter 8. Using JSON for complex parametersCopy linkLink copied to clipboard!

Chapter 9. Troubleshooting Satellite by using HammerCopy linkLink copied to clipboard!

Chapter 10. Hammer cheat sheetCopy linkLink copied to clipboard!

10.1. General informationCopy linkLink copied to clipboard!

10.2. Organizations, locations, and repositoriesCopy linkLink copied to clipboard!

10.3. Content life cyclesCopy linkLink copied to clipboard!

10.4. Provisioning environmentsCopy linkLink copied to clipboard!

10.5. Activation keysCopy linkLink copied to clipboard!

10.6. Users and permissionsCopy linkLink copied to clipboard!

10.7. ErrataCopy linkLink copied to clipboard!

10.8. HostsCopy linkLink copied to clipboard!

10.9. TasksCopy linkLink copied to clipboard!

Chapter 11. Hammer referenceCopy linkLink copied to clipboard!

Legal NoticeCopy linkLink copied to clipboard!

Learn

Try, buy, & sell

Communities

About Red Hat

Making open source more inclusive

About Red Hat Documentation

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Providing feedback on Red Hat documentation
Copy link

Chapter 1. Introduction to Hammer
Copy link

1.1. Hammer compared to Satellite web UI
Copy link

1.2. Hammer compared to Satellite API
Copy link

1.3. Getting help
Copy link

Chapter 2. Installing standalone Hammer
Copy link

Chapter 3. Hammer authentication
Copy link

3.1. Authenticating Hammer using a configuration file
Copy link

3.2. Authenticating Hammer using CLI options
Copy link

3.3. Authenticating Hammer using sessions
Copy link

Chapter 4. Configuring Hammer
Copy link

4.1. Setting a default organization and location context
Copy link

4.2. Increasing the logging level for Hammer
Copy link

Chapter 5. Using interactive Hammer shell
Copy link

Chapter 6. Formatting Hammer output
Copy link

Chapter 7. Hiding header output from Hammer commands
Copy link

Chapter 8. Using JSON for complex parameters
Copy link

Chapter 9. Troubleshooting Satellite by using Hammer
Copy link

Chapter 10. Hammer cheat sheet
Copy link

10.1. General information
Copy link

10.2. Organizations, locations, and repositories
Copy link

10.3. Content life cycles
Copy link

10.4. Provisioning environments
Copy link

10.5. Activation keys
Copy link

10.6. Users and permissions
Copy link

10.7. Errata
Copy link

10.8. Hosts
Copy link

10.9. Tasks
Copy link

Chapter 11. Hammer reference
Copy link

Legal Notice
Copy link