Ansible を使用してエージェントをインストールする


目的

各ホストに手作業で VM エージェントをインストールするには多大な工数が必要です。 また、手順の実行時にミスが発生する可能性があります。

このような悩みを解決するために、VM エージェントのインストール手順を自動化する Ansible Playbook をご用意しました。 この Playbook を実行するだけで VM エージェントのインストールを自動的に完了できます。 ぜひご利用ください。

Ansible とは

Ansible とは、オープンソースの構成管理ツールの一種です。次の特徴を持ちます。

  • エージェントレスのため、ホストに追加でインストールするソフトウェアは不要です。(ssh 経由での接続は必要)
  • Playbook と呼ばれる処理内容を記述したファイルを実行することによって、同じ処理を異なるホスト上で実行可能です。
  • ファイル形式は YAML のため、容易に記述できます。

前提条件

  • Ansible のコントロールノードからエージェントをインストールするノード (以下「ホスト」といいます。) へ SSH 接続が可能であること。
  • ホストにおいて root 権限で操作可能なユーザが存在すること。
  • ホストで Python 2 (2.6 以上) または Python3 (3.5 以上) が使用可能であること。
  • ホストから VM サーバに対して HTTP (HTTPS) でアクセス可能であること (Proxy 経由可)
  • ホストから www.softek.co.jp へ HTTPS でアクセス可能であること。(Proxy 経由可)
  • エージェントのディストリビューションが次のいずれかであること。
    • Amazon Linux 2
    • Red Hat Enterprise Linux 6/7
    • CentOS 6/7
    • Ubuntu 14.04 LTS/16.04 LTS/18.04 LTS

