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 (its name will be the hostname of the server running the agent), and its logs will be ignored.

A good idea can be to use a combination of the hostname and deployment environment as the instance_name. Also, remember that you can use environment variables anywhere in the configuration file.

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.

add_rule_ids_header

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

If this setting is enabled, a response header named X-RedirectionIo-RuleIds will be added to the response. Its value will contain the list of the redirection.io rule ids applied to this response, separated by the ; character.

This option is available since the release 2.2.5.

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.

Using environment variables in the configuration file

It is possible to use env vars in the configuration file, which may be helpful in dynamic environments like cloud-based deployments:

See this example:

instance_name: "${REDIRECTIONIO_INSTANCE_NAME}"
datadir: "${REDIRECTIONIO_APPLICATION_DIR}/rules"
log:
    file:
        level: info
        path: "${REDIRECTIONIO_APPLICATION_DIR}/log/agent.log"

In this example, the REDIRECTIONIO_INSTANCE_NAME and REDIRECTIONIO_APPLICATION_DIR environment variables must be defined set when the agent is started (of course, you can use any name you want for the environment variables). If they are not defined, the variables will be replaced with an empty string:

$ redirectionio-agent
level=error msg="[server] The agent is Misconfigured: The 'instance_name' is not defined."

When the required env vars are set, they are interpreted during the startup of the agent:

$ export REDIRECTIONIO_INSTANCE_NAME=example-agent
$ export REDIRECTIONIO_APPLICATION_DIR=/tmp/redirectionio
$ redirectionio-agent
level=info msg="redirectionio-agent (version: 2.2.6, build date: 2021-08-05T13:25:14Z)" instance_name=example-agent
...

If set, the special HTTPS_PROXY environment variable will be used by the agent to route the communications with the redirection.io APIs through an https proxy.

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
	    add_rule_ids_header: true # Add a X-RedirectionIo-RuleIds response 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 option 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 option is available since the release 2.2.0.

Using the agent behind a HTTPS proxy

In some enterprise configurations, it can be complicated to get a direct connection between the agent and the redirection.io APIs. Some hosting layouts require that connections to external services go through a company proxy.

The redirection.io agent is able to use a https proxy to communicate with the redirection.io APIs. This can be done by using a HTTPS_PROXY environment variable:

HTTPS_PROXY=http://192.168.0.254:8443 /usr/bin/redirectionio-agent

This option is available since the release 2.2.4.

This page has been updated on September 7th, 2021.
Can't find your answer?
Contact our support