How To Configure Apache Content Caching on CentOS 7

Authentication caching is useful if you are using an expensive authentication method, such as LDAP or database authentication. These types of operations can have a significant impact on performance if the backend must be hit every time an authentication request is made.

Setting up caching involves modifying your existing authentication configuration (we will not cover how to set up authentication in this guide). The modifications themselves will be much the same regardless of the backend authentication method. We’ll use mod_socache_shmcb for our demonstration. This module is already enabled in our /etc/httpd/conf.modules.d/00-base.conf file.

Open your main Apache configuration file so that you can specify this shared cache backend for use with authentication:

sudo nano /etc/httpd/conf/httpd.conf

Inside, towards the top of the file, add the AuthnCacheSOCache directive. Specify that shmcb should be used as the provider. If the bug discussed earlier preventing option passing is fixed by the time you read this, you can specify a location and size for the cache. The number is in bytes, so the commented example will result in a 512 kilobyte cache:

AuthnCacheSOCache shmcb

# If the bug preventing passed arguments to the provider gets fixed,
# you can customize the location and size like this
#AuthnCacheSOCache shmcb:${APACHE_RUN_DIR}/auth_cache(512000)

Save and close the file when you are finished.

Next, open your virtual host configuration page that has authentication configured. We’ll assume you’re using a virtual host config called site.conf located within the /etc/httpd/conf.d directory, but you should modify it to reflect your environment:

sudo nano /etc/httpd/conf.d/site.conf

A basic virtual host set up with authentication may look something like this:

<VirtualHost *:80>
    ServerName server_domain_or_IP
    DocumentRoot /var/www/html

    <Directory /var/www/html/private>
        AuthType Basic
        AuthName "Restricted Files"
        AuthUserFile /etc/httpd/.htpasswd
        AuthBasicProvider file
        Require valid-user
    </Directory>
</VirtualHost>

In the location where you’ve configured authentication, modify the block to add caching. Specifically, you need to add the AuthnCacheProvideFor to tell it which authentication sources to cache, add a cache timeout with AuthnCacheTimeout, and add socache to the AuthBasicProvider list ahead of your conventional authentication method. The results will look something like this:

<VirtualHost *:80>
    ServerName server_domain_or_IP
    DocumentRoot /var/www/html

    <Directory /var/www/html/private>
        AuthType Basic
        AuthName "Restricted Files"
        AuthUserFile /etc/apache/.htpasswd
        AuthBasicProvider socache file
        AuthnCacheProvideFor file
        AuthnCacheTimeout 300
        Require valid-user
    </Directory>
</VirtualHost>

The above example is for file authentication, which probably won’t benefit from caching very much. However, the implmentation should be very similar when using other authentiation methods. The only substantial difference would be where the “file” specification is in the above example, the other authentication method would be used instead.

Save and close the file. Check your changes for syntax errors by typing:

sudo apachectl configtest

If no syntax errors are found, restart Apache to implement your caching changes:

sudo systemctl restart httpd

The handshake that must be performed to establish an SSL connection carries significant overhead. As such, caching the session data to avoid this initialization step for further requests can potentially skirt this penalty. The shared object cache is a perfect place for this.

If you have SSL already configured for your Apache server, mod_ssl will be enabled (if not, use yum to install the mod_ssl module). On CentOS 7, this means that an ssl.conf file will be available in the /etc/httpd/conf.d directory. This actually already sets up caching. Inside, you will see some lines like this:

. . .

SSLSessionCache         shmcb:/run/httpd/sslcache(512000)
SSLSessionCacheTimeout  300

. . .

This is actually enough to set up session caching. To test this, you can use OpenSSL’s connection client. Type:

openssl s_client -connect 127.0.0.1:443 -reconnect -no_ticket | grep Session-ID

If the session ID is the same in all of the results, your session cache is working correctly. Press CTRL-C to exit back to the terminal.

The HTTP caching logic is available through the mod_cache module. The actual caching is done with one of the caching providers. Typically, the cache is stored on disk using the mod_cache_disk module, but shared object caching is also available through the mod_cache_socache module.

