This is documentation for an outdated product. See the current documentation

ISPmanager 5 Business Documentation

Template engine for configuration files

 

A new mechanism that allows generating Apache and Nginx configuration files. The mechanism is based on a template that enables to use logical branches and parameter setting, allowing for more flexible creation and modification configuration parameters of a web-server.

With this mechanism, you can use the required parameters in order to configure Apache and Nginx. Besides, after you add user parameters into the configuration file, other operations that the template engine performs, won't modify them.

Starting from version 5.57, ISPmanager supports this feature by default. This article will walk you through the steps you need to perform to start using a template engine, describe its general functions and syntax.

How to start?

If you have just installed ISPmanager Lite or ISPmanager Business 5.57 and later, the template engine will be used by default to generate configuration files of the "WWW-domains" module.

If you updated your panel to version 5.57 or later, you need to add the Option EnableWebTemplate parameter in ISPmanager Lite /usr/local/mgr5/etc/ispmgr.conf configuration file and ISPmanager Business /usr/local/mgr5/etc/ispmgr.conf, located on a local cluster node, and restart the panel.

Starting from version 5.57 the AlphaWebTemplate option that enabled this mechanism in older versions is no longer supported.

General principles

In the WWW-domains module every function has a corresponding configuration file template. E.g., web-domain creation/edit function has a corresponding template in the /usr/local/mgr5/etc/templates/default/apache2-vhosts.template file for Apache configuration file, and /usr/local/mgr5/etc/templates/default/nginx-vhosts.template for Nginx.


Files with configuration templates can be re-defined by user parameters. Copy a file with template into the /usr/local/mgr5/etc/templates directory with the same name. If the /usr/local/mgr5/etc/templates directory contains a template file, the template in the /usr/local/mgr5/etc/templates/default/ directory will be ignored. When the panel updates, files in the /usr/local/mgr5/etc/templates/default/ directory will be overwritten, that's why you should make changes in /usr/local/mgr5/etc/templates/.

The table below shows correspondence between a file with a template, and a function to call in the WWW-domains module.

FunctionNginx templateApache template
Add/Edit WWW-domainnginx-vhosts.templatenginx-vhosts-ssl.templateapache2-vhosts.templateapache2-vhosts-ssl.template
Add/Edit/Delete error pagenginx-error-page.templateapache2-error-page.template
Add/Edit/Delete redirectsnginx-rewrite.templateapache2-redirect.template
Add/Delete access permissionsnginx-access.templateapache2-access.template
Resume/Suspend WWW-domainnginx-suspend.templateapache2-suspend.template

Syntax

All template sections must locate between tags {% and %}. E.g. a variable should look like this: {% $VARIABLE_NAME %}.

Variables

A variable name should meet the following requirements:

  • user upper-case letters
  • start with $
  • have the same name as the parameter passed to the session by the control panel.

If a configuration string in template contains a variable that is not present in the session, the string will be ignored. Let's consider an example where the template will create the VirtualHost section for the Apache configuration file. In the example below, we will use the {%$LISTEN_ON %} variable where an address and port are kept: 192.168.0.1:80.

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

As a result, the VirtualHost section will be created in the configuration file:

<VirtualHost 192.168.0.1:80>
</VirtualHost>

Conditions

A condition is the main selection tool. It will choose, what parameter to add or delete depending on variable during condition check. Conditions should start with the if statement and end with endif. Let's consider a simple condition containing only if.

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

If a result of this condition is true, every parameter located between if and endif will be added into the configuration file (if that parameter is not present). If the result is false, every parameter between if and endif will be deleted from the configuration file.

Advanced conditions

You can create an advanced condition containing else. Parameters located between else and endif will be added into the configuration file if a result of the if statement is false, or deleted from the configuration file, if it is true. Let's consider an example where parameter will be added or deleted depending on Apache version:

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

The VirtualHost section will be created in the configuration file, if ApacheITK is used, the AssignUserID owner group parameter will be added into VirtualHost, and the SuexecUserGroup owner group parameter will be deleted from VirtualHost, if it was present in that section. The following example shows what parameters the configuration file will contain if ApacheITK is used:

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

If another version of Apache is used, the configuration file will contain the following parameters:

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

Conditions for multiple selections

