Registering an Agent

Each PEM agent must be registered with the PEM server. The registration process provides the PEM server with the information it needs to communicate with the agent. The PEM agent graphical installer for Windows supports self-registration for the agent. You must use the pemworker utility to register the agent if the agent is on a Linux host.

The RPM installer places the PEM agent in the /usr/edb/pem/agent/bin directory. To register an agent, include the --register-agent keywords along with registration details when invoking the pemworker utility:

pemworker --register-agent

Append command line options to the command string when invoking the pemworker utility. Each option should be followed by a corresponding value:

Option	Description
--pem-server	Specifies the IP address of the PEM backend database server. This parameter is required.
--pem-port	Specifies the port of the PEM backend database server. The default value is 5432.
--pem-user	Specifies the name of the Database user (having superuser privileges) of the PEM backend database server. This parameter is required.
--pem-agent-user	Specifies the agent user to connect the PEM server backend database server.
--cert-path	Specifies the complete path to the directory in which certificates will be created. If you do not provide a path, certificates will be created in: On Linux, ~/.pem On Windows, %APPDATA%/pem
--config-dir	Specifies the directory path where configuration file can be found. The default is the <pemworker path>/../etc.
--display-name	Specifies a user-friendly name for the agent that will be displayed in the PEM Browser tree control. The default is the system hostname.
--force-registration	Include the force_registration clause to instruct the PEM server to register the agent with the arguments provided; this clause is useful if you are overriding an existing agent configuration. The default value is Yes.
--group	The name of the group in which the agent will be displayed.
--team	The name of the database role, on the PEM backend database server, that should have access to the monitored database server.
--owner	The name of the database user, on the PEM backend database server, who will own the agent.
--allow_server_restart	Enable the allow-server_restart parameter to allow PEM to restart the monitored server. The default value is True.
--allow-batch-probes	Enable the allow-batch-probes parameter to allow PEM to run batch probes on this agent. The default value is false.
--batch-script-user	Specifies the operating system user that should be used for executing the batch/shell scripts. The default value is none; the scripts will not be executed if you leave this parameter blank or the specified user does not exist.
--enable-heartbeat-connection	Enable the enable-heartbeat-connection parameter to create a dedicated heartbeat connection between PEM Agent and server to update the active status. The default value is false.
--enable-smtp	Enable the enable-smtp parameter to allow the PEM agent to send the email on behalf of the PEM server.The default value is false.
--enable-snmp	Enable the enable-snmp parameter to allow the PEM agent to send the SNMP traps on behalf of the PEM server.The default value is false.
-o	Specify if you want to override the configuration file options.

Before using any PEM feature for which a database server restart is required by the pemagent (such as Audit Manager, Log Manager, or Tuning Wizard), you must first set the value for allow_server_restart to true in the agent.cfg file.

Note

When configuring a shell/batch script run by a PEM agent that has PEM 7.11 or later version installed, the user for the batch_script_user parameter must be specified. It is strongly recommended that a non-root user is used to run the scripts. Using the root user may result in compromising the data security and operating system security. However, if you want to restore the pemagent to its original settings using root user to run the scripts, then the batch_script_user parameter value must be set to root.

You can use the PEM_SERVER_PASSWORD environment variable to set the password of the PEM Admin User. If the PEM_SERVER_PASSWORD is not set, the server will use the PGPASSWORD or .pgpass file when connecting to the PEM Database Server.

Failure to provide the password will result in a password authentication error; you will be prompted for any other required but omitted information. When the registration is complete, the server will confirm that the agent has been successfully registered.

Setting PEM Agent Configuration Parameters

The PEM agent RPM installer creates a sample configuration file named agent.cfg.sample in the /usr/edb/pem/agent/etc directory. When you register the PEM agent, the pemworker program creates the actual agent configuration file (named agent.cfg). You must modify the agent.cfg file, adding the following configuration parameter:

heartbeat_connection = true

You must also add the location of the ca-bundle.crt file (the certificate authority). By default, the installer creates a ca-bundle.crt file in the location specified in your agent.cfg.sample file. You can copy the default parameter value from the sample file, or, if you use a ca-bundle.crt file that is stored in a different location, specify that value in the ca_file parameter:

ca_file=/usr/libexec/libcurl-pem7/share/certs/ca-bundle.crt

Then, use a platform-specific command to start the PEM agent service; the service is named pemagent.

On a RHEL or CentOS 7.x or 8.x host, use systemctl to start the service:

systemctl start pemagent

The service will confirm that it is starting the agent; when the agent is registered and started, it will be displayed on the Global Overview dashboard and in the Object browser tree control of the PEM web interface.

For information about using the pemworker utility to register a server, please see the PEM Administrator’s Guide, available at:

https://www.enterprisedb.com/edb-docs

Using a non-root User Account to Register a PEM Agent

To use a non-root user account to register a PEM agent, you must first install the PEM agent as a root user. After installation, assume the identity of a non-root user (for example, edb) and perform the following steps:

1. Create the .pem directory and logs directory and assign read, write, and execute permissions to the file:

   mkdir /home/<edb>/.pem
   mkdir /home/<edb>/.pem/logs
   chmod 700 /home/<edb>/.pem
   chmod 700 /home/<edb>/.pem/logs
   

2. Register the agent with PEM server:

   ./pemworker --register-agent --pem-server <172.19.11.230> --pem-user <postgres> --pem-port <5432> --display-name <non_root> --cert-path /home/<edb> --config-dir /home/<edb>
   
   The above command creates agent certificates and an agent configuration file (``agent.cfg``) in the ``/home/edb/.pem`` directory. Use the following command to assign read and write permissions to these files:
   
   ``chmod -R 600 /home/edb/.pem/agent*``
   

3. Change the parameters of the agent.cfg file:

   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
   

4. Update the values for the configuration file path and the user in the pemagent service file:

   • If you are using RHEL or CentOS 7 or 8, update the parameters as shown below:

   User=edb
   ExecStart=/usr/edb/pem/agent/bin/pemagent -c /home/edb/.pem/agent.cfg
   

5. Stop the agent process, and then restart the agent service using the non-root user:

   • If you are using RHEL or CentOS 7 or 8, sudo systemctl start/stop/restart pemagent

6. Check the agent status on PEM dashboard.