Руководство по установке#

В руководстве приведены инструкции по установке и первичной настройке компонента Веб-сервер и обратный прокси-сервер SynGX (SNGX) из состава программного продукта Platform V SynGX (SNX).

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

Системные требования#

Настройки безопасности окружения и перечень сторонних (дополнительных внешних) продуктов, используемых для установки, настройки и контроля в конечной информационной системе (далее — ИС), выбираются клиентом при разработке конечной ИС, исходя из характера обрабатываемой в ней информации и иных требований информационной безопасности (далее — ИБ), предъявляемых к ней.

Системное программное обеспечение#

Описание комплекса технических средств и стороннего программного обеспечения, необходимых для работы SynGX

Примечание:

*

• Да — категория ПО обязательна для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данной категории ПО).

• Нет — категория ПО необязательна для функционирования сервиса (это означает, что сервис может выполнять свои основные функции без установки данной категории ПО).

**

• Рекомендовано — рекомендованный АО «СберТех» продукт.

• Опционально — альтернативный по отношению к рекомендованному АО «СберТех» продукт.

Платформенные зависимости#

В данной версии Продукта платформенные зависимости не предусмотрены (дополнительная интеграция с программными продуктами, правообладателем которых является АО «СберТех», для работы SynGX не требуется).

Аппаратные требования#

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

Внимание: не рекомендуется размещение двух и более СПО (одного или разных типов) на одной VM в связи с конкуренцией за аппаратные ресурсы, и, как следствие, сложность в локализации проблем при возникновении инцидентов при промышленной эксплуатации.

Состав дистрибутива#

Дистрибутив с кодом SynGX поставляется в виде zip-архива, название которого соответствует маске SNX-<DISTRIB_VERSION>-x86_64-distrib.zip.

Внутри этого zip-архива находятся следующие RPM-пакеты:

, где:

• <DISTRIB_VERSION> - версия дистрибутива с кодом SynGX;

• <rpm_version> - устанавливаемая версия rpm-пакета SynGX;

• <os_type> - версия rpm-пакета динамического модуля для требуемой ОС: alt10 - для ОС Альт 8 СП, el8 - для ОС RHEL 8.7, sl8 - для ОС SberLinux OS Server 8.10, sl9 - для ОС SberLinux OS Server 9.3.

Помимо выше перечисленных RPM-пакетов, в дистрибутиве присутствует папка /package, в которой находятся Dockerfile-ы на основе базовых образов поддерживаемых ОС.

Выбор способа установки#

Установка SynGX заключается в установке или обновлении RPM-пакета самого SynGX, а также необходимых для его работы библиотек и пакетов.

Установить RPM-пакет SynGX можно используя консольный пакетный менеджер yum.

Другим способом разворачивания SynGX является использование Docker-образа SynGX. Подробнее можно изучить ниже в разделе «Использование Docker образа SynGX».

Подготовка окружения#

Подготовка стенда (сервера)#

За подготовку стенда (VM) для SynGX отвечают администраторы SynGX.

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

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

Если требуется интеграция с HashiCorp Vault (либо Secret Management System), администратору необходимо самостоятельно подготовить сервер, согласно эксплуатационной документации на HashiCorp Vault/Secret Management System и требованиям (включая требования по безопасности) эксплуатирующей организации.

Если необходимо использовать функционал предоставляемый модулем ngx_stream_rst_send_module (Подробнее см. в Руководстве по системному администрированию - раздел «Отправка пакета TCP с флагом RST на входящие TCP соединения»), администратору самостоятельно необходимо установить утилиту iptables, а также разрешить пользователю, от имени которого будет запускаться master процесс SynGX, запускать утилиту iptables

Подготовка ОС к установке SynGX#

Корректная работа SynGX гарантируется для трех ОС:

• ОС «Альт 10 СП»;

• SberLinux OS Server 8.10 (опционально);

• SberLinux OS Server 9.3 (опционально);

• ОС «Red Hat Enterprise Linux» (RHEL) 8.7 (опционально).

