ppem-agent.yml

ppem-agent.yml — Файл конфигурации YAML для агента

Обзор #

Файл конфигурации агента расположен в /etc/ppem-agent.yml.

Вы можете указать способ обработки параметров с помощью специального параметра agent.remote_config.

После внесения любых изменений в файл конфигурации необходимо перезапустить службу агента:


systemctl restart ppem-agent

Файл конфигурации состоит из следующих разделов:

Общие параметры агента #

Раздел agent позволяет настраивать общие параметры агента.

agent:
  name: уникальное_имя_агента
  remote_config: true_или_false

  manager: {параметры_подключения_к_менеджеру}
  instance: {параметры_обнаружения_экземпляров}
  commands: {параметры_выполнения_команд}
  collectors: {параметры_сборщиков}
  system: {системные_параметры}

  reconnection_delay: базовая_задержка_между_попытками_повторного_подключения
  connect_timeout: тайм_аут_установки_подключения_к_менеджеру
  request_timeout: тайм_аут_запроса_JSON_RPC
  read_timeout: тайм_аут_чтения_из_потока_WebSocket
  write_timeout: тайм_аут_записи_в_поток_WebSocket
  ping_interval: интервал_отправки_пингов_менеджеру_для_проверки_состояния
  max_connections: максимальное_количество_подключений_к _экземплярам_СУБД

Основные параметры #

Перечисленные здесь основные параметры позволяют настроить главные аспекты работы агента.

name: уникальное_имя_агента
remote_config: true_или_false
name (string, необязательный) #

Уникальное имя агента.

PPEM использует это имя для разграничения агентов.

Значение по умолчанию: "" (пустая строка) — используется имя хоста операционной системы.

remote_config (boolean, необязательный) #

Некоторые параметры конфигурации агента совпадают с параметрами менеджера.

Файл конфигурации содержит специальный параметр remote_config.

Если для этого параметра указано значение true, значения, полученные удалённо от менеджера, имеют приоритет над значениями из файла конфигурации.

Значение по умолчанию: false — агент использует параметры из файла конфигурации.

Параметры подключения к менеджеру #

Подраздел agent.manager позволяет настроить параметры подключения к менеджеру.

url: URL-адрес_менеджера
api_key: API_ключ_для_подключения_к_менеджеру
tls:
  cert_file: файл_публичного_сертификата
  key_file: файл_закрытого_ключа
  root_ca_file: файл_корневого_сертификата_ca
  insecure_skip_verify: true_или_false
strict_address_checking: true_или_false
allowed_addresses: [список_разрешённых_адресов]
url (string, непустое значение) #

URL-адрес менеджера.

Значения для формирования URL-адреса можно получить из параметров менеджера http.server.address и http.server.port.

Значение по умолчанию: http://127.0.0.1:8080.

api_key (string, непустое значение) #

API-ключ для подключения к менеджеру.

Чтобы получить ключ:

  1. Войдите в веб-приложение.

  2. В навигационной панели перейдите в Главная.

  3. Если на странице отображается инструкция по установке агента, скопируйте ключ из инструкции.

  4. Если инструкции нет, выполните следующие действия:

    1. В навигационной панели перейдите в Инфраструктура → Агенты.

    2. В столбце Ключ аутентификации для любого агента нажмите либо , чтобы скопировать ключ, либо , чтобы посмотреть ключ.

tls (object) #

Параметры TLS-сертификата, необходимые для включения HTTPS и взаимной проверки TLS (mTLS) для агента.

Если механизм mTLS включён и настроен как на стороне менеджера, так и на стороне агента, то он добавляет дополнительный уровень безопасности.

cert_file (string, необязательный) #

Абсолютный путь к файлу публичного сертификата.

Значение по умолчанию: "" (пустая строка).

key_file (string, необязательный) #

Абсолютный путь к файлу закрытого ключа.

Значение по умолчанию: "" (пустая строка).

root_ca_file (string, необязательный) #

Абсолютный путь к корневому CA-сертификату, который используется для проверки сертификата менеджера.

Значение по умолчанию: "" (пустая строка).

отключить_проверку_безопасности (boolean, необязательный) #

Важно

Использование этого параметра представляет риск для безопасности.

Рекомендуется использовать его исключительно для тестирования и отладки, но не в эксплуатационной среде.

Указывает, отключена ли проверка TLS-сертификата менеджера.

Значение по умолчанию: false — сертификат проверяется.

strict_address_checking (boolean, необязательный) #

Указывает, включён ли механизм обеспечения безопасности IP Source Guard.

Когда этот механизм включён, агент используют IP-адреса из списка allowed_addresses при подключении к URL-адресу, указанному в параметре manager.url.

