Setting 503 Service Temporarily Unavailable headers with Apache .htaccess

When temporarily taking down a website to perform maintenance, it's a good idea to return a "503 Service Temporarily Unavailable" header so search engines know to come back later. This post shows how to set this header using an Apache .htaccess file, and also how to show a response page to users with PHP so they know to try again later.

.htaccess settings

Create an .htaccess file in the website's root directory containing the following:

RewriteEngine On
RewriteCond %{REMOTE_ADDR} !^111\.111\.111\.111$
RewriteCond %{REQUEST_URI} !\.(css|gif|ico|jpg|js|png|swf|txt)$
RewriteRule .* - [R=503,L]

If you already have an .htaccess file then put the above lines in the top. The L condition means it will be the last rule so the others will be ignored while these lines are present.

Line 2 makes it so the user at the IP address 111.111.111.111 will not have the rewrite rule applied to them and can still view the website. Substitute 111.111.111.111 for your own IP address so you still have access to the website to check it while it's made unavailable.

Line 3 makes it so various media files etc do not have the rules applied. This is especially important when creating a custom error page (see below); without the rule all the image files etc in the error page would also be made unavailable.

Line 4 shows a 503 Service Temporarily Unavailable message using Apache's default page.

Specifying a custom 503 error page with ErrorDocument

In theory, you should be able to add an ErrorDocument directive to show for a 503 error instead of Apache's default page but whenever I tried it I would get a "Additionally, a 404 Not Found error was encountered while trying to use an ErrorDocument to handle the request" error message, even though the path to the file was correct.

If anyone knows the solution to this issue please leave a comment in the comments section below. But for what it's worth, this is what I tried:

ErrorDocument 503 /path/to/503.html

RewriteEngine On
RewriteCond %{REMOTE_ADDR} !^111\.111\.111\.111$
RewriteCond %{REQUEST_URI} !\.(css|gif|ico|jpg|js|png|swf|txt)$
RewriteRule .* - [R=503,L]

Specifying a custom 503 error page with PHP

A scripting language can be used to set the 503 header and also an additional "Retry-After" header so the search engines know when to come back again. This also means you can send a more user-friendly error page to the user to let them know to come back again shortly.

Put this in the .htaccess file:

RewriteEngine On
RewriteCond %{REQUEST_URI} !\.(css|gif|ico|jpg|js|png|swf|txt)$
RewriteCond %{REMOTE_ADDR} !^111\.111\.111\.111$
RewriteRule .* 503.php [L]

And then add this to the start of the PHP page (it can be called whatever you like, but 503.php made sense to me):

header('HTTP/1.1 503 Service Temporarily Unavailable');
header('Retry-After: 600');

The Retry-After header sets the amount of time for the search engines to retry in seconds; in the above example it's 10 minutes. Underneath the PHP code put whatever HTML etc is required to show a friendly error message to the website visitors.

Related posts:

• 410 "Gone" with PHP
• 303 redirect with PHP
• 301 redirect with PHP