Шаблонизатор конфигурационных файлов

Для ISPmanager реализован новый механизм генерации конфигурационных файлов Apache и Nginx. Механизм основан на разборе шаблона, который позволяет использовать логические ветвления и подстановку параметров, и дает большую гибкость в создании, редактировании конфигурационных файлов веб серверов. Благодаря шаблонному подходу появилась возможность использовать необходимые параметры для настройки веб-серверов Apache и Nginx. Кроме того, после дополнения конфигурационного файла параметрами пользователя, никакие операции шаблонизатора не изменят эти данные. Начиная с версии 5.57 ISPmanager использует по умолчанию данный механизм. В этой статье будет рассказано, как начать использовать шаблонизатор, об общих принципах работы и его синтаксических конструкциях.

Как начать использовать шаблонизатор?

Если вы используете свежую установку ISPmanager 5.57 и старше, то шаблонизатор используется по умолчанию для генерации конфигурационных файлов модуля WWW-домены. Если вы обновили панель управления до версии 5.57 или до более поздней версии, тогда необходимо установить параметр Option EnableWebTemplate в конфигурационном файле панели управления ISPmanager Business в /usr/local/mgr5/etc/ispmgr.conf расположенный на локальном узле кластера, после чего необходимо перезапустить панель управления.

Начиная с версии 5.57 опция AlphaWebTemplate, с помощью которой ранее включался данный механизм, более не доступна.

Общие принципы работы шаблонизатора

В модуле WWW-домены каждой функции соответствует свой шаблон конфигурационного файла. Например, функциям создания и редактирования веб-домена соответствует шаблон записанный в файле /usr/local/mgr5/etc/templates/default/apache2-vhosts.template для конфигурационного файла Apache и /usr/local/mgr5/etc/templates/default/nginx-vhosts.template для конфигурационного файла Nginx.

Файлы с шаблонами конфигураций могут быть переопределены пользовательскими параметрами. Для этого просто скопируйте файл с шаблоном в директорию /usr/local/mgr5/etc/templates с тем же именем. Если в директории /usr/local/mgr5/etc/templates есть файл шаблона, шаблон в директории /usr/local/mgr5/etc/templates/default/ игнорируется. При обновлении панели файлы в директории /usr/local/mgr5/etc/templates/default/ будут перезаписаны, поэтому все правки нужно производить в /usr/local/mgr5/etc/templates/.

Ниже, в таблице, указано соответствие файла с шаблоном вызываемой функции в модуле WWW-домены.

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

Синтаксис

Все шаблонные конструкции должны быть расположены между парой тегов *{%* и *%}*. Например, переменная должна быть записана следующим образом: *{% $VARIABLE_NAME %}*.

Переменные

Имя переменной должно соответствовать следующим требованиям:

• записано в верхнем регистре
• начинается со знака $
• совпадает с именем параметра, передаваемого панелью управления в сессию.

Если в шаблоне конфигурационная строка будет содержать переменную, которой нет в сессии, то эта строка будет проигнорирована. Рассмотрим пример, в котором шаблонизатор создаст секцию VirtualHost, для конфигурационного файла Apache. В данном примере мы будем использовать переменную *{%$LISTEN_ON %}*, которая хранит в себе адрес и порт: 192.168.0.1:80.

<VirtualHost {% $LISTEN_ON %}>
</VirtualHost>

В результате, в конфигурационном файле будет создана секция VirtualHost, если её не было:

<VirtualHost 192.168.0.1:80>
</VirtualHost>

Условия

Условия — это основной инструмент выбора. Проще говоря, он выбирает, какой параметр нужно добавить, а какой удалить, в зависимости от значения переменных в момент проверки условия. Условия должны начинаться с инструкции if и заканчиваться инструкцией endif. Для начала рассмотрим простое условие, состоящее из одной инструкции if.

{% if $VARIABLE_NAME == VALUE %}
    ParameterName ParameterValue;
{% endif %}

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

Расширенные условия

Простое условие может быть расширено инструкцией else. Параметры размещенные между инструкциями else и endif будут добавлены в конфигурационный файл, если результат инструкции if — ложь; или удалены из конфигурационного файла, если результат инструкции if — истина. Рассмотрим пример в котором, в зависимости от используемой версии веб-сервера Apache, необходимо добавить или удалить параметр:

<VirtualHost {% $LISTEN_ON %}>
{% if $APACHEITK == ON %}
    AssignUserID owner group
{% else %}
    SuexecUserGroup owner group
{% endif %}
</VirtualHost>

