Modifying agent configuration v9
A number of configurable parameters and registry entries control the behavior of the PEM agent. You might need to modify the PEM agent's parameter settings to enable some PEM functionality. After modifying values in the PEM agent configuration file, restart the PEM agent to apply any changes.
With the exception of the PEM_MAXCONN parameter, we strongly recommend against modifying any of these configuration parameters or registry entries without first consulting EDB support experts unless you need the modifications to enable PEM functionality.
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 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 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 | Specifies 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_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) for the PEM agent to 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) for the PEM agent to 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. 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_smtp | When set to true for multiple PEM Agents (7.13 or earlier) it might send more duplicate emails. Whereas for PEM Agents (7.14 or higher) it might send fewer duplicate emails. | true for PEM server host, false for all others. |
| enable_snmp | When set to true for multiple PEM Agents (7.13 or earlier) it might send more duplicate traps. Whereas for PEM Agents (7.14 or higher) it might send fewer duplicate traps. | 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. |
| enable_webhook | When set to true, Webhook alerting is enabled. | true for PEM server host, false for all others. |
| max_webhook_retries | Used to set the maximum number of times pemAgent retries to call webhooks on failure. | Default 3. |
| connect_timeout | The 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_restart | If 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_connections | The maximum number of probe connections used by the connection throttler. | 0 (an unlimited number) |
| connection_lifetime | Used 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 can 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 |
| batch_script_dir | Provides the path where script file (for alerting) is stored. | /tmp |
| connection_custom_setup | Used to provide SQL code to invoke when a new connection with a monitored server is made. | Not set by default. |
| ca_file | The path where the CA certificate resides. | Not set by default. |
| batch_script_user | The name of the user to use for executing the batch/shell scripts. | None |
| webhook_ssl_key | The complete path to the webhook's SSL client key file. | |
| webhook_ssl_crt | The complete path to the webhook's SSL client certificate file. | |
| webhook_ssl_crl | The complete path of the CRL file to validate webhook server certificate. | |
| webhook_ssl_ca_crt | The complete path to the webhook's SSL ca certificate file. | |
| allow_insecure_webhooks | When 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 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 | Specifies 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 |
| LongWait | The 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 |
| shortWait | The 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 |
| AlertThreads | The 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. |
| 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. |
| EnableWebhook | When set to true, Webhook alerting is enabled. | true for PEM server host, false for all others. |
| MaxWebhookRetries | Sets the maximum number of times for pemAgent to retry to call webhooks on failure. | Default 3. |
| ConnectTimeout | The 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. |
| AllowServerRestart | If 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 |
| 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 can create batch probes using the custom probes feature. | false |
| HeartbeatConnection | When set to TRUE, a dedicated connection is used for sending the heartbeats. | false |
| BatchScriptDir | The path to store the script file for alerting. | /tmp |
| ConnectionCustomSetup | Used to provide SQL code to invoke when a new connection with a monitored server is made. | Not set by default. |
| ca_file | The path where the CA certificate resides. | Not set by default. |
| AllowBatchJobSteps | If set to true,the batch/shell scripts are executed using Administrator user account. | None |
| WebhookSSLKey | The complete path to the webhook's SSL client key file. | |
| WebhookSSLCrt | The complete path to the webhook's SSL client certificate file. | |
| WebhookSSLCrl | The complete path of the CRL file to validate webhook server certificate. | |
| WebhookSSLCaCrt | The complete path to the webhook's SSL ca certificate file. | |
| AllowInsecureWebhooks | When set to true, allow webhooks to call with insecure flag. | false |
Note
If you add or remove any of the parameters in the agent.cfg file then the agent must be restarted to apply the changes.
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.