Modifying agent configuration v9

A number of configurable parameters control the behavior of the PEM agent. On Linux, these are stored in a configuration file. On Windows they're stored as registry keys.

Most agent configuration is managed automatically. We recommend against manually modifying any of these configuration parameters unless specifically directed to do so.

Note

If you add, remove, or modify any of the parameters, you must restart the agent to apply the changes.

Contents of the configuration file

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 entries shown in the following table.

Parameter nameDescriptionDefault value
pem_hostThe IP address or hostname of the PEM server.127.0.0.1.
pem_portThe database server port to which the agent connects to communicate with the PEM server.Port 5432.
pem_agentA unique identifier assigned to the PEM agent.The first agent is '1', the second agent is '2', and so on.
agent_ssl_keyThe complete path to the PEM agent's key file./root/.pem/agent.key
agent_ssl_crtThe complete path to the PEM agent's certificate file./root/.pem/agent.crt
agent_flag_dirUsed 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_levelSpecifies the type of event to write to the PEM log files, one of debug2, debug, info, warning, error. These are in descending order of logging verbosity; debug2 logs everything possible, and error only logs errors.warning
log_locationSpecifies the location of the PEM worker log file.127.0.0.1.
agent_log_locationSpecifies the location of the PEM agent log file./var/log/pem/agent.log
long_waitThe maximum length of time (in seconds) for the PEM agent to wait before attempting to connect to the PEM server if an initial connection attempt fails.30 seconds
short_waitThe minimum length of time (in seconds) for the PEM agent to wait before checking which probes are next in the queue waiting to run.10 seconds
alert_threadsThe number of alert threads to be spawned by the agent. For more information, see About alert threads.Set to 1 for the agent that resides on the host of the PEM server, 0 for all other agents.
enable_smtpWhen set to true, this agent will attempt to send email notifications as configured in the PEM web application.true for PEM server host, false for all others.
enable_snmpWhen set to true, this agent will attempt to send SNMP notifications as configured in the PEM web application.true for PEM server host, false for all others.
enable_nagiosWhen set to true, Nagios alerting is enabled.true for PEM server host, false for all others.
enable_webhookWhen set to true, Webhook alerting is enabled.true for PEM server host, false for all others.
max_webhook_retriesUsed to set the maximum number of times pemAgent retries to call webhooks on failure.Default 3.
connect_timeoutThe maximum time in seconds (a decimal integer string) for the agent to wait for a connection.Not set by default. Set to 0 to indicate for the agent to wait indefinitely.
allow_server_restartIf set to TRUE, the agent can restart the database server that it monitors. Some PEM features might be enabled/disabled, depending on the value of this parameter.False
max_connectionsThe maximum number of probe connections used by the connection throttler.0 (an unlimited number)
connection_lifetimeUsed 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_probesIf set to TRUE, the user can create batch probes using the custom probes feature.false
heartbeat_connectionWhen set to TRUE, a dedicated connection is used for sending the heartbeats. If set to TRUE, the max_connections parameter must be set to greater than 1.false
batch_script_dirProvides the path where script file (for alerting) is stored./tmp
connection_custom_setupUsed to provide SQL code to invoke when a new connection with a monitored server is made.Not set by default.
ca_fileThe path to a CA certificate to use instead of the platform default for verifying webhook server certificates. You can override this value with the --webhook_ssl_ca_crt option when defining webhooks.Not set by default.
batch_script_userThe name of the user to use for executing the batch/shell scripts.None
Webhook parametersYou can specify the following options multiple times. Each time, precede the option with a header of the form [WEBHOOK/<name>], where <name> is the name of a previously created webhook. These settings are automatically added when webhooks are created. We don't recommend adding them manually.
webhook_ssl_keyThe complete path to the webhook's SSL client key file.
webhook_ssl_crtThe complete path to the webhook's SSL client certificate file.
webhook_ssl_crlThe complete path of the CRL file to validate webhook server certificate.
webhook_ssl_ca_crtThe complete path to the webhook's SSL ca certificate file.
allow_insecure_webhooksWhen set to true, allow webhooks to call with insecure flag.false

Contents of the registry

On Windows systems, PEM registry entries are located in:

HKEY_LOCAL_MACHINE\Software\EnterpriseDB\PEM\agent

