Advanced configuration in PHP

Configuring the PHP Extension

Sqreen settings can be optionally adjusted according to your needs. This section lists the possible configuration options you have with Sqreen PHP agent.

Default Port Bindings

The daemon and the PHP extension use TCP to communicate. The daemon listens on port 7773 by default (binding on 0.0.0.0).

The PHP extension will try to connect to 127.0.0.1:7773 by default.

Configuration sources

The Sqreen PHP extension read its configuration from the PHP configuration (.ini files). This file is typically located in /etc/php/7.0/xxx/conf.d/50-sqreen.ini.

Configuration variables

The Sqreen PHP extension can be configured in the .ini file. Here are the settings that can be changed:

sqreen.ini variable name Role Default value
sqreen.token The Sqreen token. This identifies the agent to Sqreen backend servers empty
sqreen.log_location Specify a custom file to write Sqreen logs /tmp/
sqreen.log_level Sqreen logging level critical
sqreen.socket_path The address of the Sqreen daemon. 127.0.0.1:7773
sqreen.launch_daemon If set to true, the daemon will be started by the extension. 1
sqreen.disable If set to 1, the Sqreen PHP extension won't start. 0

In order to use environment variable. The value can be set to ${ENV_VARIABLE} in the ini file. eg:

sqreen.token=${SQREEN_TOKEN}

The sqreen-installer script can also be used to configured the extension. eg:

sqreen-installer set_ini launch_daemon 0

Multiple sites

Serving multiple sites from the same PHP engine is supported by Sqreen. Many tokens can be recorded in different .ini files.

SELinux

If you use SELinux you may need to authorize the extension to comunicate with the daemon.

For instance for httpd on centos just do this command (from the package policycoreutils-python)

semanage port -a -t http_port_t -p tcp 7773

Configuring the PHP daemon

Sqreen settings can be optionally adjusted according to your needs. This section lists the possible configuration options you have with Sqreen daemon for the PHP extension. The daemon can support any number of PHP clients.

PHP daemon: configuration sources

The Sqreen Agent read its configuration from different places:

  • The environment
  • A Python .ini file
  • The command line interface.

The .ini file can be located in:

  • In /etc/default/sqreen-agent
  • Your application top level directory: sqreen.ini
  • In a custom place set by the SQREEN_CONFIG_FILE environment variable

Example of .ini file:

[sqreen]

proxy_url=http://proxy_url:3128/
listen=0.0.0.0:7773

PHP daemon: configuration variables

The Sqreen agent can be configured using the environment or a JSON file. Here are the settings that can be changed:

Env variable name Role .ini key name CLI flag Default value
SQREEN_CONFIG_FILE Custom location for the .ini based configuration file --config Empty
SQREEN_LOG_LOCATION Specify a custom file to write Sqreen logs log_location --log-location Empty
SQREEN_LOG_LEVEL Sqreen logging level. One of DEBUG or CRITICAL. log_level --log-level CRITICAL
SQREEN_BACKGROUND The daemon to start in background --background False
SQREEN_LISTEN The host and port the daemon will listen on, with the form host:port listen --listen 0.0.0.0:7773
SQREEN_PROXY_URL The url of a proxy use to connect to the Backend proxy_url --proxy_url Empty
SQREEN_IP_HEADER The uppercase header to use to fetch the ip_address. (eg. X_FORWARDED_FOR) ip_header Empty

The configuration variables should be put in the /etc/default/sqreen-agent file, as detailed in this section.

Usage on a high performance application

The Sqreen agent will be listening to each PHP process using one TCP connection. The ulimit of your system should allow this process to use such a count of TCP sockets.

The following file need to go in the /etc/security/limits.conf file:

# Allow Sqreen to receive enough connections
sqreen hard nofile 1000

Configuration with FPM pools

PHP FPM pools allow many PHP FPM processes to use independant configurations.

Enabling Sqreen for all pools

This is the default behavior. After completion of the Sqreen setup (including launching sqreen-installer), Sqreen protects all the FPM pools using the configuration in the file /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini.

Enabling Sqreen for a limited number of pools

First, deactivate Sqreen globally in the FPM global configuration. For this, remove the token declaration from the file /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini:

sqreen.token = 'your token'

The token declaration is removed from the global configuration in order to be moved to pool specific configuration.

Then specify you want Sqreen to be disabled:

sqreen.disable = 1

The next step is to activate Sqreen for the pool you need. Let's assume this pool is configured in the file /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini, then let's add the following lines:

php_value[sqreen.disable] = 0
php_value[sqreen.token] = 'my token'

Finally, the PHP FPM process need to be restarted.

Configuration with apache2 mod_php

Configuring Sqreen for all virtualenv

This is the default behavior. After completion of the Sqreen setup (including launching sqreen-installer), Sqreen protects all the apache2 virtualenv using the configuration in the file /etc/php/<PHP_VERSION>/apache2/conf.d/50-sqreen.ini.

Enabling Sqreen for a limited number of virtualenv

First, deactivate Sqreen globally in the apache2 global configuration. For this, remove the token declaration from the file /etc/php/<PHP_VERSION>/apache2/conf.d/50-sqreen.ini:

sqreen.token = 'your token'

The token declaration is removed from the global configuration in order to be moved in the virtualenv specific configuration.

Then specify you want Sqreen to be disabled:

sqreen.disable = 1

The next step is to activate Sqreen for the virtualenv you need. In each virtualenv which use mod_php, add the following lines:

php_value sqreen.token 'my token'
php_value sqreen.disable 0

Finally, apache2 need to be restarted.