Red Hat SummitHammer CLI ツールの使用
Satellite コマンドラインツールである Hammer を使用して、Satellite を管理し、カスタムスクリプトを開発します。
概要
Red Hat ドキュメントへのフィードバック (英語のみ)
Red Hat ドキュメントに関するご意見やご感想をお寄せください。また、改善点があればお知らせください。
フィードバックを提供するには、Red Hat Jira の Create Issue フォームを使用します。Jira の問題が Red Hat Satellite Jira プロジェクトに作成され、その進捗状況を追跡できます。
前提条件
- Red Hat アカウント が登録されている。
手順
- Create Issue にアクセスします。Jira でログインエラーが表示された場合は、フォームにリダイレクトされた後、ログインして続行します。
- Summary フィールドと Description フィールドに入力します。Description フィールドに、ドキュメントの URL、章またはセクション番号、および問題の詳しい説明を入力します。フォーム内の他のフィールドは変更しないでください。
- Create をクリックします。
第1章 Hammer の概要
Hammer は、Red Hat Satellite 6 で提供される強力なコマンドラインツールです。Hammer を使用して、CLI コマンド、またはシェルスクリプトによる自動化により、Satellite Server を設定/管理することができます。Hammer は対話式のシェルも提供します。
1.1. Hammer と Satellite Web UI の比較
Satellite Web UI の操作感と比較すると、Hammer を使用する場合には環境変数やエイリアスなどのシェル機能が自由に使えるため、Satellite Server との対話がはるかに速くなります。また、Hammer のコマンドを再利用可能なスクリプトに組み込み、あらゆるレベルで複雑なタスクを自動化することもできます。Hammer コマンドからの出力を他のツールにリダイレクトして、既存の環境と統合できます。Hammer コマンドは、Red Hat Satellite を稼働するベースオペレーティングシステムで直接実行できます。
Hammer コマンドを発行するには、Satellite Server 上の基本オペレーティングシステムへのアクセスが必要であり、Satellite Web UI と比較して潜在的なユーザー数が制限される可能性があります。Hammer と Satellite Web UI の違いはほぼありませんが、Satellite Web UI の開発の優先度は高く、特に新しく導入される機能についてはこちらが優先されることがあります。
1.2. Hammer と Satellite API の比較
多くのタスクで、Hammer も Satellite API も同じように利用できます。Hammer は、スクリプトに適用する前に API の呼び出しの応答をテストするなど、Satellite API よりも使いやすいインターフェイスになっています (hammer -d organization list など、Hammer で実行した API の呼び出しを検査するには -d オプションを使用します)。API での変更は自動的に Hammer に適用されますが、API を直接使用するスクリプトは手動で更新する必要があります。
バックグラウンドで、各 Hammer コマンドは最初に API へのバインドを確立し、要求を送信します。この動作は、大量の Hammer コマンドを順に実行する場合に、パフォーマンスに影響を与える可能性があります。一方、API で直接接続するスクリプトを使用すると、バインドを確立するのは一度で済みます。
詳細は、Satellite REST API の使用 を 参照してください。
1.3. ヘルプの表示
hammer オプションおよびサブコマンドの完全なリストを表示するには以下を実行します。
hammer --help
$ hammer --help
以下のように --help を使用してサブコマンドを確認します。
hammer organization --help
$ hammer organization --help
以下のように grep を使用して help の出力を検索するか、テキストビューワーにリダイレクトすることができます。
hammer | less
$ hammer | less第2章 スタンドアロンの Hammer のインストール
Satellite Server がインストールされていない RHEL を実行しているホストに Hammer をインストールし、それを使用してホストからリモート Satellite に接続できます。
前提条件
手順
- ホストで必要なリポジトリーを有効にします。詳細は、ホストの管理 の ホスト上のリポジトリーの有効化 を参照してください。
次のモジュールを有効にします。
dnf module enable satellite-utils:el8
# dnf module enable satellite-utils:el8Copy to Clipboard Copied! Toggle word wrap Toggle overflow Hammer CLI をインストールします。
dnf install satellite-cli
# dnf install satellite-cliCopy to Clipboard Copied! Toggle word wrap Toggle overflow /etc/hammer/cli.modules.d/foreman.ymlファイルの:host:エントリーを Satellite URL に設定します。:host: 'https://satellite.example.com'
:host: 'https://satellite.example.com'Copy to Clipboard Copied! Toggle word wrap Toggle overflow
第3章 hammer authentication
hammer コマンドを使用する場合は Red Hat Satellite に識別子を証明する必要があります。hammer コマンドは手動または自動で実行できます。いずれの場合も、認証には Satellite 認証情報が必要です。hammer 認証には 3 つの方法があります。
- hammer 認証セッション
- hammer 設定ファイルに認証情報を保存
- hammer コマンドを使用するたびに認証情報を指定
自動でコマンドを実行する場合は、hammer 設定ファイルを使用することが推奨されます。たとえば、cron ジョブから Satellite メンテナンスコマンドを実行する場合です。コマンドを手動で実行する場合、Red Hat は、hammer 認証セッションを使用して、コマンドを実行するたびに認証情報を提供する方法を推奨します。
3.1. 設定ファイルを使用した Hammer の認証
--foreman-initial-admin-username オプションおよび --foreman-initial-admin-password オプションを使用して Satellite のインストールを実行すると、入力した認証情報が ~/.hammer/cli.modules.d/foreman.yml に保存され、hammer により認証情報の入力が求められます。
認証情報は、手動で ~/.hammer/cli.modules.d/foreman.yml 設定ファイルに追加することもできます。
:foreman: :username: 'username' :password: 'password'
:foreman:
:username: 'username'
:password: 'password'hammer 設定ファイル内のインデントにはスペースのみを使用し、タブは使用しないでください。
Satellite Server で認証情報を変更する場合は、設定ファイルを手動で更新する必要があります。インストーラーは設定ファイルを上書きしません。
3.2. CLI オプションを使用した Hammer の認証
Satellite 認証情報を ~/.hammer/cli.modules.d/foreman.yml 設定ファイルに保存しないと、コマンドを入力するたびに hammer によって認証情報が求められます。以下のように、コマンドの実行時に認証情報を指定できます。
hammer -u username -p password subcommands
$ hammer -u username -p password subcommandsこのガイドの例は、設定ファイルの認証情報が保存されているか、hammer 認証セッションを使用していることを前提としています。
3.3. セッションを使用した Hammer の認証
hammer 認証セッションでは、認証情報をキャッシュで保存するため、セッションの最初に一度だけ認証情報を入力する必要があります。この方法は、複数の hammer コマンドを含むスクリプトなど、複数の hammer コマンドを順次実行する場合に適しています。このようなシナリオでは Satellite の認証情報を一度入力すると、スクリプトは想定通りに実行します。hammer 認証セッションを使用する場合は、スクリプト自体に認証情報を保存せず、hammer 設定ファイル ~/.hammer/cli.modules.d/foreman.yml に保存します。
セッションの使用方法は以下のようになります。
セッションを有効にするには、
:use_sessions: trueを~/.hammer/cli.modules.d/foreman.ymlファイルに追加します。:foreman: :use_sessions: true
:foreman: :use_sessions: trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow セッションを有効にすると、設定ファイルに保存している認証情報は無視されます。
セッションを開始するには、以下のコマンドを入力します。
hammer auth login
# hammer auth loginCopy to Clipboard Copied! Toggle word wrap Toggle overflow Satellite 認証情報が求められ、ログインします。その認証情報は、セッションの有効期限が切れるまで持続するため、再要求はされません。
セッションのデフォルトの長さは 60 分です。必要に応じて時間を変更できます。たとえば、これを 30 分に変更するには、以下のコマンドを実行します。
hammer settings set --name idle_timeout --value 30 Setting [idle_timeout] updated to [30]
# hammer settings set --name idle_timeout --value 30 Setting [idle_timeout] updated to [30]Copy to Clipboard Copied! Toggle word wrap Toggle overflow セッションの現在のステータスを表示するには、以下のコマンドを実行します。
hammer auth status
# hammer auth statusCopy to Clipboard Copied! Toggle word wrap Toggle overflow セッションを終了するには、以下のコマンドを入力します。
hammer auth logout
# hammer auth logoutCopy to Clipboard Copied! Toggle word wrap Toggle overflow
第4章 hammer の設定
デフォルトでは、グローバルの hammer 設定は以下の場所に保存されています。
-
一般的な
hammerの設定: /etc/hammer/cli_config.yml - CLI モジュールの設定ファイル: /etc/hammer/cli.modules.d/
hammer (~/.hammer/cli_config.yml 内) または CLI モジュール (~/.hammer/cli.modules.d/ の適切な .yml ファイル) にユーザー固有のディレクティブを設定できます。
設定ファイルの読み込み順と、読み込んだモジュールのバージョンを表示するには、以下を実行します。
hammer -d --version
$ hammer -d --version
多くの CLI モジュールの設定を読み込むと、hammer コマンドの実行が遅くなる可能性があります。このような場合は、あまり使用しない CLI モジュールを無効化することを検討してください。
3章hammer authentication に記載されているような認証情報を保存する以外に、~/.hammer/ 設定ディレクトリーに他の複数のオプションを設定できます。たとえば、~/.hammer/cli_config.yml でデフォルトのログレベルを変更して、以下のディレクティブを使用してログのローテーションを設定できます。これらのディレクティブは、現在のユーザーにのみ影響を及ぼし、グローバルには適用されません。
:log_level: 'warning' :log_size: 5 #in MB
:log_level: 'warning'
:log_size: 5 #in MB同様に、ユーザーインターフェイスの設定を行います。たとえば、Hammer 出力で、要求ごとに表示するエントリー数を設定するには、以下の行を変更します。
:per_page: 30
:per_page: 30
この設定は、Hammer オプション --per-page と同等です。
4.1. デフォルトの組織およびロケーションコンテキストの設定
hammer コマンドの多くは、組織固有のものです。--organization オプションおよび --location オプションで毎回指定する必要がないように、hammer コマンドにデフォルトの組織とロケーションを設定できます。
主に単一の組織を管理する場合は、入力するコマンドが短くなるように、デフォルトの組織を指定すると便利です。別の組織に切り替える場合は、hammer コマンドを使用して、--organization オプションで切り替える組織を指定します。
手順
デフォルトの組織を設定します。
hammer defaults add --param-name organization \ --param-value "Your_Organization"
# hammer defaults add --param-name organization \ --param-value "Your_Organization"Copy to Clipboard Copied! Toggle word wrap Toggle overflow hammer organization listコマンドを使用して、組織の名前を検索します。必要に応じて、デフォルトの場所を設定します。
hammer defaults add --param-name location \ --param-value "Your_Location"
# hammer defaults add --param-name location \ --param-value "Your_Location"Copy to Clipboard Copied! Toggle word wrap Toggle overflow hammer location listコマンドを使用して、ロケーションの名前を検索します。
検証
現在指定されているデフォルト設定を確認します。
hammer defaults list
# hammer defaults listCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.2. Hammer のログレベルを上げる
ログは ~/.hammer/log/hammer.log にあります。
手順
-
/etc/hammer/cli_config.ymlで、:log_level:オプションをdebugに設定します。
:log_level: 'debug'
:log_level: 'debug'第5章 インタラクティブな Hammer シェルの使用
対話型シェルで hammer コマンドを発行することができます。シェルを起動するには、次のコマンドを実行します。
hammer shell
$ hammer shell
このシェルでは、"hammer" と入力せずに直接サブコマンドを入力できるので、スクリプトで使用する前にコマンドをテストする際に便利です。このシェルを終了するには、exit と入力するか、Ctrl + D を押します。
第6章 Hammer 出力のフォーマット
hammer コマンドのデフォルトの出力形式を変更して、他のコマンドラインツールやアプリケーションでこの出力結果を処理しやすくすることができます。たとえば、CSV 形式で、カスタムの区切り文字で (ここではセミコロンを使用) 組織を表示するには、以下のコマンドを実行します。
hammer --csv --csv-separator ";" organization list
$ hammer --csv --csv-separator ";" organization listCSV 形式の出力は、ID を解析して for ループで使用する必要がある場合などに便利です。
--output オプションには、他に複数のフォーマットオプションがあります。
hammer --output output_format organization list
$ hammer --output output_format organization listoutput_format を、以下のいずれかに置き換えます。
-
table: 人間が判読できる表形式 (デフォルト) で出力を生成します。 -
base: キーと値のペアの形式で出力を生成します。 -
yaml: YAML 形式で出力を生成します。 -
csv: コンマ区切りの値形式で出力を生成します。カスタムの区切り文字を定義する場合は、代わりに--csvオプションおよび--csv-separatorオプションを使用してください。 -
json: JavaScript Object Notation (JSON) 形式の出力を生成します。 -
silent: 出力を表示しません。
第7章 hammer コマンドのヘッダー出力の非表示
hammer コマンドの使用時には、出力からヘッダーを隠すオプションがあります。出力をパイプしたり、カスタムスクリプトで使用したりする場合は、出力を非表示にすると便利です。
-
ヘッダー出力を非表示にするには、
--no-headersオプションを hammer コマンドに追加します。
第8章 複雑なパラメーターへの JSON の使用
JSON は、複雑なパラメーターを記述するのに推奨される方法です。
JSON 形式のコンテンツの例を以下に示します。
第9章 Hammer を使用した Satellite のトラブルシューティング
hammer ping コマンドを使用して、コアの Satellite サービスのステータスを確認できます。satellite-maintain service status コマンドと併用すると、Satellite の問題の診断やトラブルシューティングに役立ちます。すべてのサービスが想定どおりに実行していると、出力は以下のようになります。
第10章 Hammer チートシート
Hammer は、Red Hat Satellite 6 で提供されるコマンドラインツールです。Hammer を使用すると、CLI コマンドまたはシェルスクリプトによる自動化により、Satellite Server を設定および管理できます。次のチートシートには、重要な Hammer コマンドの概要が簡潔にまとめられています。
10.1. 一般情報
| サブコマンド | 説明およびタスク |
|---|---|
|
| hammer コマンドとオプションを表示します。サブコマンドを追加するとより詳細な情報が表示されます。 |
| org |
この設定は組織に関するもので、 hammer defaults add \ --param-name organization_id \ --param-value org_ID |
| loc |
この設定はロケーションに関するもので、 hammer defaults add \ --param-name location_id \ --param-value loc_ID |
注記: このガイドでは、認証情報が ~/.hammer/cli_config.yml に保存されていることを想定しています。詳細は、3章hammer authentication を参照してください。
10.2. 組織、ロケーション、リポジトリー
| サブコマンド | 説明およびタスク |
|---|---|
|
| 組織を作成します。 hammer organization create \ --name org_name 組織をリスト表示します。 hammer organization list |
|
| 組織のオプションを参照してください。 |
|
| サブスクリプションマニフェストをアップロードします。 hammer subscription upload \ --file path |
|
| リポジトリーを有効にします。 hammer repository-set enable \ --product prod_name \ --basearch base_arch \ --releasever rel_v \ --name repo_name |
|
| リポジトリーを同期します。 hammer repository synchronize \ --product prod_name \ --name repo_name カスタムリポジトリーを作成します。 カスタムリポジトリーにコンテンツをアップロードします。 hammer repository upload-content \ --product prod_name \ --id repo_id \ --path path_to_dir |
10.3. コンテンツのライフサイクル
| サブコマンド | 説明およびタスク |
|---|---|
|
| ライフサイクル環境を作成します。 hammer lifecycle-environment create \ --name env_name --description env_desc --prior prior_env_name ライフサイクル環境をリスト表示します。 hammer lifecycle-environment list |
|
| コンテンツビューを作成します。 hammer content-view create \ --name cv_n \ --repository-ids repo_ID1,... \ --description cv_description コンテンツビューにリポジトリーを追加します。 hammer content-view add-repository \ --name cv_n \ --repository-id repo_ID コンテンツビューに Puppet モジュールを追加します。 hammer content-view puppet-module add \ --content-view cv_n \ --name module_name コンテンツビューを公開します。 hammer content-view publish \ --id cv_ID コンテンツビューをプロモートします。 hammer content-view version promote \ --content-view cv_n \ --to-lifecycle-environment env_name コンテンツビューの増分更新を実行します。 hammer content-view version incremental-update \ --content-view-version-id cv_ID \ --packages pkg_n1,... \ --lifecycle-environment-ids env_ID1,... |
10.4. 環境のプロビジョニング
| サブコマンド | 説明およびタスク |
|---|---|
|
| ドメインを作成します。 hammer domain create \ --name domain_name |
|
| サブネットを追加します。 |
|
| コンピュートリソースを作成します。 hammer compute-resource create \ --name cr_name \ --organization-ids org_ID1,... \ --location-ids loc_ID1,... \ --provider provider_name |
|
| インストールメディアを追加します。 hammer medium create \ --name med_name \ --path path_to_medium |
|
| パーティションテーブルを追加します。 hammer partition-table create \ --name tab_name \ --path path_to_file \ --os-family os_family |
|
| プロビジョニングテンプレートを追加します。 hammer template create \ --name tmp_name \ --file path_to_template |
|
| オペレーティングシステムを追加します。 hammer os create \ --name os_name \ --version version_num |
10.5. アクティベーションキー
| サブコマンド | 説明およびタスク |
|---|---|
|
| アクティベーションキーを作成します。 hammer activation-key create \ --name ak_name \ --content-view cv_n \ --lifecycle-environment lc_name サブスクリプションをアクティベーションキーに追加します。 hammer activation-key add-subscription \ --id ak_ID \ --subscription-id sub_ID |
10.6. ユーザーおよびパーミッション
| サブコマンド | 説明およびタスク |
|---|---|
|
| ユーザーを作成します。 hammer user create \ --login user_name \ --mail user_mail \ --auth-source-id 1 \ --organization-ids org_ID1,org_ID2,... ユーザーにロールを追加します。 hammer user add-role \ --id user_id \ --role role_name |
|
| ユーザーグループを作成します。 hammer user-group create \ --name ug_name ユーザーグループにロールを追加します。 hammer user-group add-role \ --id ug_id \ --role role_name |
|
| ロールを作成します。 hammer role create \ --name role_name |
|
| フィルターを作成し、ロールに追加します。 hammer filter create \ --role role_name \ --permission-ids perm_ID1,perm_ID2,... |
10.7. エラータ
| サブコマンド | 説明およびタスク |
|---|---|
|
| エラータをリスト表示します。 hammer erratum list CVE でエラータを検索します。 hammer erratum list --cve CVE エラータを確認します。 hammer erratum info --id err_ID |
|
| ホストに適用可能なエラータをリスト表示します。 hammer host errata list \ --host host_name エラータをホストに適用します。 hammer host errata apply \ --host host_name \ --errata-ids err_ID1,err_ID2,... |
10.8. ホスト
| サブコマンド | 説明およびタスク |
|---|---|
|
| ホストグループを作成します。 アクティベーションキーをホストグループに追加します。 hammer hostgroup set-parameter \ --hostgroup "hg_name" \ --name "kt_activation_keys" \ --value key_name |
|
| (ホストグループからパラメーターを継承する) ホストを作成します。 ホストグループからホストを削除します。 hammer host update --name host_name --hostgroup NIL |
|
| リモート実行にジョブテンプレートを追加します。 hammer job-template create \ --file path \ --name template_name \ --provider-type SSH \ --job-category category_name |
|
| リモートジョブを開始します。 hammer job-invocation create \ --job-template template_name \ --inputs key1=value,... \ --search-query query リモートジョブを監視します。 hammer job-invocation output \ --id job_id --host host_name |
10.9. タスク
| サブコマンド | 説明およびタスク |
|---|---|
|
| 全タスクをリスト表示します。 hammer task list Monitor progress of a running task: hammer task progress \ --id task_ID |
第11章 Hammer のリファレンス
Hammer ステートメントの使用法を確認できます。
このリファレンスは、Satellite 6.16 用にリリースされた Hammer コンポーネントのバージョンに合わせて最新になっています。
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}