Skip to main content

Install PHP agent with Debian

Steps

To install the PHP agent:

  1. Install the agent package from https://pkg.contrastsecurity.com. This command registers our package repository in your system:

    curl \
  https://pkg.contrastsecurity.com/api/gpg/key/public | sudo apt-key add -

echo "deb https://pkg.contrastsecurity.com/debian-public/ $(sed -rne 's/^VERSION_CODENAME=(.*)$/\1/p' /etc/*ease) contrast" \
  | sudo tee /etc/apt/sources.list.d/contrast.list

echo "deb https://pkg.contrastsecurity.com/debian-public/ all contrast" \
  | sudo tee -a /etc/apt/sources.list.d/contrast.list

  2. Once complete, use this command to install the agent. You may need to use the sudo command depending on the permissions in your environment:

    apt-get update && apt-get install contrast-php-agent

  3. Continue with configuration.

To configure the PHP agent:

There are two ways to configure the agent to work in your environment.

  1. Use the contrast-php-util command. This command installs along with the PHP agent and can be used from the command line to enable the agent in your environment.

    contrast-php-util enable-agent

    This will create an ini file in the scan directory used by PHP to manage extensions.

    OR

  2. Edit the PHP configuration file, called php.ini. It can be found on many systems under /usr/local/etc/php/.

    If the php-config command is available, it can be used to find the configuration file path using php-config --ini-path. If no configuration file yet exists under that path, it will need to be created.

    echo "extension=/usr/local/lib/contrast/php/contrast.so" >> php-config --ini-path/php.ini

    On systems in which the php-config command is not available PHP itself can be used to tell you where the ini file is located:

    php -i | grep php.ini

    The Configuration File (php.ini) Path line will tell you which ini file is active. You can then edit that file to add this to the end of the file:

     extension=/usr/local/lib/contrast/php/contrast.so

    Note that in certain environments, the ini file used by the command line instance of PHP might be different from that loaded in the server environment. FPM will use an ini file often located in the /etc/php/<php version>/fpm/ directory. Please ensure that you are operating on the proper PHP instance.

  3. Continue with the final setup.

To finalize setup:

  1. Ensure that the necessary extensions are enabled.

    The PHP agent requires that the mbstring, json, and curl PHP extensions be installed and enabled. If they are not, edit the php.ini config file as above and ensure that these lines are present in the configuration file:

    extension=curl
extension=mbstring
extension=json

  2. Configure the PHP agent using the PHP YAML template or environment variables (if not already done).

  3. Start your application in the normal way.

  4. Exercise and test your application.

  5. Verify that the PHP agent is running by checking the Contrast web interface and/or looking for the PHP agent log output (depending on configuration).

Notes

  • Library analysis and route discovery are currently performed on the first request to the application. For this reason, we expect the first request to be considerably slower than subsequent requests.

  • The agent has not been tested with third-party PHP extensions. The behavior of the agent with any other third-party extensions (including APMs, etc.) is undefined. The agent is known to be incompatible with xdebug and should not be used concurrently.

  • The agent may not work properly when preloading is enabled. Disabling preloading when using the agent is recommended.

  • By default, the agent assumes that the server’s working directory when it runs the PHP application is the same as the top-level directory of the application source tree. The agent uses this path to perform library analysis and route discovery. If this is not the case, you will need to use the application.path setting in the configuration to set the top-level working directory of your application.

In this section: