Configure the PHP microagent

The PHP microagent has two parts: a PHP extension and a Sqreen daemon. Sqreen requires both parts to secure your PHP web applications.

The Sqreen PHP extension performs the PHP code instrumentation. It is a compiled extension (like the MySQL or ODBC extensions) that uses the PHP engine's API. It inspects the PHP internal state to collect signals and apply the configured plugins' actions.

The Sqreen daemon for PHP provides a long-running background process. It enables the microagent to upload batches of reports to the Sqreen Platform, operate plugins, and perform asynchronous activities.

Default Port Bindings

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

Configure the PHP extension

The PHP extension part of the microagent reads three sources for its configuration. It follows the configurations from these sources in sequence. The order of precedence is as follows:

  1. environment variables
  2. a sqreen.ini file
  3. default configuration options

PHP extension sqreen.ini file

The Sqreen Microagent stores configurations in the sqreen.ini file. The file is typically located in /etc/php/7.0/xxx/conf.d/50-sqreen.ini in your application. You can add and edit configurations in the this file. 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 with fixed value.

sqreen-installer set_ini log_file "/my/log area/sqreen.log"
sqreen-installer set_ini_expr launch_daemon 0
sqreen-installer set_ini token 'your_token_value'
sqreen-installer set_ini token "${MY_ENVIRONMENT_VARIABLE_HOLDING_TOKEN}"  # No single quote! Value has to be read once and stored into php.ini

PHP extension configuration variables

The table below lists the variables you can use to customize the PHP extension's configuration in the sqreen.ini file.

INI key name Role Default value Allowed values
sqreen.token The token is the identifier the Sqreen Platform uses to identify the microagent. Access your token in Account Settings > Environments & Tokens. empty string
sqreen.app_name The application name as displayed on the Sqreen Dashboard. empty string
sqreen.log_file Specifies a custom file to which the microagent writes logs. string
sqreen.log_level Sets the microagent logging level. WARNING FATAL ERROR WARNING INFO DEBUG
sqreen.socket_path Specifies the address of the Sqreen daemon. 127.0.0.1:7773 host:port
sqreen.launch_daemon If set to true, the extension starts the daemon. 1 (true) 0 (false) , 1 (true)
sqreen.disable If set to true, the Sqreen PHP extension does not start. 0 (false) 0 (false) , 1 (true)
sqreen.strip_env_var Specifies an environment variable to strip or redact. SQREEN_TOKEN string
sqreen.vendor_location Specifies the location of the composer vendor directory. empty string

Get token value at start time

There are some advanced cases where you may not want to store the token value in the sqreen.ini file. For example, if you have several applications and tokens running on the same PHP engine, you likely do not want to store the token value in the file.

Instead, you can configure the Sqreen microagent to get a value from an environment variable at start time. For example, in the sqreen.ini file, specify the following (notice, no quote around dollar-braces):

sqreen.token = ${SQREEN_TOKEN}
sqreen.token = ${MY_SPECIFIC_NAME}
To do so, you must edit the sqreen.ini file. For example:
sed -i -e 's/.*sqreen.token.*/sqreen.token=${MY_SPECIFIC_NAME}/' /your/path/to/your/php/conf.d/50-sqreen.ini

SELinux

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

For example, for httpd on CentOS, run the following command from the policycoreutils-python package:

semanage port -a -t http_port_t -p tcp 7773

Configure the Sqreen daemon

This section lists the configurations you can make with the Sqreen daemon. The daemon can support any number of PHP clients.

The daemon reads three sources for its configuration. It follows the configurations from these sources in sequence. The order of precedence is as follows:

  1. environment variables
  2. a sqreen.ini file
  3. default configuration options

Sqreen daemon configuration variables

The table below lists the variables you can use to customize the daemon's configuration. You can adjust the configuration variables in the /etc/default/sqreen-agent file.

Environment variable name Role INI key name CLI flag Default value Allowed values
SQREEN_CONFIG_FILE Specifies a custom location for the .ini-based config file. --config empty string
SQREEN_LOG_LOCATION Specifies a custom file to which the daemon writes logs. log_location --log-location empty string
SQREEN_LOG_LEVEL Sets the daemon logging level. log_level --log-level CRITICAL CRITICAL ERROR INFO DEBUG
SQREEN_BACKGROUND Specifies the daemon to start in background. --background false boolean
SQREEN_LISTEN The host and port on which the daemon listens. listen --listen 0.0.0.0:7773 host:port
SQREEN_PROXY_URL Specifies an HTTP proxy server for the microagent's connection to the Sqreen Platform. proxy_url --proxy_url empty proxy URI (http://proxy:port )
SQREEN_IP_HEADER Specifies the uppercase header to use to fetch the ip_address of a client. (example: X_FORWARDED_FOR) ip_header empty header name
SQREEN_STRIP_SENSITIVE_DATA Removes sensitive data, including personally identifiable information (PII), before the microagent sends metadata to the Sqreen Platform. Refer to Sensitive data scrubbing below for details. strip_sensitive_data 1 (enabled) 1 (enabled), 0 (disabled)
SQREEN_STRIP_SENSITIVE_REGEX Regular expression that removes specific sensitive data before the microagent sends metadata to the Sqreen Platform. Refer to Sensitive data scrubbing below for details. strip_sensitive_regex empty (uses default values) (arbitrary)
SQREEN_STRIP_SENSITIVE_KEYS Comma-separated list of keys that removes specific sensitive data before the microagent sends metadata to the Sqreen Platform. Refer to Sensitive data scrubbing below for details. strip_sensitive_keys empty (uses default values) (arbitrary)

