Custom 503 error page for Apache
A 5xx error code is returned by a web server when something went wrong: The server was not able to process the request. For a reverse proxy, a common 5xx error message is 503, meaning that the backend server is not reachable.
In the technical architecture of my blog site, the WordPress site with my blogs is hosted on a Raspberry Pi in my living room, while external access is through a reverse proxy hosted on Amazon EC2. If now the reverse proxy on EC2 cannot reach my Raspberry Pi, a 503 error message is given.
The root cause can be that the Raspberry Pi is turned off, there is no Internet connection available for some reason (power outage, provider problem), or something else. In case this happens, EC2 reverse proxy will throw an error and try to show the Apache standard 503 error page. The web page used to display the 503 is the same for all Apache installations worldwide. Giving your users a more personalized message can be a nice touch. For instance, including a statement that you are aware of the issue, it won`t take long to get solved, or a better explanation of what happened.
For this to work, you need to have
- A custom 503.html file and
- Configure Apache to use this web page.
Create custom 503 file
This is up to you. Internet and Google are your friend.
Apache has the ErrorDocument directive. For an HTTP error code you specify a HTML file to be shown. Make the 503 HTML file created by you in the above section available on the web server.
Important: the document root of Apache is /var/www/html. For accessing the file, the browser will call the URL /error/503.html. Reference it in the Apache configuration.
sudo vim /etc/httpd/conf/httpd.conf
ErrorDocument 503 /error/503.html
You are done in the case of a normal web server setup. The configuration shown so fare won`t work for a reverse proxy. A reverse proxy will forward all requests to the backend server, including the request for the 503 document. To not forward /error/503.html to the backend, put /error/ in a exception list. With this, every request to /error/ won`t be forwarded by Apache, and instead be served from the local web server. To exclude /error/ from the ProxyPass rule, add:
ProxyPass /error/ !
This exclusion must be before the other ProxyPass directives. A somewhat more complete example of a Apache configuration:
<VirtualHost _default_:443> DocumentRoot "/var/www/html" ProxyPass /error/ ! ErrorDocument 503 /error/503.html SSLProxyEngine On ProxyPass / https://backend/ ProxyPassReverse / https://backend/ SSLEngine on </VirtualHost>
sudo service httpd restart
The next time the backend server is not reachable, the reverse proxy will serve the custom 503 error page to the users.