В этом случае не выполняется разрешение доменного имени.

Если для этого параметра указано значение false или список allowed_addresses пуст, IP-адрес извлекается напрямую из URL-адреса, либо определяется в процессе разрешения доменного имени.

Значение по умолчанию: false — механизм IP Source Guard не используется.

allowed_addresses (список строк, необязательный) #

Список IPv4- или IPv6-адресов, используемых, если для параметра manager.strict_address_checking указано значение true.

Значение по умолчанию: [] (пустой список).

Параметры обнаружения экземпляров #

Подраздел agent.instance позволяет настроить параметры обнаружения экземпляров.

connection_defaults:
  host: имя_хоста
  port: номер_порта
  database: имя_базы_данных
  user: имя_пользователя
  password: пароль_пользователя
  password_file: путь_к_файлу_паролей
  sslmode: режим_безопасного_подключения
  sslrootcert: путь_к_корневому_CA-сертификату
  sslcert: путь_к_клиентскому_SSL-сертификату
  sslkey: путь_к_закрытому_ключу_для_клиентского_SSL-сертификата
connection_defaults (object) #

Параметры, используемые агентом при подключении к обнаруженным экземплярам.

Если не указать параметры ssl* (указать пустые строки), агент подключается к экземплярам, используя небезопасные подключения.

За подробной информацией об этих параметрах обратитесь к официальной документации Postgres Pro по libpq.

host (string) #

Имя хоста для подключения.

Значение по умолчанию: localhost.

port (номер порта) #

Номер порта для подключения на хосте сервера.

Значение по умолчанию: 5432.

database (string) #

Имя базы данных.

Значение по умолчанию: postgres.

user (string) #

Имя пользователя для подключения.

Значение по умолчанию: postgres.

password (string, необязательный) #

Пароль пользователя.

В зависимости от содержимого файла конфигурации pg_hba.conf, пароль может быть обязательным или необязательным.

Вместо этого параметра пароль можно указать в файле паролей.

Значение по умолчанию: postgres.

password_file (string) #

Имя файла, используемого для хранения пароля пользователя.

Этот файл должен быть настроен с режимом доступа 0600, а также быть доступным пользователю операционной системы, от имени которого запущена служба агента.

Если указаны оба параметра — password и password_file, первый параметр имеет приоритет перед вторым.

sslmode (string, необязательный) #

Режим работы безопасного TCP/IP-соединения, защищённого SSL.

Значение по умолчанию: "" (пустая строка) — используется режим prefer.

sslrootcert (string, необязательный) #

Имя файла, содержащего SSL-сертификат(ы) центра сертификации (CA).

Значение по умолчанию: "" (пустая строка) — используются сертификаты из хранилища операционной системы.

sslcert (string, необязательный) #

Имя файла клиентского SSL-сертификата.

Значение по умолчанию: "" (пустая строка).

sslkey (string, необязательный) #

Имя файла закрытого ключа для клиентского SSL-сертификата.

Значение по умолчанию: "" (пустая строка).

Параметры выполнения команд #

Подраздел agent.commands позволяет настроить параметры выполнения команд.

Агент получает команды от менеджера и выполняет их.

max_workers: максимальное_количество_активных_рабочих_процессов
timeout: тайм_аут_выполнения_команд
feedback_interval: интервал_отправки_метаданных_команд
allowed_bindirs:
  paths: [список_путей_файловой_системы]
max_workers (integer, необязательный) #

Максимальное количество активных рабочих процессов, которые выполняют команды.

Если достигнуто максимальное количество рабочих процессов и все они заняты выполнением команд, новые поступающие команды ставятся в очередь до освобождения любого рабочего процесса.

Значение по умолчанию: 6.

timeout (time string, необязательный) #

Тайм-аут выполнения команд.

Если команда выполняется дольше указанного тайм-аута, её выполнение принудительно завершается.

Значение по умолчанию: 5h.

feedback_interval (time string, необязательный) #

Интервал отправки метаданных выполнения команд менеджеру.

Значение по умолчанию: 30s.

allowed_bindirs.paths (список строк, необязательный) #

Список путей файловой системы, из которых агент может выполнять команды.

Значение по умолчанию: [] (пустой список).

Параметры сборщиков, которые обнаруживают объекты #

Подраздел agent.collectors позволяет настроить параметры сборщиков.

Сборщики — это фоновые процессы, которые собирают различную информацию о серверном окружении и отправляют её менеджеру.

timeout: тайм_аут_цикла_обнаружения_для_сборщика
host:
  interval: интервал_между_циклами_сбора_данных
  bindirs:
    paths: [список_путей_файловой_системы_в_которых_можно_выполнять_поиск]