В результате, в конфигурационном файле будет создана секция VirtualHost, если ее не было, и если используется ApacheITK, в секцию VirtualHost будет добавлен параметр AssignUserID owner group, а параметр SuexecUserGroup owner group будет удален из секции VirtualHost, если он присутствовал в этой секции. Ниже показано какие параметры будет содержать конфигурационный файл, если используется ApacheITK:

<VirtualHost 192.168.0.1:80>
    AssignUserID owner group
</VirtualHost>

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

<VirtualHost 192.168.0.1:80>
    SuexecUserGroup owner group
</VirtualHost>

Условия множественного выбора

Условие может быть расширено до множественного выбора с помощью инструкции elif. Подобная конструкция может использоваться в ситуации, когда одна переменная может иметь разные значения и все необходимо обработать. Например, при создании или редактировании веб-домена ISPmanager дает возможность выбрать режим работы PHP. В качестве примера рассмотрим ситуацию с выбором режима PHP. Предположим, что у нас уже был создан веб-домен с режимом работы PHP как модуль Apache. Наш текущий конфигурационный файл имеет следующий вид:

<VirtualHost 192.168.0.1:80>
    ServerName domain.ru
    ServerAlias www.domain.ru
    <FilesMatch "\.ph(p[3-5]?|tml)$">
        SetHandler application/x-httpd-php
    </FilesMatch>
    <FilesMatch "\.phps$">
        SetHandler application/x-httpd-php-source
    </FilesMatch>
</VirtualHost>

Отредактировав параметры веб-домена мы установили режим работы PHP как CGI. Шаблон, представленный ниже, отвечает за добавление или удаление подсекций FilesMatch относительно выбранного режима работы PHP.

<VirtualHost {% $LISTEN_ON %}>
{% if $PHP_MODE == MODULE_APACHE %}
    <FilesMatch "\.ph(p[3-5]?|tml)$">
        SetHandler application/x-httpd-php
    </FilesMatch>
    <FilesMatch "\.phps$">
        SetHandler application/x-httpd-php-source
    </FilesMatch>
{% elif $PHP_MODE == CGI %}
    <FilesMatch "\.ph(p[3-5]?|tml)$">
        SetHandler application/x-httpd-php5
    </FilesMatch>
{% endif %}
</VirtualHost>

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

<VirtualHost 192.168.0.1:80>
    ServerName domain.ru
    ServerAlias www.domain.ru
    <FilesMatch "\.ph(p[3-5]?|tml)$">
        SetHandler application/x-httpd-php5
    </FilesMatch>
</VirtualHost>

Таблица операторов сравнения

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

Комментирование строк

