Skip to content

Installation

Jump to bottom
Ramil Valitov edited this page May 19, 2020 · 12 revisions

Please follow the instructions below to install and configure the template.

1. On Zabbix agents

Perform the following operations on all servers with Zabbix agent and PHP-FPM from which you want to capture the data.

1.1. Install Prerequisites

Install required packages.

For apt-get based environments (Debian, Ubuntu, etc.):
apt-get update
apt-get -y install grep gawk lsof jq libfcgi0ldbl unzip

Additionally, for Debian Jessie 8.x and earlier (or for equivalent Ubuntu version):

apt-get -y install libfcgi0ldbl

Additionally, for Debian Stretch 9.x and later (or for equivalent Ubuntu version):

apt-get -y install libfcgi-bin
For yum based environments (CentOS):
yum check-update
yum install grep gawk lsof jq fcgi unzip

If some utilities not found and failed to install, then add EPEL repository:

yum install epel-release

Then try to install the required utilities again.

1.2. Install Zabbix PHP-FPM template

First, please, download the template archive: you can use either the latest published release (the latest stable version, I hope 😅) or use the active development version (that contains all the latest features and updates). Below we will download the archive to a temporary directory /tmp that usually presents in all OS. If you don't have such directory, please, create it first.

1.2.1. To use stable release

To download a stable release, run command:

