Registering a PEM agent ======================= PEMエージェントを使用する前に、PEMサーバーに登録する必要があります。 **PEMサーバーパッケージによってインストールされたPEMエージェントは、サーバーの構成中に自動的に登録されます。** 他のすべてのエージェントの場合、これらの手順に従ってください。 .. Note:: PEMエージェントをアップグレードした後、再起動する必要があります。再度登録する必要はありません。 PEMエージェントを登録する方法 ----------------------------- LinuxおよびWindowsホストでは、PEMエージェントパッケージにはpemworkerと呼ばれるコマンドラインユーティリティが含まれています。これを使用して、 :ref:`pemworkerユーティリティを使用したPEMエージェントの登録 ` を含む管理タスクを実行できます。 Windowsでは、PEMエージェントグラフィカルインストーラーを使用して、インストール時にエージェントを登録できます。この便利なオプションは、pemworkerユーティリティが提供するすべての可能性をサポートしているわけではありません。インストーラーにエージェントを登録したくない場合は、 **Register now** チェックボックスをオフにします。詳細については、 `installation instructions `_ を参照してください。 pemworkerユーティリティを使用したPEMエージェントの登録 ------------------------------------------------------ pemworkerユーティリティは、PEMエージェントとともにインストールされます。これは、 Linuxでは\ ``/usr/edb/pem/agent/bin`` 、 Windowsでは\ ``C:\Program Files\edb\pem\agent-x64\bin`` にあります。 エージェントを登録するには、PEMサーバーのパスワードを設定し、例に示すようにユーティリティを呼び出し、必要に応じてテーブルから関連オプションを追加します。各オプションの後には、対応する値を続けます。 Linux ^^^^^ .. code:: shell export PEM_SERVER_PASSWORD=edb # Running as root pemworker --register-agent Windows ^^^^^^^ .. code:: shell set PEM_SERVER_PASSWORD=edb # Running as admin ./pemworker.exe REGISTER .. csv-table:: :header: Option,Description :widths: 10,30 :align: left :class: longtable `--pem-server`,PEMバックエンドデータベースサーバーのIPアドレス。 `--pem-registration-conn-string`を指定しない限り、このパラメーターは必須です。 `--pem-port`,PEMバックエンドデータベースサーバーのポート。デフォルト値は`5432`です。 `--pem-user`,pem_adminロールとPEMバックエンドデータベースサーバーに`rolcreaterole`フラグが設定されているデータベースユーザーまたはスーパーユーザーの名前。`--pem-agent-user`またはエージェント接続文字列を介して既存のユーザーを指定する場合、後者は必要ありません。このユーザーはPEMサーバーに接続し、エージェント登録を実行するために使用されます。 `--pem-registration-conn-string`を指定しない限り、このパラメーターは必須です。 `--pem-agent-user`,PEMバックエンドデータベースサーバー上のデータベースユーザーの名前。登録後、エージェントはこのユーザーを使用してPEMデータベースサーバーへの接続を開き、プローブデータの書き込み、アラートの評価などを行います。このパラメーターはオプショナル。省略すると、エージェントは登録時に作成された`agent`という名前の新しいユーザーを使用して接続します。``はエージェントIDです。 `--pem-ssl-mode`,使用するPEMエージェントユーザーの :ref:`Deciding on an SSL model` 上記を参照してください。使用可能な値は`prefer`、`require`、`disable`、`verify-CA`、および`verify-full`です。デフォルト値は`require`です。 `--pem-registration-conn-string`,登録中にPEMサーバーに接続するために使用される接続文字列。 :ref:`接続文字列を使用する<接続文字列を使用する>` を参照してください。 `--cert-path`,証明書を保存するディレクトリへの完全なパス。パスを提供しない場合、証明書はLinuxでは`~/.pem`、 Windowsでは`%APPDATA%/pem`で作成されます。 `--config-dir`,構成ファイルのディレクトリパス。デフォルトは`/../etc`です。 `--display-name`,PEMブラウザツリーに表示されるエージェントのわかりやすい名前。デフォルトはホストの完全修飾ドメイン名FQDNであり、このオプションが設定されていない場合はホスト名にフォールバックします。 `--force-registration`,`force-registration`句を含めて、指定された引数でエージェントを登録します。この句は、既存のエージェント構成をオーバーライドする場合に役立ちます。デフォルト値は`Yes`です。 `--group`,エージェントを配置するグループの名前。このパラメーターはオプショナル。省略すると、エージェントはグループに配置されません。 `--team`,PEMバックエンドデータベースサーバー上のデータベースロールの名前。このエージェントへのアクセスは、名前付けたロール、所有者、およびpem_super_adminロールのみに制限されています。このパラメーターはオプショナル。省略すると、チームは割り当てられず、すべてのユーザーがこのエージェントにアクセスできます。 `--owner`,PEMバックエンドデータベースサーバー上のデータベースユーザーの名前。このユーザーは、エージェントの所有者として割り当てられます。省略すると、指定された`pem-user`が所有者として割り当てられます。 `--cluster-name`,エージェントオブジェクトを追加するオブジェクトエクスプローラーでクラスター名前を指定します。クラスターが存在しない場合、自動的に作成されます。このパラメーターはオプショナル。 `--profile-id`,このエージェントに割り当てる既存のエージェントプロファイルのIDを指定します。オプショナル。 `--profile-name`,このエージェントに割り当てる既存のエージェントプロファイルの名前を指定します。このパラメーターはオプショナルであり、設定されている場合 `--profile-id`によってオーバーライドされます。 `--allow_server_restart`,PEMが監視対象サーバーを再起動できます。デフォルト値は`True`です。 `--allow-batch-probes`,PEMがこのエージェントでバッチプローブを実行できるようにします。デフォルト値は`False`です。 `--batch-script-user`,バッチ/シェルスクリプトの実行に使用するオペレーティングシステムユーザー。デフォルト値はnoneです。このパラメーターを空白のままにするか、指定されたユーザーが存在しない場合、スクリプトは実行されません。 `--enable-heartbeat-connection`,PEMエージェントとサーバーの間に専用のハートビート接続を作成して、アクティブステータスを更新します。デフォルト値は`False`です。 `--enable-smtp`,PEMエージェントがPEMサーバーに代わって電子メールを送信できるようにします。デフォルト値は`False`です。 `--enable-snmp`,PEMエージェントがPEMサーバーに代わってSNMPトラップを送信できるようにします。デフォルト値は`False`です。 `--enable-webhook`,PEMエージェントがPEMサーバーに代わってWebhookエンドポイントを呼び出すことができます。デフォルト値は`False`です。 `-o`,構成ファイルオプションをオーバーライドします。使用方法については、次の :ref:`デフォルト構成のオーバーライド-例<デフォルト構成のオーバーライド-例>` を参照してください。 .. Note:: `agent.cfg` ファイルから`pem-agent-user` パラメーターを手動で削除すると、エージェントはデフォルトユーザーを使用して接続しません。 .. Note Allowing the agent to restart the database server:: PEMエージェント監査マネージャー、ログマネージャー、またはチューニングウィザードなどによるデータベースサーバーの再起動が必要なPEMの機能を使用する場合、 `agent.cfg` ファイルで`allow_server_restart` の値を`true` に設定するか、システムを再起動する必要があります。サーバーを手動で削除して変更を有効にします。 .. Note Running shell/batch jobs:: エージェントを使用してシェル/バッチジョブを実行する場合、 `batch_script_user` パラメーターにユーザーを指定する必要があります。非rootユーザーを使用してスクリプトを実行することを強くお勧めします。 rootユーザーを使用すると、データセキュリティとオペレーティングシステムのセキュリティが危険にさらされる可能性があります。 pemworkerユーティリティの認証 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PEMデータベースに変更を加える前に、接続はPEMデータベースサーバーで認証されます。 pemworkerユーティリティを呼び出すときに、PEMサーバーの管理ユーザーロールpostgresに関連付けられたパスワードを提供する必要があります。管理パスワードは3つの方法で指定できます。 - ``PEM_SERVER_PASSWORD`` 環境変数を設定します。 - ``PGPASSWORD`` キーワードを使用して、コマンドラインにパスワードを入力します。 - ``.pgpass`` ファイルにエントリーを作成します。 - パスワードまたは暗号化されたパスワードを\ ``--pem-registration-conn-string`` に含めます パスワードを入力しない場合、パスワード認証エラーが発生します。認証が成功すると、その他の不足している必須情報の入力を求められます。登録が完了すると、サーバーはエージェントが正常に登録されたことを確認します。 PEMエージェントサービスを有効にする ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ エージェントは登録されましたが、まだ実行されていません。エージェントの実行を開始し、システムのリブート後も実行されたままであることを確認するには、PEMエージェントサービスを有効にする必要があります。 .. _linux-1: Linux ^^^^^ .. code:: shell systemctl enable --now pemagent .. _windows-1: Windows ^^^^^^^ Windowsサービスマネージャーservices.mscでpemAgentサービスを見つけ、右クリックして **Restart** を選択します。 **Startup Type** が **Automatic** に設定されていることを確認します。 PEMエージェント登録の検証 ------------------------- ``verify-registration`` サブコマンドは、PEM 10.4で導入された診断ユーティリティです。これにより、管理者は、PEMエージェントが適切に登録され、PEMデータベースでアクティブで、PEMサーバーに接続できることを確認できます。 このコマンドは、次のチェックを実行して、エージェントの動作ステータスを検証します。 1. **構成の完全性** ローカル構成に適切な認識可能なエージェントIDが含まれていることを検証します。 2. **安全な接続** ``agent.cfg`` ファイルで構成された証明書ベースの認証を使用して、PEMサーバーへの接続を確立できる機能を検証します。 3. **データベースステータス** エージェントがPEMデータベースに **アクティブ** として登録され、明示的にマークされていることを確認します。 このサブコマンドは、次の場合に特に役立ちます。 - **登録後の検証** 初期登録の直後にエージェントのセットアップを検証します。 - **接続のトラブルシューティング** エージェントとPEMサーバー間の接続の問題の診断。 - **SSL/証明書監査** SSL証明書が適切に構成され有効であることを確認します。 - **ヘルスモニタリング** 自動ヘルスチェックとモニタリングスクリプトでのエージェントステータスの確認。 コマンド構文 ^^^^^^^^^^^^ ``verify-registration`` サブコマンドの構文は、各オペレーティングシステムに固有です。 **Linux** .. code:: shell pemworker --verify-registration [verify-registration-options] **Windows** .. code:: shell pemworker VERIFY-REGISTRATION [verify-registration-options] .. csv-table:: :header: Option,Description :widths: 10,30 :align: left :class: longtable `--config-dir `,エージェント構成ファイル `agent.cfg` が存在するディレクトリパス。指定しない場合、デフォルトの構成ディレクトリが使用されますLinuxの`/usr/edb/pem/agent/etc/`など。 コマンドが実行されると、 ``pemworker`` ユーティリティは4段階の検証プロセスを実行します。 1. **ロード構成** ``agent.cfg`` デフォルトまたは指定されたパスからを読み取り、エージェントIDと接続文字列を取得します。 2. **接続の確立** 登録時に定義された証明書ベースのSSL認証を使用して、PEMデータベースサーバーへの接続を開こうとします。 3. **クエリステータス** ``pem.agent`` システムテーブルに対してチェックを実行して、IDが存在し、ステータスがアクティブに設定されていることを確認します。 4. **レポート結果** 成功または失敗メッセージをコンソールに出力し、特定の終了コードを返します。 終了コードの理解 ^^^^^^^^^^^^^^^^ コマンドは次の終了コードを返します。 .. csv-table:: :header: Code,Status,Description :widths: 12,25,15 :align: left :class: longtable 0,Success,エージェントは登録され、アクティブで、接続されています。 1,Config Error,ローカル構成からの有効なエージェントIDの取得に失敗しました。 2,Connection Error,PEMサーバーへの接続を確立できません。 3,Database Error,エージェントIDが見つかりましたが、PEMデータベースで非アクティブとしてマークされています。 使用例 ^^^^^^ **例1 基本的な検証** デフォルト設定を使用して登録を確認するには **Linux** .. code:: shell pemworker --verify-registration **Windows** .. code:: shell pemworker VERIFY-REGISTRATION **成功した場合の予想出力** .. code:: text Verify registration done successfully. **例2カスタム構成ディレクトリを使用する** デフォルト以外の構成ディレクトリを使用するエージェントを確認するには **Linux** .. code:: shell pemworker --verify-registration --config-dir /opt/custom/pem/agent/etc **Windows** .. code:: shell pemworker VERIFY-REGISTRATION --config-dir "C:\custom\pem\agent\etc" PEMエージェントの登録解除 ------------------------- pemworkerユーティリティを使用して、PEMエージェントの登録を解除できます。エージェントの登録を解除するには、以下の例に示すようにpemworkerユーティリティを呼び出します。 **Linux** .. code:: shell # Running as root pemworker --unregister-agent **Windows** .. code:: shell ./pemworker.exe UNREGISTER-AGENT pemworkerユーティリティを呼び出すときに、コマンド文字列にコマンドラインオプションを追加します。各オプションの後には、対応する値を続けます。 .. csv-table:: :header: Option,Description :widths: 10,30 :align: left :class: longtable `--pem-user `,PEMバックエンドデータベースサーバーのデータベースユーザーpem_adminロールのメンバーの名前。このパラメーターは必須です。 `--config-dir`,"構成ファイルのディレクトリパス。デフォルトは`""/../etc""`です。" 高度な使用法 ------------ 以下は、PEMエージェント登録の詳細なオプションの一部です。 接続文字列を使用する ^^^^^^^^^^^^^^^^^^^^ PEMエージェントがPEMバックエンドデータベースに接続する方法をより詳細に制御するために、接続文字列を指定できます。指定できる接続文字列は、 *registration接続文字列と* agent*接続文字列です。これらの接続文字列は、キー値またはURI形式であり、libpqでサポートされているオプションを含みます。ただし、 ``pem`` にハードコードされた\ ``dbname`` と、 ``read-write`` にハードコードされた\ ``target_session_attrs`` は除きます。 登録接続文字列 ^^^^^^^^^^^^^^ ``--pem-registration-conn-string`` を使用して指定される登録接続文字列は、PEMバックエンドへの「ワンタイム」特権接続に使用され、次のタスクを実行します。 - エージェント登録 –register-agent - エージェント登録解除 –unregister-agent - サーバー登録 –register-server - サーバーの登録解除 –unregister-server 登録文字列は、これらのアクションを実行するために必要な権限を持つユーザーを指定する必要があります、特に - ``pem_admin`` ロール - ``rolcreaterole`` ``--pem-agent-user`` またはエージェント接続文字列を介して既存のユーザーも指定しない限り 下記を参照してください。 登録接続文字列自分自身は保存されないため、これらのタスクのいずれかを実行するために使用する場合は常に入力する必要があります。ホストとポートは、エージェントの登録に使用される接続文字列から抽出され、agent.cfgファイルに保存されるため、エージェントはPEMバックエンドの場所を知ることができます。 環境変数\ ``PEM_REGISTRATION_CONN_STRING`` を使用して登録接続文字列を指定することもできます。優先順位は次のとおりです。 1. コマンドライン引数 –pem-registration-conn-string - 最も高い優先度 2. 環境変数 PEM_REGISTRATION_CONN_STRING 3. 個々のパラメーター –pem-server、–pem-port、–pem-user - 最低優先度 エージェント接続文字列 ^^^^^^^^^^^^^^^^^^^^^^ エージェント接続文字列は、エージェントが進行中のデータ収集などのためにPEMバックエンドに接続するために使用される永続的な接続に使用されます。これはオーバーライドオプションであり、agent.cfgに直接書き込まれるため、\ ``-o agent_connection_string`` を使用して指定する必要があります。 エージェント接続文字列が設定されていない場合、エージェントは\ ``agent.cfg`` ``pem_host`` 、\ ``pem_port`` などの個々のパラメーターまたはWindowsのレジストリを使用して、接続する方法と場所を決定します。 エージェント接続文字列が設定されている場合、これらのパラメーターは無視されます。エージェント登録時にエージェント接続文字列が指定された場合、PEMはエージェント接続のユーザーまたはクライアント証明書を作成しようとしません。接続文字列を指定する場合、指定されたユーザーが存在し、認証可能で、\ ``pem_agent`` ロールがあることを確認する必要があります。 エージェント接続文字列は、\ ``agent.cfg`` またはWindowsのレジストリに保存されます。文字列に\ ``password`` または\ ``sslpassword`` 値が含まれる場合、暗号化され、それぞれカスタムの\ ``pemenc_password`` または\ ``pemenc_sslpassword`` 値に置き換えられます。特殊文字を含むパスワードは、一重引用符で囲まれるキー-値スタイルまたはURLエンコードURIスタイルする必要があります。 環境変数\ ``PEM_AGENT_CONN_STRING`` を使用してエージェント接続文字列を指定することもできます。優先順位は次のとおりです。 1. コマンドライン引数 ``-oagent_conn_string=...`` - 最も高い優先度 2. 環境変数\ ``PEM_AGENT_CONN_STRING`` 3. 構成ファイル/レジストリ ``agent_conn_string`` / ``AGENT_CONN_STRING`` 4. 個々のパラメーター ``pem_host`` 、\ ``pem_port`` 、\ ``pem_ssl_mode`` など - 最低優先度 エージェントIDの設定 ^^^^^^^^^^^^^^^^^^^^ 登録された各PEMエージェントには、一意のエージェントIDが必要です。 :ref:`デフォルト構成のオーバーライド-例 <デフォルト構成のオーバーライド-例>` に示すように、 ``-o`` オプションを使用して値が提供されない限り、値\ ``max(id)+1`` は各エージェントIDに割り当てられます。 デフォルト構成のオーバーライド-例 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``-o`` オプションを使用すると、登録中に設定できないエージェント構成パラメーターLinuxでは\ ``agent.cfg`` およびWindowsでは\ ``HKEY_LOCAL_MACHINE\Software\EnterpriseDB\PEM\agent`` に保存されますをオーバーライドできます。これらの入力は通常のCLIオプションと同じ方法では検証されないため、このオプションは注意して使用する必要があります。パラメーターの完全なリストは :ref:`Modifying agent configuration ` にあります 以下に、\ ``-o`` オプションの使用例をいくつか示します。 .. _エージェントidの設定-1: エージェントIDの設定 ^^^^^^^^^^^^^^^^^^^^ コマンドラインを使用してPEMエージェントを登録します。 ``-o`` オプションを使用して、\ ``agent_id`` 値8を割り当てます。 .. code:: shell # Running as root /usr/edb/pem/agent/bin/pemworker --register-agent \ - -pem-server pemserver \ - -pem-user postgres \ - -pem-port 5432 \ - -display-name agent8 \ - o agent_id=8 __OUTPUT__ Postgres Enterprise Manager Agent registered successfully! 8の\ ``agent_id`` が利用可能なため、PEMエージェントは正常に登録されました。指定されたIDが既存のエージェントによって既に使用されている場合、エラーが発生します。 既存のSSL証明書とキーの提供 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ コマンドラインを使用してPEMエージェントを登録します。既存のSSL証明書とキーファイルを割り当てて、特定のエージェントIDに対して新しい証明書が生成されないようにします。 SSL証明書とキーファイルは、データベースユーザー\ ``agent`` に対して有効である必要があります。\ ```` は、コマンドラインを使用して指定されたものと同じである必要があります。 ``-o`` オプションを使用します。 .. code:: shell # Running as root # List the location of valid SSL certificates and key files. ls -l /root/.pem/agent5.* - rw------- 1 root root 2192 Nov 7 11:27 /root/.pem/agent5.crt - rw------- 1 root root 3244 Nov 7 11:27 /root/.pem/agent5.key # Register the PEM agent using command line. Assign the # SSL certificates and key files using the -o option. /usr/edb/pem/agent/bin/pemworker --register-agent \ - -pem-server pemserver \ - -pem-user postgres \ - -pem-port 5432 \ - -config-dir /tmp/pem-config \ - -display-name agent5 \ - o agent_id=5 \ - o agent_ssl_crt=/root/.pem/agent5.crt \ - o agent_ssl_key=/root/.pem/agent5.key __OUTPUT__ Postgres Enterprise Manager Agent registered successfully! 有効なSSL証明書とキーファイルは、適切な権限を持つ指定された場所で利用できるため、PEMエージェントは正常に登録されます。証明書またはキーファイルが有効でない場合、または適切な権限がない場合、エラーが発生します。 非rootユーザーアカウントを使用してLinuxでPEMエージェントを登録する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 非rootユーザーアカウントを使用してPEMエージェントを登録するには、最初にrootユーザーとしてPEMエージェントをインストールする必要があります。インストール後、edbなどの非rootユーザーのIDを引き継ぎます。次に 1. edbとしてログインします。 ``pem`` および\ ``logs`` ディレクトリを作成し、読み取り、書き込み、および実行権限を割り当てます。 .. code:: shell # Running as nonroot user edb mkdir /home/edb/pem mkdir /home/edb/pem/logs chmod 700 /home/edb/pem chmod 700 /home/edb/pem/logs 2. エージェントをPEMサーバーに登録します。 .. code:: shell export PEM_SERVER_PASSWORD=edb # Use the following command to create agent certificates and an agent # configuration file (`agent.cfg`) in the `/home/edb/pem` directory. /usr/edb/pem/agent/bin/pemworker --register-agent --pem-server <172.19.11.230> --pem-user postgres --pem-port 5432 --display-name non_root_pem_agent --cert-path /home/edb/pem --config-dir /home/edb/pem # Use the following command to assign read and write permissions to # these files: chmod -R 600 /home/edb/pem/agent* 3. ``agent.cfg`` ファイルのパラメーターを変更します。 .. code:: ini vi /home/edb/pem/agent.cfg agent_ssl_key=/home/edb/pem/agent.key agent_ssl_crt=/home/edb/pem/agent.crt log_location=/home/edb/pem/worker.log agent_log_location=/home/edb/pem/agent.log ```` は、割り当てられたPEMエージェントIDです。 4. ``tmp`` ディレクトリを作成し、環境変数を設定して、エージェントを起動します。 .. code:: ini mkdir /home/edb/pem/tmp # Create a script file, add the environment variable, give permissions, and execute: vi /home/edb/pem/run_pemagent.sh #!/bin/bash export TEMP=/home/edb/agent/tmp /usr/edb/pem/agent/bin/pemagent -c /home/edb/agent/agent.cfg chmod a+x /home/edb/pem/run_pemagent.sh cd /home/edb/pem ./run_pemagent.sh これで、PEMエージェントが登録され、edbユーザーで起動されました。マシンが再起動しても、このエージェントは自動的に再起動しません。前述のコマンドを使用して手動で起動する必要があります。 5. オプションで、ルートユーザーとしてこのPEMエージェントのサービスを作成して、次のようにマシンの再起動時にこのエージェントを自動的に起動できます。 a. 構成ファイルパスの値と、\ ``pemagent`` サービスファイルのユーザーをスーパーユーザーとして更新します。 .. code:: ini # Running as superuser sudo vi /usr/lib/systemd/system/pemagent.service [Service] Type=forking WorkingDirectory=/home/edb/pem Environment=LD_LIBRARY_PATH=/usr/edb/pem/agent/lib:/usr/libexec/edb-snmp++/lib Environment=TEMP=/home/edb/pem/tmp ExecStart=/usr/edb/pem/agent/bin/pemagent -c /home/edb/pem/agent.cfg b. 実行中のエージェントプロセスを停止し、エージェントサービスを再起動します。 .. code:: shell # Find the process id of the running pem agent and pem worker process and kill that process ps -ax | grep pemagent kill -9 ps -ax | grep pemworker kill -9 # Enable and start pemagent service sudo systemctl enable pemagent sudo systemctl start pemagent sudo systemctl status pemagent 6. PEMダッシュボードでエージェントのステータスを確認します。 .. Note:: - root権限または別のユーザーたとえば、enterprisedbが所有するファイルへのアクセスを必要とするプローブとジョブは失敗します。 - `agent.cfg` ファイルをデフォルトの場所から別の場所に移動すると、PEMダッシュボードにエージェントステータスが`unknown` として表示される場合があります。詳細については、 :ref:`Troubleshooting agent issues ` を参照してください。