The agent as a reverse proxy

The preferred and most straightforward redirection.io integration way is to use the redirection.io agent as a reverse proxy, using the built-in features that the agent offers.

The redirectionio-agent reverse proxy features many configuration directives, which should be helpful in many situations to get redirection.io installed on your infrastructure in a performant, simple and scalable way.

How does the redirection.io agent reverse proxy work?

The redirection.io agent reverse proxy is a very simple and straightforward stateless reverse proxy:

• it accepts incoming connections, either as http or https
• it inspects the incoming requests in order to apply any matching rule
• if no rule matches, it forwards the request to the backend of your choice - either http or https

As any reverse proxy, the redirection.io agent can be replicated across your infrastructure. If you need more than one agent in your layout, you can of course duplicate the instance / pod / container.

Here are some properties of the redirection.io agent reverse proxy:

• it is fast and can inspect several thousand of request per second (and even more)
• it supports multi-project layouts
• it is a 0-dependency binary. The agent is distributed as an APT or RPM package, and it is also available as a .tar.gz archive
• it can be monitored using the agent metrics endpoint
• as any reverse-proxy, it is scalable, by launching more instances of the agent

Some example proxies configurations

As a standalone reverse proxy, the redirection.io agent can easily be configured in many types of layouts.

• as the first layer of your incoming traffic
• behind other reverse proxies
• behind a nginx or Apache server
• as a traffic manager; between several micro-services of your application
• in front of an API, to detect issues in real-life requests

This section gives insight on how to insert the redirectionio-agent reverse proxy in your existing web stack.

A traditional and minimalist layout

Take a standard and simple nginx VirtualHost. The nginx configuration usually defines several directives (server name, port to listen to, document root, etc.). This will be our base example in the next chapters (the approach with another Web Server, like Apache, would be very similar).

The redirection.io agent as a reverse proxy

The redirection.io agent bundles a full-featured and highly performant reverse proxy. See how we changed our previous infrastructure layout by introducing the redirection.io-agent reverse proxy:

In this layout:

• the agent receives all the incoming requests, on ports 80 and 443
• it forwards these requests to a locally-available nginx server, on port 8080
• the requests are forwarded using the X-Forwarded-* request headers, so your backend can be aware of the original request properties.

In the above layout, the agent forwards requests to the backend using the http protocol. In some cases, this might not be enough for your requirements. The agent is also able to forward the requests using https - with a valid certificate or an invalid one (in this case, use the allow_invalid_certificates configuration directive):

The redirection.io reverse proxy behind another reverse proxy

The redirection.io reverse proxy has one limitation: it does not support SNI, nor does it provide ways to configure cipher suites. The SSL configuration directives that the redirection.io reverse proxy offers are rather spartan, and not as verbose and comprehensive as those provided by other SSL termination software.

For this reason, you may want to place the redirection.io reverse proxy behind another proxy server, which will then act as your SSL termination endpoint. For example, this is what we can achieve with nginx (but you may as well use Varnish, HAProxy, Envoy, etc.):

redirection.io with the nginx dynamic module

As an alternative to the deloyment using the "reverse proxy" mode, the redirection.io nginx module is a quick way to integrate redirection.io in your infrastructure. This dynamic module just hooks in the nginx request and response loop, and synchronously queries a tcp API of the locally installed agent whenever a request arrives.

We also provide an Apache module that uses the very same concepts.

While this approch is interesting - because it means few changes to the infrastructure layout and the requests flow in your stack - it can be sometimes challenging to setup:

• first, nginx dynamic modules are tied to very specific versions of nginx. We distribute per-compiled modules for the officially distribution-provided versions of nginx, but we cannot distribute a nginx module for each and every version of nginx available. In other words, the users of custom nginx installs will have to compile the nginx module themselves
• the nginx request management flow is not a quiet journey 🙂 In other words, depending on which modules are installed, unexpected behaviors may appear, and there is no way to guarantee that our module will perfectly integrate in your nginx install. For example, there might be incompatibilities with other modules
• nginx dynamic modules are developed using the C language, which does not guarantee memory-safety. The redirection.io agent itself, and the opensource libredirectionio underlying library, are Rust-based binaries
• updating a dynamic module requires a restart of the server, which is not always something that you want to do
• last and not least, using the redirection.io nginx module means that, for each and every request, a synchronous TCP call is performed from the nginx process to the redirection.io agent. We offer several tweaking directives to maintain a connection pool, and it will perfectly work on reasonnable traffic websites, but it can become a bit challenging to properly configure in highly demanding environments

