Installation

Installation requirements

Before starting the installation, please check that your server meets the supported server versions requirements.

In addition to those requirements, the PHP module called posix needs to be installed in your PHP installation.

Installation

The Hdiv package is composed of two components:

  • Agent
  • PHP extension

This guide will guide you through the steps to install each.

Before starting the installation process, it is required to gather some information about your system.

  • PHP version
  • User running your webserver
  • PHP Extensions dir
  • PHP Additional .INI parsed

The best way to gather this information is by accessing to a page served by your webserver showing the phpinfo() information. However, this information can also be gather from the command line.

Information gathering

PHPINFO

In order to do this, serve a php page with the following content:

<?php
phpinfo();
?>

You should see a page similar to:

PHP info

From that page you can get the information searching by:

  • PHP version: Search PHP Version. On the image, it is at the top. In the image the php version is 7.2
  • User running your webserver: Search for User. This value usually is either apache or www-data
  • PHP Extensions dir: Search for extension_dir
  • PHP Additional .INI parsed: Search for Scan this dir for additional .ini files

Command line

While you can obtain all this information from the command line, this may not be accurate. The reason is that on some installations, the webserver doesn´t share the configuration of the php on the CLI. However, we´ll highlight where this information differs.

All the commands used on the next section will need to be run on a CLI.

  • PHP version: Run php -v
  • User running your webserver: There are few approaches here. You can check the user owning the files on your webroot path (eg: ls -ls /var/www/ where your webroot path is /var/www). Another option is to check the user running apache/fpm process with ps aux| egrep "fpm|apache".
  • PHP Extensions dir: php -i | egrep "^extension_dir"
  • PHP Additional .INI parsed: Run php -i | grep "Additional .ini files parsed". If the path contains a folder called cli, that likely mean that you have a different configuration for php CLI. When this happens, the path we´re looking for looks like the path with the cli folder but instead of cli there is a folder at the same level called apache or fpm or similar.

Uncompressing files

Now we know where things should be moved to, unzip the provided file in any path you want to. The place where this file is unzip will be used a temporary path. You can remove it when the installation is done.

unzip Hdiv.zip
This will create a folder called Hdiv. Now untar the following.

cd Hdiv/agent/php/
tar -zxvf hdiv-php-agent-X.X.X-tarball.tar.gz

This will create a folder called hdiv_php_agent. Access to this folder

cd hdiv_php_agent

Installing agent

In order to install the agent. You have to choose where you want it to be installed. We suggest it to be installed on /opt/hdiv. If you choose another path, make sure you adapt the commands given to you from now on.

If you chose to change the path where the agent is installed, make sure you modify the file hdiv/php_agent/settings/core-settings.ini and change any property pointing to /opt/hdiv to your chosen path.

From the folder hdiv_php_agent run:

cp -r hdiv /opt/
chown -R [User running your webserver]:[User running your webserver] /opt/hdiv
You need to replace [User running your webserver] with the information you got from step Information gathering

Installing extension

Now, we need to move the extension. From the folder Hdiv/agent/php/hdiv_php_agent run:

cp extension/x86-64/[MAJOR.MINOR PHP VERSION]/hdiv.so [PHP Extensions dir]

From that command you have to change [MAJOR.MINOR PHP VERSION] to the version found on step Information gathering. Just pick the major and the minor from your php version. In our case 7.2. Make sure this file is owned by the same user as its siblings.

Now we need to tell PHP to load our extension. From the same folder Hdiv/agent/php/hdiv_php_agent run:

If you chose to change the proposed path for the agent /opt/hdiv, before running the following command, adapt the paths on file hdiv.ini

cp hdiv.ini [PHP Additional .INI parsed]
From that command you have to change [PHP Additional .INI parsed] to the version found on the previous step. Make sure this file is owned by the same user as its siblings.

Install HDIV license

Find the license.hdiv file included in the Hdiv zip you got provide with(Hdiv/license/license.hdiv). Copy license.hdiv to /opt/hdiv/php_agent/config/portable-core.

As with the previous steps, make sure this file has read permissions by user found on step Information gathering under User running your webserver.

chown [User running your webserver]:[User running your webserver] /opt/hdiv/php_agent/config/portable-core/license.hdiv

Connect to the Hdiv Console

Applications and servers using Hdiv can communicate with the Hdiv Console to send detected vulnerabilities and attacks to it and retrieve configuration options.

It is necessary to add some properties to enable communication between the applications and the console.

Add the following lines to the end of the file /opt/hdiv/php_agent/settings/core-settings.ini

hdiv.console.url=http://[console-host]:8089/hdiv-console-services
hdiv.server.name=[server-name]
hdiv.console.token=[console-token]

You should have gotten provided with [console-host], [server-name]and [console-token] by a member of Hdiv.

Checking installation

At this stage, Hdiv agent is installed. The only remaining thing is restart your webserver and check Hdiv is installed. If you use fpm, you will need to restart it too.

In order to check the Hdiv is working fine, check your phpinfo page. You should see references to Hdiv. If you can not find any reference to Hdiv, something went wrong.

If you chose to install the agent also on the CLI, you should see hdiv when running the command php -m.

Updating your installation

Go over step Information gathering in order to know where things should be moved to.

Now we know where things should be moved to, unzip the provided file in any path you want to. The place where this file is unzip will be used a temporary path. You can removed when the update is finished.

unzip Hdiv.zip
This will create a folder called Hdiv. Now untar the following.

cd Hdiv/agent/php/
tar -zxvf hdiv-php-agent-X.X.X-tarball.tar.gz

This will create a folder called hdiv_php_agent. Access to this folder

cd hdiv_php_agent

Now copy the following:

rm -rf hdiv/php_agent/config
rm -rf hdiv/php_agent/settings
cp -a hdiv /opt/
chown -R [User running your webserver]:[User running your webserver] /opt/hdiv

If you chose to change the path where the agent is installed, make sure you adapt the previous command.

Last thing you have to copy is the new version of the extension:

cp extension/x86-64/[MAJOR.MINOR PHP VERSION]/hdiv.so [PHP Extensions dir]