# Forwarding requests to the backend

When a request is accepted by the redirection.io agent, it is forwarded to a backend server. The backend server can be any server that can handle HTTP requests, such as a web server, an application server, a load balancer, a remote server, etc. The backend server can be running on the same machine as the agent, or on a different machine.

## Defining the forward address [Permalink to this section](/content/documentation/agent-documentation/forwarding-requests-to-the-backend#defining-the-forward-address "Permalink to this section"/index.html)

The `forward` configuration key allows you to specify the address of the backend server to which the requests should be forwarded. The address can be specified in the form of `host:port`, where `host` is the hostname or IP address of the backend server, and `port` is the port on which the backend server is listening for incoming requests.

For example, the following configuration will forward the requests to a backend server running on `127.0.0.1:8080`:

```yaml
instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    forward:
        address: '127.0.0.1:8080'
    agent:
        project_key: my-project-key
```

## Forwarding to a TLS backend [Permalink to this section](/content/documentation/agent-documentation/forwarding-requests-to-the-backend#forwarding-to-a-tls-backend "Permalink to this section"/index.html)

If the agent is running in front of a backend server that is configured to accept HTTPS requests, you can configure the agent to forward the requests to the backend using TLS. To do this, you need to specify the `tls` option in the `forward` configuration. For example:

```yaml
instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    forward:
        address: 'backend:4443'
        tls:
            sni: example.com
            allow_invalid_certificates: false
    agent:
        project_key: my-project-key
```

Of course, in this case the forward address must target a port that is configured to accept TLS connections.

The `sni` directive is optional, and it allows you to specify the SNI hostname to use when connecting to the backend server. If it is not specified, the agent will use the `host` part of the forward address as the SNI hostname.

The `allow_invalid_certificates` option is also optional, and it allows you to specify whether or not to allow invalid SSL certificates when connecting to the backend server. This can be useful if you are using self-signed certificates for testing purposes, or if you have a backend server with an SSL certificate that is not trusted by the agent.

## Forwarded headers management [Permalink to this section](/content/documentation/agent-documentation/forwarding-requests-to-the-backend#forwarded-headers-management "Permalink to this section"/index.html)

When the agent forwards a request to the backend server, it can include some headers in the forwarded request that provide information about the original client request. The `forwarded_for` option allows you to specify the strategy to use for these headers:

```yaml
instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    forward:
        address: '127.0.0.1:8080'
        forwarded_for: auto
    agent:
        project_key: my-project-key
```

- `false` or `none`: no forwarded headers will be appended in the request sent to the backend server. This means that:

- if "forwarded" headers were present in the original client request, they will be sent "as is" to the backend server
  - otherwise, no "forwarded" headers will be included in the request sent to the backend server.
- `legacy`: this mode uses the old `X-Forwarded-` style headers:

- the `X-Forwarded-For` header will be included in the request sent to the backend server, and it will contain the IP address of the original client. If this header was already present in the original client request, the agent will append the new values, using a comma as a separator (for example, if the original client request contains an `X-Forwarded-For` header with the value `1.2.3.4`, and the agent appends `5.6.7.8`, the resulting header will be `1.2.3.4, 5.6.7.8`).
  - the `X-Forwarded-Host` and `X-Forwarded-Proto` headers are transmitted "as is" to the backend server, which means that if they were present in the original client request, they will be included in the request sent to the backend server with the same values. If they were not present in the original client request, they will be added in the request sent to the backend server with the values of the original host header and the original protocol respectively.
