Managing a PEM Agent

The sections that follow provide information about the behavior and management of a PEM agent.

Agent Privileges

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:

Probe or Action Operating System PEM Functionality Affected
Data And Logfile Analysis Linux/ Windows The Postgres Expert will be unable to access complete information.
Session Information Linux The per-process statistics will be incomplete.
PG HBA Linux/ Windows The Postgres Expert will be unable to access complete information.
Service restart functionality Linux/ Windows The Audit Log Manager, Server Log Manager, Streaming Replication, Log Analysis Expert and PEM may be unable to apply requested modifications.
Package Deployment Linux/ Windows PEM will be unable to run downloaded installation modules.
Batch Task Windows PEM will be unable to run scheduled batch jobs in Windows.
Collect data from server (root access required) Linux/ Windows Columns such as swap usage, CPU usage, IO read, IO write will be displayed as 0 in the session activity dashboard.

..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:

Probe Operating System PEM Functionality Affected
Audit Log Collection Linux/Windows PEM will receive empty data from the PEM database.
Server Log Collection Linux/Windows PEM will be unable to collect server log information.
Database Statistics Linux/Windows The Database/Server Analysis dashboards will contain incomplete information.
Session Waits/System Waits Linux/Windows The Session/System Waits dashboards will contain incomplete information.
Locks Information Linux/Windows The Database/Server Analysis dashboards will contain incomplete information.
Streaming Replication Linux/Windows The Streaming Replication dashboard will not display information.
Slony Replication Linux/Windows Slony-related charts on the Database Analysis dashboard will not display information.
Tablespace Size Linux/Windows The Server Analysis dashboard will not display complete information.
xDB Replication Linux/Windows PEM will be unable to send xDB alerts and traps.

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.

Agent Configuration

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, such as the Streaming Replication wizard. 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 /opt/edb/pem/agent/etc. The agent.cfg file contains the following entries:

Parameter Name Description Default Value
pem_host The IP address or hostname of the PEM server. 127.0.0.1.
pem_port The database server port to which the agent connects to communicate with the PEM server. Port 5432.
pem_agent A unique identifier assigned to the PEM agent. The first agent is ‘1’, the second agent’s is ‘2’, and so on.
agent_ssl_key The complete path to the PEM agent’s key file. /root/.pem/agent.key
agent_ssl_crt The complete path to the PEM agent’s certificate file. /root/.pem/agent.crt
agent_flag_dir Used for HA support. Specifies the directory path checked for requests to take over monitoring another server. Requests are made in the form of a file in the specified flag directory. Not set by default.
log_level Log level specifies the type of event that will be written to the PEM log files. warning
log_location Specifies the location of the PEM worker log file. 127.0.0.1.
agent_log_location Specifies the location of the PEM agent log file. /var/log/pem/agent.log
long_wait The maximum length of time (in seconds) that the PEM agent will wait before attempting to connect to the PEM server if an initial connection attempt fails. 30 seconds
short_wait The minimum length of time (in seconds) that the PEM agent will wait before checking which probes are next in the queue (waiting to run). 10 seconds
alert_threads The number of alert threads to be spawned by the agent. Set to 1 for the agent that resides on the host of the PEM server; 0 for all other agents.
enable_smtp When set to true, the SMTP email feature is enabled. true for PEM server host; false for all others.
enable_snmp When set to true, the SNMP trap feature is enabled. true for PEM server host; false for all others.
enable_nagios When set to true, Nagios alerting is enabled. true for PEM server host; false for all others.
connect_timeout The max time in seconds (a decimal integer string) that the agent will wait for a connection. Not set by default; set to 0 to indicate the agent should wait indefinitely.
allow_server_restart If set to TRUE, the agent can restart the database server that it monitors. Some PEM features may be enabled/disabled, depending on the value of this parameter. True
allow_package_management If set to TRUE, the Update Monitor and Package Management features are enabled. false
max_connections The maximum number of probe connections used by the connection throttler. 0 (an unlimited number)
connection_lifetime Use ConnectionLifetime (or connection_lifetime) to specify the minimum number of seconds an open but idle connection is retained. This parameter is ignored if the value specified in MaxConnections is reached and a new connection (to a different database) is required to satisfy a waiting request. By default, set to 0 (a connection is dropped when the connection is idle after the agent’s processing loop).
allow_batch_probes If set to TRUE, the user will be able to create batch probes using the custom probes feature. false
heartbeat_connection When set to TRUE, a dedicated connection is used for sending the heartbeats. false
allow_streaming_replication If set to TRUE, the user will be able to configure and setup streaming replication. false
batch_script_dir Provide the path where script file (for alerting) will be stored. /tmp
connection_custom_setup Use to provide SQL code that will be invoked when a new connection with a monitored server is made. Not set by default.
ca_file Provide the path where the CA certificate resides. /opt/PEM/agent/share/certs/ca-bundle.crt.

