Maintenance window using Nginx web server

Introduction

It is important for a SysAdmin to know how to enable maintenance window while performing critical updates in live (or) production environment in order to avoid end users to feel that the site is unstable. Lets see how to enable maintenance window for all end users except your SysOps (or) QA (or) development team to verify the changes using Nginx web server.

Sample maintenance HTML web page

If you don’t have handy maintenance window page, then you shall use below HTML web page to show case your end users ūüėÄ Feel free to put below contents under your document root as¬†under_maintenance.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!doctype html>
<title>Site Maintenance</title>
<style>
 body { text-align: center; padding: 150px; }
 h1 { font-size: 50px; }
 body { font: 20px Helvetica, sans-serif; color: #333; }
 article { display: block; text-align: left; width: 650px; margin: 0 auto; }
 a { color: #dc8100; text-decoration: none; }
 a:hover { color: #333; text-decoration: none; }
</style>

<article>
 <h1>We will be back soon!</h1>
 <div>
 <p>Sorry for the inconvenience but we are performing some maintenance at the moment. We will be back online shortly!</p>
 <p>&mdash; The Team</p>
 </div>
</article>

Configuration changes

Add below configuration block to your main configuration file to enable / disable maintenance window when needed.

1
2
3
4
5
6
7
8
9
10
11
if (-f $document_root/maintenance.enable) {
 set $maintenance turn_on;
}

if ($remote_addr ~ (xyz.xyz.xyz.xyz|abc.abc.abc.abc)) {
 set $maintenance turn_off;
}

if ($maintenance = turn_on) {
 rewrite ^(.*)$ /under_maintenance.html break;
}


Explanation

From the above example, it is clear that the maintenance window will be enabled only if you have the file ‘maintenance.enable’ available under the document root. You can also have this settings under any available path based on your convenience. Say if your client don’t have access to the project location, but he wants to control the maintenance window and you can provide him simply using the following configuration. So when ever he needs maintenance window, he can simple create a dummy file named¬†maintenance.enable under pre-defined location (from the config)

1
2
3
if (-f $document_root/maintenance.enable) {
 set $maintenance turn_on;
}

$remote_addr —¬†IP addresses in¬†$remote_addr¬†block indicates white listed IPs. You can add the list of IP addresses here as shown above. I will show you how to white list the private IP using this config (for example)

1
2
3
if ($remote_addr ~ (192.168.1.10|172.16.2.20)) {
 set $maintenance turn_off;
}

After enabling the maintenance window, if the end user requests for the URI which may be fetched from the search engine results or from their bookmark, they will land on the maintenance page. This condition is applicable only if the maintenance.enable exist under document root (or) under pre-defined location and the IP is not white listed.

1
2
3
4
5
6
7
8
9
10
11
if ($maintenance = turn_on) {
 rewrite ^(.*)$ /under_maintenance.html break;
}
[cc]</pre>

It should be noted that if the under_maintenance.html doesn't exist in the mentioned path, then site may behave abnormally. There are many chances for throwing 500 HTTP response rather 404 HTTP response. So always ensure that the maintenance HTML file always exist in the pre-defined path as mentioned in the configuration.
<h3>Updating the config changes</h3>
It is safer to do syntax check before updating the web server configuration.

<p>[cc lang="bash"]
# nginx -t

Once it results that the syntax check are OK, then do reload | restart | graceful. It depends on your need.

1
# service nginx restart | reload

Footer notes

I will show some simple commands to enable / disable the maintenance window. Let us assume I am the client and I don’t have access the project’s document root. So you’re creating a user called techiedrone and configuring the maintenance mode file check as shown below.

1
2
3
if (-f /home/techiedrone/demo-site/maintenance.enable) {
 set $maintenance turn_on;
}

To enable maintenance window, then create a pre-defined dummy file

1
$ touch /home/techiedrone/demo-site/maintenance.enable

To remove the maintenance window

1
$ rm /home/techiedrone/demo-site/maintenance.enable

If you wish to provide client / developer to update these configurations including white listing the specific IP addresses, then you should append the configuration changes in htaccess file instead nginx configuration file. Always keep in mind site may behave unstable (many chances for 500 HTTP response) in case of syntax errors in htaccess file. Always ask them to create backup before performing configuration level changes in htaccess file.

This configuration has been tested on :

1
nginx/1.9.3 (Ubuntu)

Struck up in middle of configuring maintenance mode? Feel free to ask us through comment section. We’ll get back to you at earliest!

Spread the word :)

Leave a Reply

Be the First to Comment!

avatar
  Subscribe  
Notify of