How to BTM-enable a PHP Web Application?

To BTM-enable a PHP web application, follow the steps discussed below:

  1. Login to the server hosting the PHP web application as a root user.
  2. Then, check where SELinux is enabled on the server. Security-Enhanced Linux (SELinux) is a Linux kernel security module that provides a mechanism for supporting access control security policies, including mandatory access controls (MAC). SELinux is a set of kernel modifications and user-space tools that have been added to various Linux distributions.

    To check whether SELinux is enabled on the server, run the sestatus command at the prompt as root user. If this command returns the result disabled, it means that SELinux is disabled on the server. On the other hand, if this command returns the result enabled, it implies that SELinux is enabled.

    Where SELinux is enabled, the security policies that SELinux prescribes will:

    • Disallow the eG agent and the eG PHP Profiler to create log files or write entries to the log files in the eG agent install directory (default logs directory: /opt/egurkha/agent/logs).
    • Disable the port (default: 14002) via which the eG PHP profiler pushes data to the eG agent.

    These access restrictions will impact the operations of the eG agent and the profiler. This is why, before installing the profiler, you need to override the access policies of SELinux, so that the aforesaid restrictions are removed. To this effect, do the following:

    • At the prompt, run the chcon command as root user, to change the SELinux security context of the directory in which the eG agent and profiler will create log files - by default, this is the opt/egurkha/agent/logs directory. The syntax of this command is as follows:

      chcon -t httpd_sys_rw_content_t /opt/egurkha/agent/logs/ -R

      If the eG agent is installed in a different directory, then make sure you replace the /opt/egurkha/agent/logs/ entry in the chcon command above with <EG_AGENT_INSTALL_DIR>/agent/logs directory.

    • Next, enable the socket connection agent, so that the eG PHP profiler can transmit metrics to the eG agent. For that, run the following command:

      setsebool -P httpd_can_network_connect on

    • Finally, restart the PHP web server.
  3. Next, log back into the PHP web server as a user with rights to run scripts on the server. From the shell prompt, switch to the directory where the eG agent is installed. By default, this will be /opt/egurkha.
  4. Next, switch to the lib directory within /opt/egurkha.
  5. From the lib directory, run the following command to install the eG PHP Profiler:

    ./eGPHPBTM_Install.sh -e <1/2> -p <Path of php/php-fpm executable> -a <Path of eG agent install directory>

    In the command above, the alphabets prefixed by a hyphen (-) represent arguments that the script takes. Each of these arguments should be configured with a valid value. In the command above, the information provided within angular braces(<>) describes the value that you should configure for the corresponding argument. Make sure you configure every argument as per the guidelines provided in the table below:

    Argument

    Description

    -e

    This is a mandatory argument. The value of this argument indicates the mode in which the eG PHP Profiler should be run - i.e., whether in the mod_php mode or in the php-fpm mode.

    • mod_php: In this mode, the profiler will run as an Apache module. In other words, the PHP interpreter will be 'embedded' inside the Apache process - there will be no external PHP profiler process. This means that Apache and the profiler can communicate better. If the profiler is to be run in this mode, then set the -e argument in the command to 1.
    • php-fpm: This is PHP's FastCGI implementation. If the profiler is run in this mode, then it will run as a standalone FastCGI server. Apache will connect to the server using Apache's module, usually mod_fcgid or mod_fastcgi. If PHP is run in this mode, then set the -e argument in the command to 2.

    -p

    This argument takes the full path to the location of the mod_php or php-fpm (as the case may be) executable as its value. This is an optional argument, meaning, by default, you do not have to explicitly configure this argument when running the BTM install script. If no value is provided for this argument, then the install script does the following:

    • If the -e argument is configured with the value 1, then the eG BTM installer will automatically run the mod_php executable from the 'default location' of that executable.
    • If the -e argument is configured with the value 2, then the installer will automatically run the php-fpm executable from its 'default location'.

    Under the following circumstances however, you will have to explicitly configure the -p parameter with a valid path:

    • If more than one PHP instance is running on the same machine, and the instance you want to BTM-enable is not the 'default' instance;
    • If the mod_php or php-fpm executable (as the case may be) resides in a location other than its default location;

    -a

    This argument takes the full path to the install directory of the eG agent as its value. Typically, profiler logs are written to this path only. This is an optional argument, meaning, by default, you do not have to explicitly configure this argument when running the BTM install script. If no value is provided for this argument, then the profiler will automatically create and write eG PHP Profiler logs in the default install directory of the eG agent - i.e., in the /opt/egurkha directory.

    However, if you have installed the eG agent in a different location in your environment, then make sure you explicitly configure the -a argument with the valid path to the install directory.

    The command with sample values is provided below:

    ./eGPHPBTM_Install.sh -e 1 -p opt/php -a opt/eGAgent

  1. The successful execution of the command indicates the successful installation of the eG PHP Profiler.
  2. After successful installation, restart the PHP web server.