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

Помимо собственных динамических модулей для Angie и Angie PRO, мы собираем и публикуем в нашем репозитории пакеты для ряда популярных сторонних nginx-совместимых модулей, разработанных за пределами нашей компании.

Установка и настройка#

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

Чтобы использовать установленный модуль в конфигурации, загрузите его с помощью директивы load_module в контексте main:

load_module modules/<имя модуля>.so;

Совет

Имена пакетов и самих модулей в конфигурации имеют следующие префиксы:

  • Angie: angie-module-<имя>;

  • Angie PRO: angie-pro-module-<имя>.

Примечание

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

Перечень пакетов#

Модуль

Версия

Пакеты

Auth JWT

0.15.0

angie-module-auth-jwt
angie-pro-module-auth-jwt

Auth LDAP

241200e

angie-module-auth-ldap
angie-pro-module-auth-ldap

Auth PAM

v1.5.5

angie-module-auth-pam
angie-pro-module-auth-pam

Auth SPNEGO

v1.1.3

angie-module-auth-spnego
angie-pro-module-auth-spnego

Auth TOTP

1.2.0

angie-module-auth-totp
angie-pro-module-auth-totp

Brotli

v1.0.0rc

angie-module-brotli
angie-pro-module-brotli

Cache Purge

3.0.3

angie-module-cache-purge
angie-pro-module-cache-purge

CGI

v0.15.2

angie-module-cgi
angie-pro-module-cgi

Combined Upstreams

2.3.1

angie-module-combined-upstreams
angie-pro-module-combined-upstreams

DAV Ext

v4.0.1

angie-module-dav-ext
angie-pro-module-dav-ext

Dynamic Limit Req

1.9.3

angie-module-dynamic-limit-req
angie-pro-module-dynamic-limit-req

Echo

v0.65

angie-module-echo
angie-pro-module-echo

Enhanced Memcached

v0.3

angie-module-enhanced-memcached
angie-pro-module-enhanced-memcached

Eval

2016.06.10

angie-module-eval
angie-pro-module-eval

GeoIP2

3.4

angie-module-geoip2
angie-pro-module-geoip2

Headers More

v0.40

angie-module-headers-more
angie-pro-module-headers-more

HTTP Auth RADIUS

458af16

angie-module-http-auth-radius
angie-pro-module-http-auth-radius

JWT

v3.4.6

angie-module-jwt
angie-pro-module-jwt

Keyval

0.5.0

angie-module-keyval
angie-pro-module-keyval

Lua: http_lua_module, stream_lua_module

0.10.31 / v0.0.17

angie-module-lua
angie-pro-module-lua

ModSecurity

v1.0.4

angie-module-modsecurity
angie-pro-module-modsecurity

NJS: http_js, stream_js

1.0.1

angie-module-njs
angie-pro-module-njs

NDK

v0.3.4

angie-module-ndk
angie-pro-module-ndk

OIDC

0.8.0

angie-module-oidc
angie-pro-module-oidc

OpenTracing

v0.50.0

angie-module-opentracing
angie-pro-module-opentracing

OpenTelemetry

v0.1.2

angie-module-otel
angie-pro-module-otel

PostgreSQL

1.0rc7

angie-module-postgres
angie-pro-module-postgres

Redis2

v0.15

angie-module-redis2
angie-pro-module-redis2

RTMP

v1.2.2

angie-module-rtmp
angie-pro-module-rtmp

Set Misc

v0.34

angie-module-set-misc
angie-pro-module-set-misc

Subs

e12e965

angie-module-subs
angie-pro-module-subs

TestCookie

7d263d4

angie-module-testcookie
angie-pro-module-testcookie

UnBrotli

60bed63

angie-module-unbrotli
angie-pro-module-unbrotli

UnZstd

658990e

angie-module-unzstd
angie-pro-module-unzstd

Upload

2.3.0

angie-module-upload
angie-pro-module-upload

