mod_urlscheme is an Apache 1.3/2.0/2.2 module that allows the Apache configuration author control over the scheme to use when constructing self-referential URLs.
Please note that this module is different from mod_scheme, which embeds the Tinyscheme interpreter into Apache. You can find that module here. I changed the name from mod_scheme to mod_urlscheme to avoid confusion.
The original module was only written to work on Apache 2.0. There is now also a version for Apache 1.3 + EAPI, although it won't work with stock 1.3. Please see the "Apache 1.3" section at the bottom of this page for details. The 2.0 module will work almost unchanged on Apache 2.2. There is a small naming change in the API that requires a slightly different version.
In several situations, Apache will attempt to construct a URL that will point to itself and will deliver the result to the client. The most notable occasion for this is when Apache is constructing a client redirect. This can for example happen when the client requests a URL that maps to a directory but doesn't include a trailing slash: Apache will send back a redirect to the same URL, but with a trailing slash appended. Other occasions include Redirect directives in the Apache configuration, or mod_proxy rewriting redirects coming from a backend server (when mod_proxy is functioning as a reverse proxy).
A self-referential URL has four distinct major components: the scheme, the hostname, the port number and the request URI, the latter including perhaps a query string and a fragment identifier. The combination of ServerName, UseCanonicalName and the use of the client's HTTP Host header allows an Apache administrator full control over the hostname and port number part of the generated URLs, but the scheme is up to Apache itself.
Normally, the scheme is always "http". A module such as mod_ssl will override this and set the scheme to "https" for those locations where it is active. But that doesn't help you when the Apache server is behind another server that will handle the HTTPS traffic for you. Imagine the following layered approach:
· The client's HTTPS request comes in to the first machine on port 443 (the default port for HTTPS). The first machine, which perhaps has dedicated hardware to speed up SSL processing, accepts the connection and provides for all the encryption/decryption. It forwards the decrypted request as a regular HTTP request to port 81 on the next machine.
· The second machine runs Apache. It will be listening on ports 80 and 81. It will receive the request from the first machine on port 81. The fact that it's coming in on that port establishes the request as being secure, and Apache may provide different processing rules depending on whether the request is secure or not. (Of course, the Apache server should be behind a firewall, so a client can't connect to port 81 directly and circumvent the access controls.)
Now, if Apache for some reason needs to generate a redirect, the scheme on the redirect URL will be "http", because that's what Apache is serving. But that URL isn't valid on the outside: the scheme should be "https", so that the client will proceed to get the new URL from the same secure location.
One solution is to let the machine that handles the SSL work do the rewrite from http://www.example.com:81/ to https://www.example.com/. But that doesn't help you if the first machine is (for example) a dumb SSL tunnel that doesn't understand HTTP. In that case, Apache will need to be convinced its scheme is actually "https", not "http".
That's where mod_urlscheme comes in.
These instructions assume a Unix installation. For other systems, please consult the Apache documentation. mod_urlscheme is a very simple module that requires no special treatment. Simply put, if you can build mod_example from the stock Apache tree, then you can build mod_urlscheme as well.
Put the downloaded mod_urlscheme.c file in a temporary directory somewhere where you will compile it.
If you want to include mod_urlscheme as a static module in your Apache server, prepare your Apache source directory as per the Apache build instructions. When calling the ./configure command, include the option --with-module=experimental:/path/to/mod_urlscheme.c (for Apache 1.3: --add-module=/path/to/mod_urlscheme.c). You need to specify the full path to the source file after the colon. Then, proceed with the build instructions as you would normally. The module will be included in your Apache binary as a static module.
For a dynamic module, first install a full Apache distribution, including the apxs tool and the C headers. If you install from pre-packaged bundles, such as RPMs, you may need to separately install the development package. On RPM-based systems that usually means you need to have the httpd-devel package installed. You will also need a fully functional compiler suite installed.
Go to the directory where you put the mod_urlscheme.c file and run apxs -c mod_urlscheme.c. Refer to the Apache documentation to see if you need to specify more command line options for your system.
If the compile succeeded, you will now have a dynamic Apache module ready to use. You may need to look in the .libs subdirectory to find the actual mod_urlscheme.so file (under Unix, that is). Copy the module to the Apache module directory, which is the modules subdirectory of the server root (for Apache 1.3: the libexec subdirectory). Alternatively, you can put it in any other location; just make a note of where you put it, so you can refer to the location later on.
· EAPI (only for 1.3 version)
· EAPI (only for 1.3 version)