Usage with HTTP Server
In most environments you will want your OpenWGA server to not directly serve requests to clients but to have a HTTP server which handles requests and passes those on to OpenWGA/Tomcat which are intended for it. Reasons for this architecture may be:
- You cannot run OpenWGA/Tomcat on your system so it can serve on HTTP(S) default ports 80/443, which is true for most Linux systems
- You want to host other non-OpenWGA sites/offerings along with your OpenWGA web apps
- You need a special feature of your HTTP server unavailable in OpenWGA, like custom redirection rules etc.
While it is beyond the scope of this documentation to aid in the configuration of a HTTP server we want to offer some best practices here on what to use and how to connect it to OpenWGA.
We recommend using Apache HTTP Server of version 2.2 or higher with OpenWGA and to use the Apache modules mod_proxy and mod_proxy_ajp to connect both. AJP stands for "Apache JServ Protocol" and is a special protocol invented by Apache for the Communication between a HTTP server and an Application server. These would be the steps to setup the connection.
1. Enable AJP connector for OpenWGA/Apache Tomcat
First you need to setup the OpenWGA-side of communications. For that you need to edit the file "server.xml" of the Apache Tomcat Application Server. If you installed OpenWGA via debian packages you will find it here:
If you used the OpenWGA linux installer the path would be:
In this file find the following XML tag and ensure that it is not commented out. If it does not exist you should insert it anywhere inside tag <Service name="Catalina">:
<Connector port="8009" protocol="AJP/1.3" ... />
Additional attributes may exist on the tag, like f.e. "redirectPort" which can be kept if they serve a purpose but whose discussion is beyond this documentation.
We also recommend adding the following XML attributes to the Connector tag:
- connectionTimeout="milliseconds" - Some timeout that will cancel a connection after some time if no URI is given by the HTTP server. This also will set the time this connection will be kept alive while no request data is transmitted Choose a value that will not cancel regular requests but will be able to react on errors (for example 30000 for 30 seconds)
So the tag may look like this in the end:
<Connector port="8009" protocol="AJP/1.3" connectionTimeout="30000" />
You need to restart Tomcat/OpenWGA for this to become effective
2. Enable modules mod_proxy and mod_proxy_ajp
Commands for enabling these modules are already present on most Apache installations by may need to be enabled. However the ways these are enabled differ:
- Debian-based Linux installations have directories "mods-available" and "mods-enabled". The first contains enablement scripts for all available modules, the second one contains symbolic links to the scripts of the first for all those modules that are actually enabled. So to enable a module you need to create a symbolic link in "mods-enabled" to the module script from "mods-available". However Debian has a console command "a2enmod" for doing this in a controlled way. To enable both modules you would run:
- Many other installations have directives to load all modules in the main configuration file "/etc/apache2/apache2.conf", of which most are simply commented out. You need to remove the "#" command character before the directives for both modules, which might look like this:
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_ajp_module /usr/lib/apache2/modules/mod_proxy_ajp.so
3. Configure the Proxy connection
In the Virtual Host Definition of Apache which represents your website you need to use the directive "ProxyPass" to actually enable the connection between Apache and Tomcat:
ProxyPass / ajp://localhost:8009/ nocanon
This will pass on all requests to the AJP connector of tomcat. The "nocanon" parameter prevents URL decoding done by ProxyPass as OpenWGA does this itself and "double decoding" URLs may cause problems.
Additional parameters that may be of use here are:
- disablereuse=on - Will disable connection pooling. This may be helpful if very many ProxyPass directives are used (of which each has a separate connection pool if its path is not contained in another ProxyPass directive) to avoid the pooling footprint or if pooling is misbehaving in some way.
- timeout=seconds - Will set the timeout that the connection is held without any communication. This timeout is normally 5 minutes which may be too long to react on problems in time.
If you need to exclude special paths from the connection you can add ProxyPass directives with a "!" character instead of the AJP URL. These need to be specifiied BEFORE the actual ProxyPath directive to become effective. For example:
ProxyPass /server-status !
ProxyPass / ajp://localhost:8009/ nocanon
This will pass on all requests to tomcat but leave out requests to path "/server-status" (on which the Apache module "status" serves its status screen) which are still handled by Apache internally.
After this you need to let Apache reload its configuration or restart it for the changes to become effective.