エージェントをインストールする

  1. ダウンロードページをブラウザで開きます。
  2. 「SIDfm VM サブスクリプション契約約款」および「ソフトウェア使用許諾契約書」に同意し、チェックを入れたあと「ダウンロードページ」をクリックします。

  3. エージェントインストール用の Playbook のアーカイブファイルをダウンロードします。

  4. Ansible のコントロールノードへ Playbook のアーカイブファイルを配置します。

    $ ls
    ansible_playbook_for_sidfmvm_agent_installation_1.0-2.tar.gz
  5. 以下のコマンドを実行して Playbook アーカイブファイルを展開します。

    $ tar xvf ansible_playbook_for_sidfmvm_agent_installation_1.0-2.tar.gz
    ansible_playbook_for_sidfmvm_agent_installation.yml
    check_variables.yml
    debian.yml
    hosts
    redhat.yml
    register_host.yml
    set_proxy_and_install_packages_debian.yml
    set_proxy_and_install_packages_redhat.yml

    展開されたファイルの中で重要なファイルは次の二つです。

    • hosts

      管理対象となるホストやホストグループを定義するファイルです。 インベントリファイルと呼ばれます。 VM サーバの URL やホスト登録用 API キーなど、お客様の環境に依存する設定もこのファイル内に記載します。

      なおネットワークに存在する全てのホストやデバイスをこのファイルに記載する必要はありません。 (あくまでも Ansible の操作対象の特定に利用するためです。)

    • ansible_playbook_for_sidfmvm_agent_installation.yml

      エージェントのインストールに必要な一連のタスクを記述したファイルです。 エージェントをインストールしたいホストは、このファイルの「hosts」項目に指定して下さい。 ただし「hosts」項目に指定するホストは前記の hosts ファイルで定義されている必要があります。

  6. エディタで hosts を開きます。

    $ vi hosts
  7. VM サーバの URL を指定します。(ここでは VM サーバの URL を http://vmserver.example.co.jp

    としています。実際に設定する際には適切な値を設定してください。)
    vm_server_url=http://vmserver.example.co.jp
  8. ホスト登録用 API キーを設定します。(ここではホスト登録用 API キーを xxxyyyzzz としています。実際に設定する際には適切な値を設定してください。)

    register_apikey_value=xxxyyyzzz

    ホスト登録用 API キーはライセンス設定画面で発行する必要があります。ホスト登録用 API キーの発行方法は「ホスト登録用 API キーを発行する」を参照してください。なお、ホスト登録が必要な時にだけ発行し、通常運用時には削除する運用を推奨しています。 これは、このホスト登録用 API キーがあれば、自由にホスト登録が可能となるため、意図しないホストの登録が行われる可能性があるためです。

  9. yum や apt コマンドでパッケージを取得する際に Proxy 経由でアクセスする場合は、 http(s)_proxy_for_pkg パラメータに Proxy サーバの URL を設定します。 (ここでは HTTP Proxy を http://proxy.example.co.jp:3001 としています。実際に設定する際には適切な値を設定してください。)

    [HTTP Proxy が不必要な場合]

    # Proxy for yum/apt
    http_proxy_for_pkg=
    http_proxy_for_pkg=

    [HTTP Proxy が必要な場合]

    # Proxy for yum/apt
    http_proxy_for_pkg=http://proxy.example.co.jp:3001
    http_proxy_for_pkg=http://proxy.example.co.jp:3001
  10. VM サーバとホストの通信に 必要な場合、HTTP Proxy を設定します。 (ここでは HTTP Proxy を proxy.example.com:8080 としています。実際に設定する際には適切な値を設定してください。)

    [HTTP Proxy が不必要な場合]

    # Proxy for SIDfmVM Agent
    http_proxy_for_vmagent=
    https_proxy_for_vmagent=

    [HTTP Proxyが必要な場合(HTTP/HTTPSが同一の設定、認証無し)]

    # Proxy for SIDfmVM Agent
    http_proxy_for_vmagent=proxy.example.com:8080
    https_proxy_for_vmagent=proxy.example.com:8080

    [HTTP Proxyが必要な場合(HTTP/HTTPSが異なる設定、認証無し)]

    # Proxy for SIDfmVM Agent
    http_proxy_for_vmagent=http.proxy.example.com:8080
    https_proxy_for_vmagent=https.proxy.example.com:8080

    [HTTP Proxyが必要な場合(HTTP/HTTPSが同一の設定、認証有)]

    # Proxy for SIDfmVM Agent
    http_proxy_for_vmagent=user:pass@proxy.example.com:8080
    https_proxy_for_vmagent=user:pass@proxy.example.com:8080
  11. グループを作成します。(設定する際には適切な値を設定してください。)

    [example_group]
  12. グループにホストを追加します。(設定する際には適切な値を設定してください。)

    [example_group]
    host0
    host1
    host2
  13. 必要な場合、SIDfm VM に登録するホスト名を明示的に指定します。

    [example_group]
    host0
    host1
    host2 hostname_on_the_vmserver=host2.example.co.jp

    ※ なおこの hostname_on_the_vmserver 変数は、SIDfm VM に登録するホスト名を明示的に指定するためにのみ使用されるものであり、 Playbook (ansible_playbook_for_sidfmvm_agent_installation.yml) の「hosts」項目から参照される名前ではないことにご注意ください。

  14. 保存後、閉じます。

    編集後の hosts ファイル:

    [all:vars]
    # SIDfmVM Server URL
    vm_server_url=http://vmserver.example.co.jp
     
    # Register API Key
    register_apikey_value=xxxyyyzzz
     
    # Proxy for yum/apt
    http_proxy_for_pkg=http://proxy.example.co.jp:3001
    https_proxy_for_pkg=https://proxy.example.co.jp:3001
     
    # Proxy for SIDfmVM Agent
    http_proxy_for_vmagent=
    https_proxy_for_vmagent=
     
    [example_group]
    host0
    host1
    host2 hostname_on_the_vmserver=host2.example.co.jp
  15. エディタで ansible_playbook_for_sidfmvm_agent_installation.yml を開きます。

    $ vi ansible_playbook_for_sidfmvm_agent_installation.yml
  16. hosts 項目に先程の hosts ファイルで定義したホスト名あるいはグループ名を設定します。

    [編集後の ansible_playbook_for_sidfmvm_agent_installation.yml]

    - name: Install SIDfm VM Agent
      hosts:
        - host0
        - host1
        - host2
      become: true

    保存して閉じます。

  17. Playbook を実行します。

    -u オプションの引数 <user> には、ホストへ接続する実際のユーザを指定してください。 (なおこの <user> は、root 権限でのコマンド実行が許可されている必要があります。)

    $ ansible-playbook -i hosts -u <user> ansible_playbook_for_sidfmvm_agent_installation.yml

    状態が Failed になった場合は、何らかの原因で処理に失敗しています。トラブルシューティングを参照の上、原因を修正し、再度 Playbook を実行してください。

インストール後に行う作業

エージェントのインストール作業が終わりましたら、VM にログインしホスト登録の確認、並びに、同期の確認を行います。

ホストが正常に登録されているか確認する

Web ブラウザーを起動し SIDfm VM のログインページにアクセスします。

  1. Web プラウザを起動します。
  2. http://<VM サーバのホスト名>/redmine/ にアクセスします。
  3. ログイン ID とパスワードを入力し、「ログイン」をクリックします。
  4. 設定メニューの「ホスト設定」をクリックします。
  5. 登録ホスト一覧の中にインストールしたホストが登録されているか確認します。

ホストと SIDfmAPI との同期を確認する

登録ホストが「」になっているか確認します。同期ボタンにカーソルを合わせるとVM エージェントからのデータ受信日時、脆弱性照合日時を確認することができます。

2 日以内に SIDfmAPI との脆弱性照合 (同期) を行っている
  • 最後に脆弱性照合 (同期) してから 2 日経過している
  • 同期待機中 : 登録してからまだ最初の脆弱性照合 (同期) が行われていない、システムカテゴリが割り当てられていない
  • 同期無効 : 何らかの問題で脆弱性照合 (同期) がされない状態

ホスト登録用 API キーを削除する

エージェントによりホスト登録を終了する場合、ホスト登録用 API キーの不正使用や意図しないホストの登録を防止するため、ホスト登録用 API キーはホスト登録作業後、削除してください。ホスト登録用 API キーの削除方法については「ホスト登録用 API キーを削除する」を参照してください。

トラブルシューティング

ホストへの接続に失敗する

ホストへの接続に失敗する場合は、次の 2 点を確認してください。

  1. コントロールノードからホストへ ssh 経由でアクセス可能
  2. インベントリファイル (hosts ファイル) で定義されているホスト名が正しいこと

Connection timed out が発生し、ホストへの接続に失敗した際には、下記のエラーが出力されます。

Connection timed out による接続失敗例

TASK [Gathering Facts] *********************************************************
fatal: [host0]: UNREACHABLE! => {
    "changed": false, 
    "msg": "Failed to connect to the host via ssh: ssh: connect to host host0 port 22: Connection timed out", 
    "unreachable": true
}

前記の 2 項目をチェック後、 ping モジュールを利用し、当該ホスト (この例では host0) への接続テストを実施してください。

ping モジュールによる接続テスト - 接続失敗例

$ ansible -i hosts -m ping host0
host0 | UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: ssh: connect to host host0 port 22: No route to host",
    "unreachable": true
}

