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, you'll find below the instructions.

Prerequisite

The Sqreen PHP agent collects signals for the enabled security plugins and apply the configured protection and logging actions. Installing Sqreen in your PHP application takes less than a minute:

  • Sign up to Sqreen to create an account.
  • Create your first application. The application name can for example be the name of the git repository, or anything that is meaningful to identify the application.
  • Follow the procedure detailed below.

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

Debian / Ubuntu

Add repository for Sqreen Debian packages

Follow those steps to add the Sqreen apt repository.

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

Install a package called apt-transport-https for 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 precise or trusty).

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=precise&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

Configure the Sqreen extension

Add your Sqreen token in the agent's configuration (the token is available on the application dashboard you've created earlier).

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

Don't forget to restart your HTTP server.

Please visit your website or query your server to complete the installation.

All done! 🙌

Sqreen is now monitoring your PHP app! No further configuration or installation is necessary in most cases. However, if you need to e.g. use the daemon on another machine, then please read on to the next section.

Install the agent outside production environment

Typically you will install the Sqreen PHP agent in your production environment, but you can create several applications using your Sqreen dashboard, and specifying the environment (development, staging, production). A unique Sqreen token will be provided for each environment.

Disable the agent

You can disable Sqreen anytime by visiting your dashboard.

Uninstall the agent

To uninstall the Sqreen agent, remove the packages:

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

Red Hat / CentOS

Add repository for Sqreen RPM packages

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

Start by installing pygpgme and yum-utils. This will enable yum to handle GPG signatures, and will install some helpful 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

Configure the Sqreen extension

Add your Sqreen token in the agent's configuration (the token is available on the application dashboard you've created earlier).

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

Don't forget to restart your HTTP server.

Please visit your website or query your server to complete the installation.

All done! 🙌

Sqreen is now monitoring your PHP app! No further configuration or installation is necessary in most cases. However, if you need to e.g. use the daemon on another machine, then please read on to the next section.

Install the agent outside production environment

Typically you will install the Sqreen PHP agent in your production environment, but you can create several applications using your Sqreen dashboard, and specifying the environment (development, staging, production). A unique Sqreen token will be provided for each environment.

Disable the agent

You can disable Sqreen anytime by visiting your dashboard.

Uninstall the agent

To uninstall the Sqreen agent, simply remove the packages:

sudo yum erase sqreen-agent sqreen-php-extension

Alpine Linux

Install the extension

To install the extension on Alpine Linux download apk packages from here:

$ curl https://download.sqreen.io/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

The Sqreen PHP extension files will be extracted on your disk.

Now note down your PHP version - it is required to setup 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.io/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

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, the configuration file can be placed in the directory /usr/local/etc/php/conf.d:

Then configure the following entries of this file.

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

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

The daemon address should be configured too (see the next section for more information on how to run the daemon):

sqreen.socket_path = 'sqreen-daemon:7773'

Then the PHP extension must be configured. Please follow the manual installation steps.

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

More information about the Docker image can be found here: https://hub.docker.com/r/sqreen/php-agent/

Don't forget that the PHP extension must be properly configured to reach the daemon. See the previous section to learn how to configure it.