С помощью символов *{#}* можно комментировать строки в шаблоне конфигурационного файла. Все, что записано после знака комментария будет проигнорировано шаблонизатором. Например:

<VirtualHost {% $LISTEN_ON %}>
    ServerName {% $NAME %} {#} Комментарий
    {#} ServerAlias {% $ALIASES %}
</VirtualHost>

После обработки шаблона конфигурационный файл будет иметь вид:

<VirtualHost 192.168.0.1:80>
    ServerName domain.ru
</VirtualHost>

Импортирование шаблона

В шаблон конфигурационного файла могут быть импортированы другие шаблоны. Импортировать шаблон можно с помощью конструкции import. Например:

<VirtualHost {% $LISTEN_ON %}>
    {% import /path/to/template/apache-params.template %}
</VirtualHost>

Путь до импортируемого шаблона должен быть абсолютный.

Параметры идентифицирующие секции

Для каждого типа конфигурационных файлов определены параметры, благодаря которым шаблонизатор идентифицирует секции. Например, для конфигурационного файла Nginx в качестве ключевых параметров выбраны server_name и ssl. Т.е. когда необходимо что-то добавить или удалить из конфигурационного файла, шаблонизатор точно знает, в какой именно секции нужно выполнить действия. Однако, если попытаться изменить эти параметры, в конфигурационном файле, в обход панели управления, то появляется вероятность, что изменения не попадут в ожидаемую секцию, а будут применены в новой секции.

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

Существует дополнительная пара тегов — [%* и *%]. В них могут быть записаны только переменные, например [% $VARIABLE_NAME %]. Данное выражение интерпретируется как обычная переменная, однако для него выделена отдельная роль в поиске параметра. Эти теги определяют значения, которые не будут участвовать в поиске параметра. Для примера предположим, что конфигурационный файл нашего веб-домена имеет следующий вид:

<VirtualHost 192.168.0.1:80>
    ServerName domain.ru
    ServerAlias www.domain.ru
</VirtualHost>

Для работы со страницей ошибки используем шаблон:

<VirtualHost {% $LISTEN_ON %}>
{% if $ERROR == on %}
    ErrorDocument {% $CODE %} [% $URI %]
{% endif %}
</VirtualHost>

Если значение переменной $ERROR будет равно on, тогда в секцию VirtualHost будет добавлен параметр ErrorDocument со значениями переменных $CODE и $URI. Значения $CODE и $URI задаются в панели управления, на форме создания страницы ошибки. В процессе создания страницы ошибки переменная $ERROR принимает значение on, следовательно условие выполнилось и наш конфигурационный файл имеет следующий вид:

<VirtualHost 192.168.0.1:80>
    ServerName domain.ru
    ServerAlias www.domain.ru
    ErrorDocument 404 /404.php
</VirtualHost>

Далее, мы решили самостоятельно изменить в конфигурационном файле путь /404.php на /404.html. Наш конфигурационный файл будет иметь вид:

<VirtualHost 192.168.0.1:80>
    ServerName domain.ru
    ServerAlias www.domain.ru
    ErrorDocument 404 /404.html
</VirtualHost>

В таком виде параметр ErrorDocument существенно отличается от того, что у нас записано в панели управления. Если мы решим удалить страницу ошибки из панели управления, то шаблонизатор не сможет найти нужный параметр в конфигурационном файле и удалить его. Но так как в шаблоне значение $URI отмечено как незначащее, то для поиска будет использована строка ErrorDocument 404. В процессе удаления страницы-ошибки переменная $ERROR принимает значение off, следовательно условие, используемое в шаблоне, не выполнится. Для поиска нашего параметра будет использована не полная строка, а её часть — ErrorDocument 404, что поможет найти параметр в конфигурационном файле и удалить его.

Список стандартных переменных

Каждая вызванная функция использует свой набор параметров, которые передаются в сессию. Ниже мы рассмотрим для каждой функции управления WWW-доменом список стандартных переменных.

Создание/Изменение WWW-домена

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

Переменные веб-сервера Apache

Переменные веб-сервера Nginx

Страницы ошибок

Редиректы

Доступ

Набор параметров на вашем сервере может отличаться от приведенного выше, в зависимости от активированных возможностей, установленных плагинов и т.д. Актуальный набор параметров, для вызванной функции, вы всегда можете узнать в лог-файле панели управления /usr/local/mgr5/var/ispmgr.log. Вызов функции, в лог-файле, обозначен зеленым цветом. Также переданные параметры можно посмотреть в консоли вашего веб-браузера, после отправки формы на сервер.

Пример использования

Рассмотрим ситуацию, когда в зависимости от типа шаблона учетной записи, по которому был создан пользователь, необходимо сгенерировать разные параметры конфигурационного файла. В примере будет всего два типа шаблона учетных записей: для пользователей CMS «1C-Bitrix» и веб-фреймворка «Django». Для начала создадим шаблоны учетных записей. В ISPmanager Lite перейдем в модуль «Шаблоны», расположенный в разделе меню «Настройки» и создадим новый шаблон учетной записи с названием «Bitrix». Параметры «Ограничения» могут быть выставлены произвольным образом, в разделе «Доступ» установим параметр Может использовать PHP как модуль apache, кодировку домена установим UTF-8 и Тип обработчика PHP как модуль Apache. Далее создадим шаблон учетной записи для Django. В качестве названия пишем Django, ограничения и доступы могут быть выставлены произвольным образом, раздел «Значения по умолчанию» устанавливаем по аналогии с предыдущим шаблоном.

Для работы сайта под управлением CMS «1С-Bitrix» достаточно в шаблоне apache2-vhost.template определить дополнительные параметры, однако для работы сайта под управлением веб-фреймворка Django необходимо установить модуль «mod_wsgi» для Apache. Для Linux дистрибутива Debian данный модуль устанавливается командной:

# apt-get install libapache2-mod-wsgi

Для Linux дистрибутива CentOS данный модуль устанавливается командной:

# yum install mod_wsgi

Также для обработки запросов нам понадобится интерфейс к модулю «mod_wsgi». Исходный код интерфейса можно найти на ресурсах посвященных веб-фреймворку «Django». В данном пример определим только имя интерфейса — django.wsgi, который нужно будет расположить в корневой директории веб-домена.

Теперь нужно подготовить шаблон конфигурационного файла. Скопируем шаблон */usr/local/mgr5/etc/templates/default/apache2-vhosts.template* в директорию */usr/local/mgr5/etc/templates/* и добавим в конец секции ** параметры:

{% if $USER_PRESET == Bitrix %}
    php_admin_value mbstring.func_overload 2
    php_admin_value mbstring.internal_encoding UTF-8
    php_admin_value opcache.revalidate_freq 0
    php_admin_value display_errors on
{% elif $USER_PRESET == Django %}
    WSGIScriptAlias / {% $DOCROOT %}/django.wsgi
    WSGIDaemonProcess [% $NAME %] processes=2 maximum-requests=5 threads=1
    WSGIProcessGroup {% $NAME %}
{% endif %}

В итоге шаблон секции VirtualHost будет выглядеть таким образом:

<VirtualHost {% $LISTEN_ON %}>
	ServerName {% $NAME %}
	ServerAlias {% $ALIASES %}
	DocumentRoot {% $DOCROOT %}
	ServerAdmin {% $EMAIL %}
	DirectoryIndex {% $DIRINDEX %}
	AddDefaultCharset {% $CHARSET %}
{% if $APACHEITK == on %}
	AssignUserID {% $OWNER %} {% $OWNER_GROUP %}
{% else %}
	SuexecUserGroup {% $OWNER %} {% $OWNER_GROUP %}
{% endif %}
{% if $LOG_ACCESS == on %}
	CustomLog {% $ACCESS_LOG_PATH %} combined
{% else %}
	CustomLog /dev/null combined
{% endif %}
{% if $LOG_ERROR == on %}
	ErrorLog {% $ERROR_LOG_PATH %}
{% else %}
	ErrorLog /dev/null
{% endif %}
{% if $CGI == on %}
	ScriptAlias /cgi-bin/ {% $CGI_EXT_PATH %}
{% endif %}
{% if $INCLUDE %}
	Include {% $INCLUDE %}
{% endif %}
{% if $PHP == on and $FILES_MATCH == on %}
	<FilesMatch "\.ph(p[3-5]?|tml)$">
		SetHandler {% $PHP_HANDLER %}
{% if $APACHE_FCGID == on %}
		FCGIWrapper {% $PHP_BIN_WRAPPER %}
		Options ExecCGI
{% endif %}
	</FilesMatch>
{% endif %}
{% if $PHP_MODE == php_mode_mod %}
	<FilesMatch "\.phps$">
		SetHandler application/x-httpd-php-source
	</FilesMatch>
{% if $INCLUDE_PHP %}
	Include {% $INCLUDE_PHP %}
{% endif %}
	php_admin_value sendmail_path "/usr/sbin/sendmail -t -i -f {% $EMAIL %}"
	php_admin_value upload_tmp_dir "{% $MOD_TMP_PATH %}"
	php_admin_value session.save_path "{% $MOD_TMP_PATH %}"
{% if $OPEN_BASEDIR != / %}
	php_admin_value open_basedir "{% $OPEN_BASEDIR %}"
{% endif %}
{% elif $PHP_MODE == php_mode_cgi %}
	ScriptAlias /php-bin/ {% $PHP_BIN_DIR %}
	AddHandler application/x-httpd-php5 .php .php3 .php4 .php5 .phtml
	Action application/x-httpd-php5 /php-bin/php
{% elif $PHP_MODE == php_mode_fcgi_apache and $APACHE_FCGID != on %}
	AddType application/x-httpd-fastphp .php .php3 .php4 .php5 .phtml
	Alias /php-fcgi/ {% $PHP_BIN_DIR %}
{% endif %}
{% if $VIRTUAL_DOCROOT == on %}
	VirtualDocumentRoot {% $VIRTUAL_DOCROOT_PATH %}
{% endif %}
{% if $USER_PRESET == Bitrix %}
    php_admin_value mbstring.func_overload 2
    php_admin_value mbstring.internal_encoding UTF-8
    php_admin_value opcache.revalidate_freq 0
    php_admin_value display_errors on
{% elif $USER_PRESET == Django %}
    WSGIScriptAlias / {% $DOCROOT %}/django.wsgi
    WSGIDaemonProcess [% $NAME %] processes=2 maximum-requests=5 threads=1
    WSGIProcessGroup {% $NAME %}
{% endif %}
</VirtualHost>

Теперь при создании веб-домена, в зависимости от того по какому шаблону учетных записей создан пользователь, будут генерироваться конфигурационные данные для использования CMS «1C-Bitrix» или веб-фреймворка «Django».