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.
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
- it can be monitored using the agent metrics endpoint
- as any reverse-proxy, it is scalable, by launching more instances of the agent
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.
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 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
- it forwards these requests to a locally-available nginx server, on port
- 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 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.):
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.
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
httpsrequests (on ports
- depending on the domain of the request, it routes the requests to one of the redirectionio-agent exposed proxies (on ports
- the proxies defined in the redirectionio-agent configuration forward the requests to their respective
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.
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:
# your application service
Define the corresponding service in its Dockerfile, in
FROM alpine:3.17 as alpine
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
# 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
Also, set the redirection.io configuration in
This file uses two environment variables (
INSTANCE_NAME) that are passed by docker. Set the according values in a
REDIRECTIONIO_INSTANCE_NAME=docker dev env
REDIRECTIONIO_PROJECT_KEY=YOUR PROJECT KEY HERE
A complete docker example is available.
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.
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.