# 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](/content/documentation/agent-documentation/index.html), 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):

- `/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:

```bash
$ sudo systemctl reload redirectionio-agent.service
```

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

```bash
$ 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:

```yaml
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:

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

### Cache
- Type: `integer`
- Default: `10000`
- This directive is optional

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

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

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

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

## 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
- Type: `string`
- Default: `127.0.0.1:10301`
- This directive is optional

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

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

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

### 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
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
- Type: `string`
- Default: `-`
- This directive is optional

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
- Type: `string`
- Possible values: `file`, `stdout`, `stderr`, `syslog`
- This directive is **required**

Defines where the agent logs are sent to.

### Path
- Type: `string`
- Default: `-`
- This directive is optional

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

### Address
- Type: `string`
- Default: `-`
- This directive is optional

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

### Format
- Type: `string`
- Possible values: `json`, `text`, `rfc5424`, `rfc3164`
- This directive is optional

Defines the format of the logs.

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

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

## Configuration Examples
We provide [a list of configuration examples](/content/documentation/agent-documentation/examples/index.html) to explore all the configuration possibilities. Check it out to get inspiration for your own configuration!