第1章 Hammer の概要

Hammer は、Red Hat Satellite 6 で提供される強力なコマンドラインツールです。Hammer を使用して、CLI コマンド、またはシェルスクリプトによる自動化により、Red Hat Satellite Server を設定/管理することができます。Hammer は対話式のシェルも提供します。

Hammer と Satellite Web UI の比較

Web UI を使用した移動と比較すると、Hammer を使用する場合には環境変数やエイリアスなどのシェル機能が自由に使えるため、Satellite Server との対話がはるかに速くなります。また、Hammer のコマンドを再利用可能なスクリプトに組み込み、あらゆるレベルで複雑なタスクを自動化することもできます。Hammer コマンドからの出力を他のツールにリダイレクトして、既存の環境と統合することができます。Hammer コマンドは、Red Hat Satellite を実行するベースのオペレーティングシステムに直接発行することができます。

Hammer コマンドを発行するには、Satellite Server のベースのオペレーティングシステムにアクセスする必要があるため、Web UI と比較すると、潜在的なユーザー数が限定されてしまいます。Hammer と Web UI の違いはほぼありませんが、Web UI の開発の優先度は高く、特に新しく導入される機能についてはこちらが」優勢となっています。

Hammer と Satellite API の比較

多くのタスクで、Hammer も Satellite API も同等に利用可能です。Hammer は、スクリプトに適用する前に API の呼び出しの応答をテストするなど、Satellite API よりも使いやすいインターフェースとして利用できます (hammer -d organization list など、Hammer で発行した API の呼び出しを検査するには -d オプションを使用します)。API での変更は自動的に Hammer に適用されますが、API を直接使用するスクリプトは手動で更新する必要があります。

バックグラウンドで、各 Hammer コマンドは最初に API へのバインドを確立し、要求を送信します。大量の Hammer コマンドを順番に実行する場合には、パフォーマンスに影響が出る可能性があります。反対に、API で直接通信するスクリプトではバインドを確立するのは一度で済みます。詳しい情報は『Red Hat Satellite API ガイド』を参照してください。

1.1. ヘルプ

hammer オプションおよびサブコマンドの完全な一覧を表示するには以下を実行します。 

$ hammer --help

以下のように --help を使用してサブコマンドを確認します。 

$ hammer organization --help

以下のように grep を使用して help の出力を検索するか、テキストビューワーにリダイレクトすることができます。 

$ hammer | less

1.2. 認証

hammer コマンドを使用する場合は Red Hat Satellite に ID を証明する必要があります。hammer コマンドは手動または自動で実行できます。いずれの場合も、認証には Satellite 認証情報が必要です。hammer 認証には 3 つの方法があります。

  • Hammer 認証セッション
  • hammer 設定ファイルに認証情報を保存
  • hammer コマンドを使用するたびに認証情報を指定

自動でコマンドを実行する場合は、hammer 設定ファイルを使用することが推奨されます。たとえば、cron ジョブから Satellite メンテナンスコマンドを実行する場合です。コマンドを手動で実行する場合は、hammer 認証セッションを使用して、コマンドを実行するたびに認証情報を提供する方法が推奨されます。

1.2.1. 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

    セッションを有効にすると、設定ファイルに保存している認証情報は無視されます。

  • セッションを開始するには、以下のコマンドを入力します。 

    # hammer auth login

    Satellite 認証情報が求められ、ログインします。その認証情報は、セッションの有効期限が切れるまで持続するため、再要求はされません。

  • セッションのデフォルトの長さは 60 分ですが、自由に変更できます。たとえば、30 分に変更するには、以下のコマンドを使用します。 

    # hammer settings set --name idle_timeout --value 30
Setting [idle_timeout] updated to [30]

  • セッションの現在のステータスを表示するには、以下のコマンドを実行します。 

    # hammer auth status

  • セッションを終了するには、以下のコマンドを入力します。 

    # hammer auth logout

1.2.2. Hammer 設定ファイル

--foreman-admin-username オプションおよび --foreman-admin-password オプションを使用して Satellite のインストールを実行すると、入力した認証情報が ~/.hammer/cli.modules.d/foreman.yml に保存され、hammer により認証情報の入力が求められます。

認証情報は、手動で ~/.hammer/cli.modules.d/foreman.yml 設定ファイルに追加することもできます。 

:foreman:
 :username: 'username'
 :password: 'password'
重要

hammer 設定ファイルのインデントには、スペースのみを使用するようにしてください。タブは使用しないでください。

1.2.3. コマンドライン

Satellite 認証情報を ~/.hammer/cli.modules.d/foreman.yml 設定ファイルに保存しないと、コマンドを入力するたびに hammer によって認証情報が求められます。以下のように、コマンドの実行時に認証情報を指定できます。 

$ hammer -u username -p password subcommands
注記

本ガイドの例は、設定ファイルの認証情報が保存されているか、hammer 認証セッションを使用していることを前提としています。

1.3. Hammer のスタンドアロンでの使用

Satellite がインストールされていないサーバーに hammer を別途インストールして、そのサーバーをリモートの Satellite と接続して使用することができます。

