Configure FastCGI for Apache 2.4

For Apache 2.4, you configure FastCGI to connect to the GAS using the mod_proxy_fcgi module. If authorization is used, configure a rewrite rule.

About this task:

Warning: Apache configuration subject to change

Configuration instructions provided in this page will probably work in the majority of situations, but sometimes they may require adaptation depending on the version of Apache you have. Therefore, we recommend that you refer to the Apache documentation (external link) if you need to know about specific configuration options. In production environments, the configuration of the Apache HTTP server should be carried out by a system administrator to avoid security issues.

In this page, there are details for configuring FastCGI when Apache is on the same server as the GAS or on an external machine.

If you are using authorization headers, go to Create a configuration for the GAS with a rewrite-rule for authorization headers.

Module mod_proxy_fcgi is the FastCGI Apache module to use for Apache 2.4. This module requires GAS 2.50 or later. Apache 2.4 does not officially support the mod_fastcgi module used in earlier Apache versions. For more information on Apache modules, refer to the Apache documentation (external link).

Steps to configure Apache to connect to a GAS

Find the Apache configuration file (for example, httpd.conf). It is likely to be located in the /etc/apache2/ path.
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
```
Create a configuration for the GAS based on the version of Apache 2.4 you have:
- For Apache 2.4.11 and later, add this configuration:
  These directives typically need to be added to your virtual host configuration (identified by the element <VirtualHost>) for both HTTP and HTTPS. An example configuration for HTTP is shown.
```
...
<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 in this sample:
  1. The proxy-fcgi-pathinfo=unescape setting sets the PATH_INFO environment variable with the path component of the URL and ensures application URLs and filenames with non-ASCII characters or spaces are decoded correctly.
    Important:
    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.
  2. In the ProxyPass setting:
    - /gas/ directory is just a virtual directory, no need to create one.
    - fcgi://localhost:6394/ means the fastcgidispatch dispatcher is running on the localhost and is listening on port 6394. If the GAS is running on an external server, the format is similar: fcgi://gas-server-ip:gas-server-port/.
    - The enablereuse=on setting enables the recycling of connections to the FastCGI dispatcher.
      Important:
      Starting with Apache 2.4.11 the enablereuse=on option in the ProxyPass must be added to recycle connections to the FastCGI dispatcher.
    - timeout=100. To avoid request timeout issues, set the ProxyPass timeout greater than the REQUEST_RESULT GAS configuration. For instance, if REQUEST_RESULT is set to 45 seconds (default setting), set the timeout higher at 100 seconds.
- For Apache versions prior to 2.4.11, add this configuration:
  These directives typically need to be added to your virtual host configuration (identified by the element <VirtualHost>) for both HTTP and HTTPS. An example configuration for HTTP is shown.
```
...
<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 this sample:
  1. The proxy-fcgi-pathinfo=1 sets the PATH_INFO environment variable with the path component of the URL.
  2. In the ProxyPass setting:
    - /gas/ directory is just a virtual directory, no need to create one.
    - fcgi://localhost:6394/ means the fastcgidispatch dispatcher is running on the localhost and is listening on port 6394. If the GAS is running on an external server, the format is similar: fcgi://gas-server-ip:gas-server-port/.
    - timeout=100. To avoid request timeout issues, set the ProxyPass timeout greater than the REQUEST_RESULT GAS configuration. For instance, if REQUEST_RESULT is set to 45 seconds (default setting), set the timeout higher at 100 seconds.
Start fastcgidispatch in standalone mode with fastcgidispatch -s. If this dispatcher fails, it must be restarted manually.
Changes to the Apache configuration file requires a restart of the dispatcher.

Create a configuration for the GAS with a rewrite-rule for authorization headers

Before you begin:

If your applications use authorization headers, the configuration will require a RewriteRule because Apache will discard the authorization header if it is not a base64-encoded user/password combination. For more information on rewrite rules, refer to the Apache 2.4 documentation (external link).

Tip: Configure Apache to pass the authorization header

As Apache configuration may vary from version to version, you may need to select one of these methods to pass the authorization header:

You can configure a rewrite rule as shown (this is the method used in this task):

# Requires mod_rewrite module
RewriteEngine on
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

Or you can configure a rewrite rule, by defining a condition under which rewriting takes place using RewriteCond:

# Requires mod_rewrite module
RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [E=HTTP_AUTHORIZATION:%1]

Or, if you have SetEnv module enabled, you can use SetEnvIf:

# Requires SetEnv module
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

Steps to configure Apache to connect to a GAS

Find the Apache configuration file (for example, httpd.conf). It is likely to be located in the /etc/apache2/ path.
Ensure the modules mod_proxy, mod_proxy_fcgi, and mod_rewrite 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
LoadModule rewrite_module modules/mod_rewrite.so
```
Create a configuration for the GAS.
These directives typically need to be added to your virtual host configuration (identified by the element <VirtualHost>) for both HTTP and HTTPS. An example configuration for HTTP is shown.
```
...
<VirtualHost _default_>
  
  <IfModule proxy_fcgi_module>
    ...
    # Unescapes the path component of the request URL
    SetEnvIf Request_URI . proxy-fcgi-pathinfo=unescape

   
    RewriteEngine on
    # Recreates the authorization header from the %{HTTP:Authorization} variable
    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>
... 
```
Where in this sample:
1. The proxy-fcgi-pathinfo=unescape setting sets the PATH_INFO environment variable with the path component of the URL and ensures application URLs and filenames with non-ASCII characters or spaces are decoded correctly.
  Important:
  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.
2. RewriteEngine is set to on.
3. A RewriteRule sets the environment variable, HTTP_AUTHORIZATION, with the value from the authorization header.
4. In the ProxyPass setting:
  - /gas/ directory is just a virtual directory, no need to create one.
  - fcgi://gas-server-ip:gas-server-port/ maps the FastCGI server to the GAS URL space.
  - The enablereuse=on setting enables the recycling of connections to the FastCGI dispatcher.
  - timeout=100. To avoid request timeout issues, set the ProxyPass timeout greater than the REQUEST_RESULT GAS configuration. For instance, if REQUEST_RESULT is set to 45 seconds (default setting), set the timeout higher at 100 seconds.
5. A ProxyPassReverse directive can be set 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 directives, refer to Apache 2.4 documentation (external link).
Start fastcgidispatch in standalone mode with fastcgidispatch -s. If this dispatcher fails, it must be restarted manually.
Changes to the Apache configuration file require a restart of the dispatcher.