How to setup custom 503 error page in Nginx that intercepts all requests?
Solution 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 canrm
the file to disable. - Error
502
will be mapped to503
which is what most people want. You don't want to give Google a502
. - Custom
502
and503
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;
}
}
Solution 2
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;
}
Solution 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
Solution 4
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.xmpl.link 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;
}
![suchislife](https://i.stack.imgur.com/zG5KD.jpg?s=256&g=1)
suchislife
Updated on November 17, 2021Comments
-
suchislife over 2 years
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:
location / { root www; index index.php; try_files /503.html =503; } error_page 503 /503.html; location = /503.html { root www; }
As you can see, according to the code above, if a page called
503.html
is found in my root directory, the site will return this page to the user.But it seems that although the code above works when someone simply visits my site typing
it does not trap requests like:
With my code, the user can still see the profile page or any other pages besides
index.php
.The question:
How do I trap requests to all pages in my site and forward them to
503.html
whenever503.html
is present in my root folder? -
suchislife about 13 yearstry_files is the best practice. Also, it is not missing. It's just incomplete.
-
Ken Cochrane about 13 years@Vini what's the difference between not missing and incomplete, to me it is the same thing. I updated the example to include try_files instead of if -f. Hope that helps.
-
suchislife about 13 yearsThank you Ken. By the way, what does $uri do? I see it twice in a row.
-
Ken Cochrane about 13 years@Vini $uri is equal to current URI in the request (without arguments, those are in $args.) It can differ from $request_uri which is what is sent by the browser. it is there twice but notice the second one has a / so it is $url $url/ . Basically what try_files does is look for the files in that order, and it returns the first one that it finds. If it finds the maintenance page it returns that, if it doesn't it moves to the next one, in this case the $uri, and if it can resolve that url correctly it will return it. I need to update my code so that it has correct @maintenance at the end.
-
Andrew Roberts over 12 yearsThis serves /maintenance.html with a status code of 200. How can the page be served with the proper status of 503?
-
Andreas Kavountzis almost 11 yearsThank you for this. I couldn't find a way to do it without using an
if
either. Glad to see it's an acceptable use! -
Yoni Jah over 8 yearsNot sure about your 'if' solution but this solution wont work properly - It will return maintenance.html with status code 200 for success - if the site is on normal operation but $uri does not exist instead of returning a 404 error nginx will redirect to @maintenance and will just return a 503 error The best explanation and partial solution for this I found was here - stackoverflow.com/questions/16693209/…
-
Capripot over 7 yearsThis would never return the
503
http code if you have a file/maintenance.html
since thetry_files
instruction would stop there. -
JustAMartin almost 4 yearsI find it can fail if the user does POST and not GET - in that case they receive 405 empty response instead of 503. Not sure, how to solve that. Tried everything I could find.