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.

You should follow me on twitter here or grab rss feed to keep track of new changes.

Featured Articles:

{ 5 comments… read them below or add one }

1 roy 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!

2 Phoenix May 17, 2012 at 1:42 am

Also with those if conditions his is a highly inefficient way to do this.

3 Quran 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

4 jaap October 30, 2012 at 7:01 am

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

5 nixCraft October 30, 2012 at 7:18 am

It only returns HTTP status code 503 and not 200. Did you test this using curl command?