- `rfc7239`: the `Forwarded` header will be included in the request sent to the backend server, and it will contain the IP address of the original client, the original host header, and the original protocol (http or https) in a format that follows [the RFC 7239 standard](https://www.rfc-editor.org/rfc/rfc7239.html). If it was already present in the original client request, the agent will append the new values.
- `auto`: the agent will try to use the RFC 7239 standard whenever possible:
  - if the `X-Forwarded-For` header is present, the agent tries to convert this header to the RFC 7239 standard. If the conversion is not possible, it uses the `legacy` strategy.
  - otherwise, it uses the `rfc7239` strategy.

## IPV6 support [Permalink to this section](/content/documentation/agent-documentation/forwarding-requests-to-the-backend#ipv6-support "Permalink to this section"/index.html)

When the forward address is defined as a hostname (eg. `my-backend-server.com:8080`), the agent will automatically resolve the hostname to an IP address. By default, this resolution only returns IPV4 addresses, but you can configure the agent to also accept IPV6 addresses by setting the `allow_ipv6` option to `true` in the `forward` configuration. For example:

```yaml
instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    forward:
        address: 'backend:8080'
        allow_ipv6: true
    agent:
        project_key: my-project-key
```

## Persistent connections to the backend [Permalink to this section](/content/documentation/agent-documentation/forwarding-requests-to-the-backend#persistent-connections-to-the-backend "Permalink to this section"/index.html)

The redirection.io agent supports persistent connections to the backend server, which can improve the performance of the requests handling by reusing the same connection for multiple requests. This is especially useful if the backend server is running on the same machine as the agent, or if it is running on a fast network.

To enable persistent connections to the backend, you can enable the `keep_alive` option to `true` in the `forward` configuration. For example:

```yaml
instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    forward:
        address: 'backend:8080'
        keep_alive: true
    agent:
        project_key: my-project-key
```

By default, the `keep_alive` option is set to `false`, which means that the agent will close the connection to the backend server after each request. If you enable the `keep_alive` option, the agent will keep the connection to the backend server open for a certain amount of time, and it will reuse the same connection for multiple requests.

The timeout and maximum number of requests for the persistent connections can be configured using the detailed `keep_alive` syntax, for example:

```yaml
instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    forward:
        address: 'backend:8080'
        keep_alive:
            idle_timeout: 30s
            born_timeout: 1h
            max_requests: 10000
    agent:
        project_key: my-project-key
```

By default:
- the `idle_timeout` is set to `5s`, which means that the agent will close the connection to the backend server if it is idle for more than 5 seconds
- the `born_timeout` is set to `3600s`, which means that the agent will close the connection to the backend server if it has been open for more than 1 hour, regardless of the activity on the connection
- the `max_requests` option is set to `0` by default, which means that there is no limit on the number of requests that can be handled by the same connection.

## Timeouts configuration [Permalink to this section](/content/documentation/agent-documentation/forwarding-requests-to-the-backend#timeouts-configuration "Permalink to this section"/index.html)

The configuration of the redirection.io agent regarding timeouts is very flexible, and allows you to fine-tune the behavior of the agent in case of slow or unresponsive backends, or in case of long-running requests.

The available timeout options regarding the requests management are located under the `timeout` configuration key, and they allow you to specify the maximum time to wait for different stages of the request handling process.

```yaml
instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    forward:
        address: 'backend:8080'
    timeout:
        resolve: 100ms
        connect: 100ms
        tls_handshake: 100ms
        request: 1s
        response: 1s
    agent:
        project_key: my-project-key
```

Here are the available timeout options:
- `resolve`: the maximum time to wait for the hostname resolution of the backend server (if the forward address is defined as a hostname)
- `connect`: the maximum time to wait for the connection to the backend server to be established
- `tls_handshake`: the maximum time to wait for the TLS handshake to be completed (when connecting to a TLS backend server)
- `request`: 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`: 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.

If one of these timeouts is reached, the agent will consider that the backend server is unresponsive, and it will return an error response to the client. The error response will have a status code of `503 Service Unavailable`, and it will include an error message in the response body that indicates which timeout was reached.

## The local filesystem as a backend [Permalink to this section](/content/documentation/agent-documentation/forwarding-requests-to-the-backend#the-local-filesystem-as-a-backend "Permalink to this section"/index.html)

The redirection.io agent also supports using the local filesystem as a backend, which can be useful for serving static files, such as images, videos, documents, etc. To do this, you need to specify the `directory` option in the `forward` configuration, and provide the path to the directory that contains the files to be served. For example:

```yaml
instance:
    name: 'My Instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    forward:
        directory: /var/www/media
    agent:
        project_key: my-project-key
```

When using the local filesystem as a backend, the agent will serve the files as they are, without any processing. If the resource is not found in the specified directory, the agent will return a `404 Not Found` error response (that can be customized by creating a redirection.io rule with the "backend status code" trigger set to `404`).

This page has been updated on Apr 16, 2026.