Руководство по системному администрированию#

Аннотация#

Настоящий документ представляет собой руководство по системному администрированию программного компонента Веб-сервер и обратный прокси-сервер SynGX (SNGX) из состава программного продукта Platform V SynGX (SNX). Программный компонент Веб-сервер и обратный прокси-сервер SynGX (далее - SynGX) является системным программным обеспечением (СПО).

Руководство содержит сценарии администрирования SynGX, а также описание событий системного журнала и мониторинга.

Термины и определения#

Сценарии администрирования#

Администрирование#

Подключение к VM (VM - виртуальная машина), на которых установлен Продукт SynGX, для выполнения действий администрирования, должно осуществляться по протоколу SSH с использованием SSH-ключей.

Администрирование проводится от имени пользователя syngx, созданного ранее при установке SynGX.

Перечень доступных стандартных сценариев администрирования SynGX:

• Запуск SynGX;

• Остановка SynGX;

• Перезапуск SynGX;

• Изменение конфигурации SynGX;

• Проверка корректности конфигурации с точки зрения SynGX;

• Обновление версии SynGX (см. Руководство по установке);

• Удаление SynGX (см. Руководство по установке);

• Получение логов (см. раздел События системного журнала);

• Получение метрик (см. раздел События мониторинга).

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

Описание основных сценариев администрирования#

В данном разделе будут описаны основные сценарии администрирования - запуск, остановка и перезагрузка конфигурации Продукта.

Предполагается, что SynGX уже установлен на сервере и произведена первичная настройка конфигурации Продукта.

Запуск SynGX

Важно: (опционально; обязательно при интеграции с HashiCorp Vault-решением) если требуется интеграция SynGX с HashiCorp Vault (либо Secret Management System (SecMan)), то перед запуском необходимо произвести настройку конфигурационного файла согласно разделу «Настройка интеграции SynGX с HashiCorp Vault» ниже.

В начале переходим под учётную запись ОС с административными правами:

$ sudo su 

Затем необходимо прописать переменные окружения для пакета, выполнив команду:

$ source /etc/environment

После чего, нужно убедиться, что syngx не запущен, - проверить c помощью команды ps -ef | grep syngx.

Теперь можно произвести запуск SynGX (варианты на выбор):

• Запуск с базовой конфигурацией SynGX:

$ syngx

• Запуск SynGX с отличной от базовой конфигурацией:

$ syngx -c /<путь к требуемому конфигурационному файлу>

• Запуск SynGX с использованием команды systemctl:

$ systemctl start syngx.service

Тем самым, будет произведен запуск SynGX.

Опцианально, если требуется, чтобы SynGX автоматически запускался после перезагрузки ОС, это можно сделать, выполнив команду:

$ systemctl enable syngx.service

Управление SynGX

Когда SynGX запущен, им можно управлять, вызывая исполняемый файл с параметром -s. Ниже показан базовый синтаксис:

syngx -s сигнал

Флаг -s отправляет сигнал главному процессу SynGX.

Вместо «сигнал» нужно подставить одно из следующих значений для управления процессом SynGX:

• stop — быстрое завершение работы SynGX: немедленно завершает все процессы SynGX, останавливает обслуживание полученных запросов;

• quit — плавное завершение работы SynGX: останавливает процессы SynGX после завершения обработки полученных до команды запросов;

• reload — перезагрузка (применение) конфигурации: позволяет применить новую конфигурацию без остановки работы SynGX. Запросы, которые были получены до перезагрузки SynGX, будут обрабатываться согласно старой конфигурации, а новые запросы - согласно новой конфигурации.

Как происходит перезагрузка конфигурационного файла: получив соответствующий сигнал, главный процесс проверяет правильность синтаксиса нового конфигурационного файла и пытается применить конфигурацию, содержащуюся в нем. Если это ему удается, главный процесс запускает новые рабочие процессы и отправляет сообщения старым рабочим процессам требование завершиться. Если не получается применить новую конфигурацию, главный процесс откатывает изменения и продолжает работать со старой конфигурацией. Старые рабочие процессы, получив команду завершиться, прекращают принимать новые запросы и продолжают обслуживать текущие запросы до тех пор, пока все такие запросы не будут обслужены. После чего старые рабочие процессы завершаются.

Настройка способов балансировки нагрузки и распределения запросов при проксировании#

SynGX поддерживает следующие способы балансировки нагрузки и распределения запросов при проксировании:

• (Weighted) Round Robin - запросы распределяются по узлам в группе балансировки циклически в соответствии с весами узлов. Если вес узла не указан явно, он считается равным 1. Это алгоритм используется по умолчанию в upstream и может использоваться для протоколов HTTP, TCP и UDP.

• (Weighted) Least Connections – запрос посылается на узел в группе балансировки с наименьшим количество активных соединений в соответствии с весами узлов. Если вес узла не указан явно, он считается равным 1. Для использования данного метода балансировки, необходимо указать директиву least_conn в секции upstream. Этот алгоритм может использоваться для протоколов HTTP, TCP и UDP.

• IP Hash – узел в группе балансировки, на который будет отправлен запрос, определяется на основании IP клиента. Этот метод гарантирует, что запросы с одного IP-адреса будут направляться на один тот же узел, пока он работоспособен. Для использования данного метода балансировки необходимо указать директиву ip_hash в секции upstream. Этот алгоритм может использоваться для протоколов HTTP.

• Hash - узел в группе балансировки, на который будет направлен запрос, определяется на основании определенного в конфигурации ключа, который может быть строкой, переменной или их комбинацией. Для использования данного метода балансировки необходимо указать директиву hash с параметрами в секции upstream. Этот алгоритм может использоваться для протоколов HTTP, TCP и UDP.

• Random - запрос передаётся случайно выбранному узлу в группе балансировки в соответствии с весами узлов. Для использования данного метода балансировки необходимо указать директиву random в секции upstream. Этот алгоритм может использоваться для протоколов HTTP, TCP и UDP.

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

Пример задания способа балансировки:

    upstream myapp1 {
        <способ балансировки>;
        server srv1.example.com weight=2;
        server srv2.example.com;
        server srv3.example.com;
    }

Примечание: параметр weight опционален.

Помимо выше перечисленных способов балансировки, можно настроить прилипание по cookie (sticky session) - для запросов по протоколу HTTP.

При использовании протокола HTTP SynGX может добавлять cookie в ответ на первый запрос клиента с тем, чтобы все последующие запросы с этой cookie попадали на один и тот же узел в группе балансировки (действует при условии, что клиент согласился за использование cookie). Эту функциональность предоставляет модуль nginx-sticky-module-ng. Для этого необходимо указать директиву sticky (вместо <способ балансировки>) с параметрами в секции upstream. Он работает следующим образом:

1. первый запрос от клиента без cookie распределяется на узел в группе балансировки с использованием Round Robin-способа балансировки;

