Using Hammer CLI

Introduction to Hammer

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

Hammer compared to orcharhino management UI

Compared to navigating the orcharhino management UI, using Hammer can result in much faster interaction with the orcharhino 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 orcharhino.

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

Hammer compared to orcharhino API

For many tasks, both Hammer and orcharhino API are equally applicable. Hammer can be used as a human friendly interface to orcharhino 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.

Getting help

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

Installing Hammer

You can install Hammer CLI and its plugins on your orcharhino Server. If you want to install Hammer CLI on a separate AlmaLinux 8, Oracle Linux 8, Red Hat Enterprise Linux 8, and Rocky Linux 8 host, see Installing standalone Hammer.

$ dnf install rubygem-hammer_cli_katello

Table 1. List of Hammer plugins
Plugin	Package
Ansible	`rubygem-hammer_cli_foreman_ansible`
Boot Disk	`rubygem-hammer_cli_foreman_bootdisk`
Discovery	`rubygem-hammer_cli_foreman_discovery`
OpenSCAP	`rubygem-hammer_cli_foreman_openscap`
Remote Execution	`rubygem-hammer_cli_foreman_remote_execution`
SCC Manager	`rubygem-hammer_cli_foreman_scc_manager`
Salt	`rubygem-hammer_cli_foreman_salt`

Installing standalone Hammer

You can install Hammer on a host running AlmaLinux 9, Oracle Linux 9, Red Hat Enterprise Linux 9, and Rocky Linux 9 that has no orcharhino Server installed, and use it to connect from the host to a remote orcharhino.

Prerequisites

Ensure that you register the host to orcharhino Server or orcharhino Proxy Server.
If you are installing on AlmaLinux 9, ensure that the following repositories are enabled and synchronized on orcharhino Server:
- AlmaLinux 9 BaseOS
- AlmaLinux 9 AppStream
If you are installing on AlmaLinux 8, ensure that the following repositories are enabled and synchronized on orcharhino Server:
- AlmaLinux 8 BaseOS
- AlmaLinux 8 AppStream

Procedure

Enable the required repositories on the host.
Install Hammer CLI:
```
$ dnf install orcharhino-cli
```
Set the :host: entry in the /etc/hammer/cli.modules.d/foreman.yml file to the orcharhino URL:
```
:host: 'https://orcharhino.example.com'
```

Additional resources

Enabling repositories on hosts in Managing Hosts
Registering Hosts in Managing Hosts
Synchronizing Repositories in Managing Content

Hammer authentication

A orcharhino user must prove their identity to orcharhino when entering hammer commands. Hammer commands can be run manually or automatically. In either case, hammer requires orcharhino 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 orcharhino maintenance commands from a cron job. When running commands manually, ATIX AG recommends using the hammer authentication session and providing credentials with each command.

Authenticating Hammer using a configuration file

If you ran the orcharhino 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.

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

Authenticating Hammer using CLI options

If you do not have your orcharhino 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

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

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. In this scenario, you enter your orcharhino 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 orcharhino 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
```

Configuring Hammer

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

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.

Setting a default organization and location context

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

Increasing the logging level for Hammer

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'

Using interactive Hammer shell

You can issue hammer commands through an interactive shell. To start the shell, run the following command:

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

Formatting Hammer output

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.

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.

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

Using JSON for complex parameters

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

Troubleshooting orcharhino by using Hammer

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

Hammer cheat sheet

Hammer is a command-line tool provided with orcharhino. You can use Hammer to configure and manage a orcharhino Server by using either CLI commands or shell script automation. Run hammer full-help on your orcharhino to view the complete Hammer CLI help.

The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution Share Alike 4.0 International ("CC BY-SA 4.0") license. This page also contains text from the official Foreman documentation which uses the same license ("CC BY-SA 4.0").