Registering a PEM agent#

PEMエージェントを使用する前に、PEMサーバーに登録する必要があります。 PEMサーバーパッケージによってインストールされたPEMエージェントは、サーバーの構成中に自動的に登録されます。 他のすべてのエージェントの場合、これらの手順に従ってください。

注釈

PEMエージェントをアップグレードした後、再起動する必要があります。再度登録する必要はありません。

PEMエージェントを登録する方法#

LinuxおよびWindowsホストでは、PEMエージェントパッケージにはpemworkerと呼ばれるコマンドラインユーティリティが含まれています。これを使用して、 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#

export PEM_SERVER_PASSWORD=edb

#  Running as root

pemworker --register-agent

Windows#

set PEM_SERVER_PASSWORD=edb

#  Running as admin

./pemworker.exe REGISTER

Option	Description
--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<N>`という名前の新しいユーザーを使用して接続します。`<N>`はエージェントIDです。
--pem-ssl-mode	使用するPEMエージェントユーザーの Deciding on an SSL model 上記を参照してください。使用可能な値は`prefer`、require、disable、verify-CA、および`verify-full`です。デフォルト値は`require`です。
--pem-registration-conn-string	登録中にPEMサーバーに接続するために使用される接続文字列。接続文字列を使用するを参照してください。
--cert-path	証明書を保存するディレクトリへの完全なパス。パスを提供しない場合、証明書はLinuxでは`~/.pem`、 Windowsでは`%APPDATA%/pem`で作成されます。
--config-dir	構成ファイルのディレクトリパス。デフォルトは`<pemworker path>/../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	構成ファイルオプションをオーバーライドします。使用方法については、次のデフォルト構成のオーバーライド-例を参照してください。

注釈

agent.cfg ファイルから`pem-agent-user` パラメーターを手動で削除すると、エージェントはデフォルトユーザーを使用して接続しません。

pemworkerユーティリティの認証#

PEMデータベースに変更を加える前に、接続はPEMデータベースサーバーで認証されます。 pemworkerユーティリティを呼び出すときに、PEMサーバーの管理ユーザーロールpostgresに関連付けられたパスワードを提供する必要があります。管理パスワードは3つの方法で指定できます。

PEM_SERVER_PASSWORD 環境変数を設定します。
PGPASSWORD キーワードを使用して、コマンドラインにパスワードを入力します。
.pgpass ファイルにエントリーを作成します。
パスワードまたは暗号化されたパスワードを--pem-registration-conn-string に含めます

パスワードを入力しない場合、パスワード認証エラーが発生します。認証が成功すると、その他の不足している必須情報の入力を求められます。登録が完了すると、サーバーはエージェントが正常に登録されたことを確認します。

PEMエージェントサービスを有効にする#

エージェントは登録されましたが、まだ実行されていません。エージェントの実行を開始し、システムのリブート後も実行されたままであることを確認するには、PEMエージェントサービスを有効にする必要があります。

Linux#

systemctl enable --now pemagent

Windows#

Windowsサービスマネージャーservices.mscでpemAgentサービスを見つけ、右クリックして Restart を選択します。 Startup Type が Automatic に設定されていることを確認します。

PEMエージェント登録の検証#

verify-registration サブコマンドは、PEM 10.4で導入された診断ユーティリティです。これにより、管理者は、PEMエージェントが適切に登録され、PEMデータベースでアクティブで、PEMサーバーに接続できることを確認できます。

このコマンドは、次のチェックを実行して、エージェントの動作ステータスを検証します。

構成の完全性 ローカル構成に適切な認識可能なエージェントIDが含まれていることを検証します。
安全な接続 agent.cfg ファイルで構成された証明書ベースの認証を使用して、PEMサーバーへの接続を確立できる機能を検証します。
データベースステータス エージェントがPEMデータベースに アクティブ として登録され、明示的にマークされていることを確認します。

このサブコマンドは、次の場合に特に役立ちます。

登録後の検証 初期登録の直後にエージェントのセットアップを検証します。
接続のトラブルシューティング エージェントとPEMサーバー間の接続の問題の診断。
SSL/証明書監査 SSL証明書が適切に構成され有効であることを確認します。
ヘルスモニタリング 自動ヘルスチェックとモニタリングスクリプトでのエージェントステータスの確認。

コマンド構文#

verify-registration サブコマンドの構文は、各オペレーティングシステムに固有です。

Linux

pemworker --verify-registration [verify-registration-options]

Windows

pemworker VERIFY-REGISTRATION [verify-registration-options]

Option	Description
--config-dir <path>	エージェント構成ファイル agent.cfg が存在するディレクトリパス。指定しない場合、デフォルトの構成ディレクトリが使用されますLinuxの`/usr/edb/pem/agent/etc/`など。

コマンドが実行されると、 pemworker ユーティリティは4段階の検証プロセスを実行します。

ロード構成 agent.cfg デフォルトまたは指定されたパスからを読み取り、エージェントIDと接続文字列を取得します。
接続の確立 登録時に定義された証明書ベースのSSL認証を使用して、PEMデータベースサーバーへの接続を開こうとします。
クエリステータス pem.agent システムテーブルに対してチェックを実行して、IDが存在し、ステータスがアクティブに設定されていることを確認します。
レポート結果 成功または失敗メッセージをコンソールに出力し、特定の終了コードを返します。

終了コードの理解#

コマンドは次の終了コードを返します。

Code	Status	Description
0	Success	エージェントは登録され、アクティブで、接続されています。
1	Config Error	ローカル構成からの有効なエージェントIDの取得に失敗しました。
2	Connection Error	PEMサーバーへの接続を確立できません。
3	Database Error	エージェントIDが見つかりましたが、PEMデータベースで非アクティブとしてマークされています。