2. в ответ на первый запрос SynGX добавляет cookie, значение которой в последующих запросах будет использоваться при выборе узла в группе балансировки.

3. при последующих запросах от клиента с cookie, запросы будут проксироваться на первоначально выбранный узел в группе балансировки.

Пример настройки прилипания (sticky) приведен ниже:

upstream {
  sticky [name=route] [domain=.foo.bar] [path=/] [expires=1h] [hash=index|md5|sha1] [no_fallback] [secure] [httponly];

  server 127.0.0.1:9000;
  server 127.0.0.1:9001;
  server 127.0.0.1:9002;
}

Примечание: в [] приведен формат записи для каждого параметра директивы.

Синтаксис:

name: устанавливает имя файла cookie, используемого для привязки к узлу в группе балансировки (upstream-серверу); default: route.

domain: установливает доменное имя файла; default: nothing. Если данное поле не заполнено, данные будут браться на основе данных браузера (клиента).

path: задает путь URL, используемый файлом cookie, корневым каталогом по умолчанию; default: / - означает, что разрешено для всех location URI.

expires: срок действия файла cookie (сессии куки); default: nothing. Ограничение: значение должно быть больше 1 секунды.

hash: параметр, который задействует хэш-алгоритм для присвоения уникального значения узлу в группе балансировки (upstream-сервера). Ограничение: нельзя использовать с hmac; default: md5. Возможные значения:

• md5|sha1: хэш-алгоритм по md5 либо sha1;

• index: (не использует хеш-алгоритм) будет использоваться индекс в списке памяти (in-memory index). Увеличивает скорость обработки cookie, но может приводить к неправильному выбору узла: при перезагрузке системы, если список узлов в группе балансировки (upstreams-серверы) изменился, то значениям индексов могут быть присвоены другие значения узлов в группе балансировки (привязки к серверам не гарантируется). Используйте данный алгоритм с осторожностью!

hmac: параметр, который задействует хэш-механизм hmac для присвоения уникального значения узлу в группе балансировки (upstream-сервера); используется как альтернатива конструкции hash (не может быть использован совместно с hash). Он похож на хэш-механизм hash, но использует hmac_key для обеспечения безопасности хэширования. default: none. hmac имеет конструкцию вида [hmac=md5|sha1 hmac_key=<foobar_key>]. Возможные значения:

• md5|sha1: хэш-алгоритм по md5 либо sha1;

• hmac_key: ключ для использования с hmac.

no_fallback: флаг; когда выставлен данный флаг, Nginx будет выдавать ответ 502 (Bad Gateway or Proxy Error) на запросы с cookie при недоступном узле (который соответствует данной cookie) в группе балансировки.

secure: включает защиту cookies (Добавляет атрибут Secure в cookie); используется только при HTTPS-соединениях. Таким образом, при включении данного параметра, secure куки будут отсылаться на сервер только тогда, когда запрос отправляется по протоколу TLS (HTTPS).

httponly: не позволяет использовать cookies в JS. Добавляет атрибут HttpOnly в файл cookie. Куки HTTPonly не доступны из JavaScript через свойства Document.cookie API, что помогает избежать межсайтового скриптинга (XSS). Устанавливайте этот флаг для тех кук, к которым не требуется обращаться через JavaScript.

Пример части конфигурации SynGX с директивой sticky:

upstream sticky_session {
    sticky name=test_sticky_session expires=1h path=/;

    server 127.0.0.1:9000;
    server 127.0.0.1:9001;
    server 127.0.0.1:9002;
}

Подключение динамических модулей SynGX#

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

Ниже представлен список модулей с динамическим подключением:

Необходимые действия для подключения динамического модуля:

1. (опционально; пройти этот шаг 1, если требуется установка динамических модулей ngx_http_lua_module, ngx_stream_lua_module либо ngx_http_set_misc_module) Установить и добавить в конфигурационный файл SynGX (файл с расширением .conf) модуль ndk_http_module (контекст main). Без него подключить модуль ngx_http_lua_module, ngx_stream_lua_module либо ngx_http_set_misc_module будет нельзя!

   • Для установки модуля ndk_http_module в командной строке необходимо выполнить команду (пример команды): $sudo yum install ndk_http_module.rpm .

   • После чего в конфигурационном файле SynGX (файл с расширением .conf) требуется добавить директиву с указанием пути к файлу ndk_http_module.so (контекст main). Пример задания директивы: load_module /opt/syngx/modules/ndk_http_module.so .

2. Установить модуль(-и) из RPM-пакета(-в) и добавить в конфигурационный файл (файл с расширением .conf) директиву(-ы) подключения модуля(-ей) (контекст main):

   • установить требуемый(-ые) динамический(-ие) модуль(-и). Для этого нужно для каждого модуля выполнить команду $sudo yum install {module_name}.rpm. Где {module_name} - название модуля (см. в таблице выше, названия динамических модулей SynGX даны в скобках);

   • после чего в конфигурационном файле SynGX (файл с расширением .conf) требуется добавить директиву(-ы) с указанием пути(-ей) к файлу(-ам) динамических модулей (контекст main). Пример задания директивы: load_module /opt/syngx/modules/{module_name}.so .

3. После выполнения действий в шаге 2 необходимо выполнить перезагрузку конфигурационного файла SynGX сигналом reload.

Пример указания динамических модулей в конфигурационном файле SynGX (часть конфигурации SynGX):

Важно!:

• при применении директив из модуля ngx_http_set_misc_module следует использовать актуальные криптостойкие алгоритмы, исходя из требований эксплуатирующей организации (не следует использовать слабые криптографиеские алгоритмы, например, SHA-1 либо SSHA).

Настройка интеграции SynGX с HashiCorp Vault#

Описание

Примечание: возможно использование как HashiCorp Vault, так и Secret Management System/SecMan. Далее по тексту интеграцию с HashiCorp Vault (упоминание HashiCorp Vault) считать аналогичным интеграции с Secret Management System/SecMan.

Описание интеграции SynGX с HashiCorp Vault приведено в Детальной архитектуре SynGX. Краткая информация для администратора:

SynGX может получать сертификаты и закрытые ключи сертификатов из движка секретов PKI Hashicorp Vault и использовать их вместо следующих директив в секциях http и stream:

• http/ssl_certificate, http/ssl_certificate_key

• http/proxy_ssl_certificate, http/proxy_ssl_certificate_key

• http/snx_ahc_ssl_certificate, http/snx_ahc_ssl_certificate_key

• stream/ssl_certificate, stream/ssl_certificate_key

• stream/proxy_ssl_certificate, stream/proxy_ssl_certificate_key

• stream/snx_ahc_ssl_certificate, stream/snx_ahc_ssl_certificate_key

Функциональность получения сертификатов и закрытых ключей сертификатов из движка секретов PKI Hashicorp Vault обеспечивает динамический модуль ngx_hashicorp_vault, который должен быть подключен в конфигурации SynGX.

