I know how to create a custom http 503 maintenance page under Lighttpd or Apache web server. How do I create a custom Nginx web server maintenance page?
HTTP error code 503 informs clients and search engines that the website is temporary out of service because it is overloaded or down for maintenance. Generally, this is a temporary state.
Step #1: Create a Custom 503 Service Unavailable HTML Page
First, you need to create a custom http 503 page at /usr/local/nginx/html/error503.html:
<html> <head> <title>Error 503 Service Unavailable</title> </head> <body> <h1>503 Service Unavailable</h1> Our apologies for the temporary inconvenience. The requested URL generated 503 "Service Unavailable" error due to overloading or maintenance of the server. </body> </html>
Step #2: Update Nginx Configuration
Edit /usr/local/nginx/config/nginx.conf, enter:
# vi /usr/local/nginx/config/nginx.conf
Update configuration as follows:
if (-f $document_root/error503.html) { return 503; } error_page 503 @maintenance; location @maintenance { rewrite ^(.*)$ /error503.html break; }
A complete config is as follows:
server { access_log logs/example.com_access.log main; error_log logs/example.com_error.log info; index index.html; limit_conn gulag 50; listen xxx.yyy.zzz.www:80 default; root /usr/local/nginx/html; server_name example.com www.example.com; ## Only requests to our Host are allowed if ($host !~ ^(example.com|www.example.com)$ ) { return 444; } ## redirect www to nowww if ($host = 'www.example.com' ) { rewrite ^/(.*)$ http://example.com/$1 permanent; } # Only allow these request methods if ($request_method !~ ^(GET|HEAD|POST)$ ) { return 444; } location / { if (-f $document_root/error503.html) { return 503; } } # redirect server error pages to the static page /50x.html error_page 500 502 504 /50x.html; location = /50x.html { root html; } # error 403 error_page 403 /error403.html; location = /error403.html { root html; allow all; } # error 503 redirect to errror503.html error_page 503 @maintenance; location @maintenance { rewrite ^(.*)$ /error503.html break; } }
Save and close the file. Reload nginx server, enter:
# /usr/local/nginx/sbin/nginx -s reload
Serve the Maintenance Page To All Visitors But Allow Full Access To Certain IP
You can use the $remote_addr variable to check against the remote or local IP address, if the visitor isn’t local or remote, then send a 503 maintenance page. Update configuration as follows:
# skip our office router ip or webmaster ip 1.2.3.4 if ($remote_addr != "1.2.3.4") { return 503; } error_page 503 @maintenance; location @maintenance { rewrite ^(.*)$ /error503.html break; }
Save and close the file. Finally, restart or reload nginx web server:
# /usr/local/nginx/sbin/nginx -s reload
Using Geo IP Modules To Skip Certain IPs or Subnets
If you’ve Geo IP module installed under nginx, you could add the following in the global section:
## add in global section ### geo $maintenance { default 0; 123.1.2.0/28 0; # allow our office subnet to skip http 503 mode 202.54.1.5 0; # allow webmaster remote ip to skip http 503 mode } ## add in server section ### location / { if ($maintenance) { return 503; } } error_page 503 @maintenance; location @maintenance { rewrite ^(.*)$ /error503.html break; }
To turn on maintenance set default from:
default 0;
To:
default 1;
Finally, reload the nginx web server:
# nginx -s reload
Sample Outputs:
One my own domain displaying error 503:
Fig.01: Displaying a Custom Nginx Maintenance Page - 503 Service Unavailable Page
How Do I Remove Maintenance Mode?
Edit nginx.conf and comment out the maintenance related directives:
# skip our office router ip or webmaster ip
###if ($remote_addr != "1.2.3.4") {
### return 503;
### }
OR if you are using Geo IP module set default from 1 to 0:
default 0;
Finally, reload the nginx web server:
# service nginx reload
References:
- Nginx mailing list discussion thread about a custom page and maintenance mode.
🐧 Get the latest tutorials on SysAdmin, Linux/Unix, Open Source/DevOps topics:
- RSS feed or Weekly email newsletter
- Share on Twitter • Facebook • 6 comments... add one ↓
| Category | List of Unix and Linux commands |
|---|---|
| File Management | cat |
| Firewall | Alpine Awall • CentOS 8 • OpenSUSE • RHEL 8 • Ubuntu 16.04 • Ubuntu 18.04 • Ubuntu 20.04 |
| Network Utilities | dig • host • ip • nmap |
| OpenVPN | CentOS 7 • CentOS 8 • Debian 10 • Debian 8/9 • Ubuntu 18.04 • Ubuntu 20.04 |
| Package Manager | apk • apt |
| Processes Management | bg • chroot • cron • disown • fg • jobs • killall • kill • pidof • pstree • pwdx • time |
| Searching | grep • whereis • which |
| User Information | groups • id • lastcomm • last • lid/libuser-lid • logname • members • users • whoami • who • w |
| WireGuard VPN | Alpine • CentOS 8 • Debian 10 • Firewall • Ubuntu 20.04 |
this does NOT return http status code 503! it only displays the custom html with the status code 200, which your error page will get indexed by the search engines!
Also with those if conditions his is a highly inefficient way to do this.
Hi,
Thanks for this information, but you need to return code 503 and avoid using if statements because they are very consuming.
still very helpful to learn how to write rules for nginx.
Thanks
Hi,
How can i force the maintenance page to return code 503 instead of 200 ? when i do a return 503 it just shows me the default 503 page and not the maintenace anymore.
thanks
It only returns HTTP status code 503 and not 200. Did you test this using curl command?
In order to skip the default 503 page, you have to remove it from nginx conf:
To:
After, set your custom 503 page:
And than, “return 503;” will show your custom maintenance page with status code 503!