How can I setup a custom 503 error page in NGINX?

Question

I learned how to get NGINX to return 503 customer error pages, but I cannot find out how to do the following:

Sample config file:

    lo         


        

Answer 1

The below configuration works for close to the latest stable nginx 1.2.4. I could not find a way to enable a maintenance page with out using an if but apparently according to IfIsEvil it is an ok if.

• To enable maintenance touch /srv/sites/blah/public/maintenance.enable. You can rm the file to disable.
• Error 502 will be mapped to 503 which is what most people want. You don't want to give Google a 502.
• Custom 502 and 503 pages. Your app will generate the other error pages.

There are other configurations on the web but they didn't seem to work on the latest nginx.

server {
    listen       80;
    server_name blah.com;

    access_log  /srv/sites/blah/logs/access.log;
    error_log  /srv/sites/blah/logs/error.log;

    root   /srv/sites/blah/public/;
    index  index.html;

    location / {
        if (-f $document_root/maintenance.enable) {
            return 503;
        }
        try_files /override.html @tomcat;
    }

    location = /502.html {
    }

    location @maintenance {
       rewrite ^(.*)$ /maintenance.html break;
    }

    error_page 503 @maintenance;
    error_page 502 =503 /502.html;

    location @tomcat {
         client_max_body_size 50M;

         proxy_set_header  X-Real-IP  $remote_addr;
         proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header  Host $http_host;
         proxy_set_header  Referer $http_referer;
         proxy_set_header  X-Forwarded-Proto http;
         proxy_pass http://tomcat;
         proxy_redirect off;
    }
}

Answer 2

Years later, here is what I currently use for completely custom error messages.

HTML Error pages are stored in /http-error directory located in your site root directory.

I've created an NGINX PHP-FPM quick setup guide at www.npo.run where you can learn how to spin up a server, download ready to use error page templates and more.

######    #####     #####      ####     #####        #####       ##       ####     ######     ####  
#         #    #    #    #    #    #    #    #       #    #     #  #     #    #    #         #      
#####     #    #    #    #    #    #    #    #       #    #    #    #    #         #####      ####  
#         #####     #####     #    #    #####        #####     ######    #  ###    #              # 
#         #   #     #   #     #    #    #   #        #         #    #    #    #    #         #    # 
######    #    #    #    #     ####     #    #       #         #    #     ####     ######     ####  

# ------------------------------------------------------------------------------
# HTTP > SERVER > ERROR_PAGE :: WWW.EXAMPLE1.COM
# ------------------------------------------------------------------------------
# Optionally include these error pages as a file.
# include /etc/nginx/conf.d/www.example1.com_error_page.conf;
# ------------------------------------------------------------------------------
# Description
# Defines the URI that will be shown for the specified errors.
# 
# ------------------------------------------------------------------------------
# 
# 
# 400 Bad Request
error_page            400 @400;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 400 error must be returned in this manner for custom http error pages to be served correctly.
location @400 {
   rewrite ^(.*)$     /http-error/400-error.html break;
}
# 401 Unauthorized
error_page            401 @401;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 401 error must be returned in this manner for custom http error pages to be served correctly.
location @401 {
   rewrite ^(.*)$     /http-error/401-error.html break;
}
# 403 Forbidden
error_page            403 @403;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 403 error must be returned in this manner for custom http error pages to be served correctly.
location @403 {
   rewrite ^(.*)$     /http-error/403-error.html break;
}
# 404 Not Found
error_page            404 @404;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 404 error must be returned in this manner for custom http error pages to be served correctly.
location @404 {
   rewrite ^(.*)$     /http-error/404-error.html break;
}

# 405 Method Not Allowed
# unreachable do to nature of the error itself. here only for completeness.
# error_page            405 /http-error/405-error.html break;

# Request Timeout
error_page            408 @408;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 408 error must be returned in this manner for custom http error pages to be served correctly.
location @408 {
   rewrite ^(.*)$     /http-error/408-error.html break;
}

# 500 Internal Server Error
error_page            500 @500;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 500 error must be returned in this manner for custom http error pages to be served correctly.
location @500 {
   rewrite ^(.*)$     /http-error/500-error.html break;
}
# 502 Bad Gateway
error_page            502 @502;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 502 error must be returned in this manner for custom http error pages to be served correctly.
location @502 {
   rewrite ^(.*)$     /http-error/502-error.html break;
}
# 503 Service Unavailable
error_page            503 @503;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 503 error must be returned in this manner for custom http error pages to be served correctly.
location @503 {
   rewrite ^(.*)$     /http-error/503-error.html break;
}
# 504 Gateway Time-out
error_page            504 @504;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 504 error must be returned in this manner for custom http error pages to be served correctly.
location @504 {
   rewrite ^(.*)$     /http-error/504-error.html break;
}
# 505 HTTP Version Not Supported
error_page            505 @505;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 505 error must be returned in this manner for custom http error pages to be served correctly.
location @505 {
   rewrite ^(.*)$     /http-error/505-error.html break;
}
# 511 HTTP Version Not Supported
error_page            511 @511;

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# An http 511 error must be returned in this manner for custom http error pages to be served correctly.
location @511 {
   rewrite ^(.*)$     /http-error/511-error.html break;
}

#       ####   ####    ##   ##### #  ####  #    # 
#      #    # #    #  #  #    #   # #    # ##   # 
#      #    # #      #    #   #   # #    # # #  # 
#      #    # #      ######   #   # #    # #  # # 
#      #    # #    # #    #   #   # #    # #   ## 
######  ####   ####  #    #   #   #  ####  #    # 

# example1.com internal error pages located at...
location /http-error/ {
  # Specifies that a given location can only be used for internal requests.
  # returns a 404 Not Found http error if accessed directly.
  internal;
}

Answer 3

Updated: changed "if -f" to "try_files".

Try this:

server {
    listen      80;
    server_name mysite.com;
    root    /var/www/mysite.com/;

    location / {
        try_files /maintenance.html $uri $uri/ @maintenance;

        # When maintenance ends, just mv maintenance.html from $root
        ... # the rest of your config goes here
     }

    location @maintenance {
      return 503;
    }

}

More info:

https://serverfault.com/questions/18994/nginx-best-practices

http://wiki.nginx.org/HttpCoreModule#try_files

Answer 4

The other answers are both correct, but just to add, that if you use internal proxies you also need to add proxy_intercept_errors on; on one of your proxy servers.

So for example...

    proxy_intercept_errors on;
    root /var/www/site.com/public;
    error_page 503 @503;
    location @503 {
       rewrite ^(.*)$ /scripts/503.html break;
    }