Модуль работает следующим образом:

• после старта SynGX:

1. с помощью указанных в конфигурации секретов проходит аутентификацию и авторизацию в HashiCorp Vault и получает необходимые для дальнейшей работы токены;

2. с помощью полученных на предыдущем шаге токенов запрашивает в HashiCorp Vault все определенные в конфигурации SynGX сертификаты;

3. для каждого сертификата разделяет ответ на две части - публичную часть сертификата вместе с цепочками доверия и закрытый ключ сертификата. Публичная часть сертификата вместе с цепочками доверия сохраняется на файловой системе на VM SynGX. Закрытый ключ хранится в hashicorp_shm_zone (shared memory), доступ - только у «syngx privileged agent process» (привилегированный агент процесс) и master process (мастер процесс). Обе части используются для инициализации в памяти значений переменных для сертификатов, которые указываются в конфигурации.

• во время работы SynGX:

1. проверяет срок действия сертификатов, и при приближении к дате окончания действия сертификата - запрашивает новый сертификат, обновляет публичную часть сертификата на файловой системе, обновляет в памяти соответствующие переменные и перезагружает SynGX;

2. при перезагрузке SynGX, в том числе, при изменении конфигурации - проверяет наличие в конфигурации директив для работы с Hashicorp Vault и наличие в памяти соответствующих публичных частей сертификатов и закрытых ключей сертификатов;

3. предоставляет метрики по взаимодействию с Hashicorp Vault;

4. запись в error log событий, связанных с взаимодействием с Hashicorp Vault.

Настройка модуля ngx_hashicorp_vault_module

Ниже будет дана информация о настройках динамического модуля ngx_hashicorp_vault_module, который обеспечивает интеграцию SynGX с HashiCorp Vault.

Поддержка TLS: модуль поддерживает обращение к Hashicorp Vault с использованием протокола TLS версии не ниже 1.2

Пререквизиты для интеграции SynGX с HashiCorp Vault (что необходимо сделать перед настройкой интеграции SynGX с HashiCorp Vault):

1. наличие и штатная работа HashiCorp Vault в сети;

2. до запуска SynGX на сервер SynGX администратором загружены актуальные role_id и wrapped_token.

3. установлен модуль ngx_hashicorp_vault_module из RPM пакета, и добавлены директивы для работы модуля в конфигурацию SynGX. Описание шагов установки и подключения приведено в разделе «Подключение динамических модулей SynGX».

Для включения возможности интеграции SynGX с HashiCorp Vault необходимо в конфигурации syngx.conf (конфигурационный файл SynGX с расширением .conf; далее будем обозначать как syngx.conf):

• задать директиву delayed_load_cert (контекст: main); после чего указать директивы и параметры к ним для получения сертификатов (конфигурация для интеграции с с HashiCorp Vault);

• потом задать директивы для использования сертификатов.

Ниже будет дан пример части конфигурации с параметрами для интеграции с HashiCorp Vault.

Пример части конфигурации для интеграции с HashiCorp Vault

...

delayed_load_cert;

hv_pki secman_1 {
    host <адрес SecMan>; # SecMan hostname, обязательный параметр
    port 8443;  # SecMan port, обязательный параметр
    api_version v1; # версия api Hashicorp Vault, необязательный параметр, если не указан - используется значение по умолчанию - v1
    namespace DEV_TEST; # используется для получения токена и генерации сертификата (заголовок X-Vault-Namespace), обязательный параметр

    # параметры для аутентификации и получения токена, который будет использоваться установкой заголовка "X-Vault-Token:"
    auth_approle {
       role_id_file /opt/secman/syngx/roleid.txt; #обязательный параметр
       wrapped_token_file /opt/secman/syngx/wrapped_token2.txt; # обязательный параметр 

    # параметры для ssl соединения с Secman - необязательные
    #    hv_ssl_trusted_certificate /home/syngx/syngx/tests/cert/ca.crt;
    #    hv_ssl_verify on; # default off
    #    hv_ssl_protocols TLSv1.2;
    #    hv_ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;  
    }

    # параметры для поиска или генерации сертификата. 
    get_cert cert1 {
        path PKI; # path - путь до хранилища (он же PKI), обязательный параметр
        role role-secman-snx; # роль, обязательный параметр

        email test@example.ru;  # Почтовый адрес владельца сертификата для отправки уведомлений от УЦ, обязательный параметр  
        common_name test.app.yyy; # Указывает CN для сертификата, обязательный параметр    
        # alt_names example.ru; # Указывает SAN в списке, необязательный параметр, если не указан - не используется

        save_certificate_path /opt/syngx/ssl/server3.crt; # путь для сохранения публичной части сертификата, обязательный параметр
    }

    get_cert cert2 {
        path PKI; # path - путь до хранилища (он же PKI), обязательный параметр
        role role-secman-snx2; # роль, обязательный параметр

        email test@example.ru;  # Почтовый адрес владельца сертификата для отправки уведомлений от УЦ, обязательный параметр  
        common_name test.app.yyy; # Указывает CN для сертификата, обязательный параметр    

        save_certificate_path /opt/syngx/ssl/server4.crt; # путь для сохранения публичной части сертификата, обязательный параметр
    }
}
...

Описание параметров

Параметры format и private_key_format в конфигурации не указываются, но при обращении в SecMan они указываются со значением pem.

Параметр method (метод получения) в конфигурации не указываются, но при обращении в SecMan он указываются со значением fetch.

Полный список параметров для интеграции с Secret Management System/SecMan можно изучить в документации на данную систему (Руководство администраторов АС по выпуску сертификатов через плагин SbrCA).

Примечание: SynGX не поддерживает метод passphrase. Остальные - поддерживает.

Описание и настройка директив для использования сертификатов

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

1. Для настройки TLS между клиентом и SynGX (работа в режиме веб-сервера) - вместо директив ssl_certificate, ssl_certificate_key:

   • указать директиву и параметры (approle:роль) вида: hv_pki_ssl_certificate      secman_2:cert1 .

2. Для настройки TLS между SynGX и узлами в группе балансировки (работа в режиме прокси-сервера) - вместо директив proxy_ssl_certificate, proxy_ssl_certificate_key:

   • указать директиву и параметры (approle:роль) вида: hv_pki_proxy_ssl_certificate      secman_1:cert2 .

3. Для настройки TLS при активной проверке работоспособности узлов в группе балансировки - вместо директив snx_ahc_ssl_certificate и snx_ahc_ssl_certificate_key:

   • указать директиву и параметры (approle:роль) вида: hv_pki_ahc_ssl_certificate      secman_1:cert1.

Примечание: approle:роль могут называться произвольным образом - в зависимости от заданных <имя approle> и <имя роли> в настройках с HashiCorp Vault.