agent:
  interval: интервал_между_циклами_сбора_данных
instances:
  disabled: true_или_false
  interval: интервал_между_циклами_сбора_данных
instance_objects:
  batch_size: размер_пакета_для_отправки_в_одном_запросе
  interval: интервал_между_циклами_сбора_данных
  initial_delay: начальная_задержка_обнаружения
  jitter_interval: джиттер_начальной_задержки_обнаружения
  extended:
    enabled: true_или_false
    schedule: выражение_расписания_CRON
instance_settings:
  interval: интервал_между_циклами_сбора_данных
replication:
  interval: интервал_между_циклами_сбора_данных
timeout (time string, необязательный) #

Тайм-аут цикла обнаружения для сборщика.

Значение по умолчанию: 30m.

host (object) #

Параметры сборщика host.

Этот сборщик обнаруживает и собирает информацию об операционной системе, в которой запущена служба агента.

interval (time string, необязательный) #

Интервал между циклами сбора данных.

Значение по умолчанию: 1m.

bindirs.paths (список строк, необязательный) #

Список путей файловой системы для поиска исполняемых файлов и пакетов.

Этот список используется в качестве дополнения к списку commands.allowed_bindirs.paths.

Значение по умолчанию: [] (пустой список) — используются только пути, указанные в параметре commands.allowed_bindirs.paths.

agent (object) #

Этот сборщик обнаруживает и собирает информацию о запущенной службе агента.

interval (time string, необязательный) #

Интервал между циклами сбора данных.

Значение по умолчанию: 1m.

instances (object) #

Этот сборщик обнаруживает экземпляры.

disabled (boolean, необязательный) #

Указывает, отключено ли автоматическое обнаружение экземпляров.

Значение по умолчанию: false — автоматическое обнаружение включено.

interval (time string, необязательный) #

Интервал между циклами сбора данных.

Значение по умолчанию: 1m.

instance_objects (object) #

Этот сборщик обнаруживает различные объекты, существующие в экземплярах, такие как схемы, таблицы и т.д.

batch_size (integer, необязательный) #

Размер пакета для отправки в одном запросе менеджеру.

Этот параметр полезен, когда экземпляр содержит большое количество объектов.

Значение по умолчанию: 1000.

interval (time string, необязательный) #

Интервал между циклами сбора данных.

Значение по умолчанию: 1m.

initial_delay (time string, необязательный) #

Начальная задержка перед первым циклом сборки данных.

С помощью этого параметра можно снизить нагрузку на СУБД.

Значение по умолчанию: 0s — нет задержки.

jitter_interval (time string, необязательный) #

Значение джиттера для initial_delay.

Реальная начальная задержка становится случайной в диапазоне [initial_delay - jitter;initial_delay + jitter], что позволяет избежать перегрузки экземпляров запросами от сборщика.

Значение по умолчанию: 0s.

extended (object) #

Расширенные параметры обнаружения.

enabled (boolean, необязательный) #

Указывает, включено ли расширенное обнаружение объектов экземпляров.

Включение этого параметра может привести к снижению производительности, если экземпляр содержит большое количество объектов.

Значение по умолчанию: true — расширенное обнаружение включено.

schedule #

Выражение расписания CRON, определяющее время запуска расширенного процесса обнаружения объектов, например:

@every 5m

Расписание можно настроить так, чтобы процесс обнаружения запускался в моменты минимальной нагрузки на экземпляр. Например, в ночное время или в выходные дни.

Значение по умолчанию: "" (пустая строка) — используется значение instance_objects.interval × 5.

instance_settings (object) #

Этот сборщик обнаруживает параметры экземпляров.

interval (time string, необязательный) #

Интервал между циклами сбора данных.

Значение по умолчанию: 1m.

репликации (object) #

Этот сборщик обнаруживает конфигурацию репликации экземпляров.

interval (time string, необязательный) #

Интервал между циклами сбора данных.

Значение по умолчанию: 10s.

Системные параметры #

Подраздел agent.system позволяет настроить различные системные параметры.

systemd_units_path: путь_к_хранилищу_файлов_юнитов_systemd
postgresql_configs_path: путь_к_хранилищу_файлов_конфигурации_Postgres
systemd_units_path (string, необязательный) #

Путь к хранилищу, в котором агент хранит файлы юнитов systemd, необходимые для работы агента.

Значение по умолчанию: "" (пустая строка).

postgresql_configs_path (string, необязательный) #

Путь к хранилищу, в котором агент хранит файлы конфигурации PostgreSQL или Postgres Pro, необходимые для работы агента.

Значение по умолчанию: "" (пустая строка).