Use Sqreen in a high performance application

The microagent listens to each PHP process using one TCP connection. The ulimit of your system must 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

Sqreen Daemon INI file

The sqreen.ini file can exist in one of the following locations:

  • /etc/default/sqreen-agent
  • your application's top level directory as sqreen.ini
  • a custom location set by the SQREEN_CONFIG_FILE environment variable

Example of a sqreen.ini file:

[sqreen]

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

Restrict where the PHP daemon listens

We recommend to configure the Sqreen Daemon to listen on the localhost by default. This can be done by changing either:

  1. the daemon startup command:

    $ sqreen_daemon --listen=127.0.0.1:7773
    
  2. the sqreen.ini file that holds the daemon configuration:

    [sqreen]
    
    proxy_url=http://proxy_url:3128/
    listen=127.0.0.1:7773
    
  3. the environment variables:

    SQREEN_LISTEN=127.0.0.1:7773
    

Configure the microagent for FPM pools

PHP FPM pools allow different processes to use independent configurations.

Enable the microagent for all pools

The microagent enables all pools by default. After setup (including launching sqreen-installer), the microagent monitors all the FPM pools using the configuration in the /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini file.

Enable the microagent for limited pools

  1. Ensure that the organization token exists in the FPM global configuration.
    sqreen.token = 'the organization token'
    
  2. Deactivate the microagent in the FPM global configuration. Add the following instruction in the /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini configuration file:
    sqreen.disable = 1
    
  3. Enable the microagent on select pools in the /etc/php/<PHP_VERSION>/fpm/conf.d/50-sqreen.ini file:
    php_value[sqreen.disable] = 0
    php_value[sqreen.app_name] = 'the application name'
    
  4. Restart the PHP FPM process.

Configure the microagent for Apache mod_php

Enable the microagent for all virtual hosts

The microagent enables all virtual by default. After setup (including launching sqreen-installer), the microagent monitors all the Apache 2 virtual hosts using the configuration in the /etc/php/<PHP_VERSION>/apache2/conf.d/50-sqreen.ini file.

Enable the microagent for limited virtual hosts

  1. Ensure that the organization token exists in the apache2 global configuration file.
    sqreen.token = 'the organization token'
    
  2. Deactivate the microagent in the apache2 global configuration. Add the following instruction in the /etc/php/{PHP_VERSION}/apache2/conf.d/50-sqreen.ini configuration file:
    sqreen.disable = 1
    
  3. Enable the microagent on select virtual environments. In each virtual environment that uses mod_php, add the following lines:
    php_value sqreen.app_name 'the application name'
    php_value sqreen.disable 0
    
  4. Restart Apache.

Sensitive data scrubbing

The microagent does not send sensitive data, including Personally Identifiable Information (PII), to the Sqreen Platform. With each heartbeat, the microagent scrubs the metadata to remove sensitive data and replace any instances with Redacted by Sqreen.

By default, the microagent scrubs the following values from the metadata it sends:

  • Values that look like they contain credit card numbers, according to a basic regular expression: ^(?:\d[ -]*?){13,16}$
  • Values associated with any of the following keys:
    • password
    • secret
    • passwd
    • authorization
    • api_key
    • apikey
    • access_token

Turn off sensitive data scrubbing

To turn off sensitive data scrubbing, in the sqreen.ini file, set strip_sensitive_data to 0 (disabled).

Customize sensitive scrubbing

You can customize the sensitive data that the microagent redacts.

  1. In the sqreen.ini file, use strip_sensitive_keys to replace the default values (case insensitive) that the microagent redacts.

  2. In the sqreen.ini file, use strip_sensitive_regex to replace the default values, including arrays, that match a regular expression. Be aware that adding a large number of regular expressions to this configuration may affect the application's performance.

Replace, not add

Be aware that the values you set in strip_sensitive_keys and strip_sensitive_regex replace the default values that the microagent redacts. In other words, the values you configure here are not added to the default values the microagent redacts, they override them