Apache 2.4: mod_proxy_fcgi

For Apache 2.4 you configure fastCGI with the mod_proxy_fcgi module. If authorization is used, configure a rewrite rule.

In this task you configure your Apache configuration file for mod_proxy_fcgi to connect to a GAS server. The GAS may be on a local or a remote machine.

Note: Assume the Genero Application Server is installed in the following directory (FGLASDIR): /opt/gas. Make the appropriate substitution for the FGLASDIR when applying these examples to your own configuration.

If you are using authorization headers, see the configuration example in the section Rewrite-rule for authorization headers.

Apache 2.4 does not officially support mod_fastcgi, use mod_proxy_fcgi instead. This module requires Genero Application Server 2.50 (or later). For more information on Apache modules, refer to the Apache documentation.

  1. Find the Apache configuration file (for example, httpd.conf). It is likely to be located in the /etc/apache2/ path.
  2. Ensure the modules mod_proxy and mod_proxy_fcgi are enabled.
    Check your Apache configuration file for the load module directives for these modules; bearing in mind that your configuration may be different. Make sure the hash symbol (#) is removed from the start of the line.
    LoadModule proxy_module modules/mod_proxy.so
    LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so
  3. Choose the configuration to add based on the version of Apache 2.4 you have:

    These directives typically need to be added to your GAS virtual host configuration (identified by the element <VirtualHost>) for both HTTP and HTTPS. An example configuration is shown.

    • For Apache version 2.4.11 and later, add this configuration:

      Note: Starting with Apache 2.4.11:
      • To ensure application URLs and filenames with spaces are decoded correctly, proxy-fcgi-pathinfo must be set to unescape. Apache will replace the hexadecimal characters in the URL or filename with the actual characters they represent using this directive. There is no PATH_INFO with mod_proxy_fcgi unless this is set.
      • Add the enablereuse=on option in the ProxyPass configuration line, in order to recycle connections to the fastcgi dispatcher.
      ...
      <VirtualHost _default_>
        <IfModule proxy_fcgi_module>
      
      
        # Unescapes the path component of the request URL 
        SetEnvIf Request_URI . proxy-fcgi-pathinfo=unescape
      
        # Maps the fastcgi server to the GAS URL space
        ProxyPass /gas/ fcgi://localhost:6394/ enablereuse=on timeout=100  
      
        # No alias 
        </IfModule>
      </VirtualHost >
      ... 
    • For Apache versions prior to 2.4.11, add this configuration:
      ...
      <VirtualHost _default_>
        <IfModule proxy_fcgi_module>
      
        # No PATH_INFO with mod_proxy_fcgi unless this is set 
        SetEnvIf Request_URI . proxy-fcgi-pathinfo=1
      
        # Maps the fastcgi server to the GAS URL space
        ProxyPass /gas/ fcgi://localhost:6394/ timeout=100
      
        # No alias 
       </IfModule>
      </VirtualHost >
      ... 
    Where in these sample excerpts:
    • fcgi://localhost:6394/ means the fastcgidispatch dispatcher is running on the localhost and is listening on port 6394. If the GAS is running on a remote server, the format is similar: fcgi://gas-server-ip:gas-server-port/.
    • /gas/ directory is just a virtual directory, no need to create one.
    • timeout=100. To avoid request timeout issues, set the ProxyPass timeout greater than the REQUEST_RESULT GAS configuration. If, for instance, REQUEST_RESULT is set to 45 seconds (default setting), you need to ensure you set the ProxyPass timeout higher at 100 seconds.
  4. Start fastcgidispatch in standalone mode with fastcgidispatch -s. If this dispatcher fails, it must be restarted manually.

Rewrite-rule for authorization headers

If you are using authorization headers, the module mod_rewrite must be enabled in your Apache configuration file. For example, the load module directive for this module must appear without the hash (#) at the start of the line:

LoadModule rewrite_module modules/mod_rewrite.so
Also you need to be aware of the following:
  • Authorization headers need to be base64 encoded. Apache discards the Authorization header if it is not a base64-encoded user/password combination. A rewrite rule (see Apache 2.4 documentation) can be used to rewrite it from the server variable.
  • A ProxyPassReverse directive can be set to adjust or rewrite URLs in response headers before forwarding them on to the client. For example, if an authorization request causes a redirect to an authentication server, Apache adjusts this URL to the local URL before forwarding the HTTP redirect response to the client.

    For more details on Apache, see Apache 2.4 documentation.

    An example configuration is shown:

...
<VirtualHost _default_>
  
  <IfModule proxy_fcgi_module>
    ...
    # Unescapes the path component of the request URL
    SetEnvIf Request_URI . proxy-fcgi-pathinfo=unescape

    # Recreates the authorization header from the %{HTTP:Authorization} variable
    RewriteEngine on
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Maps the fastcgi server to the GAS URL space
    ProxyPass /gas/ fcgi://gas-server-ip:gas-server-port/gas/ enablereuse=on timeout=100
    
    # Rewrites URL in response headers
    ProxyPassReverse /gas/ http://gas-server-ip:gas-server-port/gas/
    # No alias
  </IfModule>

</VirtualHost>
...