Параметры различных временных интервалов и тайм-аутов #

В этом разделе можно настроить различные временные интервалы и тайм-ауты.

reconnection_delay: базовая_задержка_между_попытками_повторного_подключения
connect_timeout: тайм_аут_установки_подключения_к_менеджеру
request_timeout: тайм_аут_запроса_JSON_RPC
read_timeout: тайм_аут_чтения_из_потока_WebSocket
write_timeout: тайм_аут_записи_в_поток_WebSocket
ping_interval: интервал_отправки_пингов_менеджеру_для_проверки_состояния
max_connections: максимальное_количество_подключений_к _экземплярам_СУБД
reconnection_delay (time string, необязательный) #

Базовая задержка между попытками повторного подключения при потере соединения с менеджером.

Реальная задержка является случайной и находится в диапазоне [0.75×base_delay;1.25×base_delay], что позволяет избежать перегрузки менеджера одновременными попытками подключения от нескольких агентов.

Значение по умолчанию: 2s.

connect_timeout (time string, необязательный) #

Тайм-аут установки подключения к менеджеру.

Если менеджер не отвечает в течение этого времени, агент пытается выполнить повторное подключение.

Значение по умолчанию: 2s.

request_timeout (time string, необязательный) #

Тайм-аут запросов JSON-RPC.

Значение по умолчанию: 2s.

read_timeout (time string, необязательный) #

Тайм-аут чтения из потока WebSocket.

Значение по умолчанию: 30s.

write_timeout (time string, необязательный) #

Тайм-аут записи в поток WebSocket.

Значение по умолчанию: 2s.

ping_interval #

Интервал отправки эхо-запросов менеджеру для поддержания существующего подключения (keep-alive).

Если значение не указано, автоматически используется значение, равное 80% от величины значения read_timeout.

max_connections (integer, необязательный) #

Максимальное количество одновременных подключений к экземплярам.

Значение по умолчанию: 0 — не ограничено.

Параметры автоматического обнаружения #

В этом разделе можно задать шаблон имени для экземпляров, обнаруженных автоматически.

autodiscovery:
  instance_name_template: шаблон_имени_экземпляра
instance_name_template (string, необязательный) #

Шаблон имени для экземпляров, обнаруженных автоматически.

Менеджер также поддерживает этот параметр. При этом значение из файла конфигурации агента имеет приоритет над значением, заданным в файле конфигурации менеджера.

Этот параметр используется агентом при регистрации экземпляра.

Шаблон должен представлять собой одну строку без переносов.

Поддерживаются следующие переменные: {{.Host}}, {{.HostName}}, {{.Port}}, {{.Version}}, {{.Edition}}, {{.ServiceType}}, {{.ClusterType}} и {{.SystemIdentifier}}.

Если полученное имя совпадает с именем существующего экземпляра, к нему добавляется числовой суффикс (-1, -2 и так далее).

Если шаблон не задан ни агентом, ни менеджером, используется шаблон по умолчанию instance-{ID}.

Значение по умолчанию: "" (пустая строка).

Параметры журналирования #

Раздел log позволяет настроить параметры журналирования агента.

log:
  level: уровень_журналирования
  format: формат_журналов
  options:
    csv_field_delimiter: символ_разделителя
  file:
    path: абсолютный_путь_к_файлу_журнала
    mode: режим_доступа_к_файлу_журнала
    rotation_age: интервал_ротации_файла_журнала
    rotation_size: размер_файла_журнала_для_ротации
level (enum) #

Уровень журналирования.

Возможные значения:

  • debug

  • info

  • warn

  • error

Каждый уровень журналирования включает в себя предыдущие, например warn содержит сообщения журнала уровней info и debug.

format (enum, необязательный) #

Формат журналирования.

Возможные значения:

  • json: формат JSON.

  • pretty: отформатированный формат JSON, например создаваемый утилитой jq.

  • csv: текстовый формат CSV.

    Разделитель CSV можно указать с помощью параметра options.csv_field_delimiter.

Значение по умолчанию: json.

options.csv_field_delimiter (string, необязательный) #

Строка из одного символа, которая используется в качестве разделителя CSV.

Этот параметр применим, только если для параметра format указано значение csv.

Значение по умолчанию: , (символ запятой).

file (object, необязательный) #

Файл для записи журналов. У агента должны быть права на запись в этот файл. Если файл не существует, агент создаёт его автоматически.

Если этот параметр не указан, PPEM записывает журналы в stdout.

PPEM выполняет ротацию файла журнала, если выполняется любое из следующих условий:

  • Служба ppem-agent получает сигнал SIGHUP.

  • Время жизни или размер файла журнала равен значению параметра rotation_age или rotation_size соответственно.