使用例#

例1 基本的な検証

デフォルト設定を使用して登録を確認するには

Linux

pemworker --verify-registration

Windows

pemworker VERIFY-REGISTRATION

成功した場合の予想出力

Verify registration done successfully.

例2カスタム構成ディレクトリを使用する

デフォルト以外の構成ディレクトリを使用するエージェントを確認するには

Linux

pemworker --verify-registration --config-dir /opt/custom/pem/agent/etc

Windows

pemworker VERIFY-REGISTRATION --config-dir "C:\custom\pem\agent\etc"

PEMエージェントの登録解除#

pemworkerユーティリティを使用して、PEMエージェントの登録を解除できます。エージェントの登録を解除するには、以下の例に示すようにpemworkerユーティリティを呼び出します。

Linux

#  Running as root

pemworker --unregister-agent

Windows

./pemworker.exe UNREGISTER-AGENT

pemworkerユーティリティを呼び出すときに、コマンド文字列にコマンドラインオプションを追加します。各オプションの後には、対応する値を続けます。

Option	Description
--pem-user <username>	PEMバックエンドデータベースサーバーのデータベースユーザーpem_adminロールのメンバーの名前。このパラメーターは必須です。
--config-dir	構成ファイルのディレクトリパス。デフォルトは`"<pemworker path>/../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 を使用して登録接続文字列を指定することもできます。優先順位は次のとおりです。

コマンドライン引数 –pem-registration-conn-string - 最も高い優先度
環境変数 PEM_REGISTRATION_CONN_STRING
個々のパラメーター –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 を使用してエージェント接続文字列を指定することもできます。優先順位は次のとおりです。

コマンドライン引数 -oagent_conn_string=... - 最も高い優先度
環境変数PEM_AGENT_CONN_STRING
構成ファイル/レジストリ agent_conn_string / AGENT_CONN_STRING
個々のパラメーター pem_host 、pem_port 、pem_ssl_mode など - 最低優先度

エージェントIDの設定#

登録された各PEMエージェントには、一意のエージェントIDが必要です。デフォルト構成のオーバーライド-例に示すように、 -o オプションを使用して値が提供されない限り、値max(id)+1 は各エージェントIDに割り当てられます。

デフォルト構成のオーバーライド-例#

-o オプションを使用すると、登録中に設定できないエージェント構成パラメーターLinuxではagent.cfg およびWindowsではHKEY_LOCAL_MACHINE\Software\EnterpriseDB\PEM\agent に保存されますをオーバーライドできます。これらの入力は通常のCLIオプションと同じ方法では検証されないため、このオプションは注意して使用する必要があります。パラメーターの完全なリストは Modifying agent configuration にあります

以下に、-o オプションの使用例をいくつか示します。

エージェントIDの設定#

コマンドラインを使用してPEMエージェントを登録します。 -o オプションを使用して、agent_id 値8を割り当てます。

#  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<ID> に対して有効である必要があります。<ID> は、コマンドラインを使用して指定されたものと同じである必要があります。 -o オプションを使用します。

#  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を引き継ぎます。次に

edbとしてログインします。 pem およびlogs ディレクトリを作成し、読み取り、書き込み、および実行権限を割り当てます。

# 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

エージェントをPEMサーバーに登録します。

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*

agent.cfg ファイルのパラメーターを変更します。

vi /home/edb/pem/agent.cfg
agent_ssl_key=/home/edb/pem/agent<id>.key
agent_ssl_crt=/home/edb/pem/agent<id>.crt
log_location=/home/edb/pem/worker.log
agent_log_location=/home/edb/pem/agent.log

<id> は、割り当てられたPEMエージェントIDです。

tmp ディレクトリを作成し、環境変数を設定して、エージェントを起動します。

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ユーザーで起動されました。マシンが再起動しても、このエージェントは自動的に再起動しません。前述のコマンドを使用して手動で起動する必要があります。

オプションで、ルートユーザーとしてこのPEMエージェントのサービスを作成して、次のようにマシンの再起動時にこのエージェントを自動的に起動できます。

構成ファイルパスの値と、pemagent サービスファイルのユーザーをスーパーユーザーとして更新します。

# 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

実行中のエージェントプロセスを停止し、エージェントサービスを再起動します。

# Find the process id of the running pem agent and pem worker process and kill that process
ps -ax | grep pemagent
kill -9 <process_id_of_pemagent>
ps -ax | grep pemworker
kill -9 <process_id_of_pemworker>
# Enable and start pemagent service
sudo systemctl enable pemagent
sudo systemctl start pemagent
sudo systemctl status pemagent

PEMダッシュボードでエージェントのステータスを確認します。

注釈

root権限または別のユーザーたとえば、enterprisedbが所有するファイルへのアクセスを必要とするプローブとジョブは失敗します。 - agent.cfg ファイルをデフォルトの場所から別の場所に移動すると、PEMダッシュボードにエージェントステータスが`unknown` として表示される場合があります。詳細については、 Troubleshooting agent issues を参照してください。

Registering a PEM agent

目次

Registering a PEM agent#

PEMエージェントを登録する方法#

pemworkerユーティリティを使用したPEMエージェントの登録#

Linux#

Windows#

pemworkerユーティリティの認証#

PEMエージェントサービスを有効にする#

Linux#

Windows#

PEMエージェント登録の検証#

コマンド構文#

終了コードの理解#

使用例#

PEMエージェントの登録解除#

高度な使用法#

接続文字列を使用する#

登録接続文字列#

エージェント接続文字列#

エージェントIDの設定#

デフォルト構成のオーバーライド-例#

エージェントIDの設定#

既存のSSL証明書とキーの提供#

非rootユーザーアカウントを使用してLinuxでPEMエージェントを登録する#