VOD

v1.10.1

angie-module-vod
angie-pro-module-vod

VTS: module-vts, module-sts, module-stream-sts

v0.2.7 / v0.1.1 / v0.1.1

angie-module-vts
angie-pro-module-vts

Weserv Images

v5.1.0

angie-module-weserv-images
angie-pro-module-weserv-images

ZIP

1.3.0

angie-module-zip
angie-pro-module-zip

Zstd

0.90.9

angie-module-zstd
angie-pro-module-zstd

Сборка модуля для пакетной версии Angie или Angie PRO#

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

  • для того же продукта — Angie или Angie PRO;

  • для той же самой версии;

  • с совпадающими параметрами сборки.

Наши пакеты собираются без параметра --with-compat, поэтому установленные из них Angie и Angie PRO отклонят модуль, собранный с параметрами ./configure по умолчанию или с --with-compat. Ниже описано, как собрать модуль так, чтобы установленный из пакета Angie или Angie PRO его загрузил. Пересобирать или заменять сам Angie или Angie PRO при этом не нужно: пакет остается установленным, а модуль собирается отдельно и подключается к нему. Модуль собирается в дереве исходного кода Angie той же версии, что и установленный пакет, с параметрами сборки этого пакета. Angie PRO поставляется только в виде пакетов, без исходного кода, но использует ту же систему сборки, что и Angie. Модуль для Angie PRO собирается в том же дереве исходного кода Angie с заголовочными файлами и конфигурацией сборки Angie PRO из пакета angie-pro-headers.

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

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

  1. Установите компилятор, библиотеки, с которыми собран Angie, и инструменты для получения исходного кода. В Debian и Ubuntu:

    $ sudo apt install build-essential libpcre2-dev zlib1g-dev libssl-dev libcrypt-dev curl git

    В RHEL, Fedora и производных установите также пакет redhat-rpm-config, который содержит настройки компилятора для сборки наших пакетов:

    $ sudo dnf install gcc make pcre2-devel zlib-devel openssl-devel libxcrypt-devel redhat-rpm-config git

  2. Только для Angie PRO: установите angie-pro-headers той же версии, что и установленный пакет angie-pro. Пакет angie-pro-headers устанавливает заголовочные файлы и конфигурацию сборки Angie PRO в каталог /usr/include/angie-pro/. Он берется из того же репозитория, что и angie-pro, а его доступность зависит от вашей лицензии. От angie-pro он не зависит, поэтому пакетный менеджер не согласует их версии; укажите версию явно. В Debian и Ubuntu:

    $ sudo apt install "angie-pro-headers=$(dpkg-query -W -f='${Version}' angie-pro)"

    В RHEL, Fedora и производных:

    $ sudo dnf install "angie-pro-headers-$(rpm -q --qf '%{VERSION}-%{RELEASE}' angie-pro)"

  3. Скачайте и распакуйте исходный код Angie установленной версии. Для Angie PRO это исходный код Angie той же версии; файлы Angie PRO добавляются в него на шаге 6. Angie PRO выводит версию с суффиксом (PRO), который первая команда отбрасывает:

    $ VERSION=$(sudo angie -v 2>&1 | sed -n 's|^Angie version: Angie/\([0-9.]*\).*|\1|p')
$ echo "$VERSION"

    1.12.3

$ curl -fsSO "https://download.angie.software/files/angie-$VERSION.tar.gz"
$ tar -xzf "angie-$VERSION.tar.gz"

  4. Склонируйте репозиторий модуля в каталог рядом с деревом исходников Angie; в примере это ngx-fancyindex:

    $ git clone https://github.com/aperezdc/ngx-fancyindex

  5. Сконфигурируйте сборку с параметрами установленного Angie или Angie PRO, добавив к ним модуль. В RHEL, Fedora и производных сначала задайте стандартные флаги компилятора дистрибутива — с ними собраны и наши пакеты, но angie -V их не выводит:

    $ export CFLAGS="$(rpm --eval '%{optflags}')"

    Затем в любом дистрибутиве выполните:

    $ cd "angie-$VERSION"
