Registering a PEM agent v9
You must register each PEM agent installed on a separate host with the PEM server. (The PEM agent is different from the PEM server host.) 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. On a Linux host, you must use the pemworker utility to register the agent.
The PEM agent package 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. Run the pemworker utility as the root user.
- The PEM agent installed on the PEM server host is registered with the PEM server by default.
- After upgrading the PEM agent, you need to restart it. It doesn't require registration.
Append command line options to the command string when invoking the pemworker utility. Follow each option with a corresponding value.
|The IP address of the PEM backend database server. This parameter is required.|
|The port of the PEM backend database server. The default value is |
|The name of the database user having superuser privileges of the PEM backend database server. This parameter is required.|
|The agent user to connect the PEM server backend database server.|
|The complete path to the directory where certificates are created. If you don't provide a path, certificates are created in |
|The directory path for the configuration file. The default is |
|A user-friendly name for the agent to display in the PEM browser tree. The default is the system hostname.|
|Include the |
|The name of the group in which the agent is displayed.|
|The name of the database role on the PEM backend database server with access to the monitored database server.|
|The name of the database user on the PEM backend database server who owns the agent.|
|Enable the |
|Enable the |
|The operating system user to use for executing the batch/shell scripts. The default value is none. The scripts don't execute if you leave this parameter blank or the specified user doesn't exist.|
|Enable the |
|Enable the |
|Enable the |
|Specifies whether 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
true in the
When configuring a shell/batch script run by a PEM agent that has PEM version 7.11 or later installed, you must specify the user for the
batch_script_user parameter. We strongly recommend that you use a nonroot user to run the scripts. Using the root user might 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 you must set the
batch_script_user parameter to
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). You can specify the administrative password in three ways:
- Set the
- Provide the password on the command line with the
- Create an entry in the
If you don't provide the password, a password authentication error occurs. You are prompted for any other missing required information. When the registration is complete, the server confirms that the agent was successfully registered.
Each registered PEM agent must have a unique agent ID. For 9.0 and later:
- The value
max(id)+1is assigned to each agent ID.
- You can override the agent ID manually using the command line.
For 8.6 and earlier, the sequence
pem.agent_id_seq generates and gives a unique ID to the PEM agent.
This example shows how to register the PEM agent overriding the default configurations in versions 9.0 and later.
Register the PEM agent using the command line. Assign an
agent_id value of 8 using the
agent_id of 8 is available, the PEM agent registers successfully. If the given ID is already in use by the existing agent, it throws an error.
Register the PEM agent using the command line. Assign the existing SSL certificates and key files to avoid generating new ones for a particular agent ID in versions 9.0 and later. The SSL certificates and key files must be valid for the database user
agent<ID> , where
<ID> must be the same as provided using the command line. Use the
Because the valid SSL certificates and key files are available at the given location with proper permissions, the PEM agent registers successfully. If the certificate or key files are not valid or do not have proper permissions it throws an error.
You can use the pemworker utility to unregister a PEM agent. To unregister an agent, include the
--unregister-agent keywords along with the details when invoking the pemworker utility:
Append command line options to the command string when invoking the pemworker utility. Follow each option with a corresponding value:
|Specifies the name of the database user (member of pem_admin role) of the PEM backend database server. This parameter is required.|
|Specifies the directory path for the configuration file. The default is |
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 certificate authority file. 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's stored in a different location, specify that value in the
Then, use a platform-specific command to start the PEM agent service. The service is named
On a RHEL or CentOS 7.x or 8.x host, use systemctl to start the service:
systemctl start pemagent
The service confirms that it's starting the agent. When the agent is registered and started, it appears on the Global Overview dashboard and in the Object browser tree of the PEM web interface.
For information about using the pemworker utility to register a server, see Registering a database server.
To use a nonroot 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 nonroot user, such as edb. Then:
Log in as edb. Create
logsdirectories and assign read, write, and execute permissions:
Register the agent with PEM server:
Change the parameters of the
<id>is the assigned PEM agent ID.
tmpdirectory, set the environment variable, and start the agent:
Your PEM agent is now registered and started with the edb user. If your machine restarts, then this agent doesn't restart automatically. You need to start it manually using the previous command.
Optionally, you can create the service for this PEM agent as the root user to start this agent automatically at machine restart as follows:
a. Update the values for the configuration file path and the user in the
pemagentservice file as superuser:
b. Stop the running agent process, and then restart the agent service:
Check the agent status on the PEM dashboard.
- Any probes and jobs that require root permission or access to a file owned by another user (for example, enterprisedb) fail.
- If you move the
agent.cfgfile from its default location to another, the PEM dashboard might display the agent status as “unknown”. See Troubleshooting agent issues, for more information.