nginx: Create HTTP 503 Maintenance Custom Page

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.

Posted by: Vivek Gite

The author is the creator of nixCraft and a seasoned sysadmin, DevOps engineer, and a trainer for the Linux operating system/Unix shell scripting. Get the latest tutorials on SysAdmin, Linux/Unix and open source topics via RSS/XML feed or weekly email newsletter.

6 comment

roy says:
March 3, 2012 at 5:20 am
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!
Phoenix says:
May 17, 2012 at 1:42 am
Also with those if conditions his is a highly inefficient way to do this.
Quran says:
September 30, 2012 at 5:18 am
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
jaap says:
October 30, 2012 at 7:01 am
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
1. nixCraft says:
  October 30, 2012 at 7:18 am
  It only returns HTTP status code 503 and not 200. Did you test this using curl command?
```
curl -I www.example.com
```
2. avery says:
  February 18, 2013 at 7:46 pm
  In order to skip the default 503 page, you have to remove it from nginx conf:
  error_page 500 502 503 504 /50x.html;
  To:
  error_page 500 502 504 /50x.html;
  After, set your custom 503 page:
  error_page 503 @maintenance;
  And than, “return 503;” will show your custom maintenance page with status code 503!

Have a question? Post it on our forum!