При ротации файла журнала PPEM сохраняет его и добавляет метку времени к его имени. Затем файл журнала, указанный в параметре path, очищается.

path (string, непустое значение) #

Абсолютный путь к файлу журнала, например /var/log/ppem.log.

mode (string, непустое значение) #

Числовая строка, которая определяет режим доступа к файлу в формате, аналогичном формату, используемому chmod, например 0644.

rotation_age (time string, необязательный) #

Максимальное время жизни отдельного файла журнала. По истечении этого времени создаётся новый файл.

Значение по умолчанию: "" (пустая строка) — смена файлов по времени жизни не производится.

rotation_size (string, необязательный) #

Максимальный размер отдельного файла журнала. При достижении этого размера создаётся новый файл.

Значение по умолчанию: "" (пустая строка) — смена файлов по размеру не производится.

Параметры HTTP #

Раздел http позволяет настроить параметры HTTP-сервера и клиента, а также несколько параметров, связанных с API.

http:
  server:
    address: сетевой_адрес_прослушивания
    port: сетевой_порт_прослушивания
    tls:
      cert_file: файл_публичного_сертификата
      key_file: файл_закрытого_ключа
    timeout: тайм_аут_обработки_HTTP_запросов
    security:
      enabled: true_или_false
      csp_policy: заголовок_content_security_policy
      cache_control: заголовок_cache_control
      pragma: заголовок_Pragma
      expires: заголовок_expires
      frame_options: заголовок_x_content_type
      content_type_options: заголовок_x_content_type_options
      permissions_policy: заголовок_permissions_policy
      referrer_policy: заголовок_referrer_policy
      strict_transport_security: заголовок_strict_transport_security
      cross_origin_embedder_policy: заголовок_cross_origin_embedder_policy
      cross_origin_opener_policy: заголовок_cross_origin_opener_policy
      cross_origin_resource_policy: заголовок_cross_origin_resource_policy

  client:
    timeouts:
      http: тайм_аут_HTTP_запросов
      tls_handshake: тайм_аут_TLS-рукопожатия
      dialer: тайм_аут_установки_подключения_к_серверу_для_HTTP
      response_header: тайм_аут_ожидания_заголовков_HTTP_ответа
    insecure_skip_verify: пропустить_проверку_сертификата_сервера
    root_ca_files: [список_файлов_корневых_сертификатов_CA]

  pagination:
    max_page_size: максимальное_количество_объектов_в_одном_ответе

Параметры HTTP-сервера #

address (string, необязательный) #

Сетевой адрес, на котором необходимо слушать.

Если указать пустую строку, сервер будет слушать на всех сетевых интерфейсах.

Значение по умолчанию: localhost.

port (номер порта, необязательный) #

Сетевой порт, на котором необходимо слушать.

Значение по умолчанию: 8080.

tls (object) #

Параметры TLS-сертификата, необходимые для включения HTTPS на сервере.

Если не указать файлы сертификата и ключа (пустые строки), агент использует HTTP вместо HTTPS.

cert_file (string) #

Абсолютный путь к файлу публичного сертификата.

Значение по умолчанию: "" (пустая строка).

key_file (string) #

Абсолютный путь к файлу закрытого ключа.

Значение по умолчанию: "" (пустая строка).

timeout (time string, необязательный) #

Тайм-аут обработки HTTP-запроса.

Значение по умолчанию: 10s.

security (object) #

Параметры безопасности HTTP-сервера. Эти параметры в основном используются для указания значений HTTP-заголовков, связанных с безопасностью.

Параметры cross-origin-*-policy необходимо настроить вручную, так как PPEM не предоставляет для них значений по умолчанию.

enabled (boolean, необязательный) #

Указывает, включена ли обработка HTTP-заголовков, связанных с безопасностью.

Значение по умолчанию: false — обработка отключена.

csp_policy (string, необязательный) #

Значение HTTP-заголовка ответа Content-Security-Policy. Помогает предотвратить XSS, кликджекинг и другие атаки с внедрением кода.

Значение по умолчанию зависит от того, настроен ли HTTP-сервер на работу с HTTPS:

  • Режим HTTP: 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: 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, необязательный) #

Значение HTTP-заголовка Cache-Control. Управляет кешированием в браузерах. Значение по умолчанию помогает предотвратить кеширование API-ответов, которые могут содержать конфиденциальные или постоянно изменяющиеся данные.

Значение по умолчанию: no-store, no-cache, must-revalidate.

pragma (string, необязательный) #

Значение HTTP-заголовка Pragma.

