Install the PHP agent

Install the PHP agent on your system.


Quickstart

Installing the Sqreen PHP agent helps you to monitor the security of your application and block attacks in real-time, and takes less than a minute:

This procedure installs the two parts of the agent: the language extension and the daemon. Both parts are required. Read more about the PHP agent architecture.

Standard PHP application

The following command installs and configures the PHP extension and the Sqreen daemon. Your Sqreen token is available on the application dashboard you created earlier.

curl -s https://download.sqreen.com/php/install.sh > sqreen-install.sh \
&& bash sqreen-install.sh [YOUR ORG TOKEN HERE] "[YOUR APP NAME HERE]"

Find your organization token by going to Account Settings > Tokens in your Sqreen dashboard, or (https://my.sqreen.com/profile/organization/tokens). Your token has the prefix org_.

To help Sqreen identify the application when you use an organization token, you also need to set a unique application name.

Application tokens deprecated

Application tokens are unique to an application. Organization tokens are available throughout the organization your account belongs to.

While Sqreen will continue to support application tokens for backward compatibility in the short term, they are now deprecated, and we encourage you to convert your applications to use organization tokens as soon as possible.

Then, restart Apache or FPM.

Last, visit your website or query our application for the PHP extension to start

Complete the installation

Restart your application server and query your application to complete the installation.

Install the agent in a non-production environment

Typically you install the Sqreen agent in your production environment, but you can create several applications by specifying the environment in the application name.

Basic configuration

Find your organization token by going to Account Settings > Tokens in your Sqreen dashboard, or (https://my.sqreen.com/profile/organization/tokens). Your token has the prefix org_.

To help Sqreen identify the application when you use an organization token, you also need to set a unique application name.

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

Then restart your HTTP server.

Visit your website or query your server to complete the installation.

The Sqreen PHP agent provides flexible configuration settings. Refer to Configuration in PHP for more detailed information.

Uninstall the agent

You can disable Sqreen at any time by visiting your dashboard.

To uninstall the Sqreen agent, remove the PHP extension and the daemon.

Manual installation

The one line installation procedure should work out of the box with most Linux distributions. In the rare cases where the procedure doesn't work, or if you want more visibility over the installation process, follow the following instructions.

Debian / Ubuntu

Add repository for Sqreen Debian packages

Follow these steps to add the Sqreen repository.

sudo apt-get update
sudo apt-get install debian-archive-keyring
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 7B5248ECE3E59766

Install the apt-transport-https package to allow apt to fetch packages over https.

sudo apt-get install -y apt-transport-https

Next, use the following command to create a read token and output the necessary repository configuration.

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).

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.list?os=ubuntu&dist=cosmic&name=${UNIQUE_ID}' > /etc/apt/sources.list.d/sqreen_sqreen.list

Then update the package cache:

sudo apt-get update

You can now install the daemon sqreen-agent and the PHP extension sqreen-php-extension:

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

Next, refer to basic configuration.

Uninstall the agent

To uninstall the Sqreen agent, remove the packages:

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

Red Hat / CentOS

Add the repository for Sqreen RPM packages

Use the following steps to manually add the Sqreen yum repository.

Start by installing pygpgme and yum-utils. This allows yum to handle GPG signatures, and installs tools to install source-based RPMs.

sudo yum install pygpgme yum-utils

Next, use this command to 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

Then update the package cache:

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

Install Sqreen packages

You can now install the daemon sqreen-agent and the PHP extension sqreen-php-extension:

sudo yum install sqreen-agent sqreen-php-extension

Next, refer to basic configuration.

Uninstall the agent

To uninstall the Sqreen agent, remove the packages:

sudo yum erase sqreen-agent sqreen-php-extension

Alpine Linux

Install the extension

To install Sqreen on Alpine Linux, download the apk packages from here and extract them:

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

Note your PHP version. You need it to set up the right version of the PHP extension:

$ 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

In this case, the PHP version is 7.2.

Install the apk matching your PHP version:

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

If you use a Dockerfile, here's a 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

Basic configuration on Alpine Linux

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

In this case, you can place the configuration file in the /usr/local/etc/php/conf.d directory:

Then configure the following entries of this 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}

You also need to configure the daemon address (see the next section for more information on how to run the daemon):

sqreen.socket_path = 'sqreen-daemon:7773'

Install the Sqreen daemon

We don't provide packages for the sqreen-agent on Alpine Linux. The easiest way is to run it within a dedicated container:

docker run sqreen/php-agent

You can find more information about the Docker image here https://hub.docker.com/r/sqreen/php-agent/

PHP extension configuration

You must configure the PHP extension must be properly to reach the daemon. See Basic configuration on Alpine Linux to learn how.

Configure manual daemon startup

If you began by installing the PHP extension, the daemon should automatically start. If you prefer to have more control over the daemon process, it's possible to launch the daemon manually.

Prevent the extension from starting the daemon

Use 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 doesn't start automatically.

Run the daemon using Docker

Use the Sqreen Docker image for the daemon:

docker run sqreen/php-agent

You can find more information about the Docker image here https://hub.docker.com/r/sqreen/php-agent/

PHP extension configuration

You must configure the PHP extension properly to reach the daemon. See Basic configuration on Alpine Linux to learn how.

Manual daemon installation

On top of having packages for most Linux distributions, the Sqreen daemon is available from static repositories. Download it manually from here or 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

Next copy the daemon binary:

mkdir -p /usr/local/sqreen/bin/
cp sqreen-agent /usr/bin/

Then, run the daemon:

$ ./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 daemon startup

Below are several examples on how to configure the daemon startup with common service managers.

systemd

You can configure systemd to start the daemon:

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

Debian / Ubuntu init.d

You can configure init.d to start the daemon:

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 / CentOS init.d

You can configure init.d to start the daemon:

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