Chapter 1. Introduction to Hammer

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

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:

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, the hammer authentication session and providing credentials with each command are recommended.

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

$ hammer -u username -p password subcommands

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

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.

The default location for global hammer configuration is:

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

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

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

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

# satellite-maintain service restart

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

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.

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

$ hammer --output output_format organization list

Replace output_format with one of:

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.

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