curl -L $(curl -s https://api.github.com/repos/rvalitov/zabbix-php-fpm/releases/latest | grep 'zipball_' | cut -d\" -f4) --output /tmp/zabbix-php-fpm.zip

1.2.2. To use development version

To download a developement version, run command:

wget https://github.com/rvalitov/zabbix-php-fpm/archive/master.zip -O /tmp/zabbix-php-fpm.zip

1.2.3. Unzip and configure

Unzip the downloaded archive:

unzip -j /tmp/zabbix-php-fpm.zip "*/zabbix/*" "*/ispconfig/*" -d /tmp/zabbix-php-fpm

Copy the required files to the Zabbix agent configuration directory:

cp /tmp/zabbix-php-fpm/userparameter_php_fpm.conf $(find /etc/zabbix/ -name zabbix_agentd*.d -type d | head -n1)
cp /tmp/zabbix-php-fpm/zabbix_php_fpm_discovery.sh /etc/zabbix/
cp /tmp/zabbix-php-fpm/zabbix_php_fpm_status.sh /etc/zabbix/

Configure access rights:

chmod +x /etc/zabbix/zabbix_php_fpm_discovery.sh
chmod +x /etc/zabbix/zabbix_php_fpm_status.sh

1.3. Root privileges

Automatic detection of pools requires root privileges. You can achieve it using one of the methods below.

1.3.1. Method #1. Root privileges for Zabbix Agent

This method sets root privileges for Zabbix Agent, i.e. the Zabbix Agent will run under root user, as a result all user scripts will also have the root access rights.

Edit Zabbix agent configuration file /etc/zabbix/zabbix_agentd.conf, find AllowRoot option and enable it:

### Option: AllowRoot
#       Allow the agent to run as 'root'. If disabled and the agent is started by 'root', the agent
#       will try to switch to the user specified by the User configuration option instead.
#       Has no effect if started under a regular user.
#       0 - do not allow
#       1 - allow
#
# Mandatory: no
# Default:
# AllowRoot=0
AllowRoot=1

In the same file find option User and set it to root:

### Option: User
#       Drop privileges to a specific, existing user on the system.
#       Only has effect if run as 'root' and AllowRoot is disabled.
#
# Mandatory: no
# Default:
# User=zabbix
User=root

Restart the Zabbix agent service, for example:

systemctl restart zabbix-agent

Check that the Zabbix agent runs under root user:

user@server:~$ ps aux | grep "zabbix_agent"
user       3761  0.0  0.0   8132   928 pts/0    S+   18:32   0:00 grep zabbix_agent
root      6026  0.0  0.0  86968  3472 ?        S    Dec14   0:00 /usr/sbin/zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf
root      6027  0.7  0.0  87056  5044 ?        S    Dec14  76:00 /usr/sbin/zabbix_agentd: collector [idle 1 sec]
root      6028  0.0  0.0 161160 11092 ?        S    Dec14   7:41 /usr/sbin/zabbix_agentd: listener #1 [waiting for connection]
root      6029  0.0  0.0 161244 11180 ?        S    Dec14   7:43 /usr/sbin/zabbix_agentd: listener #2 [waiting for connection]
root      6030  0.0  0.0 161136 11072 ?        S    Dec14   7:43 /usr/sbin/zabbix_agentd: listener #3 [waiting for connection]

You should see root above. Otherwise, the Zabbix agent works without root privileges and will not be able to discover the PHP pools.

Since some updates of Zabbix agent and in some OS the above changes are not enough and the following actions must be performed (as desribed in Zabbix manual for versions 4.0, 4.4).

Create a directory for configuration file:

mkdir /etc/systemd/system/zabbix-agent.service.d

Create file /etc/systemd/system/zabbix-agent.service.d/override.conf with the following content:

[Service]
User=root
Group=root

Reload daemons and restart zabbix-agent service:

systemctl daemon-reload
systemctl restart zabbix-agent

Check again that the Zabbix agent runs as root now.

1.3.2. Method #2. Grant privileges to the PHP-FPM auto discovery script only

If you don't want to run Zabbix Agent as root, then you can configure the privileges only to our script. In this case you need to have sudo installed:

For apt-get based environments (Debian, Ubuntu, etc.):
apt-get install sudo
For yum based environments (CentOS):
yum install sudo

Now edit the /etc/sudoers file by running command:

visudo

Add the following line to this file:

zabbix ALL = NOPASSWD: /etc/zabbix/zabbix_php_fpm_discovery.sh

Here we specified zabbix as the user under which the Zabbix Agent is run. This is the default name, but if you have a custom installation with different name, then please, change it accordingly. Save and exit the editor. Your modifications will be applied.

Now edit the file /etc/zabbix/zabbix_agentd.d/userparameter_php_fpm.conf. Find the line:

UserParameter=php-fpm.discover[*],/etc/zabbix/zabbix_php_fpm_discovery.sh $1

Add sudo there, so the line should be:

UserParameter=php-fpm.discover[*],sudo /etc/zabbix/zabbix_php_fpm_discovery.sh $1

If you have SELinux enabled, please disable it, otherwise everything we've done with visudo will be ignored. You can disable SELinux using the following command:

setenforce 0

Alternatively, you can configure SELinux to handle our modifications to sudoers, but this is beyond the scope of this manual. If you achieve success with such configuration, please, share it to update this manual.

That's all.

1.4. Linux Tuning (optional)

Usually PHP-FPM backlog option is limited by Linux kernel settings and equals to 128 by default. In most cases you want to increase this value (latest PHP use 511 by default). The main option that limits the PHP-FPM backlog option is net.core.somaxconn. See the current setting, usually it's 128:

cat /proc/sys/net/core/somaxconn
128

Let's increase it to 1024:

echo "net.core.somaxconn=1024" >> /etc/sysctl.conf

Now we can cause the settings to be loaded by running:

sysctl -p

1.5. Adjust ISPConfig

This step is required only if you use ISPConfig. ISPConfig does not enable PHP-FPM status page by default. We will enable it by making an override of original template of ISPConfig and add a custom directive there. Please, check the installation path of ISPConfig in your system. Below we use default paths as used in Debian 9/10. Please, use one of the methods below to adjust the settings of ISPConfig.

Note: every time you upgrade the ISPConfig you may want to perform the operations below again to use the latest PHP-FPM template shipped with ISPConfig.

1.5.1. Method #1. Apply a patch

Caution: don't use this method if you already have your own customizations of the PHP-FPM template in ISPConfig.

Apply the patch using the following command:

patch /usr/local/ispconfig/server/conf/php_fpm_pool.conf.master --input=/tmp/zabbix-php-fpm/ispconfig.patch --output=/usr/local/ispconfig/server/conf-custom/php_fpm_pool.conf.master --reject-file=-

1.5.2. Method #2. Manually adjust the template

Use this method if any of the statements below are true:

  • the patch above does not work
  • you already have your own customizations of the PHP-FPM template in ISPConfig
  • you prefer to have a full control of what happens on your server.

First we need to copy the original template file php_fpm_pool.conf.master of ISPConfig to the override directory (don't do that if you already have your own customizations of the PHP-FPM template in ISPConfig - in this case you should already have the required file in the required location):

cp /usr/local/ispconfig/server/conf/php_fpm_pool.conf.master /usr/local/ispconfig/server/conf-custom/

Edit the copied file /usr/local/ispconfig/server/conf-custom/php_fpm_pool.conf.master and add there the following line after the last pm setting:

pm.status_path = /php-fpm-status

In our version of ISPConfig the last pm setting is pm.max_requests, so the resulting part of the file will have the following contents (the new line is bold):

<tmpl_if name='pm' op='==' value='ondemand'>
pm.process_idle_timeout = <tmpl_var name='pm_process_idle_timeout'>s;
</tmpl_if>
pm.max_requests = <tmpl_var name='pm_max_requests'>
pm.status_path = /php-fpm-status

chdir = /
<tmpl_if name='php_fpm_chroot'>

1.5.3. Final adjustments for ISPConfig

Set correct access rights:

chmod +x /usr/local/ispconfig/server/conf-custom/php_fpm_pool.conf.master

Now resync the websites using ISPConfig control panel: go to "Tools"->"Sync Tools"->"Resync". Check "Websites" only and click "Start":

ISPConfig resync interface

1.6. Adjust PHP-FPM pools configuration

This step is required if you don't use ISPConfig. In this case you need to enable the PHP-FPM status page for all of your pools manually. Each pool must have the same status path, recommended value is /php-fpm-status. Please, edit all the pools configuration files (for example for PHP 7.3 they are located in directory /etc/php/7.3/fpm/pool.d) by adding the following line:

pm.status_path = /php-fpm-status

You can set another path here if needed. Finally, restart the PHP-FPM, for example:

service php7.3-fpm restart

1.7. Clean up

Delete temporary files:

rm /tmp/zabbix-php-fpm.zip
rm -rf /tmp/zabbix-php-fpm/

2. On Zabbix Server

2.1. Import Zabbix PHP-FPM template

Download this project's archive to your computer (the release must be the same you selected when installing template archive at Zabbix agent):

  • To use a stable release, open the latest release page and click on "Source code (zip)" button at the end of the page.
  • To use a developement version, download this archive.

Extract the XML template file from the archive that corresponds to your version of Zabbix server. For example, use file /zabbix/zabbix_php_fpm_template_4.0.xml for Zabbix server 4.0. If there's no version of the template that matches your version of Zabbix server, then try to use the nearest version of the template that is not higher than your version of Zabbix server. For example, template version 4.0 also works for higher versions of Zabbix server, such as 4.2 and 4.4. But template version 4.0 will not work for Zabbix 3.x. Upload the extracted file to your Zabbix server. To do so go to "Configuration"->"Templates"->"Import" in Zabbix frontend: Zabbix template import interface

2.2. Add the template to your hosts

Add template "Template App PHP-FPM" to the desired hosts. If you use a custom status path (the default is /php-fpm-status), then configure it in the macros section of the host by adding value:

{$PHP_FPM_STATUS_URL}=your status path

The setup is finished, just wait a couple of minutes till Zabbix discovers all your pools and captures the data.

Clone this wiki locally