On 64 bit Windows systems, PEM registry entries are located in:

HKEY_LOCAL_MACHINE\\Software\\Wow6432Node\\EnterpriseDB\\PEM\\agent.

The registry contains the following entries:

Parameter Name Description Default Value
PEM_HOST The IP address or hostname of the PEM server. 127.0.0.1.
PEM_PORT The database server port to which the agent connects to communicate with the PEM server. Port 5432.
AgentID A unique identifier assigned to the PEM agent. The first agent is ‘1’, the second agent is ‘2’, and so on.
AgentKeyPath The complete path to the PEM agent’s key file. %APPDATA%\Roaming\pem\agent.key.
AgentCrtPath The complete path to the PEM agent’s certificate file. %APPDATA%\Roaming\pem\agent.crt
AgentFlagDir Used for HA support. Specifies the directory path checked for requests to take over monitoring another server. Requests are made in the form of a file in the specified flag directory. Not set by default.
LogLevel Log level specifies the type of event that will be written to the PEM log files. warning
LongWait The maximum length of time (in seconds) that the PEM agent will wait before attempting to connect to the PEM server if an initial connection attempt fails. 30 seconds
shortWait The minimum length of time (in seconds) that the PEM agent will wait before checking which probes are next in the queue (waiting to run). 10 seconds
AlertThreads The number of alert threads to be spawned by the agent. Set to 1 for the agent that resides on the host of the PEM server; 0 for all other agents.
EnableSMTP When set to true, the SMTP email feature is enabled. true for PEM server host; false for all others.
EnableSNMP When set to true, the SNMP trap feature is enabled. true for PEM server host; false for all others.
ConnectTimeout The max time in seconds (a decimal integer string) that the agent will wait for a connection. Not set by default; if set to 0, the agent will wait indefinitely.
AllowServerRestart If set to TRUE, the agent can restart the database server that it monitors. Some PEM features may be enabled/disabled, depending on the value of this parameter. true
AllowPackageManagement If set to TRUE, the Update Monitor and Package Management features are enabled. false
MaxConnections The maximum number of probe connections used by the connection throttler. 0 (an unlimited number)
ConnectionLifetime Use ConnectionLifetime (or connection_lifetime) to specify the minimum number of seconds an open but idle connection is retained. This parameter is ignored if the value specified in MaxConnections is reached and a new connection (to a different database) is required to satisfy a waiting request. By default, set to 0 (a connection is dropped when the connection is idle after the agent’s processing loop).
AllowBatchProbes If set to TRUE, the user will be able to create batch probes using the custom probes feature. false
HeartbeatConnection When set to TRUE, a dedicated connection is used for sending the heartbeats. false
AllowStreamingReplication If set to TRUE, the user will be able to configure and setup streaming replication. false
BatchScriptDir Provide the path where script file (for alerting) will be stored. /tmp
ConnectionCustomSetup Use to provide SQL code that will be invoked when a new connection with a monitored server is made. Not set by default.
ca_file Provide the path where the CA certificate resides. /opt/PEM/agent/share/certs/ca-bundle.crt.

Agent Properties

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.

The PEM Agent Properties dialog

The PEM Agent Properties dialog

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 monitored 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.