Installing APM Insight PHP Agent in Linux

To install APM Insight PHP agent in Linux operating system, follow the below given instructions:

Instructions for installation using script

  1. In Applications Manager web client, go to APM tab and copy the License Key present in the helpcard.
  2. Download the APM Insight PHP Agent agent Linux file (agent_php.zip) from the download page to the required Linux server.
  3. Start by logging into root.
  4. Extract the agent_php.zip file into /opt directory. This will create a sub-directory called zpa.

    For Linux :

    $ cd /opt
    $ wget https://www.manageengine.com/products/applications_manager/54974026/agent_php.zip
    $ unzip agent_php.zip

    For ARM :

    $ cd /opt
    $ wget https://www.manageengine.com/products/applications_manager/54974026/agent_php_arm.zip
    $ unzip agent_php_arm.zip

    For ALPINE :

    $ cd /opt
    $ wget https://www.manageengine.com/products/applications_manager/54974026/agent_php_alpine.zip
    $ unzip agent_php_alpine.zip

  5. Navigate to zpa/bin directory and execute the command:

    $ cd zpa/bin
    $ sudo sh configure.sh [LICENSE KEY] [HOSTNAME] [APPLICATION NAME]

    where,
    [LICENSE KEY] - License key from Applications Manager. (mandatory)
    [HOSTNAME] - Hostname of the Applications Manager. (mandatory)
    [APPLICATION NAME] - Monitor name to be shown in the Applications Manager console. By default, it is set to PHP-Application. (optional)

  6. Open the apminsight.conf file available in the zpa/confdirectory and include the following keys:

    For PHP agent versions below 2.9.3:

    apm.host=[HOST-NAME]
    apm.port=[HOST-PORT]
    use.https=[true/false]

    For PHP agent versions 2.9.3 and above:

    apm.host=[HOST-NAME]
    apm.port=[HOST-PORT]
    apm.protocol.https=[true/false]

    Example:

    For PHP agent versions below 2.9.3:

    apm.host=localhost
    apm.port=8443
    use.https=true

    For PHP agent versions 2.9.3 and above:

    apm.host=localhost
    apm.port=8443
    apm.protocol.https=true

    After including the required keys, save and close the file.

  7. Restart your PHP agent using the following command:

    $ sh run.sh restart

  8. Restart your web server / FPM server using the following commands:

    #For Apache servers,
    $ sudo service apache2 restart

    #For FPM servers,
    $ sudo service php-fpm restart

How to verify if the installation is successful:

After the installation, go to the terminal and execute the following command:

$ php -m | grep zpa

The output should contain zpa.

Note:

The agent does not restart automatically during server reboots. To start, stop or restart the agent, use the following commands:

$ cd /opt/zpa/bin

#Start the agent
$ sh run.sh start

#Stop the agent
$ sh run.sh stop

#Restart the agent
$ sh run.sh restart

#For systemd supported OS, use the following command to restart:
$ service zpdpsvc restart

Instructions for manual installation

If PHP is installed using third-party managed services, like cPanel/WHM, or if the PHP path is not set properly during the installation, you might get the following message: PHP is not found in PATH. Kindly install PHP or add PHP installation directory to PATH!

In these cases, you can retry the installation after setting the correct PHP directory in the PATH variable, or you can proceed to configure the agent manually, using these steps:

    1. Download the agent using the following command:
      For Linux:

      wget https://www.manageengine.com/products/applications_manager/54974026/agent_php.zip

      For ARM:

      wget https://www.manageengine.com/products/applications_manager/54974026/agent_php_arm.zip

      For ALPINE:

      wget https://www.manageengine.com/products/applications_manager/54974026/agent_php_alpine.zip

      Verify the integrity of the downloaded agent using checksum validation.
    2. Move the agent under /opt/ directory and extract the contents of the downloaded file. This will create a directory zpa/ under /opt/.

      sudo unzip -d /opt/ agent_php.zip

    3. Find your PHP API version, using the following command. There should be a corresponding zpa.so file in the /opt/zpa/libdirectory for the respective API version. Eg., zpa20131226.so for API version 20131226.

      php -i | grep "PHP API"
      # Example output
      PHP API => 20131226

    4. Find your PHP's ini configuration path. This is the path where dynamically loaded extension configurations are added. Copy the /opt/zpa/bin/zpa.inito this location.

      php -i | grep "Scan this dir"
      # Example output
      # Scan this dir for additional .ini files => /opt/cpanel/ea-php56/root/etc/php.d/
      cp /opt/zpa/bin/zpa.ini /opt/cpanel/ea-php56/root/etc/php.d/zpa.ini

