Install the PHP microagent manually¶

The PHP microagent has two parts: a PHP extension and a Sqreen daemon. Sqreen requires both parts to secure your PHP web applications.

The Sqreen PHP extension performs the PHP code instrumentation. It is a compiled extension (like the MySQL or ODBC extensions) that uses the PHP engine's API. It inspects the PHP internal state to collect signals and apply the configured plugins' actions.

The Sqreen daemon for PHP provides a long-running background process. It enables the microagent to upload batches of reports to the Sqreen Platform, operate plugins, and perform asynchronous activities.

Use the Sqreen installer

The Sqreen installer works for most distributions. Try using the standard installation procedure before using one of the manual installation procedures below.

Install on a custom PHP setup¶

Before installing the PHP microagent, begin by gathering information about your PHP application. Use the php command, or the phpinfo() function, to gather the following information about your custom setup.

the PHP version (5.3, 5.4, 5.5, 5.6, 7.0, ...)
the PHP binary extensions directory
PHP's use of ZTS (Zend Thread Safety)
the PHP configuration directory

For example:

$ php -i | grep 'PHP Version'
PHP Version => 5.6.30

$ php -i | grep extension_dir
extension_dir => /usr/local/Cellar/php56/5.6.30_6/lib/php/extensions/no-debug-non-zts-20131226 => /usr/local/Cellar/php56/5.6.30_6/lib/php/extensions/no-debug-non-zts-20131226

$ php -i | grep 'additional .ini files'
Scan this dir for additional .ini files => /usr/local/etc/php/5.6/conf.d

$ php -i | grep ZTS
# If nothing is returned, then ZTS is not enabled

Setting name	Returned value	Configuration value to use
PHP version	`PHP Version => 5.6.30`	5.6
PHP binary extensions directory	`extension_dir => /usr/lib/php/extensions/no-debug-non-zts-20131226 => /usr/lib/php/extensions/no-debug-non-zts-20131226`	/usr/lib/php/extensions/no-debug-non-zts-20131226
ZTS	nothing!	ZTS is not enabled.
PHP configuration directory	`Scan this dir for additional .ini files => /usr/local/etc/php/5.6/conf.d`	/usr/local/etc/php/5.6/conf.d

If have not already done so, sign up to create your Sqreen account.
Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token.

Retrieve the Sqreen extension files using one of the following methods:

download it manually

use the following commands to download and extract the agent files:

curl https://download.sqreen.io/php/sqreen-php-extension/linux/sqreen-php-extension-latest-linux.tar.gz -o sqreen-php-extension.tar.gz

tar xf sqreen-php-extension.tar.gz

Add the binary extension to the PHP binary extensions directory using one of the following methods:
- if your PHP installation uses ZTS, use the following command:
```
cp /usr/lib/sqreen/extensions/{PHP_VERSION}-zts/sqreen.so {PHP_BINARY_EXTENSION_DIR}
```
- if your PHP installation does not use ZTS, copy the binary extension to the PHP binary extensions directory:
```
cp /usr/lib/sqreen/extensions/{PHP_VERSION}/sqreen.so /{PHP_BINARY_EXTENSION_DIR}
```
Copy the sample configuration sqreen.ini file to the correct location:
```
cp /usr/lib/sqreen/conf/sqreen.ini {PHP_CONFIG_DIR}
```
Edit the sqreen.ini file to set your Sqreen token.
```
sqreen.token = 'your token value'
```
Set the priority so that Sqreen loads after other extensions, such as database drivers. Set the value to 50, then adjust according to the needs of your custom setup.
```
priority = 50
```

Uninstall the microagent¶

To uninstall the Sqreen microagent, remove the PHP extension and the daemon from your application.

Install on Debian or Ubuntu¶

If you have not already done so, sign up to create your Sqreen account.
Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token.

Add the repository for Sqreen Debian packages.

sudo apt-get update
sudo apt-get install debian-archive-keyring

Install the apt-transport-https package to allow apt to fetch packages over https.
```
sudo apt-get install -y curl gnupg apt-transport-https
```

Install the GPG key that the system will use to sign repository metadata.