The registry contains the entries shown in the following table.

Parameter nameDescriptionDefault value
PEM_HOSTThe IP address or hostname of the PEM server.127.0.0.1.
PEM_PORTThe database server port to which the agent connects to communicate with the PEM server.Port 5432.
AgentIDA unique identifier assigned to the PEM agent.The first agent is '1', the second agent is '2', and so on.
AgentKeyPathThe complete path to the PEM agent's key file.%APPDATA%\Roaming\pem\ agent.key.
AgentCrtPathThe complete path to the PEM agent's certificate file.%APPDATA%\Roaming\pem\ agent.crt
AgentFlagDirUsed 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.
LogLevelSpecifies the type of event to write to the PEM log files. These are in descending order of logging verbosity; debug2 logs everything possible, and error only logs errors.warning
LongWaitThe maximum length of time (in seconds) that the PEM agent waits before attempting to connect to the PEM server if an initial connection attempt fails.30 seconds
shortWaitThe minimum length of time in seconds that the PEM agent waits before checking which probes are next in the queue (waiting to run).10 seconds
AlertThreadsThe number of alert threads for the agent to spawn. For more information, see About alert threads.Set to 1 for the agent that resides on the host of the PEM server, 0 for all other agents.
EnableSMTPWhen set to true, the SMTP email feature is enabled.true for PEM server host, false for all others.
EnableSNMPWhen set to true, the SNMP trap feature is enabled.true for PEM server host, false for all others.
EnableWebhookWhen set to true, Webhook alerting is enabled.true for PEM server host, false for all others.
MaxWebhookRetriesSets the maximum number of times for pemAgent to retry to call webhooks on failure.Default 3.
ConnectTimeoutThe maximum time in seconds (a decimal integer string) that the agent waits for a connection.Not set by default. If set to 0, the agent waits indefinitely.
AllowServerRestartIf set to TRUE, the agent can restart the database server that it monitors. Some PEM features might be enabled/disabled, depending on the value of this parameter.true
MaxConnectionsThe maximum number of probe connections used by the connection throttler.0 (an unlimited number)
ConnectionLifetimeUse 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).
AllowBatchProbesIf set to TRUE, the user can create batch probes using the custom probes feature.false
HeartbeatConnectionWhen set to TRUE, a dedicated connection is used for sending the heartbeats.false
BatchScriptDirThe path to store the script file for alerting./tmp
ConnectionCustomSetupUsed to provide SQL code to invoke when a new connection with a monitored server is made.Not set by default.
AllowBatchJobStepsIf set to true, the batch/shell scripts are executed. Scripts are executed by the user account under which the PEM agent is running.None
Webhook parametersYou can specify the following options multiple times. They must be placed in a subkey Software\EnterpriseDB\PEM\agent\WEBHOOK\<name>, where <name> is the name of a previously created webhook. These settings are automatically added when webhooks are created. We don't recommended adding them manually.
WebhookSSLKeyThe complete path to the webhook's SSL client key file.
WebhookSSLCrtThe complete path to the webhook's SSL client certificate file.
WebhookSSLCrlThe complete path of the CRL file to validate webhook server certificate.
WebhookSSLCaCrtThe complete path to the webhook's SSL ca certificate file.
AllowInsecureWebhooksWhen set to true, allow webhooks to call with insecure flag.false

About alert threads

The number of alert threads spawned by an agent is determined by the alert_threads or AlertThreads parameter. In general, we recommend setting this parameter to 1 on the agent that resides on the PEM server and 0 for all other agents. However, on PEM server instances with very large numbers of alerts (caused by many monitored servers, many enabled alerts, or high alert frequency), it may be necessary to increase this parameter if alerts are not being evaluated at the configured frequency. In this situation, we recommend setting this parameter to around 8 on the agent that resides on the PEM server and 0 for all other agents and tuning up or down accordingly.

When tuning this parameter, note that any agent can process any alert, so in general it is unnecessary to have a non-zero number of alert threads on more than one agent. The capacity of the PEM instance to process alerts is determined by the total number of alert thread across all agents. Increasing the number of threads on a specific agent does not give any additional performance for alerts pertaining to servers monitored by that agent.

Each alert thread opens a connection to the PEM server backend, so allocating more threads than necessary does result in additional memory and CPU usage on the PEM server.