How To Configure Nginx to Use Custom Error Pages on CentOS 7
Introduction
Nginx is a high performance web server capable of serving content with flexibility and power. 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 Nginx 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 Nginx installed on your server, you can do that using 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 /usr/share/nginx/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 Nginx to Use your Error Pages
Now, we just need to tell Nginx that it should be utilizing these pages whenever the correct error conditions occur. We’ll need to adjust our server blocks. On CentOS 7, the primary server block is located in the /etc/nginx/nginx.conf file. We’ll be configuring this server block, but you should adjust whatever other server blocks you have configured:
sudo nano /etc/nginx/nginx.conf
Inside the file, locate the block that defines the server context. We can now point Nginx to our custom error pages.
Direct 404 Errors to the Custom 404 Page
The CentOS Nginx configuration file already defines a 404 error page using the error_page directive. We’ll need to change this so that when a 404 error occurs (when a requested file is not found), the custom page you created is served. We’ll adjust the associated location block for the file so we are able to ensure that the root matches our file system location and that the file is only accessible through internal Nginx redirects (not requestable directly by clients):
http {
. . .
server {
. . .
error_page 404 /custom_404.html;
location = /custom_404.html {
root /usr/share/nginx/html;
internal;
}
. . .
}
}
Usually, we would not have to set the root in the new location block since it matches the root in the server block. However, we are being explicit here so that our error pages are served even if we move our regular web content and the associated document root to a different location.
Direct 500 Level Errors to the Custom 50x Page
Next, we can add the directives to make sure that when Nginx encounters 500-level errors (server-related problems), it will serve the other custom page we made. This will follow the exact same formula we used in the last section. This time we set multiple 500-level errors to all use the custom_50x.html page:
http {
. . .
server {
. . .
error_page 404 /custom_404.html;
location = /custom_404.html {
root /usr/share/nginx/html;
internal;
}
error_page 500 502 503 504 /custom_50x.html;
location = /custom_50x.html {
root /usr/share/nginx/html;
internal;
}
location /testing {
fastcgi_pass unix:/does/not/exist;
}
}
}
At the bottom, we also added a dummy FastCGI pass so that we can test our 500-level error page. This will not work correctly since the backend does not exist. Requesting a page here will allow us to test that 500-level errors serve our custom page.
Save and close the file when you are finished.
Restarting Nginx and Testing your Pages
Test your configuration file’s syntax by typing:
sudo nginx -t
If any errors were reported, fix them before continuing. When no syntax errors are returned, restart Nginx by typing:
sudo systemctl restart nginx
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/this_will_cause_an_error
When you go to the location we set up for the FastCGI pass, we will receive a 502 Bad Gateway error with our custom 500-level page:
http://server_domain_or_IP/testing
Check they work, and you’re done! Go back and remove the FastCGI pass location from your Nginx 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.