Этот заголовок является устаревшим и обеспечивает обратную совместимость с кешами HTTP/1.0, которые не поддерживают HTTP-заголовок Cache-Control.

Значение по умолчанию: no-cache.

expires (string, необязательный) #

Значение HTTP-заголовка ответа Expires.

Этот заголовок обеспечивает обратную совместимость с кешами HTTP/1.0, которые не поддерживают HTTP-заголовок Cache-Control.

Значение по умолчанию: 0.

frame_options (string, необязательный) #

Значение HTTP-заголовка ответа X-Frame-Options. Помогает предотвратить кликджекинг-атаки.

Значение по умолчанию: "" (пустая строка).

content_type_options (string, необязательный) #

Значение HTTP-заголовка ответа X-Content-Type-Options. Помогает предотвратить атаки с подменой MIME-типов.

Значение по умолчанию: "" (пустая строка).

permissions_policy (string, необязательный) #

Значение HTTP-заголовка ответа Permissions-Policy. Определяет, какие возможности браузера и API устройств могут быть использованы. Значение по умолчанию запрещает доступ к возможностям, которые могут раскрыть конфиденциальную информацию, таким как камера, микрофон и геолокация.

Значение по умолчанию: "accelerometer=(), autoplay=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()".

referrer_policy (string, необязательный) #

Значение HTTP-заголовка ответа Referrer-Policy. Определяет, какой объём информации о реферере включается в запросы.

Значение по умолчанию: strict-origin-when-cross-origin.

strict_transport_security (string, необязательный) #

Значение HTTP-заголовка ответа Strict-Transport-Security. Принудительно заставляет браузеры использовать только HTTPS-подключения. Применяется, только если HTTP-сервер настроен на работу с HTTPS, иначе игнорируется.

Значение по умолчанию:

  • Режим HTTP: "" (пустая строка) — не применимо.

  • Режим HTTPS: max-age=31536000; includeSubDomains.

cross_origin_embedder_policy (string) #

Значение HTTP-заголовка ответа Cross-Origin-Embedder-Policy.

Значение по умолчанию: "" (пустая строка).

cross_origin_opener_policy (string) #

Значение HTTP-заголовка ответа Cross-Origin-Opener-Policy.

Значение по умолчанию: "" (пустая строка).

cross_origin_resource_policy (string) #

Значение HTTP-заголовка ответа Cross-Origin-Resource-Policy.

Значение по умолчанию: "" (пустая строка).

Параметры HTTP-клиента #

timeouts (object) #

Тайм-ауты для HTTP-клиента.

http (time string) #

Тайм-аут HTTP-запроса.

Значение по умолчанию: 10s.

tls_handshake (time string) #

Тайм-аут TLS-рукопожатия.

Значение по умолчанию: 2s.

dialer (time string) #

Тайм-аут установки подключения, когда клиент пытается подключиться к серверу. Попытка подключения должна завершиться успешно в течение этого интервала времени.

Значение по умолчанию: 2s.

response_header (time string) #

Тайм-аут ожидания HTTP-заголовков ответа после отправки HTTP-запроса серверу.

Значение по умолчанию: 10s.

отключить_проверку_безопасности (boolean, необязательный) #

Важно

Использование этого параметра представляет риск для безопасности.

Рекомендуется использовать его исключительно для тестирования и отладки, но не в эксплуатационной среде.

Указывает, отключена ли проверка TLS-сертификата сервера.

Значение по умолчанию: false — сертификат проверяется.

root_ca_files (список строк, необязательный) #

Список абсолютных путей к корневым CA-сертификатам, которые используются для проверки сертификата сервера.

Значение по умолчанию: [] (пустой список) — используются сертификаты из хранилища операционной системы.

Параметры HTTP API-сервера #

pagination.max_page_size (integer, необязательный) #

Максимальное количество записей в одном API-ответе (размер страницы).

Значение по умолчанию: 100.

Параметры JWT-сеансов #

Раздел jwt позволяет настроить параметры, связанные с JSON Web Tokens.

jwt:
  secret: секрет_для_подписи_токенов_JWT

  lifetime:
    access: время_жизни_токена_доступа
    refresh: время_жизни_токена_обновления
secret (string) #

Секрет, используемый для подписи выпущенного токена.

Токены обновления используются для выпуска токенов доступа. Токены доступа используются для аутентификации пользователей в PPEM.

За подробной информацией об этих токенах обратитесь к Разделу 7.5.

Значение по умолчанию: secret.

lifetime (object) #

Значения времени жизни токенов. Токен, срок действия которого превышает указанное значение, считается истёкшим и не может быть использован. В таком случае необходимо выпустить новый токен.

access (time string) #

Время жизни токена доступа.

