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.

You can add and edit values there. For example:

sqreen.token = 'your token value'
sqreen.app_name = 'my app'
sqreen.launch_daemon = 0

You can also use the sqreen-installer script to configure the extension. Use set_ini for strings (will add single quotes), set_ini_expr for numbers or expressions.

sqreen-installer set_ini log_file "/my/log area/sqreen.log"
sqreen-installer set_ini_expr launch_daemon 0

Instead of a fixed value, the Sqreen agent can get a value from an environment variable at startup. For example, in the ini file:

sqreen.token = ${SQREEN_TOKEN}
sqreen.token = ${MY_SPECIFIC_NAME}

Notice there are no quotes around the braces.

You can also use the sqreen-installer script in this case. Notice the use of set_ini_expr and single quotes to avoid immediate evaluation.

sqreen-installer set_ini_expr token '${MY_SPECIFIC_NAME}'
sqreen-installer set_ini_expr log_file '${MY_ENV_VAR_NAME}'

Configuration variables

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.

You can provide this information using the SQREEN_TOKEN and SQREEN_APP_NAME environment variables.

When using the application token, only the SQREEN_TOKEN is required.

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.

Role .ini key name Default value
The Sqreen token. This identifies the agent to Sqreen backend servers sqreen.token Empty
The application name as displayed within the Sqreen dashboard sqreen.app_name Empty
Specify a custom file to write Sqreen logs sqreen.log_file log/sqreen.log
Sqreen logging level sqreen.log_level WARN
The address of the Sqreen daemon sqreen.socket_path 127.0.0.1:7773
If set to true, the extension starts the daemon. sqreen.launch_daemon 1
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 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

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 different 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

The organization token should stay in the FPM global configuration.

sqreen.token = 'the organization token'

Then, deactivate Sqreen globally in the FPM global configuration. To do this, add the following instruction in the configuration file /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini:

sqreen.disable = 1

Next, enable Sqreen on the relevant pools. This guide assumes you configure the pools in the /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini file. Add the following lines:

php_value[sqreen.disable] = 0
php_value[sqreen.app_name] = 'the application name'

Last, restart the PHP FPM process.

Configuration with Apache mod_php

Configuring Sqreen for all virtual hosts

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

Enabling Sqreen for a limited number of virtual hosts

Keep your organization token in the apache2 global configuration file.

sqreen.token = 'the organization token'

Then, deactivate Sqreen globally in the apache2 global configuration by adding add the following instruction in the /etc/php/{PHP_VERSION}/apache2/conf.d/50-sqreen.ini configuration file:

sqreen.disable = 1

Next, enable Sqreen in each relevant virtualenv. In each virtualenv that uses mod_php, add the following lines:

php_value sqreen.app_name 'the application name'
php_value sqreen.disable 0

Finally, restart Apache.

PII scrubbing

Unless you set strip_sensitive_data to false, the Sqreen agent redacts certain data before sending information 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. 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, to prevent Sqreen from collecting values matching the regular expression /\d{3}-\d{2}-\d{4}/, add the following claim in the sqreen.json file:

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

Adding a large number of regular expressions could affect the application's performance.