Linux smart help: nginx: Create HTTP 503 Maintenance Custom Page

Monday, April 23, 2012

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

Linux smart help