RH403 - ch01s07

Red Hat Satellite provides the Hammer command-line interface to access the Satellite REST API. Using Hammer to perform common, repetitive tasks is often quicker than navigating through the Satellite web UI. Hammer commands can be scripted to automate complex tasks and to create consistent, repeatable results. Hammer generates parsable output in a choice of common formats, including CSV, YAML, and JSON.

Because the Hammer CLI and the Satellite web UI both invoke the same Satellite REST API resource operations, both interfaces create identical results. However, because different developer teams manage the CLI and the web UI, new capabilities might not be simultaneously released and supported.

The Hammer commands and interface are available for use from the Satellite Server base operating system, which requires the user to have a RHEL user account on that system. This requirement limits the Hammer potential users to administrators with full access to the Satellite Server. By comparison, all users with Satellite accounts can be assigned role-limited administration privileges through the web UI, from any supported browser with network access to the Satellite Server URL.

Hammer Authentication

The Satellite API, as with all REST APIs, requires that user credentials are included on each access request. Hammer can specify user credentials by using one of the following methods:

Command options

Provide your authorized username and password with each hammer command. The repetition can become tedious when entering many Hammer tasks. This method is also a security concern, because the typed username and password are retained in your shell's command history file. The following Hammer command demonstrates the user and password options:

[root@satellite ~]# hammer -u admin -p redhat organization list
...output omitted...

Configuration file

Store your credential parameters in your Hammer configuration file in the user home directory at /.hammer/cli.modules.d/forman.yml. Use this method when running Hammer commands automatically, such as from a cron job or script. The following configuration file is an example of credential syntax:

[root@satellite ~]# cat ~/.hammer/cli.modules.d/foreman.yml
:foreman:
  :username: 'admin'
  :password: 'redhat'

The Satellite admin username and password that the --foreman-initial-admin-username and --foreman-initial-admin- password options specify during the Satellite installation are automatically stored in the root user's configuration file.

Authentication session

Hammer provides a method to enter and cache authentication credentials at the beginning of a manual user session. The cache provides the credentials for all Hammer commands until the default session expires at 60 minutes or the user ends the session. Session credentials override configuration file credentials.

Use this method when entering multiple manual commands or running Hammer command scripts. This method avoids storing the credentials in unprotected scripts. To use this method, enable session use in your configuration file:

[root@satellite ~]# cat ~/.hammer/cli.modules.d/foreman.yml
:foreman:
  :use_sessions: true

A session starts with a login, and continues through any number of commands within the time limit, and ends with a logout, as demonstrated in this authentication session example:

[root@satellite ~]# hammer auth login basic
[Foreman] Username: admin
[Foreman] Password for admin: redhat
Successfully logged in as 'admin'
[root@satellite ~]# hammer auth status
Session exists, currently logged in as 'admin'.
[root@satellite ~]# hammer organization list
...output omitted...
[root@satellite ~]# hammer environment list
...output omitted...
[root@satellite ~]# hammer auth logout
Logged out.

Hammer Shell

The Hammer program includes an interactive shell. User authentication is required only when first launching the shell. The user can use any credential method: command-line options, configuration file, or an authentication session that is started within the shell.

At the hammer shell prompt, a user can enter any subcommand with arguments. However, hammer options can be included only on the initial hammer command that launches the shell. For example, the following shell is launched with the --no-headers option, which sets that behavior for all subcommands in this shell session.

[root@satellite ~]# hammer --no-headers shell
Welcome to the hammer interactive shell.
Type 'help' for usage information.
hammer> os list
2  | RedHat 9.0 |              | Redhat
1  | RHEL 8.6   |              | Redhat
hammer> location list
2  | Default Location | Default Location |
7  | San Francisco    | San Francisco    |
8  | Tokyo            | Tokyo            |
hammer> exit

Hammer Capabilities

Hammer has subcommands for managing virtually every entity type in Red Hat Satellite. The built-in help can provide extensive information about hammer capabilities. Hammer was designed to provide flexibility when displaying command results and objects. Formatted Hammer output is easy to parse or to pass to other commands for additional processing.

Hammer Help

View a list of available subcommands, syntax, and Hammer options by using the hammer --help command.

[root@satellite ~]# hammer --help
Usage:
    hammer [OPTIONS] SUBCOMMAND [ARG] ...

