第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 で直接通信するスクリプトではバインドを確立するのは一度で済みます。詳しい情報は『 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/cli.modules.d/foreman.yml の hammer 設定ファイルに保存します。

セッションの使用方法は以下のようになります。

  • セッションを有効にするには、: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-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'
重要

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

1.2.3. コマンドライン

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

$ hammer -u username -p password subcommands
注記

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

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

Satellite Server がインストールされていないホストに、hammer をインストールして、リモートの Satellite への接続に使用できます。

前提条件

  • Satellite Server または Capsule Server にホストを登録しておく。詳細は、『プロビジョニングガイド』の「ホストの登録」を参照してください。
  • Satellite Server または Capsule Server で以下のリポジトリーを同期しておく。詳細は、『コンテンツ管理ガイド』の「Red Hat リポジトリーの同期」を参照してください。

    • rhel-7-server-rpms
    • rhel-server-rhscl-7-rpms
    • rhel-7-server-satellite-tools-6.7-rpms

手順

ホストで、以下の手順を実行して hammer をインストールします。

  1. Red Hat Enterprise Linux、Red Hat Software Collections および Red Hat Satellite Tools 6.7 の各リポジトリーを有効にします。

    # subscription-manager repos --enable=rhel-7-server-rpms \
    --enable=rhel-server-rhscl-7-rpms \
    --enable=rhel-7-server-satellite-tools-6.7-rpms
  2. hammer をインストールします。

    # yum install tfm-rubygem-hammer_cli_katello
  3. Satellite の IP アドレスまたは FQDN を含めるように、/etc/hammer/cli.modules.d/foreman.yml ファイルの :host: エントリーを編集します。

    :host: 'https://satellite.example.com'

1.4. デフォルトの組織およびロケーションの設定

hammer コマンドの多くは、組織固有のものです。--organization および --location オプションで毎回指定する必要がないように、hammer コマンドにデフォルトの組織とロケーションを設定できます。

組織 を 1 つ管理することが多い場合には、入力するコマンドが短くなるので、デフォルトの組織を指定すると便利です。ただし、別の組織に切り替える場合には、hammer コマンドを使用して、--organization オプションで切り替える組織を指定します。

手順

デフォルトの組織と場所を設定するには、次の手順を実行します。

  1. デフォルトの組織を設定するには、以下のコマンドを入力します。

    # hammer defaults add --param-name organization \
    --param-value "Your_Organization"

    hammer organization list コマンドを使用して、組織の名前を検索します。

  2. オプション: デフォルトのロケーションを設定するには、以下のコマンドを入力します。

    # hammer defaults add --param-name location \
    --param-value 'Your_Location"

    hammer location list コマンドを使用して、ロケーションの名前を検索します。

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

    # hammer defaults list

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: 30

この設定は、--per-page Hammer オプションと同等です。

1.6. Hammer ロギングの設定

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

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

注記

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

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

    # hammer admin logging --all --level-debug
    # satellite-maintain service restart
  • 実稼動レベルのロギングを設定するには、以下のコマンドを使用します。

    # hammer admin logging --all --level-production
    # satellite-maintain 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 ループで使用する必要がある場合などに便利です。

--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 コマンドの使用時には、出力からヘッダーを隠すオプションがあります。カスタムスクリプトでパイプを使用するまたは出力を使用する場合は、出力の非表示が便利です。

  • ヘッダー出力を隠すには、--no-headers オプションを hammer コマンドに追加します。

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

hammer ping コマンドを使用して、コアの Satellite サービスのステータスを確認できます。satellite-maintain 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