Registering a PEM Agent v7

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. You can use the pemworker utility to register the Agent if you use the package to install a PEM Agent.

The PEM Agent package 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:

--pem-serverSpecifies the IP address of the PEM backend database server. This parameter is required.
--pem-portSpecifies the port of the PEM backend database server. The default value is 5432.
--pem-userSpecifies the name of the Database user (having superuser privileges) of the PEM backend database server. This parameter is required.
--pem-agent-userSpecifies the Agent user to connect the PEM server backend database server.
--cert-pathSpecifies 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-dirSpecifies the directory path where configuration file can be found. The default is the <pemworker path>/../etc.
--display-nameSpecifies a user-friendly name for the Agent that will be displayed in the PEM Browser tree control. The default is the system hostname.
--force-registrationInclude 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.
--groupThe name of the group in which the Agent will be displayed.
--teamThe name of the database role, on the PEM backend database server, that should have access to the monitored database server.
--ownerThe name of the database user, on the PEM backend database server, who will own the Agent.
--allow_server_restartEnable the allow-server_restart parameter to allow PEM to restart the monitored server. The default value is True.
--allow-batch-probesEnable the allow-batch-probes parameter to allow PEM to run batch probes on this Agent. The default value is False.
--batch-script-userSpecifies 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-connectionEnable 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-smtpWhen set to true for multiple PEM Agents (7.13 or lesser) it may send more duplicate emails. Whereas for PEM Agents (7.14 or higher) it may send lesser duplicate emails.
--enable-snmpWhen set to true for multiple PEM Agents (7.13 or lesser) it may send more duplicate traps. Whereas for PEM Agents (7.14 or higher) it may send lesser duplicate traps.
-oSpecify if you want to override the configuration file options.

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


When configuring a shell/batch script run by a PEM Agent that has PEM version 7.11 or later 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 the root user to run the scripts, then the batch_script_user parameter value must be set to root.

Before any changes are made on the PEM database, the connecting agent is authenticated with the PEM database server. When invoking the pemworker utility, you must provide the password associated with the PEM server administrative user role (postgres). There are three ways to specify the administrative password; you can:

  • set the PEM_MONITORED_SERVER_PASSWORD environment variable.
  • provide the password on the command line with the PGPASSWORD keyword.
  • create an entry in the .pgpass file.

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 native package 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). Modify the agent.cfg file, changing the following configuration parameter value to true:

heartbeat_connection = true

By default, heartbeat_connection value is false but you can override the value during pemagent registration with pemworker utility using the --enable-heartbeat-connection option.

Then, use a platform-specific command to start the PEM Agent service;

On a CentOS or RHEL 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 and in the Object browser of the PEM web interface.

For information about using the pemworker utility to register a server, please see the PEM Administrator's Guide