Значение по умолчанию: 30m.

refresh (time string) #

Время жизни токена обновления.

Значение по умолчанию: 24h.

Параметры OpenTelemetry (OTLP) #

Раздел otlp позволяет настроить параметры интеграции PPEM с инструментами трассировки, совместимыми с OpenTelemetry.

otlp:
  traces:
    sampler_ratio: коэффициент_выборки_трассировок
    exporter:
      protocol: протокол_экспорта_трассировок
      endpoint_url: URL_конечной_точки_для_экспорта_трассировок
      tls:
        insecure_skip_verify: пропустить_проверку_сертификата_сборщика
traces (object) #

Параметры трассировки.

sampler_ratio (float, необязательный) #

Процент трассировок, который подлежит выборке.

В зависимости от значения параметра выборка трассировок выполняется следующим образом:

  • 0.0 < sampler_ratio < 1.0: выборке подлежит указанный процент трассировок.

    Например, значение 0.7 означает, что выборке подлежит 70% трассировок.

  • sampler_ratio ≥ 1.0: выборке подлежат все трассировки.

    Пример значения: 1.8.

  • sampler_ratio ≤ 0.0: никакие трассировки не подлежат выборке.

    Пример значения: -3.3.

Значение по умолчанию: 1.0 — выборке подлежат все трассировки.

exporter (object) #

Параметры экспортера.

protocol (enum, необязательный) #

Протокол OpenTelemetry для экспорта трассировок.

Возможные значения:

Значение по умолчанию: "" (пустая строка) — экспорт трассировок отключён.

endpoint_url (string, непустое значение) #

URL-адрес конечной точки сборщика, используемый экспортером для отправки трассировок.

URL-адрес может содержать номер порта и путь, но не должен содержать полную или частичную строку запроса.

Примеры:

  • Для OTLP через HTTP: http://localhost:4318/v1/traces.

  • Для OTLP через gRPC: http://localhost:4317.

tls.insecure_skip_verify (boolean, необязательный) #

Важно

Использование этого параметра представляет риск для безопасности.

Рекомендуется использовать его исключительно для тестирования и отладки, но не в эксплуатационной среде.

Указывает, отключена ли проверка TLS-сертификата сервера.

Значение по умолчанию: false — сертификат проверяется.

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:

General Agent Parameters #

The agent section allows configuring general parameters of the agent.

agent:
  name: unique_agent_name
  remote_config: true_or_false

  manager: {manager_connection_parameters}
  instance: {instance_discovery_parameters}
  commands: {command_execution_parameters}
  collectors: {collector_parameters}
  system: {system_related_parameters}

  reconnection_delay: base_delay_between_reconnection_attempts
  connect_timeout: timeout_for_establishing_connection_to_manager
  request_timeout: JSON_RPC_request_timeout
  read_timeout: WebSocket_stream_read_timeout
  write_timeout: WebSocket_stream_write_timeout
  ping_interval: interval_of_keep_alive_pinging_manager
  max_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_name
remote_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_config parameter.

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_manager
api_key: API_key_for_connecting_to_manager
tls:
  cert_file: public_certificate_file
  key_file: private_key_file
  root_ca_file: root_ca_certificate_file
  insecure_skip_verify: true_or_false
strict_address_checking: true_or_false
allowed_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:

  1. Log in to the web application.

  2. In the navigation panel, go to Summary.

  3. If the agent installation instruction is displayed on the page, then copy the key from the instruction.

  4. If no instruction is displayed, then complete the following steps:

    1. In the navigation panel, go to Infrastructure → Agents.

    2. In the Authentication key column for any agent, click either to copy the key or to view the key.

tls (object) #

The TLS certificate parameters that are required to enable HTTPS and mutual TLS (mTLS) for the agent.

If mTLS is enabled and configured on both the manager and agent sides, it adds an additional layer of security.

cert_file (string, optional) #

The absolute path to the public certificate file.

Default value: "" (empty string).

key_file (string, optional) #

The absolute path to the private key file.

Default value: "" (empty string).

root_ca_file (string, optional) #

The absolute path to the CA certificate file used to verify the manager certificate.

Default value: "" (empty string).

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 the manager TLS certificate is disabled.

Default value: false — the certificate is verified.

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 false or the allowed_addresses list 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_host
  port: port_number
  database: database_name
  user: user_name
  password: user_password
  password_file: path_to_password_file
  sslmode: secure_connection_mode
  sslrootcert: path_to_root_CA_certificate
  sslcert: path_to_client_SSL_certificate
  sslkey: 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.conf configuration 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 0600 access mode, and be accessible by the operating system user on behalf of which the agent service runs.