This is why we usually recommend to rather use the reverse proxy mode. However, the nginx module is a perfectly convenient, supported, and fully tested way to use redirection.io if you wish so.

Insights and questions

Can I use the agent as a reverse proxy for several websites?

Yes, the agent has a multi-projects support. In other words, you can use the same redirection.io reverse-proxy process to manage the traffic of several websites deployed, on the same mutualized infrastructure (allthough you may want to separate stacks, but this is another consideration).

In this layout:

• the front reverse proxy receives http and https requests (on ports 80 and 443)
• depending on the domain of the request, it routes the requests to one of the redirectionio-agent exposed proxies (on ports 8080 or 8081)
• the proxies defined in the redirectionio-agent configuration forward the requests to their respective forward: destinations

How can I scale the agent?

The agent is very performant, but you will surely want to scale / mutualize / shard its usage across your servers. This can be simply done by launching several instances of the process.

In a static environment / servers layout, launching several times the redirectionio-agent is absolutely acceptable. Take care to give each instance a unique name, so you can recognize it afterwards in the "instances" screen of the manager graphical interface (and receive notifications if an instance is out of date).

Note that we provide an Ansible role to install and configure the agent.

In dynamic environments, it is also perfectly allowed to launch as many instances of the agent as you need, whenever traffic spikes appear. In order to set a unique name for each instance of the agent, remember that you can use environment variables in the agent configuration.

Using the redirection.io agent in a docker container

Of course, the redirection.io agent can be used in your local or production docker environment.

Add a new redirectionio-agent service with docker-compose:

volumes:
    redirectionio-data: {}

services:
  application:
    # your application service
    
  redirectionio-agent:
    build: services/redirectionio-agent
    ports:
      - "127.0.0.1:8443:443"
      - "127.0.0.1:8080:80"
    volumes:
      - redirectionio-data:/var/lib/redirectionio
    environment:
      - INSTANCE_NAME=${REDIRECTIONIO_INSTANCE_NAME}
      - REDIRECTIONIO_PROJECT_KEY=${REDIRECTIONIO_PROJECT_KEY}

Define the corresponding service in its Dockerfile, in services/redirectionio-agent/Dockerfile :

FROM alpine:3.17 as alpine

WORKDIR /tmp

RUN apk add --no-cache wget ca-certificates \
    && wget https://packages.redirection.io/dist/stable/2/any/redirectionio-agent-latest_any_amd64.tar.gz \
    && tar -xzvf redirectionio-agent-latest_any_amd64.tar.gz

FROM scratch

# Binary copied from tar
COPY --from=alpine /tmp/redirection-agent/redirectionio-agent /usr/local/bin/redirectionio-agent

# Configuration, can be replaced by your own
COPY etc /etc

# Root SSL Certificates, needed as we do HTTPS requests to our service
COPY --from=alpine /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# Cache storage for rules
VOLUME /var/lib/redirectionio

CMD ["/usr/local/bin/redirectionio-agent"]

Also, set the redirection.io configuration in services/redirectionio-agent/etc/redirectionio/agent.yml:

instance_name: "${INSTANCE_NAME}"

proxies:
  -
      listen: 0.0.0.0:80
      forward: http://application:80
      project_key: "${REDIRECTIONIO_PROJECT_KEY}"
  -
      listen: 0.0.0.0:443
      forward: https://application:443
      project_key: "${REDIRECTIONIO_PROJECT_KEY}"
      tls_cert_file: "/etc/ssl/certs/ssl-cert-snakeoil.pem"
      tls_key_file: "/etc/ssl/private/ssl-cert-snakeoil.key"
      allow_invalid_certificates: true
      preserve_host: true

This file uses two environment variables (REDIRECTIONIO_PROJECT_KEY and INSTANCE_NAME) that are passed by docker. Set the according values in a .env file:

REDIRECTIONIO_INSTANCE_NAME=docker dev env
REDIRECTIONIO_PROJECT_KEY=YOUR PROJECT KEY HERE

A complete docker example is available.

How to monitor the redirection.io agent

As a reverse proxy, the redirection.io agent is a piece of software that you will want to cautiously monitor. It provides an embedded monitoring endpoint which exposes several health-metrics.

Expected performance

The redirection.io reverse proxy is highly performant. We do not provide numbers, but it strongly outperforms mainstream market webservers to run redirections under high load and/or with a large number of configured redirection rules.

See our documentation page about performance for more detail.