Для инсталляции на одну из выше перечисленных ОС должен использоваться соответствующий RPM пакет из дистрибутива SynGX.

Перед установкой SynGX необходимо настроить ОС:

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

• создать группу syngx, в которую включить пользователя syngx (syngx:syngx);

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

  1. Добавить (скорректировать) в файл /etc/security/limits.conf следующие строки:

     • syngx soft nofile 128000

     • syngx hard nofile 128000

     • syngx soft nproc 128000

     • syngx hard nproc 128000

  2. Добавить (скорректировать) в файл /etc/sysctl.conf следующие строки:

     • kernel.pid_max 4194304 – или большее значение

     • fs.file-max 128000 – или большее значение, но не более 10 % от оперативной памяти.

• (для ОС «Альт 10 СП») Проверить, что /usr/sbin находится в переменной окружения PATH, пример команды $echo $PATH. При отсутствии необходимо выполнить команду export PATH=$PATH:/usr/sbin. После чего переменная окружения будет выглядеть примерно так (пример) /usr/local/bin:/home/syngx/bin:/bin:/usr/bin:/usr/local/bin:/usr/games:/usr/sbin.

SynGX может быть установлен в отдельную точку монтирования /opt/syngx/ размером от 10 Гб. Если для хранения логов SynGX используется папка внутри директории /opt/ (по умолчанию /opt/syngx/logs), при отсутствии отдельной точки монтирования, необходимо следить, чтобы логи SynGX не занимали более 10% от размера директории /opt/. Однако в случае использования SynGX в виде контейнера монтировать внутреннюю папку контейнера /opt в хостовую папку /opt(например для хранения логов) не следует, для этого нужно выбрать папку из разрешенного перечня.

Установка необходимых пакетов и библиотек перед установкой SynGX#

Для корректной работы SynGX перед установкой Продукта в ОС на VM необходимо установить некоторые свободнораспространяемые пакеты и библиоткеки. Ниже даны инструкции по их установке на ОС Альт 10 СП, SberLinux OS Server 8.10, SberLinux OS Server 9.3 и на ОС RHEL 8.7 (необходимо выбрать инструкцию под используемую ОС).

1. Установка пакетов и библиотек на ОС Альт 10 СП.

Необходимо произвести установку следующих пакетов и библиотек, используя команду apt-get в командной строке:

$ sudo apt-get install unzip
$ sudo apt-get install libgd3
$ sudo apt-get install libmaxminddb

2. Установка пакетов и библиотек на SberLinux OS Server 8.10 (опционально) либо на на SberLinux OS Server 9.3 либо на ОС RHEL 8.7 (опционально).

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

$ sudo yum install unzip
$ sudo yum install gcc
$ sudo yum install gd-devel
$ sudo yum install -y libmaxminddb

Установка#

После выполнения подготовительных действий, описанных в разделе «Подготовка окружения», можно приступить к установке Продукта. Установка SynGX заключается в установке или обновлении RPM-пакета самого SynGX.

Порядок установки#

Порядок установки пакетов отличается в зависимости от конфигурации. Если не нужно использовать Lua в конфигурации:

1. SNX-<rpm_version>-syngx-distrib.<os_type>.x86_64.rpm

2. другие rpm пакеты

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

1. SNX-<rpm_version>-syngx-distrib.<os_type>.x86_64.rpm

2. SNX-<rpm_version>-luajit.<os_type>.x86_64.rpm

3. SNX-<rpm_version>-ndk-distrib.<os_type>.x86_64.rpm

4. SNX-<rpm_version>-lua-distrib.<os_type>.x86_64.rpm

5. SNX-<rpm_version>-luapack.<os_type>.x86_64.rpm

6. SNX-<rpm_version>-lua-cjson.<os_type>.x86_64.rpm

7. SNX-<rpm_version>-hashids.<os_type>.x86_64.rpm

8. другие rpm пакеты

Установить rpm пакет можно:

a. Для ОС Альт 10 СП (опционально):

$ sudo apt-get install SNX-<rpm_version>-<имя пакета>-distrib.alt10.x86_64.rpm

