Agent configuration reference

The default agent configuration can be found in the /etc/redirectionio/agent.yml file.

Minimal configuration¶

After installing the agent, you must edit this file in order to insert your redirection.io instance name. Here is the minimal configuration:

# name of this instance, mandatory for logging
instance_name: "A UNIQUE NAME"

Configuration reference¶

The agent however supports some more option keys, detailed in the sections below.

instance_name¶

• Type: string
• Default: -
• This directive is required

The instance_name configuration directive allows to give a unique name to this agent instance. You must use a unique name for this setting across all the agents running for your project. Else, the agent will appear as misconfigured on the project dashboard, and its logs will be ignored.

A good idea can be to use the hostname as the instance_name.

listen¶

• Type: string
• Default: 127.0.0.1:10301
• This directive is optional

The listen configuration directive determines on which interface the agent is listening. It defaults to 127.0.0.1:10301 (port 10301 on the localhost), but can take other values:

• /var/run/redirectionio.sock: if you prefer to use a file, please make sure that user running the agent (redirectionio, by default) has the right to create this file
• "": an empty string, if you want your agent to listen on all network interfaces, on port 10301 (not advised)

persist¶

• Type: boolean
• Default: true
• This directive is optional

The persist configuration directive allows to define whether or not to store the rules on the disk. This allows to restart the agent with existing rules without the need to call redirection.io's backend, and adds of course more resiliency to your setup.

datadir¶

• Type: string
• Default: /var/lib/redirectionio
• This directive is optional

If the persist directive is enabled, datadir defines the directory where the rules will be persisted on the local filesystem. Of course, the user running redirectionio-agent must have a write permission on this directory.

cache¶

• Type: integer
• Default: 10000
• This directive is optional

The cache configuration directive defines how many compiled versions of the rules will be stored in memory (RAM). This setting makes the agent much faster, but can consume more memory on very large rulesets if it is set high.

The default value is 10000, which should use about 150-200MB of memory for a very large ruleset. It is not required to set this value much more high, as the agent will cache in priority the hot paths.

You can completely disable the rules memory cache, in order to minimize memory usage, by setting cache: 0

logging¶

• Type: boolean
• Default: undefined
• This directive is optional

The logging setting allows to define the logging behavior for this instance. If it is set to "true", the instance will be marked as allowed to log traffic. If it is set to "false", the instance will not collect traffic logs. If this setting is not defined, or defined with any other value than "true" or "false", it will be managed by the value defined in the manager graphical interface. Else, this setting takes precedence over the logging behavior defined in the manager graphical interface.

test_mode¶

• Type: boolean
• Default: undefined
• This directive is optional

The test_mode setting allows to set this instance in "test" mode. If this setting is not defined, or defined with any other value than "true" or "false", it will be managed by the value defined in the manager graphical interface. Else, this setting takes precedence over the logging behavior defined in the manager graphical interface. If it is enabled, the value of the "logging" setting will be forced to "false".

project_keys¶

• Type: list of strings
• Default: []
• This directive is optional

The project_keys setting allows to preload the agent with some projects rulesets at startup time. If this directive is not set, the agent will start with an empty ruleset, and it will only load the rules for your project(s) when the first request arrives.

In order to avoid the first requests to fail (because the ruleset would not be loaded in time), you can use this configuration directive to set a list of project keys to load at agent startup time.

proxies¶

This optional section allows to run the agent as a reverse proxy instead of only running it as a server. If this section is missing in the configuration file, the agent will simply not run as a reverse proxy.

The proxies configuration node is an array that can contain one or more reverse proxy configuration. For each proxy that you need to define, use the following configuration directives:

listen¶

• Type: string
• Default: -
• This directive is required

The address of the interface to listen to, in the form address:port. Valid values are, for example, 0.0.0.0:80, 0.0.0.0:443 (for listening on all network interfaces), 127.0.0.1:8080, etc. The HTTP(s) requests received on this interface will be analyzed and possibly forwarded to the forward address, if necessary.