$ eval ./configure $(sudo angie -V 2>&1 | sed -n 's/^configure arguments: //p' | sed 's/ --with-license//') \
      --add-dynamic-module=../ngx-fancyindex

    eval заставляет оболочку учесть кавычки в выведенных параметрах, чтобы значения с пробелами не распались на части. Вторая команда sed убирает параметр --with-license, с которым собраны некоторые пакеты Angie PRO: ./configure Angie этого параметра не знает, а сам параметр влияет только на исполняемый файл Angie PRO, но не на модуль. В параметрах Angie его нет.

    Если ./configure завершится с ошибкой, устраните причину (например, установите недостающую библиотеку) и перед повторным запуском удалите каталог ../angie-feature-cache: параметры пакета включают --feature-cache=../angie-feature-cache, поэтому ./configure сохраняет там неудачные проверки и при следующем запуске сообщает о них как using cached проверка ... not found.

    В RHEL, Fedora и производных ошибки из-за пропущенного шага на него не указывают: без redhat-rpm-config ./configure останавливается с сообщением the invalid value in --with-ld-opt="значение", а без экспорта CFLAGS — с сообщением C99 variadic macros support is not found.

  6. Только для Angie PRO: замените заголовочные файлы и конфигурацию сборки в дереве исходного кода файлами Angie PRO:

    $ cp -r /usr/include/angie-pro/. src/
$ cp src/objs/* objs/

    Пакет повторяет структуру каталога src, поэтому первая команда заменяет заголовочные файлы. В подкаталоге objs пакета — после копирования это src/objs — лежит конфигурация сборки Angie PRO (файлы ngx_auto_config.h и ngx_auto_headers.h); вторая команда копирует эти файлы в каталог objs, созданный ./configure. Нужны обе команды. Заголовочные файлы дают модулю структуры и подпись продукта Angie PRO. Конфигурация сборки задает параметры, с которыми компилируется модуль: у Angie PRO есть параметры, которых ./configure Angie не знает, и модуль, скомпилированный с конфигурацией Angie, не совпал бы со структурами Angie PRO по расположению полей.

  7. Соберите модуль:

    $ make modules

    Результат — файл objs/ngx_http_fancyindex_module.so.

  8. Установите модуль:

    $ sudo install -m 644 objs/ngx_http_fancyindex_module.so /etc/angie/modules/

Подключение и обновление#

И в Angie, и в Angie PRO модуль подключается директивой load_module в контексте main; подключив его, проверьте и перезагрузите конфигурацию:

load_module modules/ngx_http_fancyindex_module.so;

$ sudo angie -t && sudo systemctl reload angie

Если модуль не соответствует установленному Angie или Angie PRO, angie -t завершится ошибкой с сообщением, которое указывает на несоответствие:

  • module "файл" was built for "Angie" but you are running "Angie PRO" или то же с переставленными названиями продуктов — модуль собран для другого продукта;

  • module "файл" version версия_модуля instead of версия_Angie — модуль собран для другой версии; каждая версия выводится одним целым числом, в котором младшая версия и номер исправления дополнены нулями до трех цифр;

  • module "файл" is not binary compatible — модуль собран с другими параметрами сборки.

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

После обновления пересоберите и переустановите модуль, используя его исходный код из первой сборки: повторите шаг 3 и шаги с 5 по 8, начиная с каталога, где при первой сборке выполнялся шаг 3; для Angie PRO сначала повторите шаг 2. На последнем шаге модуль устанавливается командой install, а не cp: install записывает новый файл, а не перезаписывает тот, что уже загружен работающим сервисом. Затем перезапустите сервис, чтобы новый исполняемый файл запустился с пересобранным модулем:

$ sudo angie -t && sudo systemctl restart angie

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