A condition can be enlarged with the elif statement. It can be used if one of the variables have different values, which should be processed. E.g. when creating or editing a web-domain, ISPmanager enables to choose a PHP mode. Let's consider such a situation, and suppose that we have created a web-domain with "PHP as Apache" enabled. Our configuration file looks like that:

<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>

We edited web-domain parameters and set PHP as CGI. The template below enables to add or delete the FilesMatch subsection depending on a selected PHP mode.

<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>

The VirtualHost section won't be created in the configuration file, as it is already present. All the changes will be made in existing VirtualHost. Based on conditions from our example, the result of the if statement will be false, therefore, all parameters between if and elif will be deleted from VirtualHost. Parameters between elif and endif will be added into VirtualHost. The configuration file will look like that:

<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>

Table of comparison operators

The following comparison operators can be used in conditions:

OperatorComparison
==Equality. This condition is true if two operands are equal
!=Inequality. This condition is true if two operands are not equal
>Larger. This condition is true if the first operand is larger than the second one
<Less. This condition is true if the first operand is less than the second one

String commenting

You can use {#} to comment strings in the configuration file template. Everything that you add after comment will be ignored by the template engine. Example:

<VirtualHost {% $LISTEN_ON %}>
    ServerName {% $NAME %} {#} Comment 
    {#} ServerAlias {% $ALIASES %}
</VirtualHost>

The configuration file will then look like that:

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

Template import

Other templates can be imported into the configuration file template. Use the import construction. E.g.:

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

Enter an absolute path to a template you want to import.

Parameters that identify sections

Every type of configuration file has certain parameters that are used by the template engine to identify sections. E.g. for the Nginx configuration file, server_name and ssl are selected as key parameters. Therefore, when something should be added or deleted from the configuration file without a control panel, the template engine "knows" exactly where to perform the operation. However, if you are trying to modify those parameters in the configuration file, they are likely not to be added into a required section but will be applied in a new section.

Searching for a modified parameter by key values

There are additional tags — [% и %]. They can contain only variables, such as [% $VARIABLE_NAME %]. This expression is interpreted as a common variable but plays a specific role in parameter search. These tags define values that won't be used during the search process. Let's consider the following example:

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

Use the template:

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

If the $ERROR variable is on, the ErrorDocument parameter with variables $CODE and $URI will be added into VirtualHost. The $CODE and $URI values are specified in the control panel on the error page creation form. During that process, the $ERROR variable is set to on, therefore the condition is met, and our configuration file looks like that:

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

Then, we decided in the configuration file change the path from /404.php into /404.html. We have the following configuration file:

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

In this case, the ErrorDocument parameter differs from the one specified in the control panel. If we decide to delete the error page from the control panel, the template engine won't find a required parameter in the configuration file and won't delete it. But in the template the $URI value is canceled, the search will be made by the ErrorDocument 404 string. Deleting of an error page will set the $ERROR variable to off, therefore the condition used in the template, won't be met. Only ErrorDocument 404 will be used to search for our parameter, thus it will be found and deleted in the configuration file.

Standard variables

Every function you call uses its own set of parameters that are passed to a session. The following list contains standard variables for each WWW-domain management function.

Creating/Editing WWW-domain

The table below contains a list of variables regardless a web-servers type.

VariableDescription
Main parameters of WWW-domain
$NAMEWWW-domain name
$ALIASESWWW-domains aliases
$DOCROOTRoot directory
$HOMEHome directory of a WWW-domain's owner
$OWNERWWW-domain's owner
$OWNER_GROUPWWW-domain's owner group
$UIDOwner UID
$GIDOwner GUID
$PRESETOwner templateOnly for ISPmanager Lite
$PRESET_NAMEOwner templateOnly for ISPmanager Business and if the reseller is not a user's owner
$RESELLER_NAMEReseller nameOnly for ISPmanager Business
$RESELLER_PRESETReseller templateOnly for ISPmanager Business
$IPADDRSIP-addresses to listen
$LISTEN_ONIP-addresses and port to listen
$EMAILAdministrator email
$CHARSETEncoding
$DIRINDEXIndex page
$SSLWWW-domain uses secure connection. Possible values:
  • on — used
  • off — not used
$REDIRECT_HTTPRedirect HTTP-requests to HTTPS. Possible values:
  • on — redirect
  • off — do not redirect
$SSL_PORTSecure connection port
$LISTEN_ON_SSLIP-address and port of secure connection
$SSL_CRTPath to SSL certificate
$SSL_KEYPath to SSL key
$SSL_BUNDLEChain of SSL certificate including root and intermediate certificates
$HSTSAdvanced SSL secure. Possible values:
  • on — used
  • off — not used
$SSL_SECURE_PROTOCOLSSSL protocols
$SSL_SECURE_CHIPHERSCryptographic algorithm
$SSISSI. Possible values:
  • on — enabled
  • off— disabled
$FOREGROUNDCurrent WWW-domain has the highest priority. Possible values:
  • on — has the highest priority
  • off — doesn't have the highest priority
Logging
$LOG_ACCESSAllow logging of requests to resources of this WWW-domain. Possible values:
  • on — logging enabled
  • off — logging disables
$ACCESS_LOG_PATHPath log-file with requests to resources
$LOG_ERRORAllow logging of errors that occur when processing requests to resources of this WWW-domain. Possible values:
  • on — logging enabled
  • off — logging disabled
$ERROR_LOG_PATHPath to error log-file
$ROTATION_PERIODRotation period. Possible values:
  • every_day — daily
  • every_week — weekly
  • every_month — monthly
  • by_size — by size
$ROTATION_COUNTNumber of old copies to store
$ANALYZERAnalyzer. Possible values:
  • off
  • awstats
  • webalizer
Values depend on installed applications
$ANALYZER_PERIODReport period. Possible values:
  • rotate — during rotation
  • every_hour — every hour
  • every_day — daily
  • every_week — weekly
  • every_month — monthly
$ANALYZER_LANGReport language
$ANALYZER_SECURERestrict access to statistics. Possible values:
  • on — access restricted
  • off — access is not restricted
$ANALYZER_PASSWDPassword to access statistics
Additional features
$AUTOSUBDOMAINAuto-subdomain type. Possible values:
  • off — disabled
  • autosubdomain_dir — in a separate directory
  • autosubdomain_subdir — in domain's subdirectory
$PHPAllow processing of PHP scripts. Possible values:
  • on — allow
  • off — forbid
$PHP_MODEPHP mode
$PHP_NATIVE_VERSIONPHP version

Apache variables

NameDescription
$LISTEN_ONIP-address and port to listen
$APACHEITKApache ITK is used as web-server. Possible values:
  • on — Apache ITK
  • off — another web-server
$CGIAllow CGI-scripts. Possible values:
  • on — allow
  • off — forbid
$CGI_EXTAdditional extensions of files of CGI-scripts
$CGI_EXT_PATHA path to the cgi-bin directory
$INCLUDEA path to the configuration file of WWW-domain's user resourcesThis variable is set for ISPmanager Business
$INCLUDE_PHPA path to the configuration file of WWW-domain's user resources (for PHP as Apache)This variable is set for ISPmanager Business

Nginx variables

NameDescription
$NGINX_LISTEN_ONIP-addresses and port to listen
$NO_TRAFF_COUNTTraffic statistics. Possible values
  • on — enabled
  • off — disabled
$AUTOSUBDOMAIN_SUBDOMAIN_PARTDomain's root directory
$USER_NGINX_RESOURCES_PATHA path to the configuration file of WWW-domain's user resources (for PHP as Apache)This variable is set for ISPmanager Business
$NGINX_VHOST_INCLUDESA path to Nginx service settings
$SRV_GZIPAllow compression. Possible values:
  • on — use
  • off — do not use/li>
$GZIP_LEVELCompression level
$SRV_CACHEAllow caching. Possible values:
  • on — use
  • off — do not use
$EXPIRES_VALUECaching period
$WEBSTAT_LOCATIONLocation of statistics directory
$WEBSTAT_ENCODINGStatistics encoding
$REDIRECT_TO_APACHERedirect request to Apache. Possible values:
  • on — request is redirected
$BACKEND_BIND_URIAddress and port that Apache listens
$REDIRECT_TO_PHPFPMPHP as FastCGI (Nginx + PHP-FPM). Possible values:
  • on — use FastCGI (Nginx + PHP-FPM)
  • Variable is not set in other cases
Value is set if "PHP as FastCGI (Nginx + PHP-FPM)" is used
$PHPFPM_USER_SOCKET_PATHA path to the unix socketValue is set, if the "PHP as FastCGI (Nginx + PHP-FPM)" is used
$DDOSSHIELDEnable DDoS protection. Possible values:
  • on — enabled
  • off— disabled
$NGINX_LIMITREQUESTRequests per second
$NGINX_BURSTREQUESTMaximum peak attack size
$SSL_CRT_BUNDLE_PATHPath to the file with SSL-certificate and bundle
THIS_BLOCK_FOR_REMOVE_EXPIRESAn auxiliary parameter. Used to remove all data caching directive when using PHP-FPM. For configuration files created in ISPmanager version earlier than 5.171.0.

Error pages

NameDescription
$NAMEWWW-domain names
$ALIASESWWW-domain aliases
$OWNERWWW-domain owner
$LISTEN_ONIP address and port to listen
$SSLWWW-domain uses secure connection. Possible values:
  • on — secure connection is used
  • off— secure connection is not used
$LISTEN_ON_SSLIP address and port to listen, and secure connection port
$ERRORPossible values:
  • on — if an error page is created or edited
  • off— error page is deleted
$CODEError code that will be associated with a page URI
$URIPage that will open in case of error

Redirects

NameDescription
$NAMEWWW-domain name
$ALIASESWWW-domain alias
$OWNERWWW-domain owner
$LISTEN_ONIP address and port
$SSLWWW-domain uses secure connection. Possible values:
  • on — secure connection is used
  • off— secure connection is not used
$LISTEN_ON_SSLIP address and port of the secure connection
$REDIRECTPossible values:
  • on — redirect is created and edited
  • off— redirect sis deleted
$PATHRelative path that will be redirected to another URL
$URLRedirect to this URL
$FLAGStop processing directives. Possible values:
  • permanent
  • redirect
  • last
Parameter has value only when handling the nginx-rewrite.template template

Access

NameDescription
$NAMEWWW-domain name
$ALIASESWWW-domain alias
$OWNERWWW-domain owner
$SSLWWW-domain uses secure connection. Possible values:
  • on — secure connection is used
  • off— secure connection is not used
$LOCATION_PATHRelative path to the directory that will be password protected
$ACCESSPossible values:
  • on — restrict access
  • off— do not restrict access
$AUTH_FILEFile with usernames and their passwords
$AUTH_REALMName of the login windowParameter is set only when handling the apache-access.template template

Parameters on your server may vary depending on applications, plug-ins, etc that you use. A current set of parameters of the function that you call, can be found in the /usr/local/mgr5/var/ispmgr.log log file. Function call is shown in green. You can also view parameters that were passed, in the console of your web-browser after the form is sent to server.

Example

Let's consider a situation when we need to generate different parameters of the configuration files depending on account template type that was used for user creation. In our example, we will use only two types of user templates: for CMS «1C-Bitrix» and web-framework «Django». First, we need to create user templates. Log in to ISPmanager Lite-- "Settings" -- "Templates", and create a new template named «Bitrix». You can enter any values in the «Limits» tab. In the «Access» tab select the Can use PHP as Apache checkbox, domain encoding - UTF-8, and PHP mode - Apache. Create a template for Django. Name - Django, enter any limits and access permissions, "Default values" - set the same values as in your previous template.

If you want to manage your site with «1C-Bitrix», in the apache2-vhost.template template you need to define additional parameters. If you want to use Django, you need to install the «mod_wsgi» module for Apache. If you run Debian, execute the command to install the module:

# apt-get install libapache2-mod-wsgi

If you run CentOS, execute the command:

# yum install mod_wsgi

In order to handle requests, we will need a web-interface for the «mod_wsgi» module. A source code of the interface can be found on the Internet in topics related to «Django». In our example, we will define only the interface name — django.wsgi that you should put to the WWW-domain root directory.

Create a configuration file template. Copy the /usr/local/mgr5/etc/templates/default/apache2-vhosts.template template into the /usr/local/mgr5/etc/templates/ directory, as described in General principles, and add parameters at the end of  :

{% 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 template will look like this:

<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>

When creating a WWW-domain, depending on a user template that was used for user creation, configuration data will be generated for «1C-Bitrix» or «Django».