Listening on a privileged port can require additional permissions, so you may need to run the redirectionio-agent binary with a user having appropriate permissions.

When listening on port 443, you max expect SSL-encrypted requests. In that case, you have to setup the tls_cert_file and tls_key_file configuration directives (see below).

forward¶

• Type: string
• Default: -
• This directive is required

The address of the interface to forward the HTTP requests to, in the form scheme://address:port. Valid values are, for example, http://127.0.0.1:8080, https://192.168.0.30:443, etc.

project_key¶

• Type: string
• Default: -
• This directive is required

This is the project key to use for this HTTP proxy. The HTTP requests received by this proxy will be matched against the ruleset of this redirection.io project, and the transformations defined in rules (redirections, etc.) executed directly at the proxy level.

preserve_host¶

• Type: boolean
• Default: false
• This directive is optional

This setting allows to pass the Host header to the forward destination. This is useful to get your redirection rules work when their Source URL is defined with a domain name.

tls_cert_file¶

• Type: string
• Default: -
• This directive is optional

If this proxy listens on port 443 or is expected to receive https traffic, please set in the tls_cert_file directive the absolute path to a SSL certificate file, in a location readable by the redirectionio-agent binary.

tls_key_file¶

• Type: string
• Default: -
• This directive is optional

If this proxy listens on port 443 or is expected to receive https traffic, please set in the tls_key_file directive the absolute path to a SSL key file, in a location readable by the redirectionio-agent binary.

metrics_server¶

• Type: string
• Default: -
• This directive is optional
• Available since: 2.2.0

The address of the http monitoring interface to listen to, in the form address:port. Valid values are, for example, 0.0.0.0:8080 (for listening on all network interfaces), 127.0.0.1:8080, etc. Un-commenting this option enables a HTTP endpoint which serves a JSON feed containing metrics.

Here is an example response:

[
    {
        "id": "5e11a6df-3a1a-4f30-ba91-3c79715857d2:60c680c1-3a5b-491f-a3e4-d701a82d64cd",
        "name": "example-com",
        "rules": 4242,
        "milliseconds_since_last_update": 14452,
        "last_update_duration": 325,
        "log_buffer_size": 1233,
        "total_requests": 18279
    },
    {
        "id": "fe75016c-1b78-4e6b-a769-3ecd38c4c4b1:2552637c-1080-4069-960a-07da9eb25bc3",
        "name": "other-example-com",
        "rules": 117392,
        "milliseconds_since_last_update": 13273,
        "last_update_duration": 1581,
        "log_buffer_size": 899,
        "total_requests": 21924
    }
]

The keys of the JSON array are the project keys for the redirection.io projects that this agent instance is aware of.

log¶

This optional section contains directives to configure the agent logging. Each subsection is optional and independent of one another. If this section is missing in the configuration file, the agent will not log errors or warnings.

file¶

This subsection can contain directives for file logging.

level¶

• Type: string
• Default: info
• This directive is optional

This fixes the log verbosity. It can be one of debug, info, error.

path¶

• Type: string
• Default: -
• This directive is required

Path of the log file to write in. Please make sure that user running the agent (redirectionio, by default) has the right to create this file.

syslog¶

This subsection can contain directives for syslog logging.

network¶

• Type: string
• Default: ""
• This directive is required

The type of connection to use ("", udp or tcp). Use an empty string ("") to use a local syslog server.

address¶

• Type: string
• Default: ""
• This directive is required

The address of the logging server to use. Use an empty string ("") to use a local syslog server. In order to use a remote server, or a server running on a non-standard port, use a string of the form address:port, eg. 192.168.0.30:514

level¶

• Type: string
• Default: info
• This directive is required

This fixes the log verbosity. It can be one of debug, info, error.

tag¶

• Type: string
• This directive is optional

This allows to attach a tag to the logs sent to syslog.

Complete example¶

Here is a complete configuration example, for reference:

# Name of this instance, mandatory for logging
instance_name: "A UNIQUE NAME"

