Forwarding requests to the backend - Agent documentation | Documentation

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:

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:

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:

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

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:

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:

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.

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:

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.