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.

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):

/etc/redirectionio/agent.yml
/etc/redirectionio/agent.yaml
/etc/redirectionio/agent.json
/etc/redirectionio/agent.toml

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"

In this example, the REDIRECTIONIO_INSTANCE_NAME and REDIRECTIONIO_APPLICATION_DIR environment variables must be defined 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 not be replaced, and you will obviously get an error:

$ redirectionio-agent

2026-09-26T16:07:17.753395Z ERROR cannot open file ${REDIRECTIONIO_APPLICATION_DIR}/log/agent.log: No such file or directory (os error 2)

When the required env vars are set, they are interpreted during the startup of the 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.

Configuration structure

The agent configuration is semantically divided into five main sections:

The instance section: to configure the agent on how to sync data to the redirection.io platform
The server section: a tcp server used by the nginx and apache module
The reverse_proxy section: to configure the agent as a reverse proxy
the metrics section: to configure metrics that you can collect to monitor the agent
the log section: to configure the agent technical and traffic logs

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

Type: string
Default: -
This directive is required

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

If no instance name is provided in the configuration, the hostname of the server will be used.

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.

cache

Type: integer
Default: 10000
This directive is optional

When using the redirection.io agent, rules are stored in memory and organized using a specific data structure that allows to optimize the rules matching performance. This data structure can consume a lot of memory when the number of regular expressions in the rules is high. To avoid consuming too much memory, only a limited number of compiled regular expressions are stored in memory, other are compiled on the fly, when needed. This can lead to a performance decrease when the number of regular expressions is high and the agent needs to compile them on the fly.

The cache configuration directive defines how many compiled versions of the regular expressions are 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 higher, 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. In this case, the agent will compile all the regular expressions on the fly when needed, which can lead to a performance decrease.

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, it will be managed by the value defined in the manager graphical interface.

This option must be a boolean; any non-boolean value is considered invalid and treated as if the setting was not defined. When explicitly set, this setting takes precedence over the logging behavior defined in the manager graphical interface.

persist

Type: boolean or string or object
Default: /var/lib/redirectionio
This directive is optional

The persist configuration directive allows to define whether or not to store data on the disk. With "data", we mean:

the rules downloaded from the redirection.io platform, which are stored in a compiled format to be used by the agent;
the SSL certificates generated using ACME and used by the agent when it is configured as a reverse proxy.

Storing such data on the disk allows to keep it in case of agent restart, and to avoid calling redirection.io's backend to get the rules at startup time. This can be useful in case of network issues between the agent and redirection.io's backend, or to speed up the agent startup time.

The persist directive can be set to true, false, a string or an object. If set to true, the agent will store the persistent data in the default directory (/var/lib/redirectionio). If set to false, the agent will not store data on the disk. If set to a string, the agent will store the persistent data in the specified directory:

instance:
  persist: /tmp/redirectionio-rules

max_logs_buffer_size

Type: integer
Default: 100000
This directive is optional

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. This setting can be useful to avoid consuming too much memory when the traffic is high and the agent is not able to send logs to the redirection.io platform fast enough.

If the buffer is full, the agent will start dropping logs and will log a warning message.

The default value is 100000, which should be enough for most use cases. You can set this value higher if you have a very high traffic and want to avoid losing logs, but keep in mind that it can consume more memory. Remember that logs are sent periodically to the redirection.io platform, so the buffer is not expected to be full for a long time. Also, while collecting and sending a very high number of logs to the redirection.io platform is not a problem, your project must be configured to accept this high number of logs, otherwise they will be dropped by the platform. You can check the logs limits for your project in the project settings of the manager graphical interface.

server

type: boolean or object
default: false
this directive is optional

The server section is used to configure the TCP server that is used by the nginx and apache module to communicate with the agent. By default, the server is disabled, but it can be enabled by setting the server directive to true or to an object. When enabled, the server listens on the listen address (see below) and accepts connections from the nginx and apache module to apply the redirection.io rules on the incoming requests.

The true value is a shorthand to enable the server with the default configuration. If you want to customize the server configuration, you can set the server directive to an object, which can contain the following properties:

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)

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.

reverse_proxy

The reverse_proxy section configures the built-in HTTP reverse proxy of the redirection.io agent. It allows the agent to act as a standalone proxy, receiving traffic directly and either serving local files or forwarding requests to a backend server while applying your redirection and SEO rules. See the detailed documentation on how to use the agent as a reverse proxy in the dedicated documentation page.

listen

Type: list of strings
Default: []
This directive is required

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

tcp://<ip>:<port>: standard HTTP/1.1
unix://<path>: HTTP/1.1 via Unix domain sockets
tls://<ip>:<port>: secure HTTP (HTTP/1.1 and HTTP/2)
quic://<ip>:<port>: HTTP/3 (QUIC protocol).

forward

Type: object
Default: null

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

Backend proxying ("address" forward)

In this layout, the agent forwards the request to a backend server, which can be your application server or any other HTTP server. The agent applies the redirection.io rules before forwarding the request, and can modify the request and response as needed.

For this layout, the forward configuration directive must be set to an object containing the following properties:

address: (string, required) the backend server address. This can be a hostname or an IP address, and must include a port (e.g., 127.0.0.1:8080 or backend-server:8080).
max_http_version: (string) one of h1, h2, or h3 to indicated the maximum HTTP version to use when communicating with the backend
request_host: (string) to override the Host header sent to the backend.
forwarded_for: (string) the strategy to use for forwarding headers (auto, false, none, legacy, rfc7239).
allow_ipv6: (boolean, default false) to enable or disable IPv6 for backend connections.
tls: (boolean or object) Enable TLS to the backend.
- sni: (string) Server Name Indication to use.
- allow_invalid_certificates: (boolean, default false) Allow self-signed certificates.
keep_alive: (boolean or object, default false)
- idle_timeout: (duration, e.g., 30s) sets the time to keep an idle connection open.
- born_timeout: (duration, e.g., 1h) defines the max lifetime of a keepalive connection.
- max_requests: (integer) limits the number of requests per single connection.
timeout: (object)
- resolve: (duration, e.g., 100ms) the maximum time to wait for the hostname resolution of the backend server (if the forward address is defined as a hostname)
- connect: (duration, e.g., 100ms) the maximum time to wait for the connection to the backend server to be established
- tls_handshake: (duration, e.g., 100ms) the maximum time to wait for the TLS handshake to be completed (when connecting to a TLS backend server)
- request: (duration, e.g., 1s) the maximum time to wait for the request to be sent to the backend server. The timeout is reset each time new data is sent.
- response: (duration, e.g., 1s) the maximum time to wait for the response to be received from the backend server. The timeout is reset each time new data is received.

Static Files ("directory" forward)

As an alternative to the backend proxyfying, the forward: directory strategy allows to expose a local directory.

directory: (string, required) the local path to serve static files from

agent

Type: object
Default: null

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

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 the redirection.io project associated with the project key, and the transformations defined in rules (redirections, etc.) executed directly at the proxy level.

override_request_host

Type: string
Default: -
This directive is optional

This directive allows to force the hostname to use when matching the request. This is useful if you have defined rules using URL triggers with absolute URL values (containing a scheme, a domain name, etc.), while the proxy receives the requests using another hostname.

Please note that, most of the time, you should prefer the use of the trusted_proxies directive along with the correct X-Forwarded-Host request header.

override_request_scheme

Type: string
Default: -
Possible values: http or https
This directive is optional

This directive allows to force the scheme to use when matching the request. This is useful if you have defined rules using a URL trigger with an absolute URL value (containing a scheme, a domain name, etc.), but you want to use the same rules in a proxy definition with another scheme.

Imagine, for example, a proxy definition listening https traffic only, using a project in which rules are defined using the http:// scheme: URLs would never be matched, as no rule uses the https:// scheme. In this case, setting the override_request_scheme value to http will force the matching to be performed with this scheme, not the real request scheme.

Please note that, most of the time, you should prefer the use of the trusted_proxies directive along with the correct X-Forwarded-Scheme request header.

add_rule_ids_header

Type: boolean
Default: false
This directive is optional

If this setting is enabled (value true), 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.

trusted_proxies

This configuration node defines which upstream proxies are authorized to forward client information, and which headers they are allowed to set.

ips: (list of strings, required) defines the list of trusted IP addresses or CIDR ranges.
forwarded: (boolean, default true) defines whether or not to trust the standard Forwarded header.
x_forwarded_for: (boolean, default true) defines whether or not to trust the X-Forwarded-For header.
x_forwarded_host: (boolean, default false) defines whether or not to trust X-Forwarded-Host for the original host.
x_forwarded_proto: (boolean, default false) defines whether or not to trust X-Forwarded-Proto for the original scheme.

http

The reverse_proxy.http config node allows to configure several aspects of the requests management.

cache

Type: boolean
Default: false
This directive is optional

Even if it is not its primary goal, the redirection.io agent can be used as a caching reverse proxy. It complies with the standard http cache headers and stores in memory responses that are allowed be stored in shared caches. The agent will use maximum 1GB of memory for this repsonse cache.

compress

Type: boolean
Default: false
This directive is optional

The reverse_proxy.http.compress configuration directive can be used to have the agent compress responses using gzip or brotli, which can reduce the size of the responses and improve the network performance of your website.

geo_ip

Type: object
Default: null
This directive is optional

This directive can be used to configure a MaxMind database (.mmdb) at the agent level, so it can happen custom geolocation headers to incoming requests. See the detailed documentation about the configuration of a GeoIP database.

The geo_ip node, if configured, must have sub-properties:

path: (string, required) the path to a MaxMind .mmdb database
headers: a map of header names and JSON paths in the database (in the form X-Country: "$.country.iso_code")

access_log

The reverse_proxy.access_log config nodes allow to configure the collection of trafic logs at the reverse proxy level.

output

Type: string
Possible values: stdout, stderr, file, or syslog
This directive is required if access_log is defined

Defines the output of the access logs. The file value allows to log to a file, the stdout and stderr values allow to log to the standard output and standard error streams, and the syslog value allows to log to the system syslog.

When logging to a file, the path directive must be defined (see below). When logging to syslog, the address directive must be defined.

format

Type: string
Possible values: text or json
Default:
- text for file, stdout and stderr
- rfc5424 for syslog
This directive is optional

Defines the format of the access logs. The json value allows to log in JSON format, the text value allows to log in a human-readable format, the rfc5424 and rfc3164 values allow to log in the corresponding syslog formats.

path

Type: string
Default: -
This directive is required if output is set to file

Defines the path of the log file when the output directive is set to file. The agent must have the right to create this file, and to write to it.

address

Type: string
Default: -
This directive is required if output is set to syslog

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

certificate

The reverse_proxy.certificate config nodes allow to configure TLS certificates for encrypted connections. This configuration node is required if you want to use the tls:// or quic:// schemes in the reverse_proxy.listen directive, and it is ignored otherwise.

acme

