Configure the Ruby microagent¶

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

environment variables
sqreen.yml file
default configuration options

Configuration variables¶

The table below lists the variables you can use to customize the Sqreen microagent's configuration.

Environment variable name	Role	YAML key name	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.	`token`	empty	string
`SQREEN_APP_NAME`	The application name as displayed on the Sqreen Dashboard. When using Rails, the application name derives from Rails's application class name.	`app_name`	empty (autodetected with Rails)	string
`SQREEN_CONFIG_FILE`	Specifies a custom location for the YAML-based config file.			empty
`SQREEN_LOG_LOCATION`	Specifies a custom file to which the microagent writes logs.	`log_location`	log/sqreen.log	string
`SQREEN_LOG_LEVEL`	Sets the microagent logging level.	`log_level`	WARN	FATAL ERROR WARN INFO DEBUG
`HTTP_PROXY`, `http_proxy`	Specifies an HTTP proxy server for the microagent's connection to the Sqreen Platform.	`http_proxy`	empty	proxy URI (`http://proxy:port`)
`SQREEN_REPORT_PERF`	Reports overhead for each request in the log (WARN level).	`report_perf`	`false` (disabled)	boolean
`SQREEN_REPORT_PERF_NR`	Reports overhead for each request to NewRelic as custom transaction attributes.	`report_perf_newrelic`	0 (disabled)	0 (disabled), 1 (global overhead), 2 (report duration for each protection category)
`SQREEN_IP_HEADER`	Specifies the header to use to extract the real IP address of a client.	`ip_header`	empty	header name (case insensitive)
`SQREEN_DISABLE`	Prevents the Sqreen agent from starting. Any value in this environment variable disables Sqreen.	`disable`	`false` (Sqreen is enabled)	boolean
`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 information 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 information 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)

YAML file¶

The Sqreen Microagent stores configurations in the sqreen.yml file. The microagent detects the application root based on its installation folder. Save the sqreen.yml file in the top level folder in your application.

If you wish, you can customize a location for the YAML file. Use the SQREEN_CONFIG_FILE environment variable to specify a custom location in your application's directory.

export SQREEN_CONFIG_FILE=/custom/path/sqreen.yml

When you edit the sqreen.yaml configuration file, be sure to indent with two spaces. If you do not indent correctly, the Sqreen microagent throws an error at startup: Unable to parse configuration file.

Multiple Rails environments¶

The sqreen.yml configuration file enables you to use a different section per Rails environment.

token: mysecrettoken #general configuration

production:
    token:  mysecretproductiontoken # override general configuration

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.yml file, set strip_sensitive_data to 0 (disabled).

Customize sensitive data scrubbing¶

You can customize the sensitive data that the microagent redacts.

In the sqreen.yml file, use strip_sensitive_keys to replace the default values (case insensitive) that the microagent redacts.
In the sqreen.yml 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