このパッケージのインストールには rhel-X-server-satellite-6.X-rpms リポジトリーが必要です。接続にワークステーションを使用するには、リポジトリーを手動でインストールする必要があります。詳しい情報は『インストールガイド』の「パッケージを手動でダウンロード」を参照してください。

  1. hammer をインストールします。 

    # yum install tfm-rubygem-hammer_cli_katello
  2. 適切な Satellite を参照するように /etc/hammer/cli.modules.d/foreman.yml を編集します。

1.4. デフォルトの組織の設定

多くの hammer コマンドは組織固有のものです。--organization パラメーターや --organization-id パラメーターを毎回指定しなくてもよいように、hammer コマンドにデフォルトの組織を設定できます。デフォルトの組織を設定するには、以下のいずれかのコマンドを使用します。 

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

hammer organization list コマンドの出力で org_ID を確認します。

同様に、名前または ID を指定して、デフォルトのロケーションを設定します。以下のいずれかのコマンドを実行します。 

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

現在指定しているデフォルトの設定を表示するには、以下のコマンドを実行します。 

$ hammer defaults list

1 つの組織を管理することが多い場合には、デフォルトの組織を指定するとコマンドを省略できるので便利です。ただし、別の組織に切り替える場合には、コマンドラインオプションを使用して指定する必要があります。本ガイドの例は、デフォルトの組織を指定していないことを前提としており、「Hammer コマンドで組織の特定」のように、シェル変数のアプローチを使用します。

1.5. 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
注記

多くの CLI モジュールの設定を読み込むと、hammer コマンドの実行の速度が遅くなる可能性があります。このような場合に、あまり使用しない CLI モジュールを無効化することを検討してください。

「認証」に記載されているような認証情報を保存する以外に、~/.hammer/ 設定ディレクトリーに他の複数のオプションを設定できます。たとえば、~/.hammer/cli_config.yml でデフォルトのログレベルを変更して、以下のディレクティブを使用してログのローテーションを設定することができます。これらのディレクティブは、現在のユーザーにのみ影響を及ぼし、グローバルには適用されない点に注意してください。 

:log_level: 'warning'
:log_size: 5 #in MB

同様に、hammer の出力で一度に表示される行数を設定できます (--per-page オプションと同等)。 

:per-page: 30

1.6. Hammer ロギングの設定

hammer を設定して、さまざまな Satellite コンポーネントのデバッグ情報をロギングすることができます。

全 Satellite コンポーネントに対してデバッグまたは通常の設定オプションを設定できます。

注記

hammer のロギング動作を変更したら、Satellite サービスを再起動する必要があります。 

# katello-service restart

  • 全コンポーネントのデバッグレベルを設定するには、以下のコマンドを使用します。 

    # hammer admin logging --all --level-debug
# katello-service restart

  • 実稼動レベルのロギングを設定するには、以下のコマンドを使用します。 

    # hammer admin logging --all --level-production
# katello-service restart

  • ロギングが設定可能なコンポーネントで現在認識されているものを表示するには、以下のコマンドを使用します。 

    # hammer admin logging --list

  • 利用可能なロギングオプションを一覧表示するには、以下のコマンドを使用します。 

    # hammer admin logging --help

Usage:
    hammer admin logging [OPTIONS]

1.7. Hammer シェルの呼び出し

対話型シェルで hammer コマンドを発行することができます。このシェルを呼び出すには、以下のコマンドを発行します。 

$ hammer shell

このシェルでは、「hammer」と入力せずに直接サブコマンドを入力できるので、スクリプトで使用する前にコマンドをテストする際に便利です。このシェルを終了するには、exit と入力するか、[Ctrl + D] を押してください。

1.8. フォーマット済みの出力の生成

hammer コマンドのデフォルトの出力形式を変更して、他のコマンドラインツールやアプリケーションでこの出力結果を処理しやすくすることができます。たとえば、CSV 形式で、カスタムの区切り文字を利用して (ここではセミコロンを使用) 組織を表示するには、以下のコマンドを実行します。 

$ hammer --csv --csv-separator ";" organization list

CSV 形式での出力は、ID を解析したり for ループで使用したりする必要がある場合に便利です (例2.6「ACME 組織の全リポジトリーの同期」または例2.8「複数製品への同期プランの割り当て」を参照してください)。

--output オプションには、他に複数のフォーマットオプションがあります。 

$ hammer --output output_format organization list

output_format を、以下のいずれかに置き換えます。

  • table: 人間が判読できる表形式 (デフォルト) で出力を生成します。
  • base: キーと値のペアの形式で出力を生成します。
  • yaml: YAML 形式で出力を生成します。
  • csv: コンマ区切りの値形式で出力を生成します。カスタムの区切り文字を定義するには、代わりに --csv および --csv-separator オプションを使用してください。
  • json: JavaScript Object Notation (JSON) 形式の出力を生成します。
  • silent: 出力を表示しません。

1.9. Hammer でのトラブルシューティング

hammer ping コマンドを使用して、コアの Satellite サービスのステータスを確認することができます。katello-service status コマンドと併用すると、Satellite の問題の診断、トラブルシューティングに役立ちます。すべてのサービスが予想どおりに実行されている場合には、出力は以下のようになります。 

$ 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