curl -L https://packagecloud.io/sqreen/sqreen-public/gpgkey | sudo apt-key add -

Create a file named /etc/apt/sources.list.d/sqreen_sqreen-public.list.
Use the following commands to output the necessary repository configuration into the file you created. Replace the os and dist query parameters with the Linux distribution and version strings of your system (ubuntu or debian and a version string like cosmic or stretch).
```
deb 'https://packagecloud.io/sqreen/sqreen-public/ubuntu/' trusty main > /etc/apt/sources.list.d/sqreen_sqreen-public.list
deb-src 'https://packagecloud.io/sqreen/sqreen-public/ubuntu/' trusty main > /etc/apt/sources.list.d/sqreen_sqreen-public.list
```
Update the package cache.
```
sudo apt-get update
```
Install the daemon sqreen-agent and the PHP extension sqreen-php-extension.
```
sudo apt-get install sqreen-agent sqreen-php-extension
```

Set your application name and Sqreen token.

sudo /usr/bin/sqreen-installer config {YOUR_TOKEN_HERE} {YOUR_APPLICATION_NAME}
# Alternatively, use the SQREEN_TOKEN and SQREEN_APP_NAME environment variables:
sudo /usr/bin/sqreen-installer config '${SQREEN_TOKEN}' '${SQREEN_APP_NAME}'

Restart your web application server.
Visit your website or query your server to complete the installation.

Uninstall the microagent¶

To uninstall the Sqreen agent, use the following command to remove the packages.

sudo apt-get remove sqreen-agent sqreen-php-extension

Install on Red Hat or CentOS¶

If have not already done so, sign up to create your Sqreen account.
Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token.
To manually add the Sqreen yum repository, install pygpgme and yum-utils. This enables yum to handle GPG signatures, and installs tools to install source-based RPMs.
```
sudo yum install pygpgme yum-utils
```

Create a read token and output the necessary repository configuration. Replace UNIQUE_ID with a unique identifier of your choice for your system.

UNIQUE_ID=`hostname -f` && curl "https://8dc0b36f0ea6f2f21b721765e10a7e02768cd1825b4551f4:@packagecloud.io/install/repositories/sqreen/sqreen/config_file.repo?os=el&dist=7&name=${UNIQUE_ID}" > /etc/yum.repos.d/sqreen_sqreen.repo

Update the package cache.

sudo yum -q makecache -y --disablerepo='*' --enablerepo='sqreen_sqreen'

Install the sqreen-agent daemon and the PHP extension sqreen-php-extension.
```
sudo yum install sqreen-agent sqreen-php-extension
```

Set your application name and Sqreen token.

sudo /usr/bin/sqreen-installer config {YOUR_TOKEN_HERE} {YOUR_APPLICATION_NAME}
# Alternatively, use the SQREEN_TOKEN and SQREEN_APP_NAME environment variables:
sudo /usr/bin/sqreen-installer config '${SQREEN_TOKEN}' '${SQREEN_APP_NAME}'

Restart your web application server.
Visit your website or query your server to complete the installation.

Uninstall the microagent¶

To uninstall the Sqreen agent, use the following command to remove the packages.

sudo yum erase sqreen-agent sqreen-php-extension

Install on Alpine Linux¶

If have not already done so, sign up to create your Sqreen account.
Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token.

Download and extract the apk packages.

curl https://download.sqreen.com/php/sqreen-php-extension/alpine/sqreen-php-extension-latest-alpine.tar.gz -o sqreen-php-extension.tar.gz
tar xf sqreen-php-extension.tar.gz

Install the apk package that matches the version of PHP that your app uses.

apk add --no-cache --allow-untrusted <PHP version>/sq-ext-alpine-*.apk

If you use a Dockerfile, use the Dockerfile snippet:

ENV PHP_VERSION 7.2

RUN mkdir /tmp/sqreen-apk
ADD https://download.sqreen.com/php/sqreen-php-extension/alpine/sqreen-php-extension-latest-alpine.tar.gz /tmp/sqreen-apk
RUN cd /tmp/sqreen-apk                                           && \
    tar -xzvf sqreen-php-extension-latest-alpine.tar.gz          && \
    apk add --no-cache --allow-untrusted ${PHP_VERSION}/sq-ext-alpine-*.apk && \
    rm -r /tmp/sqreen-apk

