Postgres Enterprise Manager: Release 7.15
Postgres Enterprise Manager: Release 7.15
Postgres Enterprise Manager: Release 7.15
Release 7.15
2 Registering an Agent 4
2.1 Setting PEM Agent Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Using a non-root User Account to Register a PEM Agent . . . . . . . . . . . . . . . . . . . 8
5 Conclusion 22
Index 23
i
Postgres Enterprise Manager, Release 7.15
PEM is composed of three primary components: PEM server, PEM agent, and PEM web interface. The
PEM agent is responsible for performing tasks on each managed machine and collecting statistics for the
database server and operating system.
For information about the platforms and versions supported by PEM, visit the EnterpriseDB website at:
https://www.enterprisedb.com/services-support/edb-supported-products-and-platforms#pem
For information about the installation, uninstallation, or upgrading of a PEM Agent, visit the EnterpriseDB
website at:
https://www.enterprisedb.com/edb-docs/p/edb-postgres-enterprise-manager
This document provides information that is required to work with PEM agents. The guide will acquaint
you with the basic registering, configuration, and management of agents. The guide is broken up into the
following core sections:
• Postgres Enterprise Manager - Overview - This section provides an overview of PEM architecure.
• Registering a PEM Agent - This section provides information about registration of a PEM agent.
• Managing a PEM agent - This section provides information about configuring and managing a PEM
agent.
• Troubleshooting for PEM agent - This section provides information about troubleshooting for PEM
agents.
This document uses Postgres to mean either the PostgreSQL or EDB Postgres Advanced Server database.
Contents 1
CHAPTER 1
Postgres Enterprise Manager (PEM) consists of components that provide management and analytical func-
tionality:
• PEM Server: The PEM server is used as the data repository for monitoring data and as a server to
which both agents and clients connect. The PEM server consists of an instance of PostgreSQL, an
associated database for storage of monitoring data, and a server that provides web services.
• PEM web interface: The PEM web interface allows you to manage and monitor Postgres servers
and utilize PEM extended functionality. The web interface software is installed with the PEM server
installer, and is accessed via your choice of web browser.
• PEM Agent: The PEM agent is responsible for executing tasks and reporting statistics from the agent
host and monitored Postgres instances to the PEM server. A single PEM agent can monitor multiple
installed instances of Postgres that reside on one or many hosts.
• SQL Profiler plugin: This plugin to the Postgres server is used to generate the monitoring data used
by the SQL Profiler tool. Installation of the SQL Profiler plugin is optional, but the plugin must be
installed on each instance of Postgres you wish to profile. The SQL Profiler may be used with any
supported version of an EnterpriseDB distribution of a PostgreSQL server or an Advanced Server (not
just those managed through the PEM server).
The PEM Agent installer creates two executables: the PEM worker (pemworker.exe) and the PEM agent
(pemagent.exe). Each PEM worker has a corresponding PEM agent that you can use to start or stop the
PEM worker. The PEM agent will also restart the PEM worker should it terminate unexpectedly. The PEM
worker log file contains information related to PEM worker activity (probe activities, heartbeat responses,
etc.), and is stored in /var/log/pem/worker.log.
2
Postgres Enterprise Manager, Release 7.15
The architectural diagram below illustrates the relationship between the various servers and workstations
involved in a typical PEM installation.
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 su-
peruser 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.
Continued on next page
4
Postgres Enterprise Manager, Release 7.15
5
Postgres Enterprise Manager, Release 7.15
If you want to use any PEM feature for which database server restart is required by the pema-
gent (such as Audit Manager, Log Manager, or Tuning Wizard), then you must 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.
6
Postgres Enterprise Manager, Release 7.15
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 can modify the agent.cfg file,
adding the following configuration parameter:
heartbeat_connection = true
By default, heartbeat_connection value is false but you can override the value during pemagent
registration with pemworker utility using an option --enable-heartbeat-connection.
Then, use a platform-specific command to start the PEM agent service; the service is named pemagent.
For example, on a CentOS or RHEL 6.x system, you would use the command:
/etc/init.d/pemagent
On a RHEL or CentOS 7.x or 8.x host, use systemctl to start the service:
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
To register a PEM agent using a non-root user, you first need to install 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 as following and assign read, write, and execute per-
missions 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 using the pemworker utility as shown below:
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 as following:
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 6, update the pemagent service file to reflect the correct path of
agent.cfg file and also change user su to su edb.
• If you are using RHEL or CentOS 7 or 8, update the parameters as following:
5. Stop the agent process that was started earlier, and then restart the agent service using the non-root
user as follows:
• If you are using RHEL or CentOS 6,
The sections that follow provide information about the behavior and management of a PEM agent.
By default, the PEM agent is installed with root privileges for the operating system host and superuser
privileges for the database server. These privileges allow the PEM agent to invoke unrestricted probes on
the monitored host and database server about system usage, retrieving and returning the information to the
PEM server.
Please note that PEM functionality diminishes as the privileges of the PEM agent decrease. For complete
functionality, the PEM agent should run as root. If the PEM agent is run under the database server’s
service account, PEM probes will not have complete access to the statistical information used to generate
reports, and functionality will be limited to the capabilities of that account. If the PEM agent is run under
another lesser-privileged account, functionality will be limited even further.
If you limit the operating system privileges of the PEM agent, some of the PEM probes will not return
information, and the following functionality may be affected:
9
Postgres Enterprise Manager, Release 7.15
Note: The above-mentioned list is not comprehensive, but should provide an overview of the type of
functionality that will be limited.
If you restrict the database privileges of the PEM agent, the following PEM functionality may be affected:
If the probe is querying the operating system with insufficient privileges, the probe may return a
permission denied error.
If the probe is querying the database with insufficient privileges, the probe may return a permission
denied error or display the returned data in a PEM chart or graph as an empty value.
When a probe fails, an entry will be written to the log file that contains the name of the probe, the reason the
probe failed, and a hint that will help you resolve the problem.
You can view probe-related errors that occurred on the server in the Probe Log dashboard, or review error
messages in the PEM worker log files. On Linux, the default location of the log file is:
/var/log/pem/worker.log
On Windows, log information is available on the Event Viewer.
A number of user-configurable parameters and registry entries control the behavior of the PEM agent. You
may be required to modify the PEM agent’s parameter settings to enable some PEM functionality. After
modifying values in the PEM agent configuration file, you must restart the PEM agent to apply any changes.
With the exception of the PEM_MAXCONN parameter, we strongly recommend against modifying any of
the configuration parameters or registry entries listed below without first consulting EnterpriseDB support
experts unless the modifications are required to enable PEM functionality.
On Linux systems, PEM configuration options are stored in the agent.cfg file, located in /usr/edb/
pem/agent/etc. The agent.cfg file contains the following entries:
The PEM Agent Properties dialog provides information about the PEM agent from which the dialog
was opened; to open the dialog, right-click on an agent name in the PEM client tree control, and select
Properties from the context menu.
Use fields on the PEM Agent Properties dialog to review or modify information about the PEM agent:
• The Description field displays a modifiable description of the PEM agent. This description is
displayed in the tree control of the PEM client.
• You can use groups to organize your servers and agents in the PEM client tree control. Use the Group
drop-down listbox to select the group in which the agent will be displayed.
• Use the Team field to specify the name of the group role that should be able to access servers moni-
tored by the agent; the servers monitored by this agent will be displayed in the PEM client tree control
to connected team members. Please note that this is a convenience feature. The Team field does not
provide true isolation, and should not be used for security purposes.
• The Heartbeat interval fields display the length of time that will elapse between reports from
the PEM agent to the PEM server. Use the selectors next to the Minutes or Seconds fields to
modify the interval.
Use the fields on the Job Notifications tab to configure the email notification settings on agent
level:
– Use the Override default configuration? switch to specify if you want the agent
level job notification settings to override the default job notification settings. If you select Yes
for this switch, you can use the rest of the settings on this dialog to define when and to whom
the job notifications should be sent. Please note that the rest of the settings on this dialog work
only if you enable the Override default configuration? switch.
– Use the Email on job completion? switch to specify if the job notification should be
sent on the successful job completion.
– Use the Email on a job failure? switch to specify if the job notification should be sent
on the failure of a job.
– Use the Email group field to specify the email group to whom the job notification should be
sent.
The Agent Configurations tab displays all the current configurations and capabilities of a
agent.
– The Parameter column displays a list of parameters.
– The Value column displays the current value of the corresponding parameter.
– The Category column displays the category of the corresponding parameter; it can be either
configuration or capability.
If an agent has been deleted from the pem.agent table then you cannot restore it. You will need to use the
pemworker utility to re-register the agent.
If an agent has been deleted from PEM Web client but still has an entry in the pem.agent table with value
of active = f, then you can restore the agent using the following steps:
1. Use the following command to check the values of the id and active fields:
2. Update the status for the agent to true in the pem.agent table:
Where x is the identifier that was displayed in the output of the query used in step 1.
3. Refresh the PEM web client.
The deleted agent will be restored again. However, the servers that were bound to that particular agent might
appear to be down. To resolve this issue, you need to modify the PEM agent properties of the server to add
the bound agent again; after the successful modification, the servers will be displayed as running properly.
20
Postgres Enterprise Manager, Release 7.15
4.2 Using the Command Line to Delete a PEM Agent with Down or
Unknown Status
Using the PEM web interface to delete PEM agents with Down or Unknown status may be difficult if the
number of such agents is large. In such a situation, you might want to use the command line interface to
delete Down or Unknown agents.
1. Use the following query to delete the agents that are Down for more than N number of hours:
2. Use the following query to delete the agents with an Unknown status:
4.2. Using the Command Line to Delete a PEM Agent with Down or Unknown Status 21
CHAPTER 5
Conclusion
22
Index
A
Agent Configuration, 12
Agent Privileges, 9
Agent Properties, 17
C
Conclusion, 22
D
deleting agents with Down status, 21
deleting agents with Unknown status, 21
M
Managing a PEM Agent, 9
P
PEM Agent Troubleshooting, 20
PEM architecture, 2
PEM components, 2
PEM overview, 2
R
Registering an Agent, 4
restoring a deleted agent, 20
23