The mod_cache_disk module caches on disk, so it can be useful if you are proxying content from a remote location, generating it from a dynamic process, or just trying to speed things up by caching on a faster disk than your content typically resides on. This is the most well-tested provider and should probably be your first choice in most cases. The cache is not cleaned automatically, so a tool called htcacheclean must be run occasionally to slim down the cache. This can be run manually, set up as a regular cron job, or run as a daemon.

The mod_cache_socache module caches to one of the shared object providers (the same ones discussed in the last section). This can potentially have better performance than mod_cache_disk (depending on which shared cache provider is selected). However, it is much newer and relies on the shared object providers, which have the bugs discussed earlier. Comprehensive testing is recommended before implementing the mod_cache_socache option.

Apache’s HTTP cache can be deployed in two different configurations depending on your needs.

If the CacheQuickHandler is set to “on”, the cache will be checked very early in the request handling process. If content is found, it will be served directly without any further handling. This means that it is incredibly quick, but it also means that it does not allow for processes like authentication for content. If there is content in your cache that normally requires authentication or access control, it will be accessible to anyone without authentication if the CacheQuickHandler is set to “on”.

Basically, this emulates a separate cache in front of your web server. If your web server needs to do any kind of conditional checking, authentication, or authorization, this will not happen. Apache will not even evaluate directives within <Location> or <Directory> blocks. Note that CacheQuickHandler is set to “on” by default!

If the CacheQuickHandler is set to “off”, the cache will be checked significantly later in the request processing sequence. Think of this configuration as placing the cache between your Apache processing logic and your actual content. This will allow the conventional processing directives to be run prior to retrieving content from the cache. Setting this to “off” trades a bit of speed for the ability to process requests more deeply.

On a CentOS 7 system, the htcacheclean utility, which is used to pare down the cache as it grows, is installed during the httpd installation. A systemd unit file called htcacheclean.service is included by default.

If you plan on setting up caching, it is a good idea to configure this service to run automatically. The service file actually daemonizes the service, running the cleaning operation at a configurable interval. However, by default, there is not a mechanism for starting it when Apache starts.

To set this up, we’ll make a directory called httpd.service.requires within the /etc/systemd/system directory. This can be used to specify dependencies of the httpd.service unit file that starts Apache:

sudo mkdir -p /etc/systemd/system/httpd.service.requires

Afterwards, we can link the htcacheclean.service unit file into this directory. This will cause the htcacheclean service to start and clean the cache at regular intervals when Apache is started:

sudo ln -s /usr/lib/systemd/system/htcacheclean.service /etc/systemd/system/httpd.service.requires

You can configure the htcacheclean options, including the cleaning interval, by editing the htcacheclean file in the /etc/sysconfig directory:

sudo nano /etc/sysconfig/htcacheclean

Here, you can modify the cleaning interval, the cache root, the maximum cache size, and any other options for the utility:

INTERVAL=15
CACHE_ROOT=/var/cache/httpd/proxy
LIMIT=100M
OPTIONS=

When you are finished, save and close the file.

Restart Apache to start the htcacheclean to automatically clean the cache:

sudo systemctl restart httpd

Most of the configuration for caching will take place within individual virtual host definitions or location blocks. However, there are also some global configuration items that should be used to set up some general attributes. Open your main Apache config file to configure these items:

sudo nano /etc/httpd/conf/httpd.conf

We need to add the CacheRoot directory to point to the path that should be used to store our cached items. This should always match the CACHE_ROOT value found in your /etc/sysconfig/htcacheclean file so that the cache can be managed correctly. We will also set the CacheDirLevels and CacheDirLength directives, which both contribute towards defining how the cache directory structure will be built:

CacheRoot /var/cache/httpd/proxy
CacheDirLevels 2
CacheDirLength 1