Ниже дан пример частей конфигурации с указанием директив для использования сертификатов и ключей при активной проверке узлов в группе балансировки, обработке запросов в качестве веб-сервера и при проксировании запросов с использованием TLS-соединения (будут использоваться approle, роль, полученные из HashiCorp Vault).

Примечание: approle и роль (например: secman_1:cert1) для получения сертификатов и ключей можно задавать как в контексте http, так и в контексте stream.

...
    upstream cluster_https {
        server 127.0.0.1:8997;

        check interval=3000 rise=2 fall=5 timeout=2000 type=https;
        hv_pki_ahc_ssl_certificate      secman_1:cert1;
...
    server {
	    listen 8998 ssl;
        listen [::]:8998 ssl;

        hv_pki_ssl_certificate      secman_2:cert1;

        location /xxx_https {
            return 200 "Upstream 8998! Hello world TLS\n";
        }
        location / {
            return 200;
        }
    }
...
    server
    {
...
        location /xxx_https {
            proxy_pass https://cluster_https;

            hv_pki_proxy_ssl_certificate      secman_1:cert2;
        }

Настройка активной проверки работоспособности узлов (active healthcheck)#

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

Функционал активного healthcheck предоставляют модули ngx_stream_upstream_check_module и nginx_upstream_check_module:

Для настройки активной проверки работоспособности на уровне секции http (L7 уровень модели OSI) с помощью модуля nginx_upstream_check_module и/или на уровне секции stream (L4 уровень модели OSI) с помощью модуля ngx_stream_upstream_check_module необходимо добавить директиву check в контекст директивы upstream.

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

• Round Robin;

• Least Connections;

• Hash;

• IP Hash.

Для информации: узел (server) в секции upstream - это peer в терминологии модуля.

Параметры директивы check:

• interval (milliseconds) - интервал опроса узлов в группе балансировки;

• fall (count) - количество неуспешных запросов, чтобы считать, что узел не доступен;

• rise (count) - количество успешных запросов, чтобы включить узел в балансировку;

• timeout (milliseconds) - timeout для запроса к узлу;

• default_down (true/false) - статус узла по умолчанию. true - узел не доступен для балансировки, false - узел доступен для балансировки (опционально);

• port (число) - указывает порт узла, который отличается от заданного в конфигурации в директиве server. Значением по умолчанию является 0, что означает, что порт такой же, как в директиве server.

• type (строка) - указывает необходимый тип проверки работоспособности. Возможные значения: для http - tcp, ssl_hello, http, https; для stream - udp, tcp, http, ssl_hello, tcp_tls.

Описание типов проверки:

Примечание: описание директив см. ниже.

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

http {
    upstream <название кластера> {
        # simple round-robin
        server <ip-адрес узла>:<port>;
        server <ip-адрес узла>:<port>;
        check interval=3000 rise=2 fall=5 timeout=5000 default_down=true type=tcp;
    }
    server {
        listen 522;
        proxy_pass <название кластера>;
    }
    ...
}

Ниже приведен пример базовой конфигурации для активной проверки работоспособности узлов на уровне секции stream:

stream {
    upstream <название кластера> {
        # simple round-robin
        server <ip-адрес узла>:<port>;
        server <ip-адрес узла>:<port>;
        check interval=3000 rise=2 fall=5 timeout=5000 default_down=true type=udp;
    }
    server {
        listen 522;
        proxy_pass <название кластера>;
    }
    ...
}

Дополнительные директивы, необходимые для разных типов проверки:

Описание дополнительных директив: (каждая прописывается в отдельной строке)

• check_http_send (string; Default для типов проверки http, https: "GET / HTTP/1.1\r\nHost: <имя хоста>\r\nConnection: close\r\nsyngx-http-active-healthcheck: true\r\n\r\n", Default для остальных типов: ""). Эта инструкция может настроить контент запроса, отправленный модулем. Если строка для tcp типа не задана - будет произведена попытка установить соединение с узлом в группе балансировки, но запрос отправляться не будет; установление соединения будет означать успешное прохождение проверки. Директива доступна только в секции http/upstream.

• check_http_expect_alive (syntax: [ http_2xx | http_3xx | http_4xx | ⁣http_5xx ]; Default: http_2xx | http_3xx). Задает коды ответа, которые будут означать успешность прохождения проверки. Директива доступна только в секции http/upstream.

• check_send (string; Default для типа проверки http: "GET / HTTP/1.1\r\nHost: <имя хоста>\r\nConnection: close\r\nsyngx-stream-active-healthcheck: true\r\n\r\n", Default для остальных типов: ""). Эта инструкция может настроить контент запроса, отправленный модулем. Если строка для tcp типа не задана - будет произведена попытка создать соединение с узлом в группе балансировки, но запрос отправляться не будет; установление соединения будет означать успешное прохождение проверки. Директива доступна только в секции stream/upstream.

• check_expect_alive (string; Default: none). Строка для сравнения успешного состояния ответа. Сравнение ответа с параметром происходит по минимальной длине. Если параметр не указан, то строка ответа не сравнивается и запрос считается успешным. Директива доступна только в секции stream/upstream.

Дополнительные директивы для поддержки запросов active healthcheck по TLS

Если требуется поддержка TLS, нужно выпустить SSL сертификаты и добавить параметры в конфигурацию. Каждая директива прописывается в отдельной строке.

• snx_ahc_ssl_certificate (файл; Default: none). Задаёт файл с сертификатом в формате PEM для аутентификации на upstream HTTPS-сервере. Можно использовать переменные.

• snx_ahc_ssl_certificate_key (файл; Default: none). Задаёт файл с секретным ключом в формате PEM для аутентификации на узле в группе балансировки. Вместо файла можно указать значение engine:имя:id (1.7.9), которое загружает ключ с указанным id из OpenSSL engine с заданным именем. Можно использовать переменные.

• snx_ahc_ssl_ciphers (шифры; Default: snx_ahc_ssl_ciphers DEFAULT). Описывает разрешенные шифры, которые будут использоваться при отправке запроса health check к узлу в группе балансировки. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL. Полный список можно посмотреть с помощью команды «openssl ciphers».

• snx_ahc_ssl_name (имя; Default: snx_ahc_ssl_name $peer_name). Позволяет переопределить имя сервера, используемое при проверке сертификата узла в группе балансировки, а также для передачи его через SNI при установлении соединения с узлов в группе балансировки. По умолчанию используется имя хоста из URLа upstream сервера.

• snx_ahc_ssl_protocols (TLSv1.2/TLSv1.3; Default: TLSv1.2). Разрешает указанные протоколы для запросов к узлу в группе балансировки.

• snx_ahc_ssl_server_name (on/off; Default: off). Разрешает или запрещает передачу имени сервера через расширение Server Name Indication протокола TLS (SNI, RFC 6066) при установлении соединения с узлов в группе балансировки.

• snx_ahc_ssl_trusted_certificate (файл; Default: -). Задаёт файл с доверенными сертификатами CA в формате PEM, используемыми при проверке сертификата узла в группе балансировки.

• snx_ahc_ssl_verify (on/off; Default: off). Включает или выключает проверку сертификата узла в группе балансировки.

• snx_ahc_ssl_verify_depth (число; Default: 1). Устанавливает глубину проверки в цепочке сертификатов узла в группе балансировки…

• snx_ahc_ssl_conf_command (имя значение; Default: -). Задаёт произвольные конфигурационные команды OpenSSL при установлении соединения с узлов. На одном уровне может быть указано несколько директив snx_ahc_ssl_conf_command.

• snx_ahc_ssl_crl (файл; Default: -). Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при проверке сертификата узла в группе балансировки.

• check_shm_size (size; Default: 1Mb). Все проверки работоспособности узлов балансировки хранятся в общей памяти. Данная директива позволяет задать размер общей памяти.

Дополнительные директивы для поддержки запросов active healthcheck по TCP: (каждая прописывается в отдельной строке)

• proxy_session_drop (on/off; Default: off). SynGX прекращает при проксировании запроса использовать ранее установленные соединения с узлом (сервером), когда он переходит в состояние 'down' при проверке active health check. Для проксирования выбирается новый узел, который находится в состоянии 'up' по результатам active health check. Директива доступна только в секции stream или stream/server.

Настройка location для получения данных по healthcheck

Пример базовой конфигурации для получения данных по healthcheck:

http {
    server {
        listen 80;
        
        # status interface
        location /hc_status {
            <вид метрик>;
        }
     ...
}

• <вид метрик> - заменить на: check_status - для метрик по healthcheck из секции http (L7 уровень модели OSI), либо l4check_status - для метрик по healthcheck из секции stream (L4 уровень модели OSI).

Формат вывода метрик задается добавлением вида (по умолчанию html):

* <вид метрик> html
* <вид метрик> json
* <вид метрик> prometheus

Пример настройки активной проверки работоспособности узлов с разными типами соединений (tcp,udp,http,ssl_hello,tcp_tls) в секции stream

...

stream {
    upstream tcp_cluster {
        # simple round-robin
        server 127.0.0.1:8010;
        server 127.0.0.1:8011;
        check interval=2000 rise=2 fall=2 timeout=3000 default_down=true type=tcp;
        check_send "HEAD / HTTP/1.0\r\nConnection: close\r\n\r\n";
        # check_send "Hello from hc stream tcp!"; для чистого tcp
        check_expect_alive "HTTP/1.1 200";
        # check_expect_alive "Ok"; для чистого tcp
    }
    upstream udp_cluster {
        server 127.0.0.1:8020;
        server 127.0.0.1:8021;
        check interval=3000 rise=2 fall=5 timeout=5000 default_down=true type=udp;
    }

    upstream http_cluster {
        server 127.0.0.1:8030;
        server 127.0.0.1:8031;
        check interval=2000 rise=2 fall=5 timeout=3000 type=http;
        check_send "HEAD / HTTP/1.1";
        check_expect_alive "HTTP/1.1 200";
    }
    upstream ssl_hello_cluster {
        server 127.0.0.1:8040;
        server 127.0.0.1:8041;
        check interval=2000 rise=2 fall=5 timeout=3000 type=ssl_hello;
    }
    upstream tcp_tls_cluster {
        server 127.0.0.1:8050;
        server 127.0.0.1:8051;
        check interval=2000 rise=2 fall=5 timeout=3000 type=tcp_tls;
        check_send "HEAD / HTTP/1.0\r\n\r\n";
        # check_send "Hello from hc stream tcp!"; для чистого tcp
        check_expect_alive "HTTP/1.1 200";
        # check_expect_alive "Ok"; для чистого tcp

        snx_ahc_ssl_certificate           /home/syngx/syngx/ssl_src/client.crt;
        snx_ahc_ssl_certificate_key       /home/syngx/syngx/ssl_src/client.key;
        snx_ahc_ssl_trusted_certificate   /home/syngx/syngx/ssl_src/ca.crt;
        snx_ahc_ssl_verify on;
        snx_ahc_ssl_server_name on;
        snx_ahc_ssl_name sbt-ouiefs-6545.vm.mos.cloud.sbrf.ru;
        snx_ahc_ssl_protocols TLSv1.2;
        snx_ahc_ssl_ciphers AES256-SHA;
    }

    server {
        listen 8101;
        proxy_pass tcp_cluster;
    }
    server {
        listen 8102 udp;
        proxy_pass udp_cluster;
    }
    server {
        listen 8103;
        proxy_pass http_cluster;
    }
    server {
        listen 8104;
        proxy_ssl_certificate           /home/syngx/syngx/ssl_src/client.crt;
        proxy_ssl_certificate_key       /home/syngx/syngx/ssl_src/client.key;
        proxy_ssl_trusted_certificate   /home/syngx/syngx/ssl_src/ca.crt;
        proxy_ssl_session_reuse on;
        proxy_ssl_verify on;
        proxy_ssl_server_name on;
        proxy_ssl_name sbt-ouiefs-6545.vm.mos.cloud.sbrf.ru;
        proxy_ssl_protocols TLSv1.2;
        proxy_ssl_ciphers AES256-SHA;
        proxy_pass ssl_hello_cluster;
    }
    server {
        listen 8105;
        proxy_ssl_certificate           /home/syngx/syngx/ssl_src/client.crt;
        proxy_ssl_certificate_key       /home/syngx/syngx/ssl_src/client.key;
        proxy_ssl_trusted_certificate   /home/syngx/syngx/ssl_src/ca.crt;
        proxy_ssl_session_reuse on;
        proxy_ssl_verify on;
        proxy_ssl_server_name on;
        proxy_ssl_name sbt-ouiefs-6545.vm.mos.cloud.sbrf.ru;
        proxy_ssl_protocols TLSv1.2;
        proxy_ssl_ciphers AES256-SHA;
        proxy_pass tcp_tls_cluster;
    }
}

http {
    server {
        listen 8999;
        location /status_html {
            l4check_status html;
        }
        location /status_json {
            l4check_status json;
        }
        location /status_prometheus {
            l4check_status prometheus;
        }
    }
}

Более подробно можно изучить в документе Программа и методика испытаний в сценарии проверки «Active healthcheck для TCP, UDP, HTTP, HTTPS, TCP TLS (модули ngx_stream_upstream_check_module, nginx_upstream_check_module)».

Медленный старт (slow start) узла при введении в балансировку#

Функция медленного старта (slow start) заключается в плавном увеличении веса узла, который ранее с помощью активной проверки работоспособности был выведен из балансировки, а затем введен снова, с 0 до номинального значения в течение заданного времени.

Как включить медленный старт на SynGX

Пример конфигурации:

upstream backend_servers {
    server <адрес сервера1>:<port>;
    server <адрес сервера2>:<port> slow_start=30s;       
    server <адрес сервера3>:<port> slow_start=120s;
}

Примечание: slow start работает только в секции http.

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

Важно: параметр нельзя использовать совместно с методами балансировки нагрузки hash, ip_hash и random.

Мониторинг работы SynGX#

Администратору SynGX необходимо периодически производить проверку и осуществлять просмотр:

• системных метрик сервера и SynGX (подробнее - см. ниже в разделе События мониторинга);

• метрик работоспособности и статистики обработки запросов (подробнее - см. ниже в разделе События мониторинга);

• журналов событий - error.log и access.log (подробнее - см. ниже в разделе События системного журнала).

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

При превышении пороговых значений, администратору нужно оперативно выявить причину повышенной нагрузки путем анализа значений различных системных метрик, метрик мониторинга SynGX, логов компонента SNGX, и предпринять необходимые действия для решения проблемы в соответствии с порядком разбора инцидентов АС (руководствоваться внутренним регламентом, порядком и нормами эксплуатирующей организации).

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

События системного журнала#

SynGX, как и Nginx, имеет возможность вести два вида журналов. В первый журнал, который называется error.log, SynGX записывает информацию о своей собственной работе. Количество информации, которая записывается в error.log, определяется в конфигурации SynGX, при этом формат журнала изменять нельзя. Во второй журнал, который называется access.log, SynGX записывает информацию об обработанных запросах клиентов. Формат сообщений, которые записываются в данный журнал, определяется в конфигурации SynGX.

Логгирование можно настроить в конфигурационном файле SynGX с расширением .conf, который по умолчанию располагается в директории /opt/syngx/conf. Конфигурацию задает администратор SynGX самостоятельно, согласно требованиям эксплуатирующей организации.

Журнал error log

В error log записываются сообщения об ошибках, возникающих в процессе работы сервиса, предупреждения, информационные сообщения, отладочные сообщения - в зависимости от выставленного уровня логгирования. Запись производится по следующей маске: время события, уровень события, номер процесса, сообщение по событию.

Настройка error log производится директивой error_log в конфигурационном файле с расширением .conf (по умолчанию syngx.conf).

Синтаксис:	error_log файл [уровень];

,где [уровень] - это выставляемый уровень логгирования журнала.

Основные типы (уровни) событий системного журнала:

• Error — ошибки, возникающие в процессе работы сервиса;

• Warn — предупреждения, возникающие в процессе работы сервиса;

• Info — информационные сообщения, возникающие в процессе работы сервиса;

• Debug — отладочные сообщения (детали взаимодействия с внешними системами), возникающие в процессе работы сервиса.

Подробнее про настройку директивы error log можно изучить на странице сайта Nginx: https://nginx.org/ru/docs/ngx_core_module.html#error_log .

Пример сообщения об ошибке:

2022/10/30 16:29:36 [error] 3923#3923: *63024022 connect() failed (111: Connection refused) while connecting to upstream, client: <ip-адрес клиента>, server: , request: "POST /hc_proxy/healthcheck/service-healthcheck/ufs-delivery-proxy HTTP/1.0", upstream: "https://<ip-адрес узла>:<port>/healthcheck/service-healthcheck/ufs-delivery-proxy"

Поскольку в SynGX события типа error записывает Nginx, подробнее про события данного типа, записываемые в error log, можно изучить по ссылке сайта Nginx: https://docs.nginx.com/nginx/admin-guide/monitoring/logging/ .

Журнал access log

В access.log ведется запись логов запросов в указанном формате. Логи записываются в контексте location’а, где заканчивается обработка.

Настройка access.log производится директивой access_log в конфигурационном файле с расширением .conf (по умолчанию syngx.conf).

Подробнее про настройку директивы access_log можно изучить на странице сайта Nginx: https://nginx.org/ru/docs/http/ngx_http_log_module.html#access_log .

Дополнительная информация по системному журналу

По умолчанию, настроенные администратором события журнала локально записываются в директорию /opt/syngx/logs/ :

• error.log;

• access.log.

SynGX позволяет писать журналы в файлы на VM, а также отправлять их по протоколу syslog, что также определяется в конфигурации SynGX. При записи журналов в файлы на VM, необходимо иметь ввиду, что в ходе работы SynGX размер журналов постоянно увеличивается, поэтому необходимо предусмотреть способ ограничения размера логов, например, с помощью ротирования логов с помощью log rotate.

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

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

События мониторинга#

Мониторинг необходим для раннего обнаружения и локализации технологических событий прежде, чем они окажут негативное влияние на клиентов SynGX. Мониторинг позволяет в реальном времени получать объективную информации о состоянии SynGX, отслеживать статистику обработки запросов и своевременно реагировать на нештатные или не типичные ситуации в работе.

При работе SynGX необходимо отслеживать два вида метрик:

• системные метрики, к которым относятся потребление ЦПУ, использование оперативной памяти, наличие доступного дискового пространства и т.д. на VM. Системные метрики показывают, достаточно ли всем процессам, работающим в ОС на VM, ресурсов для корректной работы. Если какой-либо процесс или приложение (необязательно SynGX) в случае сбоя или ошибки начинает потреблять все доступные ресурсы, это начинает влиять на работу других процессов и приложений. С точки зрения SynGX негативное влияние будет приводить к увеличению времени обработки сетевых запросов, возникновению ошибок при установлении соединений и т.д. За получение и мониторинг системных метрик отвечают администраторы VM, на которых установлен SynGX, в соответствии с принятыми стандартами и практиками.

• метрик работоспособности и статистики обработки запросов, к которым относятся количество установленных на текущий момент соединений, количество принятых запросов, количество обработанных HTTP запросов с кодами ответов 2xx, 3xx и т.д. Эти метрики показывают, насколько успешно обрабатываются запросы клиентов SynGX с течением времени. Например, в нормальном режиме количество обработанных HTTP запросов с кодами ответов 4xx и 5xx должно быть минимальным. Если их количество начинает расти, это признак того, что в цепочке обработки запросов возникли какие-то проблемы, которые требуют устранения. Количество установленных на текущий момент соединений характеризует текущий уровень нагрузки на SynGX. Если это количество начинает расти, это может быть признаком DoS атаки. Если это количество сильно снижается, это может означать наличие сетевых проблем при обращении к серверу SynGX (например, сбой DNS сервера).

Для мониторинга своей работы SynGX предоставляет метрики работоспособности и статистику обработки запросов в ответ на HTTP REST запрос. Адрес, на который необходимо отправлять запрос, а также формат ответа (в виде JSON-структуры или текстовом виде в формате Prometheus) настраиваются в конфигурации SynGX. Пример настройки такого рода приведен в предустановленной конфигурации SynGX.

При настройке адресов, по которым будут доступны метрики, необходимо использовать существующие в SynGX механизмы обеспечения безопасности (описанные в Руководстве по безопасности):

• Настроить доступ только с использованием протокола TLS не ниже версии 1.2.

• Настроить доступ с проверкой имени и пароля пользователя.

• Настроить доступ с определенных сетевых адресов.

Возможность настроить SynGX, чтобы он самостоятельно отправлял метрики в какую-либо систему, не предусмотрена. Дополнительные метрики могут быть настроены администратором самостоятельно в конфигурации SynGX (конфигурационный файл с расширением .conf).

Полный перечень доступных метрик SynGX и способов их настройки описан ниже.

Перечень доступных метрик#

Метрики предоставляют подключенные модули SynGX - nginx-module-vts, ngx_http_extstatus_module, nginx_upstream_check_module, ngx_stream_upstream_check_module, sts (nginx-module-stream-sts, nginx-module-sts), ngx_hashicorp_vault_module. Необходимо учесть, что некоторые модули являются динамическими, то есть, требуется их дополнительное подключение и настройка (рассмотрено в разделе «Подключение динамических модулей SynGX»).

Для доступа к конкретной группе метрик необходимо через командную строку отправить GET-запрос типа (запрос к модулю SynGX):

{ip-адрес сервера либо 127.0.0.1}/{location}

, где {location} - адрес, по которому можно получить метрики из конкретного модуля SynGX. Адрес настраивается в конфигурации SynGX.

Пример GET-запроса для отображения HTML страницы:

localhost:80/status_html

Далее подробно рассмотрим, какие метрики может выдавать каждый указанный модуль.

Модуль nginx-module-vts

Данный модуль предоставляет возможность получения статистики по запросам в разрезе виртуальных серверов в формате html-страницы, а также можно настроить выдачу в форматах json и prometheus. Помимо этого, рассматриваемый модуль может выдавать статистику по использованию кеша для статистического содержимого в форматах json и prometheus. Модуль обеспечивает предоставление следующих видов метрик:

• main:

  • время безотказной работы ((nowMsec - loadMsec)/1000); nowMsec, loadMsec - в миллисекундах;

• connections:

  • всего подключений и запросов (аналогично stub_status_module в NGINX);

• sharedZones:

  • информация об объеме общей памяти, используемой модулем nginx-module-vts;

• serverZones:

  • объем трафика (входящий/исходящий), количество запросов и ответов и коэффициент попадания в кеш на каждую зону сервера;

  • объем общего трафика (входящий/исходящий), количество запросов и ответов (имя зоны) и коэффициент совпадений;

• filterZones:

  • объем трафика (входящий/исходящий), количество запросов и ответов, а также коэффициент попадания в кеш для каждой зоны сервера, отфильтрованной с помощью vhost_traffic_status_filter_by_set_key директивы;

  • общий объем трафика (входящий / исходящий), количество запросов и ответов (имя зоны *) и коэффициент совпадений, отфильтрованные с помощью vhost_traffic_status_filter_by_set_key директивы .

• upstreamZones:

  • объем трафика (входящий/исходящий) и количество запросов и ответов на сервер в каждой вышестоящей группе;

  • текущие настройки (weight, maxfails, failtimeout…) в synx.conf

• cacheZones:

  • объем трафика (входящий/исходящий), размер (capacity/used) и коэффициент попаданий на каждую зону кэша при использовании директивы proxy_cache.

Пример конфигурации для получения метрик приведен ниже:

server {
...
 ⁣ ⁣ ⁣ ⁣⁣location /vts_html {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display_format html;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
  ⁣ ⁣ ⁣ ⁣⁣location /vts_json {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display_format json;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
   ⁣ ⁣ ⁣ ⁣⁣location /vts_prometheus {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display_format prometheus;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}

Пример вывода метрик модуля в формате HTML:

Пример вывода метрик модуля в формате JSON:

Пример вывода метрик модуля в формате Prometheus:

Модуль ngx_http_extstatus_module

Данный модуль предоставляет возможность получения детальной статистики по HTTP-запросам в разрезе кодов HTTP-ответов в форматах json и prometheus (нужна настройка в конфигурации SynGX). Помимо этого, он может выдавать статистику по использованию TLS-соединений в форматах json и prometheus (нужна настройка в конфигурации SynGX).

Ниже приведен пример метрик в json-формате, которые выдаются при обращении к данному модулю.

{
 ⁣ ⁣"active_connection" : "2",
 ⁣ ⁣"accepts" : "6",
 ⁣ ⁣"handled" : "6",
 ⁣ ⁣"requests" : "5",
 ⁣ ⁣"reading" : "0",
 ⁣ ⁣"writing" : "1",
 ⁣ ⁣"waiting" : "1",
 ⁣ ⁣"syngx_uptime" : "67635",
 ⁣ ⁣"syngx_time" : "1664952670",
 ⁣ ⁣"responses" : {
 ⁣ ⁣ ⁣ ⁣"2xx": "2",
 ⁣ ⁣ ⁣ ⁣"3xx": "0",
 ⁣ ⁣ ⁣ ⁣"4xx": "2",
 ⁣ ⁣ ⁣ ⁣"5xx": "0",
 ⁣ ⁣ ⁣ ⁣"codes" : {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣"200": "2",
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣"403": "2"
 ⁣ ⁣ ⁣ ⁣},
 ⁣ ⁣ ⁣ ⁣"total": 4
 ⁣ ⁣},
 ⁣ ⁣"ssl" : {
 ⁣ ⁣ ⁣ ⁣"handshakes" : 0,
 ⁣ ⁣ ⁣ ⁣"handshakes_failed" : 0,
 ⁣ ⁣ ⁣ ⁣"session_reuses" : 0
 ⁣ ⁣}
}

Пример конфигурации для получения метрик приведен ниже:

server {
...
 ⁣ ⁣ ⁣ ⁣location /status_prometheus {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣snx_http_extstatus_prometheus on;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣location /status_json {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣snx_http_extstatus_json on;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣location /certificates_metrics_json {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣snx_http_certificates_status_json on;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣location /certificates_metrics_prometheus {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣snx_http_certificates_status_prometheus on;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}

Пример вывода метрик модуля в формате JSON:

Пример вывода метрик модуля в формате Prometheus:

Пример вывода метрик модуля по сертификатам в формате JSON:

Пример вывода метрик модуля по сертификатам в формате Prometheus:

Модуль nginx_upstream_check_module

Данный модуль предоставляет возможность учета текущего состояния вычислительного узла в группе балансировки на уровне секции http (на уровне L7 модели OSI) при распределении запросов. При базовой настройке конфигурации, он будет выдавать метрики в виде HTML-страницы. Однако, администратор может настроить выдачу в формате json или prometeus.

Данный модуль может отображать статусы по разным видам проверок healthcheck - tcp, ssl_hello, http, https.

Информация по настройке модуля приведена в разделе «Настройка активной проверки работоспособности узлов (active healthcheck)» выше.

Пример конфигурации для получения метрик приведен ниже:

server {
...
 ⁣ ⁣ ⁣ ⁣location /l7status_html {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣check_status html;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣location /l7status_json {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣check_status json;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣location /l7status_prometheus {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣check_status prometheus;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}

Пример вывода метрик модуля в формате HTML:

Пример вывода метрик модуля в формате JSON:

Пример вывода метрик модуля в формате Prometheus:

Модуль ngx_stream_upstream_check_module

Данный модуль предоставляет возможность учета текущего состояния вычислительного узла в группе балансировки на уровне секции stream (на уровне L4 модели OSI) при распределении запросов. При базовой настройке конфигурации, он будет выдавать метрики в виде HTML-страницы. Однако, администратор может настроить выдачу в формате json или prometeus.

Данный модуль может отображать статусы по разным видам проверок healthcheck - udp, tcp, http, ssl_hello, tcp_tls.

Информация по настройке модуля приведена в разделе «Настройка активной проверки работоспособности узлов (active healthcheck)» выше.

Пример конфигурации для получения метрик приведен ниже:

http {
    server {
      ...
        location /l4hc_status_html {
            l4check_status html;
        }
        location /l4hc_status_json {
            l4check_status json;
        }
        location /l4hc_status_prometheus {
            l4check_status prometheus;
        }
     ...
}

Пример вывода метрик модуля в формате HTML:

.

Пример вывода метрик модуля в формате JSON:

.

Пример вывода метрик модуля в формате Prometheus:

Модули sts (nginx-module-stream-sts, nginx-module-sts)

Описание модулей:

• nginx-module-stream-sts - данный модуль предназначен для сбора статистики на уровне L4 OSI (UDP и TCP соединения);

• nginx-module-sts - этот модуль добавляет возможность отображения статистики по запросам на уровне L4.

Модуль nginx-module-sts обеспечивает предоставление следующих видов метрик:

• main:

  • время безотказной работы ((nowMsec - loadMsec)/1000); nowMsec, loadMsec - в миллисекундах;

• connections:

  • всего подключений и запросов;

• streamServerZones:

  • информация о трафике (входящий/исходящий), количество запросов и ответов, а также соотношение статусов (1xx, 2xx…) для каждой зоны сервера;

• streamFilterZones:

  • информация об общем трафике (входящий/исходящий), количестве запросов и ответов, а также о соотношении совпадений состояния (1xx, 2xx…) для каждой зоны сервера, отфильтрованного с помощью директивы server_traffic_status_filter_by_set_key.

  • информация о трафике (входящий/исходящий), количестве запросов и ответов для <имя зоны *> и коэффициенте совпадений, отфильтрованная с помощью директивы server_traffic_status_filter_by_set_key.

• streamUpstreamZones

  • объем трафика (входящий/исходящий) и количество запросов и ответов на сервер в каждой вышестоящей группе;

  • текущие настройки (weight, maxfails, failtimeout…) в synx.conf

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

Пример базовой настройки модуля sts дан ниже:

1. Задать директиву "server_traffic_status_zone" на уровне stream в конфигурационном файле SynGX (syngx.conf):

stream {
    server_traffic_status_zone;
    server {
        ...
    }
}

2. Добавить подключение сбора статистики на уровне директив http в конфигурационном файле SynGX (syngx.conf), добавить тестовый сервер:

http {
   stream_server_traffic_status_zone;
   
  server {
    listen <port>;
    server_name stream_sts_module;
    location /status_html {
        stream_server_traffic_status_display;
        stream_server_traffic_status_display_format html;
    }
    location /status_json {
        stream_server_traffic_status_display;
        stream_server_traffic_status_display_format json;
    }
    location /status_prometheus {
        stream_server_traffic_status_display;
        stream_server_traffic_status_display_format prometheus;
    }
  }
}

Пример вывода метрик модуля в формате HTML:

Пример вывода метрик модуля в формате JSON:

Пример вывода метрик модуля в формате Prometheus:

Модуль ngx_hashicorp_vault_module

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

Пример конфигурации для получения метрик приведен ниже:

http {
    server {
      ...
        location /get_json {
            ngx_hashicorp_vault_json on;
        }
        location /get_prometheus {
            ngx_hashicorp_vault_prometheus on;
        }
     ...
}

Пример вывода метрик модуля в формате JSON:

.

Пример вывода метрик модуля в формате Prometheus:

Часто встречающиеся проблемы и пути их устранения#

Невозможность запуска SynGX

Возможные причины:

• наличие синтаксических ошибок в конфигурации SynGX

  • рекомендация: в данном случае администратору необходимо убедиться, что в конфигурационном файле SynGX нет синтаксических ошибок. После чего произвести запуск SynGX.

• отсутствие необходимых файлов:

  • рекомендация: администратору необходимо пройти чек-лист руководства по установке SynGX. В случае отсутствия указанных в чек-листе файлов, требуется заново пройти инструкцию по подготовке сервера и инструкцию по установке SynGX;

Зависший процесс на сервере

Рекомендация: перезапустить процесс SynGX.

Зависший процесс может привести к невозможности штатной остановки SynGX. В таком случае, потребуется применить системную команду для прекращения процессов SynGX.

Некорректная логика обработки запросов

Рекомендация: администратору необходимо проверить конфигурационный файл на предмет наличия логических ошибок в конфигурации: корректность указанных директорий, путей (locations), а также настройка выставленных директив. Также нужно убедиться, что на сервере в указанных директориях присутствуют необходимые файлы.

Проблемы (ошибки) при подключении динамических модулей

Проблема: сообщение unknown directive при запуске/при перезагрузке/при проверке конфигурационного файла SynGX.

Возможные причины:

1. отсутствие установленного и корректно добавленного в конфигурационный файл требуемого динамического модуля;

2. отсутствие библиотеки libluajit при подключении динамического модуля ngx_http_lua_module либо ngx_stream_lua_module;

3. отсутствие установленного и добавленного в конфигурационный файл модуля ndk_http_module при подключении динамических модулей ngx_http_lua_module, ngx_stream_lua_module либо ngx_http_set_misc_module.

Рекомендации:

1. проверить, к какому модулю относится директива, и убедиться, что модуль установлен и корректно подключен (см. подраздел Подключение динамических модулей SynGX данного Руководства по системному администрированию);

2. при использовании динамического модуля ngx_http_lua_module либо ngx_stream_lua_module необходимо проверить наличие библиотеки libluajit. При отсутствии, ее необходимо установить согласно Руководству по установке документации SynGX;

3. при использовании динамических модулей ngx_http_lua_module, ngx_stream_lua_module либо ngx_http_set_misc_module необходимо проверить установку и добавление в конфигурационный файл SynGX модуля ndk_http_module (см. подраздел Подключение динамических модулей SynGX данного Руководства по системному администрированию).