The NGINX directives refer to the building blocks that make up the NGINX configuration file which serves as instructions that define and control the web server’s behavior.
The NGINX directives can range from simple commands that set a specific parameter such as the listen directive to specify which IP and port NGINX should listen on to complex constructs like the location directive that matches specific request URIs and decides how to process them.
Directives play a critical role in the overall performance and functionality of the NGINX server. They can control various server functions from setting up virtual servers and load balancing to implementing HTTP security headers, SSL/TLS encryption, and managing access to resources based on client IP or authentication status.
In this tutorial, we will discuss a very common directive in NGINX that allows you to configure the error pages for various status codes in the server.
Prerequisites:
To follow this tutorial, you need the following:
- Basic NGINX and server administration
- Access to a server with installed NGINX
- Basic Linux and Unix Commands
NGINX Error_Page Directive
The NGINX error_page directive allows us to configure the custom error pages for specific HTTP status codes. This is useful when you need to show a custom page or error message for various status codes within the server.
Basic HTTP Status Code
You may need to handle the following standard HTTP status codes and show the custom error pages in NGINX.
- 404: Not Found – The resource is not found on the server.
- 403: Forbidden – The server fails to fulfill the request.
- 500: Internal Server Error – Unexpected behavior on the server.
How to Use the NGINX Error_Page Block
The NGINX error_page block allows us to define a custom error page for various error codes that may occur in the server.
Let us learn how to define a custom error page 404 using HTML/CSS and the NGINX error_page block.
Using your preferred text editor, create a new file named “404.html” and add the source code for the page.
We create a simplistic but responsive 404 page using HTML and tailwindcss for demonstration purposes.
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>404 Page Not Found</title>
<!-- Include Tailwind CSS -->
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tailwind.min.css" rel="stylesheet">
<style>
/* Custom Styles */
body {
font-family: Arial, sans-serif;
background-color: #f7fafc;
}
.container {
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
height: 100vh;
}
.title {
font-size: 4rem;
font-weight: 700;
color: #374151;
margin-bottom: 1rem;
}
.description {
font-size: 1.5rem;
color: #4b5563;
margin-bottom: 2rem;
}
.home-btn {
padding: 0.75rem 1.5rem;
background-color: #2563eb;
color: #ffffff;
font-size: 1rem;
font-weight: 600;
border-radius: 0.25rem;
text-decoration: none;
transition: background-color 0.3s ease;
}
.home-btn:hover {
background-color: #1e40af;
}
</style>
</head>
<body>
<div class="container">
<h1 class="title">404</h1>
<p class="description">Page Not Found</p>
<a href="/" class="home-btn">Go Home</a>
</div>
</body>
</html>
Save the file and close the editor to proceed with the configuration.
NOTE: Ensure to save the file in a directory that NGINX can serve. For example, if your server’s root directory is /var/www/html, you might save it as /var/www/html/errors/404.html.
Once completed, we can learn how to configure NGINX to use the defined custom error page.
Start by editing the NGINX configuration file with your text editor of choice. The location of the NGINX configuration file may vary depending on your system.
In the configuration file, add the following entry in the server block:
location = /errors/404.html {
internal;
}
The error_page directive tells NGINX to use the /errors/404.html, relative to the server root directory whenever a 404 error occurs.
We also set the location block as internal which prevents the path to the file from being exposed to the client.
The full entry is as follows:
NOTE: The entry shows a basic NGINX configuration with a server block that includes a custom 404 page using the error_page block.
listen 80 default_server;
listen [::]:80 default_server;
root /var/www/html;
index index.html index.htm index.nginx-debian.html;
server_name _;
error_page 404 /errors/404.html;
location = /errors/404.html {
internal;
}
location / {
# First attempt to serve request as file, then
# as directory, then fall back to displaying a 404.
try_files $uri $uri/ =404;
}
}
Once you are satisfied with the changes to the configuration file, you can verify that the settings are correct using the following command:
The command tests the configuration file for errors and prints the result to the console. If the configuration file is okay, you should see an output as follows:
Finally, reload the NGINX configuration to apply the changes:
To test the custom error page, you can navigate to a non-existent resource on the server.
You can allow NGINX to handle more error codes by repeating the steps that are discussed in this tutorial for each error code. For example, to add a custom error page for the 500 status code, you can create a “500.html” page and add the configuration block as follows:
location = /errors/500.html {
internal;
}
There you have it!
Conclusion
We discussed what the error_page directive in NGINX does. We also covered how we can use it to implement the custom error pages for various HTTP status codes.
