Configuration in PHP


You can adjust sqreen settings to your needs. This section lists the possible configuration options you have with the 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 tries to connect to 127.0.0.1:7773 by default.

Configuration sources

The Sqreen agent reads its configuration from different places. This is the order of precedence:

  • Environment variables
  • A .ini file
  • Default configuration options

The .ini file is typically located in /etc/php/7.0/xxx/conf.d/50-sqreen.ini.

To use environment variables, you can set the value to ${ENV_VARIABLE} in the ini file.

sqreen.token=${SQREEN_TOKEN}

You can also use the sqreen-installer script to configure the extension.

sqreen-installer set_ini launch_daemon 0

Configuration variables

You can configure the Sqreen agent using environment variables or a .ini file. The SQREEN_TOKEN is required. The other settings are optional. Here are the settings you can change:

Env variable name Role .ini key name Default value
SQREEN_TOKEN The Sqreen token. This identifies the agent to Sqreen backend servers sqreen.token Empty
SQREEN_APP_NAME The application name as displayed within the Sqreen dashboard sqreen.app_name Empty
SQREEN_LOG_LOCATION Specify a custom file to write Sqreen logs sqreen.log_location log/sqreen.log
SQREEN_LOG_LEVEL Sqreen logging level sqreen.log_level WARN
SQREEN_SOCKET_PATH The address of the Sqreen daemon sqreen.socket_path 127.0.0.1:7773
SQREEN_LAUNCH_DAEMON If set to true, the daemon will be started by the extension. sqreen.launch_daemon 1
SQREEN_DISABLE If set to true, the Sqreen PHP extension won't start. sqreen.disable 0

Multiple sites

Sqreen supports serving multiple sites from the same PHP engine. You can record multiple tokens in different .ini files.

SELinux

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

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

semanage port -a -t http_port_t -p tcp 7773

Configuring the PHP daemon

You can adjust Sqreen settings 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 reads its configuration from different places. The order of precedence is:

  • Environment variables
  • A PHP .ini file
  • The command line interface parameters.

The .ini file can be located in:

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

Example of a .ini file:

[sqreen]

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

PHP daemon: configuration variables

You can configure the Sqreen agent using the environment or a JSON file. Here are the settings that you can change:

Env variable name Role json 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
SQREEN_STRIP_SENSITIVE_DATA Remove sensitive data before sending them to Sqreen strip_sensitive_data 1
SQREEN_STRIP_SENSITIVE_REGEX Regular expression used for value stripping, refer to dedicated section below for details strip_sensitive_regex see here for default values
SQREEN_STRIP_SENSITIVE_KEYS Comma separated list of keys to strip, refer to dedicated section below for details strip_sensitive_keys see here for default values

You should add the configuration variables in the /etc/default/sqreen-agent file, as detailed in this section.

Usage in a high performance application

The Sqreen agent listens to each PHP process using one TCP connection. The ulimit of your system should allow this process to use the necessary number of TCP sockets.

Include the following text 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 independent 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 and moved to pool specific configuration.

Then specify you want to disable Sqreen:

sqreen.disable = 1

The next step is to activate Sqreen for the pool you need. This guide assumes this pool is configured in the file /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini, and add the following lines:

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

Finally, restart the PHP FPM process.

Configuration with apache2 mod_php

Configuring Sqreen for all virtualenvs

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 virtualenvs

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 and moved to the virtualenv specific configuration.

Then specify you want to disable Sqreen:

sqreen.disable = 1

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

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

Finally, restart Apache.

PII scrubbing

Unless strip_sensitive_data is set to false, the Sqreen agent redacts certain data before sending to Sqreen's servers. It redacts the values of key-value pairs listed in strip_sensitive_keys (compared in a case insensitive manner), and redacts any values, including array elements, but not keys, that fully match the strip_sensitive_regex configuration setting.

You can find default PII scrubbing values in PII Scrubbing.

Changing strip_sensitive_keys or strip_sensitive_regex overrides the defaults. So you need to append your extra keys to the list of predefined keys and combine the default regular expression with your new one.

For instance, preventing Sqreen from collecting values matching the regular expression /\d{3}-\d{2}-\d{4}/ can be done by adding the following claim in the sqreen.json file:

{
  "strip_sentitive_regex": [
    "^\\d{3}-\\d{2}-\\d{4}$"
  ]
}

Please notice that adding too many regular expressions could introduce a performance impact in the application.