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

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 simply not be logging 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

address¶

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

level¶

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

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

# 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 shoud consume about 150-200 MB of memory
# Set to 0 to disable the cache and minimize memory usage
# Default value: 10000
cache: 10000

# Sets log configuration. Each section is optional and independant 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

Start-defined configuration file¶

While the agent will start using a /etc/redirectionio/agent.yml or $HOME/.redirectionio/agent.yml configuration file, you may also pass a -config-file option to force a given configuration file:

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