The CacheDirLevels and CacheDirLength both contribute towards defining how the cache directory structure will be built. An md5 hash of the URL being served will be created as the key used to store the data. The data will be organized into directories derived from the beginning characters of each hash. CacheDirLevels specifies the number of subdirectories to create and CacheDirLength specifies how many characters to use as the name of each directory. So a hash of b1946ac92492d2347c6235b4d2611184 with the default values shown above would be filed in a directory structure of b/1/946ac92492d2347c6235b4d2611184. Usually, you won’t need to modify these values, but it’s good to know what they’re used for.

Some other values you can set in this file are CacheMaxFileSize and CacheMinFileSize which set the ranges of file sizes in bytes that Apache will commit to the cache, as well as CacheReadSize and CacheReadTime, which allows you to wait and buffer content before sending to the client. This can be useful if the content resides somewhere other than this server.

Most of the configuration for caching will happen on a more granular level, either in the virtual host definition or in a specific location block.

Open one of your virtual host files to follow along. We’ll assume you’re using a file called site.conf within your /etc/httpd/conf.d directory in this guide:

sudo nano /etc/httpd/conf.d/site.conf

In the virtual host block, outside of any location block, we can begin configuring some of the caching properties. In this guide, we’ll assume that we want to turn the CacheQuickHandler off so that more processing is done. This allows us up more complete caching rules.

We will also take this opportunity to configure cache locking. This is a system of file locks that Apache will use when it is checking in with the content origin to see whether content is still valid. During the time when this query is being satisfied, if additional requests for the same content come in, it would result in additional requests to the backend resource, which could cause load spikes.

Setting a cache lock for a resource during validation tells Apache that the resource is currently being refreshed. During this time, the stale resource can be served with a warning header indicating its state. We’ll set this up with a cache lock directory in the /tmp folder. We’ll allow a maximum of 5 seconds for a lock to be considered valid. These examples are taken directly from Apache’s documentation, so they should work well for our purposes.

We will also tell Apache to ignore the Set-Cookie headers and not store them in the cache. Doing so will prevent Apache from accidentally leaking user-specific cookies out to other parties. The Set-Cookie header will be stripped before the headers are cached.

<VirtualHost *:80>
    ServerName server_domain_or_IP
    DocumentRoot /var/www/html

    CacheQuickHandler off

    CacheLock on
    CacheLockPath /tmp/mod_cache-lock
    CacheLockMaxAge 5

    CacheIgnoreHeaders Set-Cookie
</VirtualHost>

We still need to actually enable caching for this virtual host. We can do this with the CacheEnable directive. If this is set in a virtual host block, we would need to provide the caching method (disk or socache) as well as the requested URIs that should be cached. For example, to cache all responses, this could be set to CacheEnable disk /, but if you only wanted to cache responses under the /public URI, you could set this to CacheEnable disk /public.

We will take a different approach by enabling our cache within a specific location block. Doing so means we don’t have to provide a URI path to the CacheEnable command. Any URI that would be served from that location will be cached. We will also turn on the CacheHeader directive so that our response headers will indicate whether the cache was used to serve the request or not.

Another directive we’ll set is CacheDefaultExpire so that we can set an expiration (in seconds) if neither the Expires nor the Last-Modified headers are set on the content. Similarly, we’ll set CacheMaxExpire to cap the amount of time items will be saved. We’ll set the CacheLastModifiedFactor so that Apache can create an expiration date if it has a Last-Modified date, but no expiration. The factor is multiplied by the time since modification to set a reasonable expiration.

<VirtualHost *:80>
    ServerName server_domain_or_IP
    DocumentRoot /var/www/html

    CacheQuickHandler off

    CacheLock on
    CacheLockPath /tmp/mod_cache-lock
    CacheLockMaxAge 5

    CacheIgnoreHeaders Set-Cookie

    <Location />
        CacheEnable disk
        CacheHeader on

        CacheDefaultExpire 600
        CacheMaxExpire 86400
        CacheLastModifiedFactor 0.5
    </Location>
</VirtualHost>

Save and close your file when you’ve configured everything that you need.

Check your entire configuration for syntax errors by typing:

sudo apachectl configtest

If no errors are reported, restart your service by typing:

sudo systemctl restart httpd