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 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, 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_snmp | When 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_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. If set to TRUE, the max_connections parameter must be set to greater than 1. | 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 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_user | The name of the user to use for executing the batch/shell scripts. | None |
| Webhook parameters | You 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_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. |
| AllowBatchJobSteps | If 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 parameters | You 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. | |
| 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 |
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.