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 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
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, the hammer authentication session and providing credentials with each command are recommended.
1.2.1. Hammer Authentication Session
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
1.2.2. Hammer Configuration File
If you ran the Satellite installation with --foreman-admin-username
and --foreman-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 for indentation in hammer configuration files.
1.2.3. Command Line
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
Examples in this guide assume having saved credentials in the configuration file, or using a hammer authentication session.
1.3. Using Standalone Hammer
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.
Prerequisites
- Ensure that you register the host to Satellite Server or Capsule Server. For more information, see Registering a Host in the Provisioning Guide.
Ensure that you synchronize the following repositories on Satellite Server or Capsule Server. For more information, see Synchronizing Red Hat Repositories in the Content Management Guide.
- rhel-7-server-rpms
- rhel-server-rhscl-7-rpms
- rhel-7-server-satellite-tools-6.4-rpms
Procedure
On a host, complete the following steps to install hammer
:
Enable the Red Hat Enterprise Linux, Red Hat Software Collections and Red Hat Satellite Tools repositories:
# subscription-manager repos --enable=rhel-7-server-rpms \ --enable=rhel-server-rhscl-7-rpms \ --enable=rhel-7-server-satellite-tools-6.4-rpms
Install
hammer
:# yum install tfm-rubygem-hammer_cli_katello
Edit the
:host:
entry in the/etc/hammer/cli.modules.d/foreman.yml
file to include the Satellite IP address or FQDN.:host: 'https://satellite.example.com'
1.4. Setting a Default Organization
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”.
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
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 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.
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.
After changing hammer’s logging behavior, you must restart Satellite services.
# foreman-maintain service restart
To set debug level for all components, use the following command:
# hammer admin logging --all --level-debug # foreman-maintain service restart
To set production level logging, use the following command:
# hammer admin logging --all --level-production # foreman-maintain service restart
To list the currently recognized components, that you can set logging for:
# hammer admin logging --list
To list all available logging options:
# 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 ] 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:
-
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. 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.
1.10. Troubleshooting with Hammer
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