# Interface listening. "" for all interfaces (not advised)
# /run/redirectionio.sock or 127.0.0.1:10301
listen: 127.0.0.1:10301
#listen: /run/redirectionio.sock # If you use a file, please make sure that user running the agent has the right to create it

# Whether or not to store rules on the disk.
# This allows to restart the agent with existing rules without the need to call redirection.io's backend
persist: true

# Directory where the rules will be persisted
datadir: /var/lib/redirectionio
  
# This setting allows to define the logging behavior for this instance. If it is set to "true", the instance will
# be marked as allowed to log traffic. If it is set to "false", the instance will not collect traffic logs.
# If this setting is not defined, or defined with any other value than "true" or "false", it will be managed
# by the value defined in the manager graphical interface. Else, this setting takes precedence over the logging
# behavior defined in the manager graphical interface.
logging: true

# This setting allows to set this instance in "test" mode. If this setting is not defined, or defined
# with any other value than "true" or "false", it will be managed by the value defined in the
# manager graphical interface. Else, this setting takes precedence over the logging behavior defined in the
# manager graphical interface. If it is enabled, the value of the "logging" setting will be forced to "false".
test_mode: false

# Number of items to store in memory.
# This makes the agent much faster, but will consume more memory on very large rulesets if this setting is high
# With the default value, a very large ruleset should consume about 150-200 MB of memory
# Set to 0 to disable the cache and minimize memory usage
cache: 10000

# Keys of projects to preload
# This allows to preload the agent with some projects rulesets at startup time
project_keys:
    - "A VALID PROJECT KEY"

# Run the agent as a reverse proxy
# Leave it empty to disable the reverse proxy feature
proxies:
    -
	    listen: ":80"
	    forward: "http://127.0.0.1:8080"
	    project_key: "A VALID PROJECT KEY"
	    preserve_host: true # Preserve host header, defaults to false
    -
	    listen: ":443"
	    forward: "http://192.168.1.47:80"
	    project_key: "ANOTHER VALID PROJECT KEY"
	    cert_file: /path/to/ssl/cert.pem
	    key_file: /path/to/ssl.key
  

# Metrics Server
# Uncommenting this setting enables a http endpoint which serves a json feed containing metrics
# Example values: 127.0.0.1:8080, 0.0.0.0:8080, /run/redirectionio-metrics.sock
metrics_server: 127.0.0.1:9080

# Sets log configuration. Each section is optional and independent of one another.
log:
    file:
        level: debug
        path: /proc/self/fd/2

    syslog:
        # pushes to the local syslog
        network: "" # empty string
        address: "" # empty string
        level: info
        tag: redirectionio-agent

Agent command line options¶

The redirection.io agent supports several command line options:

$ redirectionio-agent --help

Usage of redirectionio-agent:
  -config-file string
    	Use this option to explicitly pass a configuration file
  -debug
    	Enable debug mode
  -test
    	Test config and exit, return non zero exit code if there is an error in the config
  -version
    	Show version and exit

Start-defined configuration file¶

By default, the agent will start using a /etc/redirectionio/agent.yml or $HOME/.redirectionio/agent.yml configuration file. If required, you can also pass the -config-file option to force a given configuration file:

/usr/bin/redirectionio-agent -config-file /path/to/some/configuration/directory/some-config-file.yml

Debug level¶

The -debug option gives more details on how the agent behaves. You may use it to troubleshoot your redirection.io agent install:

/usr/bin/redirectionio-agent -debug

Configuration test¶

The -test option allows to test the configuration file and get insights on mis-configurations. This command returns a non-zero code when the agent is not properly configured, so you may use it in provisioning scripts to only restart/reload the agent when the configuration is properly defined.

/usr/bin/redirectionio-agent -test

time="2021-05-03T12:42:42+00:00" level=info msg="redirectionio-agent (version: 2.2.0, build date: 2021-05-03T12:42:00Z)" instance_name=example-com

This options is available since the release 2.2.0.

Get the current agent version¶

The -version option displays the release name of the installed redirection.io agent:

/usr/bin/redirectionio-agent -version

2.2.0

This options is available since the release 2.2.0.