ping モジュールによる接続テスト - 接続成功例

$ ansible -i hosts -m ping host0
host0 | SUCCESS => {
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python3"
    },
    "changed": false,
    "ping": "pong"
}

hosts ファイルの解析に失敗する

hosts ファイルに文法エラーが発生し、解析に失敗した場合は次の警告が出力されます。

文法エラーによる警告メッセージ

$ ansible-playbook -i hosts -u <user> ansible_playbook_for_sidfmvm_agent_installation.yml
 [WARNING]:  * Failed to parse /path/to/hosts with yaml plugin: Syntax Error while
loading YAML.   (...)
 [WARNING]:  * Failed to parse /path/to/hosts with ini plugin: host range must be
begin:end or begin:end:step
 [WARNING]: Unable to parse /path/to/hosts as an inventory source
 [WARNING]: No inventory was parsed, only implicit localhost is available
 [WARNING]: provided hosts list is empty, only localhost is available. Note
that the implicit localhost does not match 'all'
 [WARNING]: Could not match supplied host pattern, ignoring: host0

ansible-playbook コマンドの実行時に --syntax-check オプションを追加し、文法チェックを実施してください。 (なお --syntax-check オプション指定時には文法チェックのみ行なわれ、制御対象ノードでの操作は実施されません。)

--syntax-check オプションによる文法チェック

$ ansible-playbook --syntax-check -i hosts -u <user> ansible_playbook_for_sidfmvm_agent_installation.yml
 
playbook: ansible_playbook_for_sidfmvm_agent_installation.yml

Red Hat 系/ Debian 系以外のディストリビューションに対してエージェントのインストールを試行

TASK [check of family] *********************************************************
fatal: [host0]: FAILED! => {
    "changed": false, 
    "msg": "This OS family is not supported."
}

残念ながらこの Playbook は、Red Hat 系/ Debian 系以外のディストリビューションはサポートしておりません。 エージェントのインストール手順 を参照し、 手動でエージェントをインストールしてください。

未定義のホストやグループを ansible_playbook_for_sidfmvm_agent_installation.yml の hosts 項目に指定している

下記の例では、ansible_playbook_for_sidfmvm_agent_installation.yml の hosts 項目に hostxxxxyyyy を指定しているにもかかわらず、 hosts ファイル内でそのホスト名 (あるいはグループ名) が存在しないため、ホスト hostxxxxyyyy が無視されています。

hosts ファイルにホスト名/グループ名を追加するか、ansible_playbook_for_sidfmvm_agent_installation.yml の hosts 項目に hosts ファイルに 存在するホスト名/グループ名してください。

