Skip to content

Commit

Permalink
Modularize Hammer CLI guide (theforeman#3251)
Browse files Browse the repository at this point in the history
* Split configuring Hammer CLI
* Reorder sections in Hammer CLI guide
* Split off compared to sections
* Rename standalone Hammer CLI installation
* Rename troubleshooing with Hammer
* Fix order
  • Loading branch information
maximiliankolb authored Sep 9, 2024
1 parent 3d86def commit d36835b
Show file tree
Hide file tree
Showing 20 changed files with 453 additions and 434 deletions.
15 changes: 15 additions & 0 deletions guides/common/modules/con_hammer-authentication.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
[id="hammer-authentication"]
= Hammer authentication

A {Project} user must prove their identity to {ProjectName} when entering hammer commands.
Hammer commands can be run manually or automatically.
In either case, hammer requires {Project} 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 {Project} maintenance commands from a cron job.
When running commands manually, {Team} recommends using the hammer authentication session and providing credentials with each command.
14 changes: 14 additions & 0 deletions guides/common/modules/con_hammer-compared-to-project-api.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
[id="hammer-compared-to-{project-context}-api"]
= Hammer compared to {Project} API

For many tasks, both Hammer and {Project} API are equally applicable.
Hammer can be used as a human friendly interface to {Project} 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.

ifdef::satellite[]
For more information, see the {APIDocURL}[_{APIDocTitle}_].
endif::[]
10 changes: 10 additions & 0 deletions guides/common/modules/con_hammer-compared-to-project-webui.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
[id="hammer-compared-to-{ProjectWebUI-context}"]
= Hammer compared to {ProjectWebUI}

Compared to navigating the {ProjectWebUI}, using Hammer can result in much faster interaction with the {ProjectServer}, 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 {ProjectName}.

Access to base operating system on {ProjectServer} is required to issue Hammer commands, which can limit the number of potential users compared to the {ProjectWebUI}.
Although the parity between Hammer and the {ProjectWebUI} is almost complete, the {ProjectWebUI} has development priority and can be ahead especially for newly introduced features.
Loading

0 comments on commit d36835b

Please sign in to comment.