Create your first redirections

This knowledge base article explains how to start creating a redirection plan using On this page, you will learn :

  • how to create 1:1 redirects
  • how to create redirection rules to bulk-redirect URLs
  • how to manage priorities across redirections

This tutorial assumes that you have installed a working instance of If it is not yet the case, you can either read our install documentation, learnhow to setup on Azure Cloud, or use our open source Docker example.

Create a first redirection on your website

We are going to create a first redirection rule, as explained in our documentation.

  1. The empty redirects listIn the "rules" menu, hit the "Create a new rule" link
  2. In the "Source URL" field, type /test. This means that this rule will be triggered (executed) every time an incoming request has the /test path. There are several other triggers that allow to narrow the matching of incoming requests, but for now we will continue with this simple rule.
  3. redirection examplesHit the "Next" button. The second step allows to create example requests for this rule. Examples are useful, because they help make sure that the rule behaves exactly as you expect it. Of course, for the moment this is the only rule (and its trigger is very simple), but when a redirection plan ages, it can get really complicated to understand how rules are applied, in which order, and check that adding a new rule will not break already redirected URLs.
  4. adding a redirect actionThe "Actions" step allows to define which actions have to be executed when this rule is triggered by a request. Choose the "Redirection" action, enter a target URL, and hit the "Next" button
  5. rule impactThe final step, named "Impact", explains how this rule behaves on the examples created during the second step. You can get detailed information, for each example, by clicking on its line.
  6. If the behavior seems correct, bit the "Save this rule" button

The rule is now created, and the last step is to publish the ruleset to have it applied to your server. Look at the orange bar at the top of the screen: click on the "Publish changes" button, the "Publish this version".

After some time, the published ruleset will be applied on your server. The delay before the rules are applied is about 20 seconds. You can also restart the redirectionio-agent service, as the agent tries to load rules when it is restarted:

sudo systemctl restart redirectionio-agent

Open the url http://<IP ADDRESS OF YOUR SERVER>/test, and you should get redirected to /other-url (or the target that you have defined in the rule).

Configure alternate domain(s)

The first step, in order to have a domain name managed using your brand new redirection service, is to target its DNS to the IP address of your server. In the DNS panel of your domain name registrar, change the A field and enter the public IP address provided by your hosting provider. Of course, you have to perform a similar step it if you want to redirect a subdomain. Say that you just configured the domain

Once the DNS propagation is complete, requests performed to your domain name will be handled by the redirection server. Go to : a redirection is made using the first rule created above. As this rule does not have a domain name, it will be applied to every incoming request, whatever the domain name, provided the path of the request is /test. Let's delete this rule, we do not need it anymore.

Create a new rule and click on the "Add marker" button, in the "Source URL" field. Markers are placeholders that can catch several strings based on conditions. Create a marker of the "anything" type:

redirection rule with an anything marker

Hit the "Next" button, and choose "HTTP 410 response" as the action to be executed. Go ahead, and save the rule. Publish the rule, and once it is applied to your production, you should get a "410 Gone" response for every request performed to the redirection server, whatever the requested URL.

a 410 Gone response

Now, we are going to explicitly allow your domain name to be redirected. Let's create a new rule. In the "Source URL" field, type ://, then add a "anything" marker:

redirection rule for one domain

Add and as examples (check the "must match" switch), and choose the "redirection" action. In the "Target URL" field, type the URL to redirect to. Save and publish the rule. Here is how the ruleset should look at that point:

two redirect rules

After a few minutes, try to load in your browser: you should be redirected to the domain entered in "Target URL".

I want to create deep redirections

We have not covered much of capacities until now. Try several expressions in the "Trigger" and "Action" sections to create specific redirections:

Source URL Target URL
://[ANYTHING] https://new-website/new-category-name/
:// https://new-website/landing-page
://[ANYTHING] https://new-website/[ANYTHING]


  • the first rule will redirect every request performed in http or https on the domain for every page under new-category-name/
  • the second rule will redirect every request performed in http or https on
  • the third rule will redirect every request performed in http or https on the domain for every page to the same path like the original request, but in https on the host new-website

Obviously, the second and third rules could collide, as both of their triggers match the incoming URL, for example. This is the reason why offers a "priority" feature. When editing a rule, you can define its priority: the higher the value, the higher the priority of the rule. Setting the priorities for your rules allow to create a deterministic redirection plan, which is obviously what one would want:

several rules with different priorities

However, when the redirection plan becomes larger, it can be hard to keep all priorities in mind. This is the reason why examples are so important; they help, at the rule level, check that the ruleset behaves correctly. See the "Impact" section for the third rule:

the impact allows to check is a redirection works correctly

Clicking on the example line opens an inspector lateral panel, which includes several tools:

  1. analyse if the current rule matches an example request"Current rule matching" explains if the currently edited rule matches the example request
  2. find which redirects of the ruleset match an example"Matched rules" lists all the rules that match this example request
  3. understand how the response is built"Detailed actions" give the cumulative detail of the actions performed by each rule, and help understand the expected response for this example request

The second tab is particularly useful in the case of examples that trigger several rules of the ruleset. In this case, you can move the position of the currently applied rule within the rules stack, which dynamically changes its priority in the ruleset and ensures a coherent state:

reordering rules

This page has been updated on March 28th, 2024.
Can't find your answer?