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 for hammer commands so that you do not have to specify it every time using the --organization or --organization-id parameter. To set a default organization, enter one of the following commands:

$ hammer defaults add --param-name organization --param-value org_name
$ hammer defaults add --param-name organization_id --param-value org_ID

You can find org_ID in the output of the hammer organization list command.

Similarly, you can set the default location by specifying its name or ID. To do so, enter one of the following commands:

$ hammer defaults add --param-name location --param-value loc_name
$ hammer defaults add --param-name location_id --param-value loc_ID

To view the currently specified default settings, enter 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 Section 2.1.2, “Identifying an Organization in a Hammer Command”.

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.

# foreman-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 (see ] or xref:exam-CLI_Guide-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:

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