Note: Use this step only when the output in step 4 in this section is not configured. In case the ini configuration path is not set, the extensions must be configured in the php.ini file directly. Add the following line to php.ini near the end of the file.
extension=zpa.so
  1. Find your PHP's extension directory. This is the path where extension libraries are loaded. Copy the respective zpa.so file for the API version obtained from step 3 in this section.

    php -i | grep "extension_dir"
    # Example output
    # extension_dir => /opt/cpanel/ea-php56/root/usr/lib64/php/modules
    cp /usr/lib/php/zpa20131226.so /opt/cpanel/ea-php56/root/usr/lib64/php/modules/zpa.so

  2. Restart your web servers. If you are running Apache, restart apache/httpd service. If you're running nginx/fpm based servers, restart the php-fpm services.

    # For Apache2 (Debian) sudo service apache2 restart
    # For Apache2 (RHEL/CentOS) sudo service httpd restart
    # For nginx/fpm based servers. sudo service php-fpm restart

  3. Verify if the agent is successfully loaded using the following command. The output should contain zpa.

    php -i | grep zpa
    #Example output
    #zpa
    #zpa.version => 3.0.2
    #zpa.date => 7 May 2021
    #zpa.capture_clirequest => 1 => 1
    #zpa.capture_httphost => 0 => 0
    #zpa.capture_phpself => 0 => 0

  4. To start communicating with Applications Manager, add the Applications Manager license key to apminsight.conf file under /opt/zpa/conf/. Place the license key value in the line beginning with license.key=<Enter_license_key_here>

    ################### APM Insight Agent Configuration File ###################
    #
    license.key=<Enter_license_key_here>
    #

  5. Navigate to /opt/zpa/bindirectory and start the agent service by executing the following command:

    cd /opt/zpa/bin
    sudo sh run.sh start
    # To verify the status
    # ps -ef | grep zpdp

    To make sure the agent is restarted during system reboots, you can register the agent as a service. Alternatively, you can use rc.local or cron task to ensure agent is started during system reboots.

Instructions to install in Docker

While creating container images, add these commands to the Docker files used for image creation as follows:

For Linux:

RUN cd /opt/ && wget
https://www.manageengine.com/products/applications_manager/54974026/agent_php.zip
RUN unzip agent_php.zip
RUN cd /opt/zpa/bin && sh configure.sh<licensekey><hostname><app_name>
RUN sh run.sh start

For ARM:

RUN cd /opt/ && wget
https://www.manageengine.com/products/applications_manager/54974026/agent_php_arm.zip
RUN unzip agent_php_arm.zip
RUN cd /opt/zpa/bin && sh configure.sh<licensekey><hostname><app_name>
RUN sh run.sh start

For ALPINE:

RUN cd /opt/ && wget
https://www.manageengine.com/products/applications_manager/54974026/agent_php_alpine.zip
RUN unzip agent_php_alpine.zip
RUN cd /opt/zpa/bin && sh configure.sh<licensekey><hostname><app_name>
RUN sh run.sh start

Whenever the container is started, make sure zpdpsvc is restarted using the following command (under /opt/zpa/bin directory)

sh run.sh start

Automatically restart agent during service reboots

To automatically restart APM Insight PHP agent during system reboots, use the below given steps:

For systemd servers:

The agent will automatically start during server reboots for systemd supported Linux flavors.

For non systemd servers:

  1. Edit the /etc/rc.local file
  2. Add the following lines to the rc.local:

    cd /opt/zpa/bin
    sh run.sh restart

    and save that file