b. Для SberLinux OS Server 8.10 :

$ sudo yum install SNX-<rpm_version>-<имя пакета>-distrib.sl8.x86_64.rpm

c. Для ОС RHEL 8.7 (опционально):

$ sudo yum install SNX-<rpm_version>-<имя пакета>-distrib.el8.x86_64.rpm

в. Для SberLinux OS Server 9.3 (опционально):

$ sudo yum install SNX-<rpm_version>-<имя пакета>-distrib.sl9.x86_64.rpm

, где:

• <rpm_version> - устанавливаемая версия rpm-пакета SynGX;

Использование Docker образа SynGX#

Сборка образа#

В поставке также присутствуют Docker-файлы для сборки образов с установленным SynGX, которые находятся по путям:

package/docker/alt/Dockerfile
package/docker/rhel/Dockerfile
package/docker/sbel8/Dockerfile
package/docker/sbel9/Dockerfile

Данные файлы имеют следующую структуру:

ARG BASE_IMAGE=<default_image_path>
FROM ${BASE_IMAGE}
ENV LANGUAGE="en_US.UTF-8"
ENV LC_ALL="C"
ENV LUA_PATH="/opt/syngx/modules/lua_libs/?.lua;/usr/local/share/luajit-syngx/?.lua;;"
ENV LUA_CPATH="/opt/syngx/modules/lua_libs/?.so;;"
COPY SNX-DISTRIB_VERSION-luajit-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-lua-cjson-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-luapack-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-hashids-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-brotli-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-hashicorp_vault-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-lua-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-ndk-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-njs-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-set_misc-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-sslkeylog-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-sts-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-syngx-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-rst_send-distrib.<os_type>.x86_64.rpm \
SNX-DISTRIB_VERSION-upload-distrib.<os_type>x86_64.rpm ./
RUN groupadd -g 10001 syngx && useradd -u 10001 -g 10001 syngx \ 
&& yum install -y \
./SNX-DISTRIB_VERSION-syngx-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-luajit-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-ndk-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-lua-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-luapack-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-njs-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-set_misc-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-sslkeylog-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-sts-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-rst_send-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-upload-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-brotli-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-hashicorp_vault-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-lua-cjson-distrib.<os_type>.x86_64.rpm \
./SNX-DISTRIB_VERSION-hashids-distrib.<os_type>.x86_64.rpm \
unzip \
logrotate \
cronie \
&& chown -R syngx:root /opt/syngx \
&& rm *rpm \
&& mkdir /var/log/syngx \
&& chown -R syngx:0 /var/log/syngx \
&& sed -i "s/\/opt\/syngx\/logs\//\/var\/log\/syngx\//g" /opt/syngx/conf/syngx.conf \
&& sed -i "/^http {/a \ proxy_temp_path /tmp/proxy_temp;\n client_body_temp_path /tmp/client_temp;\n fastcgi_temp_path /tmp/fastcgi_temp;\n uwsgi_temp_path /tmp/uwsgi_temp;\n scgi_temp_path /tmp/scgi_temp;\n" /opt/syngx/conf/syngx.conf \
&& chmod -R g+w /var/log/syngx
WORKDIR /home/syngx
USER 10001:10001
ENV LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64
STOPSIGNAL SIGQUIT
ENTRYPOINT ["syngx", "-g", "daemon off;"]

, где:

• default_image_path - путь к базовому образу системы по умолчанию. Может быть абсолютно любым наименованием; больше требуется для соблюдения синтаксиса докерфайлов;

• os_type - метка операционной системы (el8, sl8, alt10);

• packet_manager - пакетный менеджер, с помощью которого проводится установка rpm-пакетов.

Для того, чтобы собрать образ, нужно переместить либо скопировать rpm-пакеты в директории с докерфайлами и запустить команду сборки:

docker build --build-arg BASE_IMAGE=<base_image_path> . --rm --no-cache=true --tag <syngx_image_name>:<syngx_image_tag>

, где:

• base_image_path - адрес базового образа ОС;