Parameters:
 SUBCOMMAND                    Subcommand
 [ARG] ...                     Subcommand arguments

Subcommands:
 activation-key                Manipulate activation keys
 admin                         Administrative server-side tasks
 ansible                       Manage foreman ansible
 architecture                  Manipulate architectures
...output omitted...

Options:
 --[no-]use-defaults           Enable/disable stored defaults. Enabled by default
 --autocomplete LINE           Get list of possible endings
 --csv                         Output as CSV (same as --output=csv)
 --csv-separator SEPARATOR     Character to separate the values
...output omitted...

Use the --help option to view subcommand actions, arguments, and syntax. Most subcommands manage a single entity type, and can include create, list, modify, and delete actions as a further level of subcommands. The following example lists action subcommands and syntax for the organization subcommand.

[root@satellite ~]# hammer organization --help
Usage:
    hammer organization [OPTIONS] SUBCOMMAND [ARG] ...

Parameters:
 SUBCOMMAND                    Subcommand
 [ARG] ...                     Subcommand arguments

Subcommands:
 add-compute-resource          Associate a compute resource
 add-domain                    Associate a domain
 add-environment               Associate a Puppet environment
 add-hostgroup                 Associate a hostgroup
...output omitted...

The --help option can provide further detail on subcommand actions, as in this example for creating an activation key.

[root@satellite ~]# hammer activation-key create --help
Usage:
    hammer activation-key create [OPTIONS]

Options:
 --content-view CONTENT_VIEW_NAME    Content view name to search by
 --content-view-id CONTENT_VIEW_ID   Content view numeric identifier
 --description DESCRIPTION           Description
 --environment ENVIRONMENT_NAME      Lifecycle environment name to search by
 ...output omitted...

Hammer Output Formats

By default, Hammer provides output in human-readable table form with headers, unless the --no-header option is included. Although columnar output is convenient for interactive Satellite management, other output formats are more appropriate for additional output processing. Some output formats are useful for saving to files to use as input to other programs, or for loading into a spreadsheet for further manipulation.

Hammer command output can be piped to other programs for reporting, data analysis, and data parsing. Use the --output option to specify a format from one of the following choices:

table: A human-readable columnar table. This output is the default format.
base: A list of key-value pairs for parsing individual keys and values.
yaml: A suitable YAML structure for redirecting to files or other programs. Many programs work with YAML structures to create or work with resource objects.
json: A suitable JSON structure for redirecting to files or other programs. Use a JSON query tool to parse information from JSON-structured output.
silent: Suppresses all output. It can be useful for creating quiet scripts. Use to ignore output that is not necessary, such as when Hammer displays an object structure after being created.
csv: A suitable row of comma-separated values. It can be useful for sending to a spreadsheet or other monitoring or graphing tools that support CSV. Specify field delimiter other than a comma by using the --csv-separator option.

The following example outputs an organization list that is formatted as comma-separated values.

[root@satellite ~]# hammer --output csv organization list
Id,Title,Name,Description,Label
1,Default Organization,Default Organization,"",Default_Organization
3,Operations,Operations,Operations Department,Operations

The following example outputs an organization list by using the base formatting.

[root@satellite ~]# hammer --output base organization list
Id:          1
Title:       Default Organization
Name:        Default Organization
Description:
Label:       Default_Organization

Id:          3
Title:       Operations
Name:        Operations Department
Description:
Label:       Operations

References

For more information, see the Hammer CLI Guide at https://access.redhat.com/documentation/en-us/red_hat_satellite/6.11/html-single/hammer_cli_guide/index

For more information, see the Hammer Cheat Sheet at https://access.redhat.com/documentation/en-us/red_hat_satellite/6.11/html-single/hammer_cheat_sheet/index

Discuss Red Hat Satellite 6 Administration

Go to community

Welcome to the Red Hat Satellite 6 Administration (RH403) group in the Red Hat Learning Community!

Syed

26 wrz 2023

We are excited to launch a space dedicated to the Red Hat Training course Red Hat Satellite 6 Administration! To gain the most value from this group - click the "Join Group" button in the upper right hand corner of the group home page.We encourage group members to collaborate in this group to discuss topics, ask questions, share best practices and tips, provide course feedback, and share their accomplishments as it relates to RH403.Read more about Red Hat Satellite 6 Administration here.

Revision: rh403-6.11-3ad886e