Configure FastCGI for Apache 2.4

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

Follow this procedure to configure Apache to use the mod_proxy_fcgi module 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 the mod_fastcgi module; use the mod_proxy_fcgi module instead. This module requires GAS 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 2.4.11 and later, add this configuration:

      ...
      <VirtualHost _default_>
        <IfModule proxy_fcgi_module>
      
        # No PATH_INFO environment variable with mod_proxy_fcgi unless this is set 
        # 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 >
      ... 
      Where:
      • The proxy-fcgi-pathinfo=unescape setting ensures application URLs and file names with non-ASCII characters or spaces are decoded correctly.
        Note:

        Starting with Apache 2.4.11, proxy-fcgi-pathinfo must be set to unescape. There is no PATH_INFO environment variable with mod_proxy_fcgi unless this is set.

      • The enablereuse=on setting in the ProxyPass enables the recycling of connections to the fastcgi dispatcher.
        Note:

        Starting with Apache 2.4.11 the enablereuse=on option in the ProxyPass must be added to recycle connections to the FastCGI dispatcher.

    • For Apache versions prior to 2.4.11, add this configuration:
      ...
      <VirtualHost _default_>
        <IfModule proxy_fcgi_module>
      
        # No PATH_INFO environment variable 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 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
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>
...