Latest news from 5wire Networks

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

You’ll need a server running CentOS 7 for this tutorial. Here’s how to set it up.

You’ll also need Apache installed on your server, you can do that by following Step One in this guide.

reating 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 Nginx 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. If you want to design your own, here is the 5wire 404 page for inspiration. Don’t leave the break in!

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.

Sorted!

You now have some fancy custom error pages, rather than the ugly plain text pages that would show up otherwise.

Original Content by Justin Ellingwood and edited by the author of this post according to the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.