Listening for requests

The redirection.io agent includes a built-in reverse proxy, which allows you to forward the incoming requests to one or more backend servers.

The reverse proxy supports the http1, http2 and http3 protocols, and it can be configured to listen for incoming requests on any port using the listen directive.

For example, the following configuration will make the agent listen for incoming HTTP requests on port 80:

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

Listening for HTTPS requests

The reverse proxy supports SSL termination, which means that it can handle HTTPS requests and forward them to the backend using HTTP(s). This is useful if you want to secure your website with SSL certificates, without having to configure SSL on your backend servers.

Listening for https requests can be enabled by configuring the "listen" directive with one listener for the tls protocol. For example:

instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tls://0.0.0.0:443'
    forward:
        address: 'backend:8080'
    agent:
        project_key: my-project-key

You will usually want to listen for both http and https requests. In this case, you can configure two listeners, one for the http protocol and one for the tls protocol:

instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
        - 'tls://0.0.0.0:443'
    forward:
        address: 'backend:8080'
    agent:
        project_key: my-project-key

The agent also supports HTTP3, often refered as QUIC. To enable HTTP3 support, you can also configure a listener for the quic protocol:

instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
        - 'tls://0.0.0.0:443'
        - 'quic://0.0.0.0:443'
    forward:
        address: 'backend:8080'
    agent:
        project_key: my-project-key

SSL certificates management

The agent supports two modes for SSL configuration:

• using Let's Encrypt (or any other ACME provider) to automatically generate and renew SSL certificates for your domains
• using your own SSL certificates, for which you can specify the paths to the certificate and private key files in the agent configuration

ACME certificates

The "letsencrypt" mode is very convenient if you don't want to worry about managing your SSL certificates. The agent will automatically generate and renew the certificates for you, as long as your domains are correctly configured to point to the agent - under the hood, redirection.io uses the HTTP-01 challenge.

If you only use the "letsencrypt" mode, you will need to wait for the certificates to be generated before your website can be accessed over HTTPS. This usually takes a few minutes, but it can take longer if there are issues with the domain configuration or if you have a large number of domains. Once the certificates are generated, the agent will automatically switch to using them for HTTPS requests, and it will store them in the storage configured under the instance.persist configuration key, for future use.

Here is a configuration example for the "letsencrypt" (acme) mode:

instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
        - 'tls://0.0.0.0:443'
    certificate:
        acme:
            contacts:
                - myemail@example.com
            directory_url: 'https://acme-v02.api.letsencrypt.org/directory'
    forward:
        address: 'backend:8080'
    agent:
        project_key: my-project-key

The directory_url option allows you to specify which ACME provider you want to use. As an example, you can use Let's Encrypt production or staging URLs:

• Production: https://acme-v02.api.letsencrypt.org/directory
• Staging: https://acme-staging-v02.api.letsencrypt.org/directory

Local file certificates

The "file" mode is useful if you already have your SSL certificates ready, or if you want to use self-signed certificates for testing purposes. In this case, you can specify the paths to the certificate and private key files in the agent configuration. Here is a configuration example for the "file" mode:

instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
        - 'tls://0.0.0.0:443'
    certificate:
        file:
            key: /path/to/cert.key
            certificates:
                - /path/to/chain.pem
                - /path/to/cert.pem
    forward:
        address: 'backend:8080'
    agent:
        project_key: my-project-key

ACME and local files certificates at the same time

Both modes ("acme" and "file") can be combined - in this case, the agent will use the "file" mode certificates at startup time, and will automatically switch to the "acme" mode certificates once they are generated. This allows you to have SSL support from the very beginning, even if you don't have your certificates ready yet:

instance:
    name: 'Example instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
        - 'tls://0.0.0.0:443'
    certificate:
        acme:
            contacts:
                - myemail@example.com
            directory_url: 'https://acme-v02.api.letsencrypt.org/directory'
        file:
            key: /path/to/cert.key
            certificates:
                - /path/to/chain.pem
                - /path/to/cert.pem
    forward:
        address: 'backend:8080'
    agent:
        project_key: my-project-key