XSREDIR(5) BSD File Formats Manual XSREDIR(5)NAME
.redir — XS-httpd HTTP redirection file
DESCRIPTION
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.
*.redir
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 abso‐
lute URL. It does not matter if the file that was requested by
the client actually exists or not.
*.Redir
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 con‐
tain 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 sub‐
directory).
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 with‐
out any redirection. This could be useful within an ifenv block.
passexist
This expression will match if the requested URL matches a file
that exists on disk. In this case no further rules will be pro‐
cessed 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 loca‐
tion. 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-301 oldurl newurl
This directive is similar to the redir command, but performs re‐
direction using the HTTP status 301 (Moved Permanently).
redir-302 oldurl newurl
This directive is similar to the redir command, but performs re‐
direction using the HTTP status 302 (Found).
redir-303 oldurl newurl
This directive is similar to the redir command, but performs re‐
direction using the HTTP status 303 (See Other).
redir-307 oldurl newurl
This directive is similar to the redir command, but performs re‐
direction using the HTTP status 307 (Temporary Redirect).
redir-308 oldurl newurl
This directive is similar to the redir command, but performs re‐
direction using the HTTP status 308 (Permanent Redirect).
Redir oldurl newurl
This directive is deprecated and will be removed in future ver‐
sions. It is identical to the redir-301 command.
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 permit‐
ted (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 web‐
server will retrieve the resulting file from a remote webserver.
URL matching and rewriting works the same as for the redir com‐
mand. The resulting URL must be an absolute URL including proto‐
col, 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 web‐
server 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 descrip‐
tion 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 every‐
thing 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.
EXAMPLES
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/(.*)$ http://www.example.org:8080/~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).
SEE ALSOhttpd(1), pcrepattern(3), xsconf(5)
The project homepage: http://www.xs-httpd.org/
xs-httpd/3.5 December 17, 2006 xs-httpd/3.5