• syngx_image_name - имя собираемого образа с SynGX;

• syngx_image_tag - версия собираемого образа, определяет версии пакетов в образе;

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

• для «SberLinux OS Server 8.10», «SberLinux OS Server 9.3» либо «RHEL 8.7»:

RUN rm /etc/yum.repos.d/*
COPY "*.repo" /etc/yum.repos.d/

• для «Альт 10 СП»:

RUN rm /etc/apt/sources.list.d/*
COPY "*.list" /etc/apt/sources.list.d/

В данном случае, *.list и *.repo - это репо-файлы, которые перед сборкой следует поместить в директорию с Docker-файлом.

Хранение образа#

После сборки образ будет храниться только в вашем локальном docker-regestry, иначе говоря, находиться только на вашей локальной машине, его наличие можно будет проверить коммандой:

docker image ls

Для загрузки образа в ваш облачный regestry, требуется авторизироваться в нем через команду:

docker login <regestry_path>

, где:

• regestry_path - домен облачного regestry.

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

docker push <syngx_image_name>:<syngx_image_tag>

Теперь в любой момент времени с любой машины в вашей сети можно будет загрузить образ командой:

docker pull <syngx_image_name>:<syngx_image_tag>

Либо, если тег будет выставлен как latest, можно не указывать версию:

docker pull <syngx_image_name>

Использование образа#

Чтобы воспользоваться образом, нужно, во первых, скачать его, либо же просто собрать, как было сказано ранее, после чего запустить контейнер через команду:

docker run -it <syngx_image_name>:<syngx_image_tag> -p <host_port>:8080 /bin/bash

После чего вы попадете в консоль контейнера с уже запущенным SynGX, и сможете в нем получить доступ к приветсвенной странице через команду:

curl 127.0.0.1

С серверной машины можно будет получить доступ через браузер по адресу http://127.0.0.1:<host_port>, либо также через консоль:

curl 127.0.0.1:<host_port>

Также, контейнер можно запустить в фоне командой:

docker run -d -p <host_port>:8080 <syngx_image_name>:<syngx_image_tag>

В Kubernetes-конфигурациях пользоваться образом можно будет, указывая его имя в директивах image для Pod или Deployment-конфигурациях:

...
   image:<syngx_image_name>:<syngx_image_tag>
...

Список директорий и файлов после установки SynGX#

При установке RPM пакета в ОС появляются следующие файлы:

Подробнее:

1. Исполняемый файл syngx. Расположение файла после установки RPM пакета - /usr/sbin/syngx. Параметры, с которыми был собран SynGX, можно посмотреть командой syngx -V. Вывод команды может выглядеть следующим образом:

syngx version: SynGX/3.2.0 (based on nginx-1.24.0)
built by gcc 8.5.0 20210514 (Red Hat 8.5.0-18) (GCC) 
built with OpenSSL 1.1.1k  FIPS 25 Mar 2021
TLS SNI support enabled
configure arguments: --with-ld-opt=-lpcre --with-cc-opt=-g3 --prefix=/opt/syngx --with-http_ssl_module --with-compat --with-http_addition_module --with-http_dav_module --with-http_random_index_module --with-http_secure_link_module --with-http_slice_module --with-http_degradation_module --with-http_xslt_module --with-mail --with-mail_ssl_module --with-stream_realip_module --with-stream_ssl_preread_module --with-stream --with-stream_ssl_module --with-http_v2_module --with-http_image_filter_module --with-threads --with-file-aio --with-http_gzip_static_module --with-poll_module --with-http_auth_request_module --with-http_sub_module --with-http_flv_module --with-http_gunzip_module --with-http_mp4_module --with-http_stub_status_module --with-http_realip_module --with-debug --with-perl_modules_path=/usr/lib64/perl5/ --with-perl=/usr/bin/perl --with-pcre-opt=-fPIC --with-cc-opt=-fPIC --add-module=../ngx_http_extstatus_module --add-module=../nginx_upstream_check_module --add-module=../nginx-sticky-module-ng --add-module=../headers-more-nginx-module --add-module=../ngx_http_geoip2_module --add-module=../nginx-module-vts --add-module=../ngx_stream_upstream_check_module --add-module=../ngx_http_proxy_connect_module --add-module=../echo-nginx-module --add-dynamic-module=../ngx_hashicorp_vault_module --add-dynamic-module=../ngx_http_upload_module --add-dynamic-module=../ngx_brotli --add-dynamic-module=../ngx_devel_kit --add-dynamic-module=../lua-nginx-module --add-dynamic-module=../stream-lua-nginx-module --add-dynamic-module=../njs/nginx --add-dynamic-module=../nginx-sslkeylog --add-dynamic-module=../nginx-module-sts --add-dynamic-module=../ngx_http_set_misc_module --add-dynamic-module=../nginx-module-stream-sts --add-dynamic-module=../ngx_stream_rst_send_module --sbin-path=/usr/sbin/syngx --modules-path=/opt/syngx/modules

2. Systemd unit, включающий в себя описание управления службой syngx. Расположение файла - /etc/systemd/system/syngx.service. Состав файла:

[Unit]

Description=The SynGX HTTP and reverse proxy server

After=syslog.target

Wants=network.target network-online.target

After=network.target network-online.target

After=remote-fs.target

After=nss-lookup.target

[Service]

Type=forking

PIDFile=/opt/syngx/logs/syngx.pid

WorkingDirectory=/opt/syngx

ExecStartPre=/usr/sbin/syngx -t

ExecStart=/usr/sbin/syngx

ExecStop=/bin/kill -s QUIT $MAINPID

ExecReload=/usr/sbin/syngx -s reload

PrivateTmp=true

[Install]

WantedBy=multi-user.target

3. Sudoers файл, включающий в себя разрешенный набор команд для пользователя syngx, запускаемых из-под привилегированного пользователя root. Расположение файла после установки RPM пакета - /etc/sudoers.d/syngx. Содержимое файла:

Defaults: syngx !requiretty
Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin
#
syngx ALL = (ALL) NOPASSWD:/usr/bin/systemctl start syngx
syngx ALL = (ALL) NOPASSWD:/usr/bin/systemctl stop syngx
syngx ALL = (ALL) NOPASSWD:/usr/bin/systemctl enable syngx
syngx ALL = (ALL) NOPASSWD:/usr/bin/systemctl disable syngx
syngx ALL = (ALL) NOPASSWD:/usr/bin/systemctl restart syngx
syngx ALL = (ALL) NOPASSWD:/usr/bin/systemctl reload syngx
syngx ALL = (ALL) NOPASSWD:/usr/sbin/syngx -t
#
syngx ALL = (ALL) NOPASSWD: /bin/chown -R syngx\:syngx /opt/syngx/html, /bin/chown -R syngx\:syngx /opt/syngx/conf, /bin/chown syngx\:syngx /opt/syngx/logs/

4. Файл ротации логов, включающий в себя правила и параметры ротирования журналов SynGX. Расположение файла - /etc/logrotate.d/syngx. Содержимое файла:

/opt/syngx/logs/*.log {
    rotate 10

    size=100M

    daily

    dateext

    dateformat -%Y-%m-%d_%H-%s

    missingok

    compress

    delaycompress

    create 644 syngx syngx

    postrotate

        /bin/kill -USR1 cat /opt/syngx/logs/syngx.pid 2> /dev/null 2> /dev/null || true

    endscript
}

5. SWID tag файл - это файл который используется для идентификации программных продуктов используя технологию SWID-тегов. Технология SWID-тегов является стандартизированной (ISO, ГОСТ) и определяет формат и способы идентификации ПП в процессах учета цифровых активов от момента создания актива до развертывания в среде эксплуатации.

6. Каталоги хранения конфигурационных файлов, файлов статического контента, файлов журналов, временных файлов, исполняемых файлов, сертификатов и прочее - находятся в директории:

• /opt/syngx/ – основная папка, куда устанавливается SynGX. Владелец syngx:syngx: права 755.
  После установки выставляются следующие права на каталог /opt/syngx и все вложенные в него каталоги и файлы:

  • доступ к каталогу /opt/syngx/ будет у пользователя syngx и группы пользователей syngx

  • все файлы, находящиеся в каталоге /opt/syngx/, будут иметь права 664

  • все каталоги, находящиеся в /opt/syngx/, будут иметь права 775

  • все каталоги с расширением .key, находящиеся по пути /opt/syngx/ssl/, будут иметь права 660

  • каталог /opt/syngx/logs будет иметь права 755

  • файлы с расширением .so и .lua будут иметь права 644

Первичная настройка SynGX#

Работа SynGX и его модулей определятся конфигурацией, которая содержится в конфигурационном файле с расширением .conf (конфигурационный файл по умолчанию находится в директории /opt/syngx/conf/syngx.conf).

Настройка SynGX производится директивами, которые делятся на простые и блочные. Простая директива состоит из имени и параметров, разделенных пробелами, и оканчивается точкой с запятой (;). Блочная директива устроена так же, как и простая директива, но вместо точки с запятой после имени и параметров следует набор дополнительных инструкций, помещенных внутри фигурных скобок ({ и }). Если у блочной директивы внутри фигурных скобок можно задавать другие директивы, то она называется контекстом (примеры: events, http, server и location).

Перечень наиболее критичных директив, на которые стоит обратить внимание при настройке сервиса:

Все пути в конфигурационных файлах должны иметь абсолютный вид, например, для директивы ssl_certificate абсолютный путь расположения файла сертификата будет выглядеть следующим образом – /opt/syngx/ssl/certificate.file.crt.

Директивы, помещенные в конфигурационном файле вне любого контекста, считаются находящимися в контексте main. Директивы events и http располагаются в контексте main, server — в http, а location — в server. Строка конфигурации, вначале которой установлен символ «#» считается комментарием.

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

Пример настройки сбора статистики и состояния вычислительных узлов в группах балансировки

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

• /status_prometheus - предоставляет детальную статистику по HTTP-запросам в разрезе кодов HTTP-ответов в формате prometheus;

• /status_json - предоставляет детальную статистику по HTTP-запросам в разрезе кодов HTTP-ответов в формате json;

• /monitor_html - предоставляет текущее состояние вычислительного узла в группе балансировки при распределении запросов в формате HTML;

• /monitor_json - предоставляет текущее состояние вычислительного узла в группе балансировки при распределении запросов в формате json;

• /vts - предоставляет статистику по запросам в разрезе виртуальных серверов.

Метрики предоставляют модули SynGX - nginx-module-vts, ngx_http_extstatus_module, nginx_upstream_check_module. Описание доступных метрик SynGX приведено в «Руководстве по системному администрированию» документации SynGX.

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

server {
 ⁣ ⁣ ⁣ ⁣listen 8080;

 ⁣ ⁣ ⁣ ⁣⁣location / {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣root ⁣ ⁣ ⁣/opt/syngx/conf/;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣index ⁣ ⁣start_page.html;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}

 ⁣ ⁣ ⁣ ⁣location /status_prometheus {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣snx_http_extstatus_prometheus on;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣allow ⁣ ⁣all;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣deny ⁣ ⁣all;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}

 ⁣ ⁣ ⁣ ⁣location /status_json {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣snx_http_extstatus_json on;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣allow ⁣ ⁣all;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣deny ⁣ ⁣all;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}

 ⁣ ⁣ ⁣ ⁣location /monitor_html {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣check_status html;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}

 ⁣ ⁣ ⁣ ⁣location /monitor_json {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣check_status json;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}

 ⁣ ⁣ ⁣ ⁣⁣location /vts {
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣vhost_traffic_status_display_format html;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣error_log ⁣ ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣access_log ⁣ ⁣ ⁣off;
 ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣ ⁣}
 ⁣ ⁣ ⁣ ⁣}

Запуск SynGX#

Перед вводом в эксплуатацию должны быть соблюдены следующие требования:

1. Дистрибутив SynGX имеет актуальную поддерживаемую версию;

2. Установка SynGX произведена согласно разделам «Подготовка окружения», «Установка» данного Руководства по установке;

3. Конфигурация SynGX имеет характеристики в соответствии с проведенным НТ и удовлетворяет минимально допустимым требованиям.

4. (опционально; обязательно при интеграции с HashiCorp Vault-решением) Если требуется интеграция SynGX с HashiCorp Vault, то перед запуском необходимо произвести настройку конфигурационного файла согласно разделу «Настройка интеграции SynGX с HashiCorp Vault» Руководства по системному администрированию.

5. Запуск SynGX следует производить согласно разделу «Запуск» Руководства по системному администрированию.

Обновление#

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

1. Обновление самой версии SynGX:

   a. Обновить саму версию SynGX через update RPM (обновить RPM-пакеты);
   В этом случае файл /etc/systemd/system/syngx.service обновляться не будет.

   либо

   b. Произвести удаление, после чего заново произвести полную установку требуемых RPM-пакетов.

2. Обновление конфигурации SynGX:

   • Для обновления конфигурации SynGX необходимо внести корректировки в конфигурацию продукта, после чего - выполнить команды «остановить», «запустить» - отправить сигналы SynGX-у в консоли «stop», «start» (со сбросом всех соединений и запросов), либо «reload» (подробнее - в руководстве по системному администрированию).

Удаление#

Удаление SynGX производится путем удаления RPM-пакетов SynGX. Для этого в консоли нужно прописать команду для SynGX-процессов:

sudo yum remove syngx

Будут удалены:

• RPM-пакеты SynGX,

• папки SynGX,

• логи (если записывались).

Проверка работоспособности#

Факт работы SynGX можно подтвердить путем выполнения команды в командной строке:

$ ps -ef | grep syngx

Данная команда выдаст список процессов syngx, которые запущены на данной машине. В случае успешности раскатки SynGX, будут отображаться master-процесс, worker-процессы.

Проверку работоспособности SynGX можно произвести с помощью отправки curl-запроса на localhost в командной строке:

curl 127.0.0.1:8080/

Если SynGX работает в штатном режиме, то будет возвращен ответ «200 OK».

Также проверку работоспособности можно выполнить в любом браузере, обратившись по адресу 127.0.0.1:8080/, если SynGX установлен на той же машине, на которой открывается браузер.

Если браузер установлен на другой машине, то следует обращаться по «белому» ip-адресу машины SynGX к порту 8080, перед этим убедившись, что межсетевой экран машины, на которой установлен SynGX, держит открытым этот порт к запросам.

Если SynGX работает в штатном режиме, то будет возвращена стартовая страница SynGX. Если SynGX не работоспособен, то будет показано сообщение об ошибке.

Стартовая станица выглядит следующим образом:

Откат#

Принудительный откат SynGX на предыдущую версию выполняется посредством развертывания артефактов предыдущей версии. Перед откатом на предыдущую версию SynGX не требуется удаление установленной версии (актуально для версий 1.2.0 и выше). Максимальное количество версий для отката составляет 1 версию. Исключение для модуля rst_send, данный модуль для отката необходимо удалить и установить модуль из предыдущей версии.

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

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

Проблемы, которые могут возникнуть при установке сервиса:

RPM пакет SynGX не устанавливается

Необходимо детально посмотреть в лог установки SynGX на сообщения об ошибках.

В явном виде причинами могут быть обозначены:

• отсутствие необходимых библиотек из раздела «Подготовка окружения»:

  • рекомендация: администратору стенда необходимо установить необходимые библиотеки согласно разделам «Системные требования» и «Подготовка стенда (сервера)» данного руководства по установке;

• неправильно выбранный пакет под конкретную ОС:

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

• некорректно прописанные названия rpm-пакетов в установке:

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

SynGX не запускается

В данном случае необходимо просмотреть в лог ошибок, который находится по пути /opt/syngx/logs/error.log при конфигурации по умолчанию.

В процессе эксплуатации продукта могут возникать такие ошибки запуска, например:

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

  • рекомендация: администратору стенда необходимо периодически проверять сертификаты на срок их действия, корректность настроенной конфигурации SynGX (указание путей расположения сертификатов);

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

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

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

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

• ошибки, связанные с настройкой межсетевого экрана:

  • рекомендация: администратору стенда, в случае, если он самостоятельно настраивал межсетевой экран (не относится к документации SynGX), необходимо проверить правильность его настройки;

• использование занятых портов, прописанных в конфигурации SynGX:

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

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

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

SynGX не удаляется

Необходимо детально посмотреть в лог на сообщения об ошибках.

Причинами могут быть:

• отсутствие необходимых прав на папку /opt/syngx:

  • рекомендация: администратору необходимо убедиться, что на сервере у него есть права в директории SynGX. В случае отсутствия необходимых прав, требуется самостоятельно, средствами ОС, предоставить необходимые права;

• уже пустой каталог на сервере:

  • рекомендация: администратору необходимо убедиться, что директории SynGX не пустые. Если директории пустые, то требуется удалить требуемые остаточные директории и файлы;

• зависший процесс на сервере:

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

Действия в случае несоблюдения условий выполнения технологического процесса

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

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

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

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

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

Чек-лист валидации установки#

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

1. Настройка ОС

   • Создан пользователь syngx.

   • Создана группа syngx, в которую включен пользователь syngx (syngx:syngx).

   • (рекомендация) В файле /etc/security/limits.conf присутствуют следующие строки:

     • syngx soft nofile 128000

     • syngx hard nofile 128000

     • syngx soft nproc 128000

     • syngx hard nproc 128000

   • (рекомендация) В файле /etc/sysctl.conf присутствуют следующие строки:

     • kernel.pid_max 4194304 – или большее значение

     • fs.file-max 128000 – или большее значение, (рекомендуется исходить из расчета 256 единиц на каждые 4 мегабайта оперативной памяти. Значение 128000 соответствует 2 Гб)

     • Установлены пакеты и библиотеки для ОС Альт 10 СП (опционально):

     • unzip

     • yum

     • libgd3

     • libmaxminddb

     • luajit-syngx

   • Установлены пакеты и библиотеки для ОС SberLinux OS Server 8.10, SberLinux OS Server 9.3 либо RHEL (опционально):

     • unzip

     • gcc

     • gd-devel

     • libmaxminddb

     • luajit-syngx

     , где: * - мета-данные библиотеки luajit;

2. Установка SynGX

   • Установлен корректный RPM-пакет SynGX под требуемую ОС. Ошибок в ходе установки не возникало.

   • После установки на сервере появились следующие директории и файлы (приведены стандартные пути и названия):

     /usr/sbin/syngx
     /etc/systemd/system/syngx.service
     /etc/sudoers.d/syngx
     /etc/logrotate.d/syngx
     /opt/syngx/
     

3. Настройка и запуск SynGX (опционально)

   • Администратором самостоятельно произведена настройка конфигурационного файла с расширением .conf, согласно требованиям и нормам эксплуатирующей организации.

   • Прописаны переменные окружения для пакета (/etc/environment).

   • Произведен запуск SynGX. Запуск прошел штатно.

4. Проверка интеграции с Hashicorp (опциально)

   • Администратором самостоятельно произведена настройка пререквизитов для интеграции SynGX с HashiCorp Vault и настроена конфигурация согласно разделу «Настройка интеграции SynGX с HashiCorp Vault > Настройка модуля ngx_hashicorp_vault_module» Руководства по системному администрированию.

   • Администратором добавлены директивы для получения статистики работы HashiCorp модуля согласно разделу «Мониторинг работы SynGX > Модуль ngx_hashicorp_vault_module» Руководства по системному администрированию.

   • Произведен запуск SynGX. Запуск прошел штатно.

   • Сделан запрос для получения статистики работы HashiCorp модуля. Результат запроса показывает, что идет взаимодействие с HashiCorp Vault.