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?

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 Linux, Open Source & DevOps via RSS feed or Weekly email newsletter.

🐧 6 comments so far... add one ↓

Related Tutorials

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

6 comments… add one

roy Mar 3, 2012 @ 5:20

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!

Reply Link
Phoenix May 17, 2012 @ 1:42

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

Reply Link
Quran Sep 30, 2012 @ 5:18

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

Reply Link
jaap Oct 30, 2012 @ 7:01

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

Reply Link
- 🐧 nixCraft Oct 30, 2012 @ 7:18
  It only returns HTTP status code 503 and not 200. Did you test this using curl command?
```
curl -I www.example.com
```
  Reply Link
- avery Feb 18, 2013 @ 19:46
  
  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!
  
  Reply Link

Use HTML <pre>...</pre> for code samples. Problem posting comment? Email me @ webmaster@cyberciti.biz