Tutorial

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

Published on June 9, 2015
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:

  1. echo "<h1 style='color:red'>Error 404: Not found :-(</h1>" | sudo tee /var/www/html/custom_404.html
  2. 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
  3. echo "<h1>Oops! Something went wrong...</h1>" | sudo tee /var/www/html/custom_50x.html
  4. 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:

  1. 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:

/etc/httpd/conf.d/custom_errors.conf
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:

/etc/httpd/conf.d/custom_errors.conf
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):

/etc/httpd/conf.d/custom_errors.conf
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:

  1. sudo apachectl configtest

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

  1. 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

apache custom 404

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

apache custom 50x

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.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


About the authors

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
1 Comments


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Hi I followed exactly what you say. But I could not change the 503 page error . Whatever I did I could not change the text if I put the html location for 503 error. If I put just string it works. I mean ** ErrorDocument 503 /custom_50x.html** does not work

ErrorDocument 503 “This is 503 error page” it work. Why

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel