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 port10301
(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 simply 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.
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
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
# 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
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