Basic Templating Concepts
The following points provide some basic information about the templating system. More detailed information will be provided on each topic later in this guide.
1. The templating system makes use of the YAML syntax.
2. Variables can be used in the templates which expand to the value specific to the domain in each pool. The [% homedir %] variable for example will expand to the home directory for each domain in the final generated configuration.
3. Default Templates set defaults that can be overridden by the individual Pool Override Templates.
On cPanel, there is a 1 to 1 relationship between PHP-FPM pools and domains. Each domain gets its own pool.
4. If the systems administrator finds it necessary to override one of the default settings for an individual domain/pool, they may create a Pool Override Template to store those override settings.
5. In order for PHP-FPM to be able to read the settings, a raw PHP-FPM configuration file must be built for each individual pool. When a configuration rebuild is initiated, cPanel will parse all available PHP-FPM templates, and then generate the raw PHP-FPM pool configuration files from them. The raw configuration files for each pool are not intended to be edited manually. Instead, edits should be made to the templates, and then the raw configuration files should be rebuilt from the templates.
The Default Templates
There are two different types of PHP-FPM directives.
The first type of PHP-FPM directive is the Global Directive. They are listed in the PHP Documentation under the table titled:
List of global php-fpm.conf directives
The second type of PHP-FPM configuration directive is called the Pool Directive. They are listed on the same page under the table titled:
Because there are two different types of directives, cPanel's templating system has a separate default template file for each type of directive to segregate them.
The Global Defaults Template
If you would like to edit the existing defaults for the Global FPM directives (mentioned above), you must create the following template file:
/var/cpanel/ApachePHPFPM/system.yaml
Because the templating system makes use of the YAML syntax, this file should begin with three dashes at the top. The name of each Global directive goes on the left, followed by a colon (:) symbol, and then the value for the directive is placed to the right of the colon. Also, any period characters found in the PHP-FPM directive name must be replaced with an underscore symbol due to the fact that the template is written in YAML. Below is an example template, as well as what that example would look like if it were written in the standard syntax used by the PHP-FPM configuration:
cPanel's Template Example:
---
pid: /opt/cpanel/[% ea_php_version %]/root/usr/var/run/php-fpm/php-fpm.pid
syslog_facility: daemon
syslog_ident: php-fpm
The following shows what this same configuration would look like in a raw PHP-FPM configuration file. You will not be creating the raw configuration file. This is only provided as an example to help demonstrate how you would adjust your habits if you are used to editing raw FPM configurations:
pid = /opt/cpanel/php74/root/usr/var/run/php-fpm/php-fpm.pid
syslog.facility = daemon
syslog.ident = php-fpm
NOTE: Remember only the Global FPM directives go in the Global Default template above.
The Pool Defaults Template
If you would like to edit the existing defaults for the FPM Pool Directives (mentioned above), you must create the following template file:
/var/cpanel/ApachePHPFPM/system_pool_defaults.yaml
Because the templating system makes use of the YAML syntax, this file should begin with three dashes at the top. The name of each Pool Directive goes on the left, followed by a colon (:) symbol, and then the value for the directive is placed to the right of the colon. Also, any period characters found in the PHP-FPM directive name must be replaced with an underscore symbol due to the fact that the template is written in YAML. Below is an example template, as well as what that example would look like if it were written in the standard syntax used by the PHP-FPM configuration:
cPanel's Template Example:
---
pm: dynamic
chdir: [% homedir %]
listen_allowed_clients: any
listen_backlog: -1
The following shows what this same configuration would look like in a raw PHP-FPM configuration file. You will not be creating the raw configuration file. This is only provided as an example to help demonstrate how you would adjust your habits if you are used to editing raw FPM configurations:
pm = dynamic
chdir = /home/exampleuser/
listen.allowed_clients = any
listen.backlog = -1
NOTE: Remember only the Pool FPM directives go in the Pool Defaults template above.
The Pool Override Templates
On cPanel, each domain has its own separate pool. Each pool has its own separate configuration file, and therefore optionally, there can be a Pool Override Template for each domain to allow for ultimate customization.
If the systems administrator would like to override the default configuration values that have been set in one of the Default templates explained in the earlier sections, they have the ability to create a Pool Override Template that contains the directives and values to implement the desired overrides.
These templates are located as follows where USER represents the username of the cPanel account that owns the domain, and DOMAIN represents the domain for the pool:/var/cpanel/userdata/USER/DOMAIN.php_fpm.yaml
These Pool Override Templates should only contain the directives listed as Pool directives within the PHP FPM documentation.
Because the templating system makes use of the YAML syntax, this file should begin with three dashes at the top. The name of each Pool Directive goes on the left, followed by a colon (:) symbol, and then the value for the directive is placed to the right of the colon. Also, any period characters found in the PHP-FPM directive name must be replaced with an underscore symbol due to the fact that the template is written in YAML. Below is an example template, as well as what that example would look like if it were written in the standard syntax used by the PHP-FPM configuration:
cPanel's Template Example:
---
pm: static
chdir: [% homedir %]
listen_allowed_clients: any
listen_backlog: 128
The following shows what this same configuration would look like in a raw PHP-FPM configuration file. You will not be creating the raw configuration file. This is only provided as an example to help demonstrate how you would adjust your habits if you are used to editing raw FPM configurations:
pm = static
chdir = /home/exampleuser/
listen.allowed_clients = any
listen.backlog = 128
Comments
0 comments
Article is closed for comments.