Defining the reverse_proxy.certificate.acme node allows to have the agent automatically manage TLS certificates for your domains using the ACME protocol (e.g., via Let's Encrypt). The agent will automatically request and renew certificates for the domains defined in the virtual_hosts section. If the instance.persist directory is defined, the certificates will be stored in a persistent way, so they will be kept in case of agent restart.

The acme node must contain the following properties:

contacts: (list of strings) the list of email addresses for notifications about certificate expiration and renewal
directory_url: (string) the ACME API endpoint to use (e.g., https://acme-v02.api.letsencrypt.org/directory for Let's Encrypt).

file

This config node allows to define manually the TLS certificates to use for encrypted connections. It must contain the following properties:

certificates: (list of strings) the paths to certificate chains
key: (string) the path to the private key

It is possible to combine the file and acme certificate management strategies, in order to have the agent use the manually defined certificates at startup time, and then automatically switch to the ACME-managed certificates when they are ready.

virtual_hosts

The concept of "virtual host" allows to define specific configurations for specific domains, which can be useful if you want to apply different rules or use different certificates for different domains. A virtual host is defined by a list of domains, and can contain overrides for all the other reverse_proxy config nodes: agent, forward, http, access_log, and certificate.

The domains listed in the virtual_hosts section will be matched against the Host header of the incoming requests, and the corresponding virtual host configuration will be applied if a match is found. If no match is found, the default configuration (defined at the root of the reverse_proxy section) will be applied.

The reverse_proxy.virtual_hosts.*.domains config node must be a list of (sub-)domains, and is required for each virtual host definition.

Threading and Performance

The reverse_proxy section also allows to configure some performance-related values:

server_threads: (integer) threads for accepting connections. Default is 1.
worker_threads: (integer) threads for processing requests. Default is the number of CPU cores.
worker_max_blocking_threads: (integer) max threads per worker for blocking operations.

You should usually not need to tweak these values, as the default configuration is designed to provide good performance for most use cases. However, in some specific cases (e.g., very high traffic, or very long processing times), you may want to adjust the number of worker threads to improve the throughput of the reverse proxy. You can read our detailed documentation about reverse proxy performance tuning for more information and examples.

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, which provides several metrics intended to be loaded by your favorite monitoring dashboard.

Read our detailed documentation about monitoring the agent for more information about the available metrics and how to use them.

listen

Type: string
Default: -
This directive is optional

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.

log

This optional section contains directives to configure the agent technical logging (restarts, errors, warnings, etc.). If this section is missing in the configuration file, the agent will not log errors or warnings.

output

Type: string
Possible values: file, stdout, stderr, syslog
This directive is required

Defines where the agent logs are sent to. The file value allows to log to a file, the stdout and stderr values allow to log to the standard output and standard error streams, and the syslog value allows to log to the system syslog.

When logging to a file, the path directive must be defined (see below). When logging to syslog, the address directive must be defined.

path

Type: string
Default: -
This directive is optional

Defines the path of the log file when the output directive is set to file. The agent must have the right to create this file, and to write to it.

If this directive is defined while the output directive is not set to file, it will be ignored.

address

Type: string
Default: -
This directive is optional

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

If this directive is defined while the output directive is not set to syslog, it will be ignored.

format

Type: string
Possible values: json, text, rfc5424, rfc3164
Default:
- text for file, stdout and stderr
- rfc5424 for syslog
This directive is optional

Defines the format of the logs. The json value allows to log in JSON format, the text value allows to log in a human-readable format, the rfc5424 and rfc3164 values allow to log in the corresponding syslog formats.

Please note that:

the rfc5424 and rfc3164 formats are only available when the output directive is set to syslog, and that the default format for syslog is rfc5424.
the text and json formats are only available when the output directive is set to file, stdout or stderr, and that the default format for these outputs is text.

min_level

Type: string
Possible values: debug, info, warning, error
Default: -
This directive is optional

This option allows to define the minimum level of logs that are sent to the output. For example, the warning value allows to log only warning and error logs.

If it is not defined, the agent will not restrict the logs to a minimum level.

max_level

Type: string
Possible values: debug, info, warning, error
Default: -
This directive is optional

This option allows to define the maximum level of logs that are sent to the output. For example, the warning value allows to log only debug, info and warning logs.

If it is not defined, the agent will not restrict the logs to a maximum 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!

This page has been updated on Mar 30, 2026

Can't find your answer?

Contact our support