How To Configure Apache to Use Custom Error Pages on CentOS 7

Introduction

Apache is the most popular web server in the world. It is well-supported, feature-rich, and flexible. When designing your web pages, it is often helpful to customize every piece of content that your users will see. This includes error pages for when they request content that is not available. In this guide, we’ll demonstrate how to configure Apache to use custom error pages on CentOS 7.

Prerequisites

To get started on with this guide, you will need a non-root user with sudo privileges. You can set up a user of this type by following along with our initial set up guide for CentOS 7. You will also need to have Apache installed on your system. Learn how to set this up by following the first step of this guide.

Creating Your Custom Error Pages

We will create a few custom error pages for demonstration purposes, but your custom pages will obviously be different.

We will put our custom error pages in the /var/www/html directory where CentOS’s Apache installation sets its default document root. We’ll make a page for 404 errors called custom_404.html and one for general 500-level errors called custom_50x.html. You can use the following lines if you are just testing. Otherwise, put your own content in these locations:

echo "<h1 style='color:red'>Error 404: Not found :-(</h1>" | sudo tee /var/www/html/custom_404.html
echo "<p>I have no idea where that file is, sorry.  Are you sure you typed in the correct URL?</p>" | sudo tee -a /var/www/html/custom_404.html
echo "<h1>Oops! Something went wrong...</h1>" | sudo tee /var/www/html/custom_50x.html
echo "<p>We seem to be having some technical difficulties. Hang tight.</p>" | sudo tee -a /var/www/html/custom_50x.html

We now have two custom error pages that we can serve when client requests result in different errors.

Configuring Apache to Use your Error Pages

Now, we just need to tell Apache that it should be utilizing these pages whenever the correct error conditions occur. We can create a new configuration file in the /etc/httpd/conf.d directory where Apache reads config snippets. We’ll call the new file custom_errors.conf:

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

We can now point Apache to our custom error pages.

Direct Errors to the Correct Custom Pages

We can use the ErrorDocument directive to associate each type of error with an associated error page. Basically, we just have to map the http status code for each error to the page we want to serve when it occurs.

For our example, the error mapping will look like this:

ErrorDocument 404 /custom_404.html
ErrorDocument 500 /custom_50x.html
ErrorDocument 502 /custom_50x.html
ErrorDocument 503 /custom_50x.html
ErrorDocument 504 /custom_50x.html

This change alone is enough to serve the custom error pages when the specified errors occur.

However, we will add an additional set of configurations so that our error pages cannot be requested directly by clients. This can prevent some strange situations where the text of a page references an error, but the http status is “200” (indicating a successful request).

Respond with 404 When Error Pages are Directly Requested

To implement this behavior, we’ll need to add a Files block for each of our custom pages. Inside, we can test whether the REDIRECT_STATUS environmental variable is set. This should only be set when the ErrorDocument directive processes a request. If the environmental variable is empty, we’ll serve a 404 error:

ErrorDocument 404 /custom_404.html
ErrorDocument 500 /custom_50x.html
ErrorDocument 502 /custom_50x.html
ErrorDocument 503 /custom_50x.html
ErrorDocument 504 /custom_50x.html

<Files "custom_404.html">
    <If "-z %{ENV:REDIRECT_STATUS}">
        RedirectMatch 404 ^/custom_404.html$
    </If>
</Files>

<Files "custom_50x.html">
    <If "-z %{ENV:REDIRECT_STATUS}">
        RedirectMatch 404 ^/custom_50x.html$
    </If>
</Files>

When the error pages are requested directly by clients, a 404 error will occur because the correct environmental variable is not set.

Set Up Testing for 500-Level Errors

We can easily produce 404 errors to test our configuration by requesting content that doesn’t exist. To test the 500-level errors, we’ll have to set up a dummy proxy pass so that we can ensure that the correct pages are returned.

Add a ProxyPass directive to the bottom of the file. Send requests for /proxytest to port 9000 on the local machine (where no service is running):

ErrorDocument 404 /custom_404.html
ErrorDocument 500 /custom_50x.html
ErrorDocument 502 /custom_50x.html
ErrorDocument 503 /custom_50x.html
ErrorDocument 504 /custom_50x.html

<Files "custom_404.html">
    <If "-z %{ENV:REDIRECT_STATUS}">
        RedirectMatch 404 ^/custom_404.html$
    </If>
</Files>

<Files "custom_50x.html">
    <If "-z %{ENV:REDIRECT_STATUS}">
        RedirectMatch 404 ^/custom_50x.html$
    </If>
</Files>

ProxyPass /proxytest "http://localhost:9000"

Save and close the file when you are finished.

Restarting Apache and Testing your Pages

Test your configuration file for syntax errors by typing:

sudo apachectl configtest

Address any issues that are reported. When your files contain no syntax errors, restart Apache by typing:

sudo systemctl restart httpd

Now, when you go to your server’s domain or IP address and request a non-existent file, you should see the 404 page we set up:

http://server_domain_or_IP/thiswillerror

When you go to the location we set up for the dummy proxy pass, we will receive a “503 service unavailable” error with our custom 500-level page:

http://server_domain_or_IP/proxytest

You can now go back and remove the fake proxy pass line from your Apache config.

Conclusion

You should now be serving custom error pages for your site. This is an easy way to personalize your users’ experience even when they are experiencing problems. One suggestion for these pages is to include links to locations where they can go to get help or more information. If you do this, make sure that the link destinations are accessible even when the associated errors are occurring.