Red Hat Training

A Red Hat training course is available for Red Hat Satellite

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 Red Hat Satellite Server either through CLI commands or automation in shell scripts. Hammer also provides an interactive shell.

Hammer compared to Satellite web UI

Compared to navigating the 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 Satellite Server’s base operating system is required to issue Hammer commands, which can limit the number of potential users compared to the web UI. Although the parity between Hammer and the web UI is almost complete, the web UI has development priority and can be ahead especially for newly introduced features.

Hammer compared to Satellite API

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. See the Red Hat Satellite API Guide for more information.

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

1.2. Authentication

By default, hammer prompts for your Satellite credentials each time you issue a command. You can specify your credentials when executing a command as follows: 

$ hammer -u <username> -p <password> <subcommands>

As an alternative, follow these steps to use saved credentials:

  1. Create the file ~/.hammer/cli_config.yml and add the following contents to the file: 

    :foreman:
 :host: 'https://satellite.example.com/'
 :username: 'username'
 :password: 'password'

    Replace the example values with your own details. Do not use tabs in the file, always use indentation by spaces.

  2. To protect your password, make sure the file is readable only by the current user: 

    $ chmod 600 ~/.hammer/cli_config.yml

  3. Save and close the file. Now when you start hammer it will use the credentials in the ~/.hammer/cli_config.yml file.

    Important

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

Note

Examples in this guide assume saved credentials.

1.3. Standalone Use of Hammer

It is possible to install hammer individually on a server where there is no Satellite installed, and use it to connect the server to a remote Satellite.

The rhel-X-server-satellite-6.X-rpms repository is required to install the package. Users desiring to use a workstation to connect should install the repository manually, see the Red Hat Satellite Installation Guide.

  1. Install hammer. 

    # yum install tfm-rubygem-hammer_cli_katello
  2. Edit /etc/hammer/cli.modules.d/foreman.yml to point to the desired Satellite.

1.4. Setting a Default Organization

Many hammer commands are organization specific. You can set a default organization, as well as location, for hammer commands so that you do not have to specify it every time using the --organization-id parameter. To do so, issue: 

$ hammer defaults add --param-name organization_id --param-value <org_ID>

Find <org_ID> in the output of the hammer organization list command. Similarly, you can set the default location as follows: 

$ hammer defaults add --param-name location_id --param-value <loc_ID>

To view the currently specified default settings, issue the following command: 

$ hammer defaults list

Specifying a default organization is useful when you mostly manage a single organization, as it makes your commands shorter. However, when switching to a different organization, you still have to use a command-line option to specify it. Examples in this guide do not assume a saved default organization, instead they use the shell variable approach described in Note.

1.5. 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, issue: 

$ 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 Section 1.2, “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. Note that these directives affect only the current user and are not applied globally. 

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

Similarly, you can set the number of lines displayed at once in the hammer output (equivalent of the --per-page option): 

:per-page: 30

1.6. Configuring Hammer Logging

You can set hammer to log debugging information for various Satellite components.

You can set debug or normal configuration options for all Satellite components.

Note

After changing hammer’s logging behavior, you must restart Satellite services. 

# katello-service restart

  • To set debug level for all components, use the following command: 

    # hammer admin logging --all --level-debug
# katello-service restart

  • To set production level logging, use the following command: 

    # hammer admin logging --all --level-production
# katello-service restart

  • To list the currently recognized components, that you can set logging for: 

    # hammer admin logging --list

  • To list all the available options of this tool: 

    # hammer admin logging --help

Usage:
    hammer admin logging [OPTIONS]

1.7. Invoking the Hammer Shell

You can issue hammer commands through the interactive shell. To invoke the shell, issue the following command: 

$ hammer shell

In the shell, you can enter subcommands 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].

1.8. Generating Formatted 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), issue 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 (see Example 2.6, “Synchronizing All Repositories in ACME Organization” or Example 2.8, “Assigning a Synchronization Plan to Multiple Products”).

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.

1.9. Troubleshooting with Hammer

You can use the hammer ping command to check the status of core Satellite services. Together with the katello-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
candlepin:
    Status:          ok
    Server Response: Duration: 22ms
candlepin_auth:
    Status:          ok
    Server Response: Duration: 17ms
pulp:
    Status:          ok
    Server Response: Duration: 41ms
pulp_auth:
    Status:          ok
    Server Response: Duration: 23ms
foreman_tasks:
    Status:          ok
    Server Response: Duration: 33ms