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¶
There are three different ways of installing the Hdiv PHP agent:
- Installing from binary package(preferred)
- Installing from a python wheel package
- Manual installation
Before starting with any of those methods, unzip the package provided by Hdiv.
unzip Hdiv.zip
Installing from binary package¶
This method is very straight forward. The self-contained binary will install everything for you. However, if you are interested in knowing more about what is installed behind the scenes, please refer to the manual installation.
The installer will first attempt to identify your current setup but if it can´t, it will ask you for some information regarding your setup.
In order to run the binary, you have to give execution permissions
chmod +x hdiv_php_installer_vX.X.X-63-g0f90b8e-glibc
And then, just run it
./hdiv_php_installer_vX.X.X-63-g0f90b8e-glibc
Once the installation is finished, it is safe to delete the binary.
Installing from a python wheel package¶
This method is also very straight forward. This approach requires Python 3.6+
with pip
installed. If you are interested in knowing more about what is installed behind the scenes, please refer to the manual installation.
First add the hdiv_php_intaller
package to your python with:
pip install -i hdiv_php_installer-vX.X.X_161_g4640f099-py3-none-any.whl
Then run the installer with:
hdiv_php_installer
The installer will first attempt to identify your current setup but if it can´t, it will ask you for some information regarding your setup.
Once the installation is finished, it is safe to uninstall the package:
pip uninstall hdiv_php_installer
Manual installation¶
This is the slowest option but probably the one that most sysadmins/devops will choose since it gives them more control and knowledge about the changes done to the system. Even if you choose any of the more automatic options, reading this section will help you understand better the installation procedure.
Uncompress the installation files:¶
From the folder called Hdiv
created when unzipping on the first step, type the following:
cd Hdiv/agent/php/ tar -zxvf hdiv-php-agent-X.X.X-tarball.tar.gz
This will create a tree with these directories/files under the
repos
directory:
README.user.md agent/ binary-core/ extension/ php/
- agent: PHP source code of the agent
- binary-core: contains the binaries (either Java and native) of the agent core.
- extension: Compiled Hdiv extension
- php: has the hdiv.ini config file.
Install the native extension¶
On this step we will install the Hdiv PHP extension needed for the agent. The procedure is the standard one for any PHP extension.
First, we have to identify where our system is looking for PHP extensions. In order to do so, type the following command:
php -i | grep "extension_dir"
You should see an output similar to
[root@d6603c980a4b extension]# php -i | grep "extension_dir" extension_dir => /usr/lib64/php/modules => /usr/lib64/php/modules
From that output, in our case, we now know the folder we were looking for is /usr/lib64/php/modules
Once we know the extensior dir, we have to move the file hdiv.so
which is in the extension
folder to that path. In our case:
cp extension/[YOUR-ARCH]/[YOUR-PHP-VERSION]/hdiv.so /usr/lib64/php/modules/
If we were installing on a x86-64
arch with PHP 7.4
, the previous command would look like:
cp extension/x86-64/7.4/hdiv.so /usr/lib64/php/modules/
Install the agent PHP files¶
Copy or move the contents of agent/
directory to any path of your choosing (suggestion for Unix: /opt/hdiv/php_agent
). Using the suggested as example, we would move the content with the following command:
cp -r agent/* /opt/hdiv/php_agent/
Please note that the path must be readable and traversable (g+rX
permissions) for the system user and/or group that the PHP runtime uses (e.g: chown -R apache:apache /opt/hdiv/php_agent
if you are using apache). Depending on the websever you use, the user is usually one of the following: www-data
, apache
or nginx
.
Install the core binary¶
The binary-core
directory contains several sub-directories for different architectures:
- java (multiplatform).
- linux.
- macos.
Choose the one that matches your architecture (the Java version is multiplatform. You can choose the JAVA over any other if you prefer so.)
Choose an installation path (suggestion: /opt/hdiv/bin/[CHOSEN_ARCH]
). Move the contents of the architecture chosen ARCH folder to the path chosen. (e.g: mv binary-core/linux/hdiv-ee-portable-core /opt/hdiv/bin/linux/
)
Make sure the PHP runtime can have read and execute permissions(g+rx
) on the chosen path. (e.g: chown -R apache:apache /opt/hdiv/bin
if you are using apache)
Install the PHP config file¶
On this step we will tell PHP to load Hdiv extension. In order to do so the Hdiv INI file(php/hdiv.ini
) must the moved to your PHP's installation directory.
If you're unsure about its path, you can find it using one the following approaches:
- SUGGESTED: Serve a PHP page where the following command is used:
phpinfo()
. Usually it´s displayed under the section: "Scan this dir for additional .ini files:". This methods is the most accurate since you may have differentphp.ini
configuration files forcli
andapache
. - Using the command
php -i
to get a text version ofphpinfo()
on the cli. You can then pipe its result to grep and search for addional ini files:php -i | grep "Additional .ini files parsed"
- Using
php-config --ini-dir
command. PHP-config is a tool provided by PHP.
Most likely the path will be a conf.d
or php.d
directory in the same path as the main php.ini
file, something like /etc/php/version/conf.d
or /usr/local/etc/php/version/conf.d
.
Once you have this folder located, move the file php/hdiv.ini
there.
Now, when running PHP, it should have the Hdiv extension loaded. In order to verify so, run the following command which shows a list of all PHP extension installed:
php -m
You should see hdiv
among all the modules installed under [PHP Modules]
. You could run the following command to find it faster php -m | grep hdiv
.
If the Hdiv extension is not there, that usually means the folder found on this step was not the correct one. Double check it and make sure the file hdiv.ini
is properly moved there.
Configure extension¶
Edit the file moved to PHP ini folder on the previous step called hdiv.ini
.
Change AGENT_PATH_CHANGEME
with the path which you chose on step Install the agent PHP files
. Then append to that path /src
. (E.g: We chose /opt/hdiv/php_agent
so we should replace AGENT_PATH_CHANGEME
with /opt/hdiv/php_agent/src
)
Edit the core-settings.ini
config file¶
Now we have everything on a path on the server, we have to tell the agent about those chosen paths.
Go to the folder chosen under step Install the agent PHP files
(suggested: /opt/hdiv/php_agent
). Now edit the file settings/core-settings.ini
path and change the following values:
php.run.dir
: set this to any existing directory that can be read, written and traversed (g+rwX
). It will be used by the agent and core to store runtime files. It can be a relative path. (suggested:config
). Make sure the path chosen exists and it has the right permissions.hdiv.config.dir
: same as above. It'll be used for the core. It can be the same asphp.run.dir
. (suggested:config/portable-core
). Make sure the path chosen exists and it has the right permissions.hdiv.mandatory.app.name
: The name of your app.
In addition to those changes, we have to tell the agent where the binary core is. We chose this path on the step Install the core binary
. On the example we suggested to move the file hdiv-ee-portable-core
to /opt/hdiv/bin/linux/
. Once you have this located, point the following config entry to that path:
php.core.[ARCH].bin = PATH_TO_PORTABLE_CORE
In the example case, since we are using linux, we would modify the linux entry leaving it like:
php.core.linux.bin = /opt/hdiv/bin/linux/hdiv-ee-portable-core
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 the directory you configured as hdiv.config.dir
(suggested: /opt/hdiv/php_agent/config/portable-core
). Alternatively, you can copy it to the core installation directory that you chose on under Install the core binary
step (suggested: /opt/hdiv/bin
).
As with the previous steps, make sure this file has read permissions by the user running your webserver.
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 system properties (or environment variables) to the server in the same place the Hdiv Agent is configured.
hdiv.console.url=http://${console-host}:8089/hdiv-console-services hdiv.server.name={server-name} hdiv.console.token={console-token}
hdiv.console.url
: The location of the Hdiv Console REST API. Replace${console-host}
variable with the hostname or IP address where the Hdiv Console is installed-
hdiv.server.name
: Unique name that identifies the server where the agent is installed.Only alphanumeric, '-' and '_' characters are allowed in the server name property
-
hdiv.console.token
: Authentication token used to invoke the REST API in the console. The actual value of the token for your console installation is in the System Settings / Environments section of the Hdiv console. Access the console and copy the value of the token to this property.
No Data Loss. Connectivity Fault Recovery
Hdiv agent is designed to allow connectivity errors without losing any data when console connection is not available. Hdiv stores pending information in the fileystem (with a maximun size limit) and it sends that information when the console is available again.
Checking installation¶
At this stage, Hdiv agent is installed. The only remaining thing is next step which consists on restarting your webserver.
Before doing so, we can verify the installation is ok. In order to do so, go to the folder where the php agent was installed(suggested /opt/hdiv/php_agent
) and run the following script using the same user used by your webserver:
php tools/setup-check.php --console
If everything is properly configured, the output should be similar to the following:
Hdiv extension file loaded: yes Extension is loaded: yes Php is prepending agent: yes Php is appending agent: yes Binary is properly configured on settings/core-settings.ini: yes License is configured on settings/core-settings.ini: yes Check binary-core runs: yes Console is configured on settings/core-settings.ini: yes
If there is something wrong with the installation, the output will point you out where the problem is and it will help you amending it.
For example, the following output shows the file settings/core-settings.ini
is missing the key php.core.linux.bin
:
Hdiv extension file loaded: yes Extension is loaded: yes Php is prepending agent: yes Php is appending agent: yes Binary is properly configured on settings/core-settings.ini: no Point the key php.core.linux.bin to the path where you put the binary-core file
Restart¶
Restart your webserver. You may need to restart your PHP runtime, such as php-fpm. The Hdiv agent should start working now.
Note that on the first request after each restart the core will be initialized. This first request may be a fraction of a second slower than others.
``