nginx: Create HTTP 503 Maintenance Custom Page

Author: Vivek Gite Last updated: December 8, 2010 6 comments

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?

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 to Twitter • Facebook • 6 comments... add one ↓

UP NEXT

Category	List of Unix and Linux commands
File Management	cat
Firewall	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	CentOS 8 • Debian 10 • Firewall • Ubuntu 20.04