host パターンの不一致による警告メッセージ

$ ansible-playbook -i hosts -u <user> ansible_playbook_for_sidfmvm_agent_installation.yml
 [WARNING]: Could not match supplied host pattern, ignoring: hostxxxxyyyy

既に登録済みのホストに対し、再びエージェントのインストールを試みた

特に問題はございませんが、ansible_playbook_for_sidfmvm_agent_installation.yml の hosts 項目から当該ホストを削除することで、 エラーは表示されなくなります。

TASK [check host api key] ******************************************************
fatal: [host0]: FAILED! => {
    "changed": false, 
    "msg": "The host is already registered."
}

必要なパッケージのインストールに失敗する

yum install (Red Hat 系) や apt-get update/apt-get install (Debian 系) コマンドの実行に失敗し、 VM エージェントに必要なパッケージをインストールできない状態です。 次のような原因が考えられます。

  1. Proxy が必要な環境下で Proxy を設定していない
  2. ホストが隔離されたネットワーク環境下にあり、Proxy 経由を含め外部への HTTP/HTTPS 接続が許可されていない

1. の原因が疑われる場合は、hosts ファイルを編集し、Proxy 設定を行ってください。

2. の場合、この Playbook による VM エージェントのインストールはできません。 エージェントのインストール手順 (4. オフライン・データファイルによる登録) を参照し、オフラインでのホスト情報の登録を行ってください。

apt-get update コマンド失敗時のエラーメッセージ (Debian 系)

TASK [apt update] **************************************************************
fatal: [host0]: FAILED! => {
    "changed": false, 
    "msg": "Failed to update apt cache: "
}

エージェントパッケージ (rpm, deb) のダウンロードに失敗する

次のような原因が考えられます。

  1. Proxy が必要な環境下で Proxy を設定していない
  2. 存在しないエージェントパッケージ (rpm, deb) のダウンロードを試みている

1. の原因が疑われる場合は、hosts ファイルを編集し、Proxy 設定を行ってください。

2. の場合、 ダウンロードページ から Playbook アーカイブを再取得してください。

存在しないエージェントパッケージ (deb) のダウンロードを試行した際のエラーメッセージ

TASK [get sidfm vm agent deb package] ******************************************
fatal: [host0]: FAILED! => {
    "changed": false, 
    "dest": "/opt/softek/tmp/sidfm-vm-agent_1.1-9_all.deb", 
    "elapsed": 0, 
    "msg": "Request failed", 
    "response": "HTTP Error 404: Not Found", 
    "status_code": 404, 
    "url": "https://www.softek.co.jp/SID/support/sidfmvm/download/agent/sidfm-vm-agent_1.1-9_all.deb"
}

VM サーバへの接続に失敗する

hosts ファイルの vm_server_url の項目が正しいかどうか確認してください。

VM サーバへの接続失敗時のエラーメッセージ

TASK [register host] ***********************************************************
fatal: [host0]: FAILED! => {
    "changed": true, 
    "cmd": "/opt/softek/bin/vm_agent.sh", 
    "delta": "0:00:00.233123", 
    "end": "2019-09-18 02:28:44.113906", 
    "msg": "non-zero return code", 
    "rc": 1, 
    "start": "2019-09-18 02:28:43.880783", 
    "stderr": "/opt/softek/bin/sidfm_vm_unix_agent.rb:232:in `register': cannot access api (RuntimeError)...
    (略)
}

登録用 API キーが正しくない

ライセンス設定画面でホスト登録用 API キーを参照し、 hosts ファイルの register_apikey_value 項目と 一致しているかどうかを確認してください。 ホスト登録用 API キーの参照方法は「 ホスト登録用 API キーを発行する 」をご覧ください。

指定した登録用 API キーでのホスト登録に失敗した際のエラーメッセージ

TASK [check result] ************************************************************
fatal: [host0]: FAILED! => {
    "changed": false, 
    "msg": "The Register API Key is invalid."
}

SELinux 有効時に下記のエラーが発生

ホスト上で SELinux が有効な場合、Ansible の copy/file/template 関連の操作を行なうには libselinux-python が必要です。

SELinux が有効かつ libselinux-python が存在しない場合のエラーメッセージ (Red Hat 系)

TASK [add http_proxy settings] *************************************************
fatal: [host0]: FAILED! => {
    "changed": false, 
    "msg": "Aborting, target uses selinux but python bindings (libselinux-python) aren't installed!"
}

libselinux-python パッケージをインストールしてください。

# yum install libselinux-python
  あるいは
# dnf install libselinux-python