Documentation

Handler: Redirection

The main idea of a redirection is telling the web client to go to another URL when the requested URL matches a rule. It could happen that this is not precisely what you are looking for. Check the reverse proxy handler if you are looking for more complex layer 7 operations. However, for URL redirections this handler is the place to go. A very common scenario would be rewriting URLS.

Lets suppose you have URLs like 
    http://example.com/inst/photogallery/viewphoto?photoid=1235
    http://example.com/inst/photogallery/viewcomments?photoid=1235
    http://example.com/inst/photogallery/admin?photoid=1235&method=delete
You probably would prefer URLs like 
    http://example.com/photo/1235
    http://example.com/photo/1235/cmts
    http://example.com/photo/1235/delete

Parameters

This directive uses PCRE (Perl Compatible Regular Expressions) to make the substitution.

  • Type: [External | Internal]

    • Internal: The redirection will happen internally, hence the internal URL in which the address is translated will be invisible for the client.

    • External: It works in the same way as the previous one, but in this case, it will redirect the connection to the new resource.

  • Regular Expression and Substitution are the matching request and the intended target of such petition. Getting into details of regular expressions is out of the scope of this document. Besides, there are many Perl regular expressions references. Macros can be used for these substitutions, which is specially handy for some cases that cannot be covered any other way, such as uniformly managing virtual servers with multiple matches. Take a look at the examples at the end of this section for further clarification.

    Variable Example Description

    ${host}

    example.com

    Host of the matching virtual server

    This macro uses the standard template subsystem , which provides slicing support. You should read more about this powerful feature if you are not already familiar with it.

The maximum allowed number of substitutions on an expression is limited to 20, and even though it could be raised even more, this wouldn’t actually make any difference for any real-life case.

Virtual hosts and redirections

The internal redirections, using the internal keyword, are limited to work in the same virtual host. All the internal redirections will be processed in the original virtual host, which makes a lot of sense in terms of security.

In case you do need to redirect a resource to another virtual host and/or domain, you will have to use an explicit redirection using the external keyword.

The influence of the rule type

Any rule type can be used with the redirection handler: Directory, Extensions, Regular Expression, etc. Only the case where the type is Regular Expression will require some more extra information. Because of Cherokee’s design, modularity and inheritance is heavily used throughout the code base. This one is a special case because the regex entry of the redirection handler can be empty whenever the matching rule used is a regular expression (because it is inherited by it).

The logic behind this is that you can set up a regular expression to match the rule, but once you’re in the redirection handler you could or could not be needing another matching to be performed. If not, the original one (the one from the rule) will be enough. If you do, you can specify a completely different expression to be matched. For instance, you could match the rule taking just the beginning part of the request as meaningful, and once you are into the handler you might want to consider just the end of it before making the substitution.

Examples

This example will perform internal redirections:

Regular Expression Substitution

/(\d+)$

http://example.com/inst/photogallery/viewphoto?photoid=$1

/(\d+)/cmts

http://example.com/viewcomments?photoid=$1

/(\d+)/delete

http://example.com/inst/photogallery/admin?photoid=$1&method=delete

/https_redir/(\d+)

Which would translate into the following redirections for the listed matching requests:

Request Internal translation

/photo/123

http://example.com/inst/photogallery/viewphoto?photoid=123

/photo/213/cmts

http://example.com/viewcomments?photoid=213

/photo/501/delete

http://example.com/inst/photogallery/admin?photoid=501&method=delete

/https_redir/555

https://example.com/secure?photoid=555

You might also want to check out the cookbook entry titled HTTP to HTTPS on how to redirect all traffic from HTTP to HTTPS.

Global redirections

If you want to implement global redirections that can be defined once and apply to every virtual server on your configuration, you will also have to perform matches against the host part of the request. This can be done by creating an additional virtual server using "Regular Expression" as method to match the host, which can be specified through the the Host Match tab. You will then have to define a substitution that uses both type of regex matches:

Match groups

^1,^2,^3,..

These are substituted by the host name match.

$1,$2,$3,..

These are substituted by either the handler match (if any) or its own match groups.

For more information, check out the practical example in the cookbook describing how to implement global redirections.