Manual Reference Pages  - XSREDIR (5)


.redir - XS-httpd HTTP redirection file


     Simple Redirect
     Directory Redirect
     Regular Expression Matching
See Also


The .redir and *.redir files tell the xs-httpd webserver to redirect the client to an alternative location when it attempts to retrieve a certain resource.

    Simple Redirect

A simple HTTP redirect message will be sent when the client requests a resource for which a file with the *.redir or *.Redir postfix exists.
  If a (regular) file is requested and a file exists with the same name but with .redir’ appended to it, the requested file will not be sent. Instead, the server will send a redirection message to the remote user client. The redirected location is retrieved from the *.redir file. This file should contain (only) one absolute URL. It does not matter if the file that was requested by the client actually exists or not.
  The same as *.redir, however instead of a temporary redirection (302) a permanent redirection (301) will be sent. Users probably won’t notice any difference, but it should keep robots from keep on using the old address.

    Directory Redirect

If a file named .redir is present in a certain directory, and any file is requested from that directory, then a redirection message will be sent to the remote user’s browser. It works simply by substituting the server name and the directory that the remote user to get to this file by the contents of the file. This way, an entire directory can be automatically be redirected.

    Regular Expression Matching

If PCRE (perl-compatible regular expression) support is compiled in, then more flexible redirection rules can be written. The .redir file may contain multiple redirection commands. These commands may use several types: pass, passexist, redir, Redir, rewrite or forward.

The expression that must be matched by the given PCRE is the full local request path (basically the URL without hostname, for example /~username/foo/bar.html). This expression is the same regardless of the location of the redir file (either in the user’s webroot or the foo subdirectory).
pass oldurl
  If the requested URL matches the oldurl regular expression then no redirection action will be taken. The file will be retrieved as normal and if the corresponding file does not exist, this may even lead to a 404 Not Found error. This command may be useful since .redir files are parsed line by line and the first matching directive will be executed. If the pass command matches, the rest of the redir file will be ignored.

The pass directive may be used without argument, in which case it effectively aborts processing of the redir file and returns without any redirection. This could be useful within an ifenv block.

  This expression will match if the requested URL matches a file that exists on disk. In this case no further rules will be processed and the file will be retrieved as normal. This is a shortcut notation to making a pass rule for every existing file in the directory.
passenv envvar value
  The passenv directive can be used to write conditional passes. In this expression envvar should be the name of a CGI environment variable (e.g. HTTPS) and value is a regular expression to be matched. If the environment variable is set and actually matches the given value, then no redirection action will be taken.
redir oldurl newurl
  The requested URL is matched against the oldurl expression. If this matches, the client will be redirected to the newurl location. This location may contain string substitutions. If the .redir file contains multiple matching URLs, the first match will be used for redirection. The resulting URL should be an absolute URL including protocol, hostname and path.
Redir oldurl newurl
  This directive is similar to the redir command. But rather than a temporary redirect, a permanent redirect (301) will be generated.
rewrite oldurl newurl
  In this case the same matching sceme as for redirects will be used, but rather than generating a redirect, the webserver will try to resolve the filename itself and dispay the resolved file directly. Note that unlike the redir commands, it is not allowed to generate full URL’s in this case: only local URL’s are permitted (omitting the protocol and hostname).
forward oldurl newurl
  If the webserver has been compiled with forwarding support (curl), then one can also use forward directives. Forwarding behaves transparently (like rewrite), but in this case the webserver will retrieve the resulting file from a remote webserver.

URL matching and rewriting works the same as for the redir command. The resulting URL must be an absolute URL including protocol, hostname and path.

Note that forwarding unencrypted requests to a https location or encrypted requests to a plain-text http location may lead to a false sense of security. Use forwards with care.

proxy oldurl newurl
  Proxy request by sending it on to another server and returning its response to the client. This is basically the same as forward and also only works if forwarding support is compiled in. At the moment the only real difference is that with the proxy directive, all responses will include a Via header identifying this webserver as the forwarding proxy.
error statuscode pattern [description]
  If the request matches the regilar expression pattern, then the user will be presented with an HTTP error. The error codes in the 4xx and 5xx range are valid for this operation. An error description is optional.
ifenv envvar value
  The ifenv directive can be used to write conditional redirects. In this expression envvar should be the name of a CGI environment variable (e.g. REMOTE_HOST) and value is a regular expression to be matched. If the environment variable is set and actually matches the given value, then the following block of redirect statements will be executed. If there is no match, then everything up to the next empty line (or end of file) will be ignored.

Refer to httpd_cgi(7) for a list of all environment variables that may be checked in this way. Note that if a block contains multiple ifenv statements, then the following redirect rules will only be executed if all variables match their respective values.


A common way to show information from a database is to have a single CGI handle all requests while pretending every page has its own html file:
rewrite /~user/wiki/(.*)\.html$ /~user/cgi-bin/wiki.cgi?page=\1

To have all pages (except CGI binaries) temporarily served from another machine, use something like:

pass    cgi-bin
redir   ^/~user/(.*)$\1

Instead of redir, one might use forward here instead. In that case the end-user will not be aware that information is retrieved from another webserver. This is useful if the other server is only accessible from the internal network (e.g. a local Tomcat server).


httpd(1), pcrepattern(3), xsconf(5)

The project homepage:

December 17, 2006 XSREDIR (5) xs-httpd/3.5