This chapter describes how to install the JENNIFER PHP Agent.
Versions Supporting PHP Agent
Supported OSs
The operating systems in which the PHP agent can be installed properly are as follows.
RedHat 5 or higher
CentOS 5 or higher
Ubuntu 7 or higher
JENNIFER PHP Agent operates only on Linux kernel v.2.6.18 or higher
Supported PHP Versions
JENNIFER PHP Agent operates on Apache php module, PHP-fpm, PHP-CLI, PHP-CGI. Supported PHP version are PHP 5.2 ~ 5.6, PHP 7.0 ~ PHP 7.3
JENNIFER PHP Agent does not support PHP 7.0 ZTS, PHP 7.1 ZTS, PHP 7.2 ZTS, PHP 7.3 ZTS
Library Dependencies
The PHP agent is dependent on libstdc++.so.6, libgcc_s.so.1 (GCC_4.2.0). The PHP agent will not run if the PHP module (libphp5.so or php5-fpm) is dependent on a version less than libstdc++.so.6 or dependent on libgcc_s.so.1 which does not support GCC 4.2.0.
The Supported OSs includes libstdc++.so.6 and libgcc_so_.so.1 (GCC 4.2.0).
A compatible GCC version of libgcc_s.so.1 can be found in the output of the following command:
# strings /lib/libgcc_s.so.1 | grep GCC GCC_3.0 GCC_3.3 GCC_3.3.1 GCC_3.4 GCC_3.4.2 GCC_4.0.0 GCC_4.2.0 //he result is GCC_4.2.0, so the PHP agent is executable. # strings /lib/libgcc_s.so.1 | grep GCC GCC_3.0 GCC_3.3 GCC_3.3.1 GCC_3.4 GCC_3.4.2 // The PHP agent is not executable because there is no GCC_4.2.0 in the output.
The location of libgcc_s.so.1 may vary depending on the operating system and 32bit and 64bit machines.
LAMPP(XAMPP) environment
Certain LAMPP versions include libgcc_s.so.1 and libstdc ++, but you can not install the PHP agent if the versions of libgcc_s.so.1 and libstdc ++ in LAMPP do not meet Library Dependencies requirements.
You can check the versions of libstdc++ and libgcc_so.so.1 which are used in the LAMPP version through the following procedure.
# ls /opt/lampp/lib/libstdc++* libstdc++.so.5 libstdc++.so.5.0.7 libstdc++.so.6 // In this case, LAMPP has libstdc++.so.5, so you can not run the PHP agent. // If you do not have a libstdc++* file, you can run the PHP agent because it uses libstdc++ provided by the OS. # ls /opt/lampp/lib/libgcc_s.so.1 libgcc_s.so.1 // If you do not have libgcc_s.so.1 file, you can run PHP agent because it uses libgcc_s.so.1 provided by OS. # strings /opt/lampp/lib/libgcc_s.so.1 | grep GCC GCC_3.0 GCC_3.3 GCC_3.3.1 GCC_3.4 GCC_3.4.2 // In this case, there is no GCC_4.2.0 in the libgcc_s.so.1 compatible version, so you can not run the PHP agent.
Description of Agent Directories and Files
Unzip the PHP Agent package, and the following files will be created.
Directory/File | Description | etc |
|---|---|---|
bin/ | Directory that contains execution binary files | |
install.php | PHP script file for the installation of Agent | |
jennifer.conf | Agent configuration file | |
master_agent.pid | This file is used to check the PID of the PHP agent process running in Master Agent mode. This file is not created unless the agent is running in Master Agent mode. (Version 5.2.2 or later) | Version 5.2.2 or higher, CLI, CGI only |
ipc_resource.{PID} | This file is used to check the sysv resources used by the agent. It is created when the agent is running, and is deleted if it is terminated normally. If the agent terminates abnormally, the ipc_resource. {PID} file will remain intact and the sys resource in ipc_resource. {PID} must be manually deleted (version 5.2.2 or later). | Version 5.2.2 or higher. |
File | Description |
|---|---|
libJennifer5Common.so | Common agent library file |
Jennifer5Agent | Process file that delivers the Agent information to JENNIFER Data Server |
jennifer5-php-5.2.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by the process) |
jennifer5-php-5.2.x-ZTS.so | PHP extension module that collects PHP information (applied to the module operated by a thread) |
jennifer5-php-5.3.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by a process) |
jennifer5-php-5.3.x-ZTS.so | PHP extension module that collects PHP information (applied to the module operated by a thread) |
jennifer5-php-5.4.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by a process) |
jennifer5-php-5.4.x-ZTS.so | PHP extension module that collects PHP information (applied to the module operated by a thread) |
jennifer5-php-5.5.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by a process) |
jennifer5-php-5.5.x-ZTS.so | PHP extension module that collects PHP information (applied to the module operated by a thread) |
jennifer5-php-5.6.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by a thread) |
jennifer5-php-5.6.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by a thread) |
jennifer5-php-7.0.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by a process) |
jennifer5-php-7.1.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by a process) |
jennifer5-php-7.2.x-NTS.so | PHP extension module that collects PHP information (applied to the module operated by a process) |
Installing the PHP agent using agent-installer (version 5.4.1 or later)
Starting with version 5.4.1 of the PHP agent, the agent-installer binary file has been added to the package. agent-installer is a program that inspects the currently running Apache, PHP-fpm processes, the PHP version, Thread Safe, and php.ini, and installs the PHP agent.
#./agent-installer --help
USAGE:
agent-installer
agent-installer [FLAGS]
FLAGS:
-d, --delete Uninstall PHP Agent
-h, --help Prints help information
-i, --inspect Inspect running PHP Application(mod-apache or fpm)
-V, --version Prints version informationRunning PHP Apache process, PHP-fpm process check
Run sudo ./agent-installer -i to check the running PHP Apache process, PHP-fpm process. The test results are displayed on the screen, and detailed test logs are recorded in the .inspect-info file.
#sudo ./agent-installer -i Inspect running PHP Application(mod-apache or fpm) Inspect file : "/usr/lib/apache2/modules/libphp7.so" Found PHP Thread Safety : NTS Found php.ini : /usr/local/etc/php/php.ini Found PHP Version : 7.2.16 Found 1 PHP Application * cmd: apache2, version: PHP 7.2.16, thread safety: NTS
Installing the PHP agent
Run the sudo ./agent-installer to install the PHP Agent. The PHP process detail check log is written to the .inspect-info file, and the PHP installation information is recorded in the .install-info file.
#sudo ./agent-installer
Install Jennifer PHP Agent
Inspect running PHP Application(mod-apache or fpm)
Inspect file : "/usr/lib/apache2/modules/libphp7.so"
Found PHP Thread Safety : NTS
Found php.ini : /usr/local/etc/php/php.ini
Found PHP Version : 7.2.16
1. cmd: apache2, version: PHP 7.2.16, thread safety: NTS
Found 1 PHP Application. Select PHP Application [1,n] :1
Find extension for php-7.2.16-NTS
PHP extension path : /usr/local/jennifer/agent.php/bin/jennifer5-php-7.2.x-NTS.so
Update /usr/local/etc/php/php.ini
* [jennifer]
* jenniferAgent.agent_file_root=/usr/local/jennifer/agent.php
* extension=/usr/local/jennifer/agent.php/bin/jennifer5-php-7.2.x-NTS.so
Install complete, edit /usr/local/jennifer/agent.php/jennifer.conf and restart apache or fpm.Install PHP Agent
In the agent.php directory, run the install.php using the php.cli command. At this time, designate the absolute path of the php configuration file (php.ini).
# php install.php /etc/php5/apache2/php.ini ( Ubuntu Linux ) # php install.php /etc/php.ini ( Red Hat, Cent OS Linux )
Input a directory for the PHP Agent. If you want to select the current directory, type './'. Otherwise, input an absolute path.
Start Jennifer PHP Agent Installer Enter Jennifer PHP Agent install path : /home/jennifer/agent.php Jennifer install path : /home/jennifer/agent.php -------------------------------------------------------- Current Directory : /home/jennifer/agent.php Jennifer Agent Install Path : /home/jennifer/agent.php PHP Version : 5.3.10-1ubuntu3.10 Thread Safety : disable Arch : x86_64 Jennifer PHP Agent extension file name : jennifer5-php-5.3.x-NTS.so PHP Configuration file : /etc/php5/apache2/php.ini --------------------------------------------------------
Check the PHP version and the version of the Agent to be installed, and input 'yes'.
Do you want to continue? (yes or no) : yes Write php.ini for Jennifer PHP Agent extension=/home/jennifer/agent.php/bin/jennifer5-php-5.3.x-NTS.so jenniferAgent.agent_file_root=/home/jennifer/agent.php Check a Jennifer Agent executable file : /home/jennifer/agent.php/bin/Jennifer5Agent -- exists Check a Jennifer Agent shared library file : /home/jennifer/agent.php/bin/Jennifer5Common.so -- exists Check a Jennifer Agent PHP extension file : /home/jennifer/agent.php/bin/jennifer5-php-5.3.x-NTS.so -- exists Check a Jennifer Agenet configuration file : /home/jennifer/agent.php/jennifer.conf -- exists Installation successfully complete. 1. Open your jennifer.conf in jennifer install path, and specify a server address, sid, host_id and inst_id. 2. Restart Apache Server root@NominT:/home/jennifer/agent.php#
Configure the required settings in agent.php/jennifer.conf.
Item | Default Value | Description |
|---|---|---|
server_address | 127.0.0.1 | IP address of the Data Server |
server_port | 5000 | Port of the Data Server |
domain_id | 1000 | Domain ID, valid range is an integer from 1 to 32767. |
Restart Apache or PHP-fpm.
After restarting Apache, a log file named jennifer_YYYY-MM-DD.log is created in the log directory. When the access between the Agent and the Data Server is completed, you can see the following message in the log file.
2014-03-28/10:17:00 INFO--PHP Agent 5256: Send Agent Info ---------------- [App Initialized] ---------------------- Jennifer Server Address = 192.168.0.120 Jennifer Server Port = 5000 sid = 1000 inst id = 210 Agent pid = 5256 Apache pid = 5254 MachineName = Ubuntu 12.04.4 LTS Is64BitProcess = 1 Processor Architecture = x86_64 ---------------------------------------------------------
Install PHP Agent Manually
When the Install.php script does not operate properly, you can perform installation manually as follows.
1. Using the mkdir command, create a directory to install PHP Agent and move to the applicable directory.
$mkdir /home/jennifer/agent.php $cd /home/jennifer/agent.php
2. Copy the downloaded PHP Agent.zip file to the applicable directory and unzip the file.
$unzip jennifer-agent-php-64bit-5.0.8.zip
3. Check the PHP version.
$php -v
PHP 5.4.5 (cli) (built: Apr 3 2015 16:08:35)
Copyright (c) 1997-2012 The PHP Group
Zend Engine v2.4.0, Copyright (c) 1998-2012 Zend Technologies
4. Check the thread safety of the PHP.
$php -i | grep Thread Thread Safety => disabled
5. Check whether there is a file to designate as a PHP extension. A PHP extension file is located in the bin directory and complies with the jennifer5-php-{PHP_Major_Version}.{PHP_Minor_Version}.x-{NTS or ZTS}.so rules. If the thread safety is set to disabled, you need to designate an NTS. If the thread safety is set to enabled, you need to designate a ZTS.
$ls bin/jennifer5-php-5.4.x-NTS.so bin/jennifer5-php-5.4.x-NTS.so
6. Add the absolute path for the PHP Agent and the absolute path for the installation of PHP Agent to the php.ini file.
extension=/home/jennifer/agent.php/bin/jennifer5-php-5.4.x-NTS.so jenniferAgent.agent_file_root=/home/jennifer/agent.php
7. Configure the required settings in jennifer.conf.
Item | Default Value | Description |
|---|---|---|
server_address | 127.0.0.1 | IP address of the Data Server |
server_port | 5000 | Port of the Data Server |
domain_id | 1000 | Domain ID, valid range is an integer from 1 to 32767. |
inst_id | -1 | If the Instant Agent ID is '-1', ID is automatically assigned from the server. The valid range is an integer from 1 to 32767. |
Restart Apache or PHP-fpm.
Run the PHP agent in CLI, CGI based environment (Version 5.2.2 and above)
To enable the PHP agent in the CLI or CGI environment, you need to add options to php.ini and start the PHP Agent master process.
Set JenniferAgent.enable_cgi_cli option value to 1 in the php.ini file
To enable the agent to run in a PHP environment running as CLI or CGI, set the jenniferAgent.enable_cgi_cli option to 1 in php.ini.
;jenniferAgent.enable_cgi_cli option allows you to enable PHP agent activation in the cgi, cli environment. The default value is 0. To enable it set its value to 1 jenniferAgent.enable_cgi_cli = 1
Invoking the PHP agent master process
You need to start the PHP agent master process to pass the collected information from the PHP engine to Jennifer Data Server.
PHP agents running Apache and PHP-FPM will start automatically when starting Apache and PHP-FPM, and will automatically terminate when Apache and PHP-FPM exit.
Invoking the PHP agent master process
If the PHP agent installation directory is /jennifer/agent.php, run the following command:
/jennifer/agent.php/bin/./Jennifer5Agent -k start 2017-03-24/14:12:38 INFO-- 7254: Run Jennifer5Agent
If the master process runs successfully, you can check the JENNIFER agent startup log at /jennifer/agent.php/logs and check the file /jennifer/agent.php/master_agent.pid. The CLI and CGI-driven PHP processes then collect the data and pass it to the PHP Agent master process.
Terminating the PHP agent master process
If the PHP agent installation directory is /jennifer/agent.php, run the following command:
/jennifer/agent.php/bin/./Jennifer5Agent -k stop 2017-03-24/14:15:11 INFO-- 7310: Try to kill existing Master Agent
if the master process is terminated normally, you can check the JENNIFER agent exit log at /jennifer/agent.php/logs and confirm that the /jennifer/agent.php/master_agent.pid file has been deleted.
Restarting the PHP agent master process
If the PHP agent installation directory is /jennifer/agent.php, run the following command:
/jennifer/agent.php/bin/./Jennifer5Agent -k restart 2017-03-24/14:16:46 INFO-- 7345: Try to kill existing Master Agent 2017-03-24/14:16:48 INFO-- 7346: Run Jennifer5Agent
If the master process is restarted, you can check the JENNIFER shutdown log and startup log at /jennifer/agent.php/logs.
Apache - CGI-aware PHP environment
You must allow the php-cgi process run by Apache to access the PHP agent installation directory. Possible Apache configuration is as follows.
#Allows the php-cgi process to access the agent installation directory (/home/jennifer/agent.php). <Directory "/home/jennifer/agent.php"> Require all granted </Directory>
You must also grant user read / execute permissions to the installation directory (/home/jennifer/agent.php).
chmod 755 /home/jennifer chmod 755 /home/jennifer/agent.php
If the php-cgi process does not have access to the PHP agent installation directory, you can see the following logs in the Apache error.log.
PHP Warning: PHP Startup: Unable to load dynamic library '/home/jennifer/agent.php/bin/jennifer5-php-5.3.x-NTS.so' : cannot open shared object file: Permission denied in Unknown on line 0
Uninstall PHP Agent
Annotate or delete the Jennifer-related settings in the PHP configuration file (php.ini), then restart Apache or PHP-fgm.
;extension=/home/jennifer/agent.php/jennifer5-php-5.3.x-NTS.so ;jenniferAgent.agent_file_root=/usr/local/jennifer5-debug/
How to run PHP Agent when running SELINUX on Red Hat Linux
If SELINUX is running on Red Hat Linux (Red Hat, CentOS), you should use one of the following methods.
Changed SELINUX to permissive
If you use SELINUX in permissive mode with the following command, the PHP agent will run normally.
# setenforce 0
Change the context SELINUX
If you use this method, the agent installation directory must be a subdirectory of / home.
You can change the SELINUX context using the te file included in the installation package.
// Install the policy utility. For CentOS5, it is installed by default. # yum install policycoreutils-python # chmod +x selinux_enable.sh // Execute te file for OS version. For example, for CentOS 6 or Red Hat 6, run selinux_enable.sh centos_6.te. # selinux_enable.sh centos_#.te
Additional Settings (If Needed)
Even if you change the SELINUX context with the te file included in the installation package, the PHP agent may not be activated due to the variable environment setting of the OS. In this case, you have to change the SELINUX context by repeating the following steps.
# grep httpd_t /var/log/audit/audit.log | audit2allow -m jennifer_2 > jennifer_2.te # ./selinux_enable.sh jennifer_2.te
Troubleshoot installation issues
When you restart Apache or php-fpm after installing the PHP agent, a log file should be created in the log directory of the PHP agent installation directory. If the log file has not been created, you should check the Apache or php-fpm logs that the PHP engine has not loaded the Jennifer PHP module properly.
grep jennifer error.log //error.log refers to the Apache error log file.
No such file or directory
PHP Warning: PHP Startup: Unable to load dynamic library '/home/jennifer5/agent.php/bin/jennifer5-php-5.5.x-ZTS.so' - /home/jennifer5/agent.php/bin/jennifer5-php-5.5.x-ZTS.so: cannot open shared object file: No such file or directory in Unknown on line 0
This problem occurs if php.ini has an incorrect JENNIFER installation path. You should check the extension of php.ini and the jenniferAgent.agent_file_root option specification.
undefined symbol
PHP Warning: PHP Startup: Unable to load dynamic library '/home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so' - /home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so: undefined symbol: output_globals in Unknown on line 0
This log can be checked when a jennifer extension module is specified which does not match the PHP version, or the PHP Thread Safety environment. You need to specify php.ini extension = ... / jennifer5-php-5 ...- NTS.so as the correct file for your PHP environment. For example, if you have PHP 5.5.8 running in thread safety mode, you should specify jennifer5-php-5.5.x-ZTS.so.
You can check Thread Safety as a result of executing phpinfo () function
Wrong ELF class
Warning: PHP Startup: Unable to load dynamic library '/home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so' - /home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so: wrong ELF class: ELFCLASS64 in Unknown on line 0
If you have a 64-bit PHP agent installed on a 32-bit machine, or a 32-bit PHP agent installed on a 64-bit machine, you can see the same wrong ELF class. If you use Apache, php-fpm built on 32bit on 64bit machine, you can check the above log. In this case, you have to install 32bit PHP agent even on 64bit machine.
version 'GCC_4.2.0' not found
Warning: PHP Startup: Unable to load dynamic library '/home/jennifer5/agent.php/bin/jennifer5-php-5.3.x-NTS.so' - /lib/libgcc_s.so.1: version `GCC_4.2.0' not found (required by /home/jennifer5/agent.php/bin/libJennifer5Common.so) in Unknown on line 0
You can check this log if the version of libgcc_s.so.1 referenced by Apache and php-fpm does not support GCC_4.2.0. You need to update libgcc_s.so.1, and you can not run the PHP agent if you can not update it (see Library Dependencies).