If both password and password_file parameters 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) — the prefer mode 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_processes
timeout: command_execution_timeout
feedback_interval: time_interval_of_sending_command_metadata
allowed_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_collector
host:
  interval: interval_between_data_collection_iterations
  bindirs:
    paths: [list_of_searchable_filesystem_paths]
agent:
  interval: interval_between_data_collection_iterations
instances:
  disabled: true_or_false
  interval: interval_between_data_collection_iterations
instance_objects:
  batch_size: batch_size_to_send_in_single_request
  interval: interval_between_data_collection_iterations
  initial_delay: initial_discovery_delay
  jitter_interval: jitter_for_initial_discovery_delay
  extended:
    enabled: true_or_false
    schedule: CRON_schedule_expression
instance_settings:
  interval: interval_between_data_collection_iterations
replication:
  interval: interval_between_data_collection_iterations
timeout (time string, optional) #

The discovery loop timeout for a collector.

Default value: 30m.

host (object) #

The host collector 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 the commands.allowed_bindirs.paths parameter 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.

disabled (boolean, optional) #

Specifies whether the auto-discovery of instances is disabled.

Default value: false — auto-discovery is enabled.

interval (time string, optional) #

The interval between data collection iterations.

Default value: 1m.

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_storage
postgresql_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_attempts
connect_timeout: timeout_for_establishing_connection_to_manager
request_timeout: JSON_RPC_request_timeout
read_timeout: WebSocket_stream_read_timeout
write_timeout: WebSocket_stream_write_timeout
ping_interval: interval_of_keep_alive_pinging_manager
max_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.

Automatic Discovery Parameters #

This section allows specifying the naming template for automatically discovered instances.

autodiscovery:
  instance_name_template: instance_naming_template
instance_name_template (string, optional) #

A template for naming automatically discovered instances.

The manager also supports this parameter. The value specified in the agent configuration file takes precedence over the template specified in the manager configuration file.

This parameter is used by the agent when registering an instance.

The template must be a single line without line breaks.

The following variables are supported: {{.Host}}, {{.HostName}}, {{.Port}}, {{.Version}}, {{.Edition}}, {{.ServiceType}}, {{.ClusterType}}, and {{.SystemIdentifier}}.

If the resolved name matches an existing instance, a numeric suffix (-1, -2, etc.) is added.

If neither the agent nor the manager provides a template, the default naming pattern instance-{ID} is used.

Default value: "" (empty string).

Logging Parameters #

The log section allows configuring logging parameters for the agent.

log:
  level: logging_level
  format: log_format
  options:
    csv_field_delimiter: delimiter_character
  file:
    path: absolute_path_to_log_file
    mode: access_mode_of_log_file
    rotation_age: rotation_age_of_log_file
    rotation_size: rotation_size_of_log_file
level (enum) #

The log level.

Possible values:

  • debug

  • info

  • warn

  • error

Each log level includes the previous one, for example, warn includes log messages of the info and debug levels.

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_delimiter parameter.

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 format parameter is set to csv.

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.

PPEM rotates the log file if any of the following conditions is met:

  • The ppem-agent service receives the SIGHUP signal.

  • The age or size of the log file equals to the value of the rotation_age or rotation_size parameter, respectively.

When rotating the log file, PPEM saves it and appends a timestamp to its name. Then the log file specified in the path parameter is cleared.

path (string, not empty) #

The absolute path to the log file, for example, /var/log/ppem.log.

mode (string, not empty) #

The numeric string that represents the file access mode in the format similar to the one chmod uses, for example, 0644.

rotation_age (time string, optional) #

The maximum amount of time to use an individual log file. After this time a new log file is created.

Default value: "" (empty string) — the time-based creation of new log files is disabled.

rotation_size (string, optional) #

The maximum size of an individual log file. After this amount of data is emitted into a log file, a new log file is created.

Default value: "" (empty string) — the size-based creation of new log files is disabled.

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.

cert_file (string) #

The absolute path to the public certificate file.

Default value: "" (empty string).

key_file (string) #

The absolute path to the private key file.

Default value: "" (empty string).

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-*-policy parameters 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.

HTTP API Server Parameters #

pagination.max_page_size (integer, optional) #

The maximum number of entries in a single API response (the page size).

Default value: 100.

JWT Session Parameters #

The jwt section allows configuring parameters related to JSON Web Tokens.

jwt:
  secret: secret_for_signing_JWTs

  lifetime:
    access: access_token_lifetime
    refresh: 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.

access (time string) #

The lifetime of an access token.

Default value: 30m.

refresh (time string) #

The lifetime of a refresh token.

Default value: 24h.

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

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.

FAQ