agent configuration reference

Agent Configuration Reference

The redirection.io agent is a software that runs on your server and allows you to sync data from and to the redirection.io platform. It is used to provide an efficient and performant way to apply redirection.io rules on your infrastructure, and to collect logs and metrics from your server.

This page provides a reference of the agent configuration, with explanations on the various configuration options available. It is recommended to read this documentation page before configuring the agent, in order to understand the various options and their implications.

You may also want to read the agent configuration guide section, which focuses on specific configuration topics.

Configuration Format and Location

The agent can be configured using a single configuration file, in YAML, JSON or TOML format. By default, the agent looks for a configuration file in the following locations (in order of priority):

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

Reloading the Agent Configuration

When you edit the agent configuration file, you need to reload the agent in order to apply the new configuration. This can be done using the systemctl service file:

$ sudo systemctl reload redirectionio-agent.service

Alternatively, you can also reload the agent by sending a SIGHUP signal to the agent process:

$ sudo kill -SIGHUP $(pidof redirectionio-agent)

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}"
    persist: "${REDIRECTIONIO_APPLICATION_DIR}/rules"
log:
    -
        output: "file"
        level: "info"
        path: "${REDIRECTIONIO_APPLICATION_DIR}/log/agent.log"

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

Configuration Structure

The agent configuration is semantically divided into five main sections:

Instance

The instance section is used to configure the agent on how to sync data to the redirection.io platform. It exposes several options to configure the instance name, the data persistency, the rules cache and more.

Name

The name configuration directive allows to give a name to this agent instance. You must use a unique name for this setting across all the agents running for your project.

Cache

The cache configuration directive defines how many compiled versions of the regular expressions are stored in memory (RAM).

Logging

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.

Persist

The persist configuration directive allows to define whether or not to store data on the disk.

Max Logs Buffer Size

The max_logs_buffer_size configuration directive allows to define the maximum number of logs that can be buffered in memory before being sent to the redirection.io platform.

Server

The server section is used to configure the TCP server that is used by the nginx and apache module to communicate with the agent.

Listen

The listen configuration directive determines on which interface the agent is listening.

Project Keys

The project_keys setting allows to preload the agent with some projects rulesets at startup time.

Reverse Proxy

The reverse_proxy section configures the built-in HTTP reverse proxy of the redirection.io agent.

Listen

The reverse proxy listen configuration directive allows to list addresses and protocols the reverse proxy will listen to. Supported schemes include:

Forward

The reverse_proxy.forward config node defines how the proxy handles the request after rule execution, either serving local files or proxying requests to a backend server.

Agent

The reverse_proxy.agent configuration node controls the redirection.io engine behavior for this instance. It contains several directives:

Trusted Proxies

This configuration node defines which upstream proxies are authorized to forward client information.

Metrics

When running an infrastructure, platform engineers and ops often need to monitor how services work, and be able to detect if issues are about to happen. The redirection.io agent exposes an optional monitoring endpoint in a Prometheus-compatible format.

Listen

The address of the http monitoring interface to listen to, in the form address:port.

Log

This optional section contains directives to configure the agent technical logging (restarts, errors, warnings, etc.).

Output

Defines where the agent logs are sent to.

Path

Defines the path of the log file when the output directive is set to file.

Address

Defines the address of the syslog server when the output directive is set to syslog.

Format

Defines the format of the logs.

Min Level

Max Level

Configuration Examples

We provide a list of configuration examples to explore all the configuration possibilities. Check it out to get inspiration for your own configuration!