Install the Sqreen daemon. Sqreen does not provide packages for the sqreen-agent on Alpine Linux. Instead, run it within a dedicated container. (Read more about the PHP microagent Docker image.)
```
docker run sqreen/php-agent
```

Use your app's PHP version number to set up the correct version of the PHP extension. In the example below, the PHP version is 7.2.

$ php -v
PHP 7.2.0 (cli) (built: Dec  1 2017 01:02:32) ( NTS )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.2.0, Copyright (c) 1998-2017 Zend Technologies

Retrieve the path where PHP expects the configuration files.

$ php -i |grep -w ini
Configuration File (php.ini) Path => /usr/local/etc/php
Scan this dir for additional .ini files => /usr/local/etc/php/conf.d

Using the path information you retrieved, place the conf.d files in the correct directory. The example in the preceding step indicates that the configuration file belongs in the /usr/local/etc/php/conf.d directory.

Configure the following entries in the conf.d file.

# Hardcode the token
sqreen.token = 'The Sqreen token value from your dashboard'
sqreen.app_name = 'The application name'

# Or use the environment variable
sqreen.token = ${SQREEN_TOKEN}
sqreen.app_name = ${SQREEN_APP_NAME}

In the conf.d file, configure the daemon address.
```
sqreen.socket_path = 'sqreen-daemon:7773'
```
Restart your web application server.
Visit your website or query your server to complete the installation.

Uninstall the microagent¶

To uninstall the Sqreen microagent, remove the PHP extension and the daemon from your application.

Configure daemon startup manually¶

If you began by installing the PHP extension, the daemon starts automatically. If you prefer to have more control over the daemon process, you can install and launch the daemon manually.

To prevent the PHP extension from starting the daemon, apply the following configuration variable in your sqreen.ini:

sqreen.launch_daemon=0

Note that when the variable sqreen.socket_path contains a value other than localhost, the daemon does not start automatically.

Install and run daemon manually¶

Download the Sqreen daemon from a static repository using one of the following methods:

download it manually

use the following commands:

curl https://download.sqreen.com/php/sqreen-agent/linux/sqreen-agent-latest-linux.tar.gz -o sqreen-agent.tar.gz
tar -xvzf sqreen-agent.tar.gz

Copy the daemon binary.

cp -r sqreen-agent /usr/lib/sqreen
ln -sf /usr/lib/sqreen/sqreen-agent /usr/bin/sqreen-agent

Run the daemon.

$ /usr/bin/sqreen-agent
[INFO][2017-10-17 17:23:36,620 #19.MainThread] sqreen-agent:182     sqreen-agent (1.0.2) starting up on TCP socket 0.0.0.0:7773
[INFO][2017-10-17 17:23:36,621 #19.MainThread] sqreen-agent:195     Sqreen-agent successfully started

You can isolate the daemon in its own UNIX user account:

useradd -rU sqreen
mkdir -p -m 755 /var/log/sqreen
chown sqreen:sqreen /var/log/sqreen

Configure a common service manager to start the daemon¶

systemd¶

cp ./systemd/sqreen-agent.service /usr/lib/systemd/system/sqreen-agent.service
systemctl enable sqreen-agent
systemctl start sqreen-agent

Debian or Ubuntu init.d¶

cp ./init.d/debian/sqreen-agent /etc/init.d/
chmod 755 /etc/init.d/sqreen-agent
update-rc.d sqreen-agent defaults
/etc/init.d/sqreen-agent start

Red Hat or CentOS init.d¶

cp ./init.d/centos/sqreen-agent /etc/init.d/
chmod 755 /etc/init.d/sqreen-agent
chkconfig --add sqreen-agent
chkconfig sqreen-agent on
/etc/init.d/sqreen-agent start

Install and run the daemon using Docker¶

Use the Sqreen Docker image to install and run the daemon

docker run sqreen/php-agent