ppem-agent.yml
ppem-agent.yml — YAML configuration file for the agent
Overview #
The agent configuration file is located at /etc/ppem-agent.yml.
You can specify how the parameters are handled using the special agent.remote_config parameter.
After making any changes to the configuration file, the agent service must be restarted:
systemctl restart ppem-agent
The configuration file is organized into the following sections:
agent: General agent parameters.log: Logging parameters.http: HTTP parameters.jwt: JWT session parameters.
General Agent Parameters #
The agent section allows configuring general parameters of the agent.
agent: name:unique_agent_nameremote_config:true_or_falsemanager: {manager_connection_parameters} instance: {instance_discovery_parameters} commands: {command_execution_parameters} collectors: {collector_parameters} system: {system_related_parameters} reconnection_delay:base_delay_between_reconnection_attemptsconnect_timeout:timeout_for_establishing_connection_to_managerrequest_timeout:JSON_RPC_request_timeoutread_timeout:WebSocket_stream_read_timeoutwrite_timeout:WebSocket_stream_write_timeoutping_interval:interval_of_keep_alive_pinging_managermax_connections:maximum_connections_to_DBMS_instances
Core Parameters #
The core parameters listed here allow configuring the main aspects of the agent operation.
name:unique_agent_nameremote_config:true_or_false
-
name(string, optional)# The unique agent name.
PPEM uses this name to distinguish agents.
Default value:
""(empty string) — the hostname of the operating system is used.-
remote_config(boolean, optional)# Some of the agent configuration parameters are the same as for the manager.
The configuration file contains the special
remote_configparameter.If this parameter is set to
true, values that are read remotely from the manager override the ones from the configuration file.Default value:
false— the agent uses parameters from the configuration file.
Manager Connection Parameters #
The agent.manager subsection allows configuring manager connection parameters.
url:URL_of_managerapi_key:API_key_for_connecting_to_managerstrict_address_checking:true_or_falseallowed_addresses: [list_of_allowed_addresses]
-
url(string, not empty)# The URL of the manager.
The values to construct the URL can be obtained from http.server.address and http.server.port manager parameters.
Default value:
http://127.0.0.1:8080.-
api_key(string, not empty)# The API key for connecting to the manager.
To get the key:
In the navigation panel, go to Summary.
If the agent installation instruction is displayed on the page, then copy the key from the instruction.
If no instruction is displayed, then complete the following steps:
In the navigation panel, go to Infrastructure → Agents.
In the Authentication key column for any agent, click either
to copy the key or 
to view the key.
-
strict_address_checking(boolean, optional)# Specifies whether the IP Source Guard security mechanism is enabled.
When enabled, the agent uses the IP addresses from the allowed_addresses list when connecting to the URL specified in the manager.url parameter.
In this case, no domain name resolution is performed.
If either the parameter is set to
falseor theallowed_addresseslist is empty, then the IP address is either extracted from the URL directly, or determined during the domain name resolution.Default value:
false— no IP Source Guard is used.-
allowed_addresses(list of strings, optional)# The list of IPv4 or IPv6 addresses to use if the manager.strict_address_checking parameter is set to
true.Default value:
[](empty list).
Instance Discovery Parameters #
The agent.instance subsection allows configuring instance discovery parameters.
connection_defaults: host:name_of_hostport:port_numberdatabase:database_nameuser:user_namepassword:user_passwordpassword_file:path_to_password_filesslmode:secure_connection_modesslrootcert:path_to_root_CA_certificatesslcert:path_to_client_SSL_certificatesslkey:path_to_private_key_for_client_SSL_certificate
-
connection_defaults(object)# The parameters that are used by the agent when connecting to the discovered instances.
If you do not specify the
ssl*parameters (empty strings), the agent connects to instances using insecure connections.For more information about these parameters, refer to the official Postgres Pro documentation on libpq.
-
host(string)# The name of the host to connect to.
Default value:
localhost.-
port(port number)# The port number to connect to at the server host.
Default value:
5432.-
database(string)# The database name.
Default value:
postgres.-
user(string)# The user name to connect as.
Default value:
postgres.-
password(string, optional)# The user password.
Depending on the contents of the
pg_hba.confconfiguration file, the password can be either required or optional.Alternatively, the password can be provided in a password file, not this parameter.
Default value:
postgres.-
password_file(string)# The name of the file used to store the user password.
This file must be configured with the
0600access mode, and be accessible by the operating system user on behalf of which the agent service runs.If both
passwordandpassword_fileparameters are set, the former takes precedence over the latter.-
sslmode(string, optional)# The mode of a secure SSL TCP/IP connection.
Default value:
""(empty string) — theprefermode is used.-
sslrootcert(string, optional)# The name of a file containing SSL certificate authority (CA) certificate(s).
Default value:
""(empty string) — the certificates from the operating system store are used.-
sslcert(string, optional)# The file name of the client SSL certificate.
Default value:
""(empty string).-
sslkey(string, optional)# The file name of the private key for the client SSL certificate.
Default value:
""(empty string).
-
Command Execution Parameters #
The agent.commands subsection allows configuring command execution parameters.
The agent receives commands from the manager and executes them.
max_workers:maximum_number_of_active_worker_processestimeout:command_execution_timeoutfeedback_interval:time_interval_of_sending_command_metadataallowed_bindirs: paths: [list_of_filesystem_paths]
-
max_workers(integer, optional)# The maximum number of active worker processes that execute commands.
If the limit on worker processes is reached, and the workers are busy with command execution, then the new incoming commands are queued and wait for any available worker.
Default value:
6.-
timeout(time string, optional)# The command execution timeout.
If a command executes longer than the specified timeout, the command is terminated.
Default value:
5h.-
feedback_interval(time string, optional)# The time interval for sending command execution metadata to the manager.
Default value:
30s.-
allowed_bindirs.paths(list of strings, optional)# The list of filesystem paths from which the agent can execute commands.
Default value:
[](empty list).
Discovery Collector Parameters #
The agent.collectors subsection allows configuring collector parameters.
Collectors are background jobs which discover various information about the server environment and send it to the manager.
timeout:discovery_loop_timeout_for_collectorhost: interval:interval_between_data_collection_iterationsbindirs: paths: [list_of_searchable_filesystem_paths] agent: interval:interval_between_data_collection_iterationsinstances: disabled:true_or_falseinterval:interval_between_data_collection_iterationsinstance_objects: batch_size:batch_size_to_send_in_single_requestinterval:interval_between_data_collection_iterationsinitial_delay:initial_discovery_delayjitter_interval:jitter_for_initial_discovery_delayextended: enabled:true_or_falseschedule:CRON_schedule_expressioninstance_settings: interval:interval_between_data_collection_iterationsreplication: interval:interval_between_data_collection_iterations
-
timeout(time string, optional)# The discovery loop timeout for a collector.
Default value:
30m.-
host(object)# The
hostcollector parameters.This collector discovers and gathers information about the operating system where the agent service is running.
-
interval(time string, optional)# The interval between data collection iterations.
Default value:
1m.-
bindirs.paths(list of strings, optional)# The list of filesystem paths to search for executables and packages in.
This list serves as an addition to the commands.allowed_bindirs.paths list.
Default value:
[](empty list) — only the paths specified in thecommands.allowed_bindirs.pathsparameter are used.
-
-
agent(object)# This collector discovers and gathers information about the running agent service.
-
interval(time string, optional)# The interval between data collection iterations.
Default value:
1m.
-
-
instances(object)# This collector discovers instances.
-
instance_objects(object)# This collector discovers various objects which exist in instances, such as schemas, tables, and so on.
-
batch_size(integer, optional)# The batch size to be sent in a single request to the manager.
This parameter is useful when an instance contains a large number of objects.
Default value:
1000.-
interval(time string, optional)# The interval between data collection iterations.
Default value:
1m.-
initial_delay(time string, optional)# The initial delay before the first data collection iteration.
This parameter may help to reduce the load on the DBMS.
Default value:
0s— no delay.-
jitter_interval(time string, optional)# The jitter value for initial_delay.
The actual initial delay becomes random and is in the
[initial_delay - jitter;initial_delay + jitter]range, so the instances are not overflowed with queries from the collector.Default value:
0s.-
extended(object)# The extended discovery parameters.
-
enabled(boolean, optional)# Specifies whether to enable the extended discovery of instance objects.
Enabling this parameter may result in a performance impact if the instance contains a large number of objects.
Default value:
true— extended discovery is enabled.-
schedule# The CRON schedule expression stating when to run the extended object discovery process, for example:
@every 5m
The schedule can be configured for the discovery process to run when the load on the instance is minimal. For example, during nighttime or weekends.
Default value:
""(empty string) — the instance_objects.interval × 5 value is used.
-
-
-
instance_settings(object)# This collector discovers the settings of instances.
-
interval(time string, optional)# The interval between data collection iterations.
Default value:
1m.
-
-
replication(object)# This collector discovers the replication configuration of instances.
-
interval(time string, optional)# The interval between data collection iterations.
Default value:
10s.
-
System Parameters #
The agent.system subsection allows configuring various system-related parameters.
systemd_units_path:path_to_systemd_unit_file_storagepostgresql_configs_path:path_to_Postgres_configuration_file_storage
-
systemd_units_path(string, optional)# The path to the storage where the agent stores the systemd unit files required for the agent operation.
Default value:
""(empty string).-
postgresql_configs_path(string, optional)# The path to the storage where the agent stores the PostgreSQL or Postgres Pro configuration files required for the agent operation.
Default value:
""(empty string).
Miscellaneous Time Interval and Timeout Parameters #
This section allows configuring miscellaneous time interval and timeout parameters.
reconnection_delay:base_delay_between_reconnection_attemptsconnect_timeout:timeout_for_establishing_connection_to_managerrequest_timeout:JSON_RPC_request_timeoutread_timeout:WebSocket_stream_read_timeoutwrite_timeout:WebSocket_stream_write_timeoutping_interval:interval_of_keep_alive_pinging_managermax_connections:maximum_connections_to_DBMS_instances
-
reconnection_delay(time string, optional)# The base delay between reconnection attempts when a connection to the manager is lost.
The actual delay is random and is in the
[0.75×base_delay;1.25×base_delay]range so the manager is not overloaded with simultaneous connection attempts from multiple agents.Default value:
2s.-
connect_timeout(time string, optional)# The timeout for establishing a connection to the manager.
If the manager does not respond within this time, the agent tries to reconnect.
Default value:
2s.-
request_timeout(time string, optional)# The JSON-RPC request timeout.
Default value:
2s.-
read_timeout(time string, optional)# The WebSocket stream read timeout.
Default value:
30s.-
write_timeout(time string, optional)# The WebSocket stream write timeout.
Default value:
2s.ping_interval#The interval of pinging the manager to keep the existing connection open (keep-alive).
If not specified, then the value is set to 80% of the read_timeout value.
-
max_connections(integer, optional)# The maximum number of simultaneous connections to instances.
Default value:
0— unlimited.
Logging Parameters #
The log section allows configuring logging parameters for the agent.
log: level:logging_levelformat:log_formatoptions: csv_field_delimiter:delimiter_characterfile: path:absolute_path_to_log_filemode:access_mode_of_log_file
-
level(enum)# The log level.
Possible values:
debuginfowarnerror
Each log level includes the previous one, for example,
warnincludes log messages of theinfoanddebuglevels.-
format(enum, optional)# The logging format.
Possible values:
json: The JSON format.pretty: The prettified JSON format, such as the one the jq utility generates.csv: The plaintext CSV format.You can specify the CSV delimiter using the
options.csv_field_delimiterparameter.
Default value:
json.-
options.csv_field_delimiter(string, optional)# The single-character string that represents the CSV delimiter to use.
This parameter is only applicable if the
formatparameter is set tocsv.Default value:
,(comma character).-
file(object, optional)# The file for writing logs. The agent must have the privilege to write to this file. If the file does not exist, the agent creates it.
If this parameter is not specified, PPEM writes logs to
stdout.
HTTP Parameters #
The http section allows configuring HTTP server and client parameters, as well as multiple API-related parameters.
http:
server:
address: listen_network_address
port: listen_network_port
tls:
cert_file: public_certificate_file
key_file: private_key_file
timeout: HTTP_request_processing_timeout
security:
enabled: true_or_false
csp_policy: content_security_policy_header
cache_control: cache_control_header
pragma: pragma_header
expires: expires_header
frame_options: x_content_type_header
content_type_options: x_content_type_options_header
permissions_policy: permissions_policy_header
referrer_policy: referrer_policy_header
strict_transport_security: strict_transport_security_header
cross_origin_embedder_policy: cross_origin_embedder_policy_header
cross_origin_opener_policy: cross_origin_opener_policy_header
cross_origin_resource_policy: cross_origin_resource_policy_header
client:
timeouts:
http: HTTP_request_timeout
tls_handshake: TLS_handshake_timeout
dialer: HTTP_dialer_timeout
response_header: HTTP_response_header_wait_timeout
insecure_skip_verify: skip_server_certificate_verification
root_ca_files: [list_of_root_CA_certificate_files]
pagination:
max_page_size: maximum_objects_in_single_response
HTTP Server Parameters #
-
address(string, optional)# The network address to listen on.
If you specify an empty string, the server listens on all network interfaces.
Default value:
localhost.-
port(port number, optional)# The network port to listen on.
Default value:
8080.-
tls(object)# The TLS certificate parameters that are required to enable HTTPS on the server.
If you do not specify any certificate and key files (empty strings), the agent uses HTTP, not HTTPS.
-
timeout(time string, optional)# The processing timeout for an HTTP request.
Default value:
10s.-
security(object)# Security parameters of the HTTP server. These parameters are mostly used to set the values of the security-related HTTP headers.
You must configure the
cross-origin-*-policyparameters manually because PPEM does not provide default values for them.-
enabled(boolean, optional)# Specifies whether the processing of the security-related HTTP headers is enabled.
Default value:
false— processing is disabled.-
csp_policy(string, optional)# The value of the Content-Security-Policy HTTP response header. Helps to prevent XSS, clickjacking, and other code injection attacks.
Default value depends on whether the HTTP server is configured to handle HTTPS:
HTTP mode:
default-src 'none'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self'; connect-src 'self'; media-src 'self'; form-action 'self'; base-uri 'self'; frame-ancestors 'none'; frame-src https://postgrespro.com/; object-src 'none'.HTTPS mode:
default-src 'none'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self'; connect-src 'self'; media-src 'self'; form-action 'self'; base-uri 'self'; frame-ancestors 'none'; frame-src https://postgrespro.com/; object-src 'none'; upgrade-insecure-requests.
-
cache_control(string, optional)# The value of the Cache-Control HTTP header. Controls caching in browsers. The default value helps to prevent caching of API responses that may contain sensitive or dynamic data.
Default value:
no-store, no-cache, must-revalidate.-
pragma(string, optional)# The value of the Pragma HTTP header.
This header is deprecated and provides backward compatibility with HTTP/1.0 caches that do not support the Cache-Control HTTP header.
Default value:
no-cache.-
expires(string, optional)# The value of the Expires HTTP response header.
This header provides backward compatibility with HTTP/1.0 caches that do not support the Cache-Control HTTP header.
Default value:
0.-
frame_options(string, optional)# The value of the X-Frame-Options HTTP response header. Helps to prevent clickjacking attacks.
Default value:
""(empty string).-
content_type_options(string, optional)# The value of the X-Content-Type-Options HTTP response header. Helps to prevent MIME type sniffing attacks.
Default value:
""(empty string).-
permissions_policy(string, optional)# The value of the Permissions-Policy HTTP response header. Controls which browser features and device APIs can be used. The default value denies access to the features which may disclose sensitive information, such as camera, microphone, and geolocation.
Default value:
"accelerometer=(), autoplay=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()".-
referrer_policy(string, optional)# The value of the Referrer-Policy HTTP response header. Controls how much referrer information to include with requests.
Default value:
strict-origin-when-cross-origin.-
strict_transport_security(string, optional)# The value of the Strict-Transport-Security HTTP response header. Forces browsers to use HTTPS connections only. Applicable only if the HTTP server is configured to handle HTTPS, otherwise ignored.
Default value:
HTTP mode:
""(empty string) — not applicable.HTTPS mode:
max-age=31536000; includeSubDomains.
-
cross_origin_embedder_policy(string)# The value of the Cross-Origin-Embedder-Policy HTTP response header.
Default value:
""(empty string).-
cross_origin_opener_policy(string)# The value of the Cross-Origin-Opener-Policy HTTP response header.
Default value:
""(empty string).-
cross_origin_resource_policy(string)# The value of the Cross-Origin-Resource-Policy HTTP response header.
Default value:
""(empty string).
-
HTTP Client Parameters #
-
timeouts(object)# Timeouts for the HTTP client.
-
http(time string)# The HTTP request timeout.
Default value:
10s.-
tls_handshake(time string)# The TLS handshake timeout.
Default value:
2s.-
dialer(time string)# The dialer timeout when the client tries to reach the server. A connection attempt must succeed within this time interval.
Default value:
2s.-
response_header(time string)# The timeout of waiting for the HTTP response headers after sending an HTTP request to a server.
Default value:
10s.
-
-
insecure_skip_verify(boolean, optional)# Important
Using this parameter poses a security risk.
It is recommended to use it exclusively for testing and debugging purposes, but not in the production environment.
Specifies whether the verification of a server TLS certificate is disabled.
Default value:
false— the certificate is verified.-
root_ca_files(list of strings, optional)# The list of absolute paths to root CA certificates used to verify a server certificate.
Default value:
[](empty list) — the certificates from the operating system store are used.
JWT Session Parameters #
The jwt section allows configuring parameters related to JSON Web Tokens.
jwt: secret:secret_for_signing_JWTslifetime: access:access_token_lifetimerefresh:refresh_token_lifetime
-
secret(string)# The secret that is used to sign an issued token.
Refresh tokens are used to issue access tokens. Access tokens are used to authenticate users in PPEM.
For more information about these tokens, refer to Section 7.5.
Default value:
secret.-
lifetime(object)# The token lifetime values. A token that is valid longer than the specified value is considered expired and cannot be used. In such case, a new token must be issued.
OpenTelemetry (OTLP) Parameters #
The otlp section allows configuring parameters of the PPEM integration with the OpenTelemetry-compatible tracing tools.
otlp:
traces:
sampler_ratio: trace_sampling_ratio
exporter:
protocol: protocol_for_exporting_traces
endpoint_url: collector_endpoint_URL_for_exporting_traces
tls:
insecure_skip_verify: skip_collector_certificate_verification
-
traces(object)# The tracing parameters.
-
sampler_ratio(float, optional)# The percentage of traces that are sampled.
Depending on the parameter value, traces are sampled as follows:
0.0 <
sampler_ratio< 1.0: The specified percentage of traces is sampled.For example, the
0.7value means that 70% of traces are sampled.sampler_ratio≥ 1.0: All traces are sampled.Example value:
1.8.sampler_ratio≤ 0.0: No traces are sampled.Example value:
-3.3.
Default value:
1.0— All traces are sampled.-
exporter(object)# The exporter parameters.
-
protocol(enum, optional)# The OpenTelemetry protocol to use for exporting traces.
Possible values:
http: OTLP over HTTP.grpc: OTLP over gRPC.Empty string: Trace exporting is disabled.
Default value:
""(empty string) — trace exporting is disabled.-
endpoint_url(string, not empty)# The endpoint URL of the collector to be used by the exporter for sending traces.
The URL may contain a port number and path, but not a full or partial query string.
Examples:
For OTLP over HTTP:
http://localhost:4318/v1/traces.For OTLP over gRPC:
http://localhost:4317.
-
tls.insecure_skip_verify(boolean, optional)# Important
Using this parameter poses a security risk.
It is recommended to use it exclusively for testing and debugging purposes, but not in the production environment.
Specifies whether the verification of a server TLS certificate is disabled.
Default value:
false— the certificate is verified.
-
-