iRules Recipe 4: Static Maintenance Page
The Problem
You wish to provide a static maintenance splash page when all members of a pool serving a Virtual Server are currently down or disabled.
The Configuration
# cat /var/tmp/splash-page.html
<!DOCTYPE html>
<html lang="en">
<head><title>Site Maintenance</title></head>
<body>
<!-- YOUR GREAT CONTENT HERE -->
</body>
</html>
# tmsh create sys file ifile maintenance-splash-page.html source-path file:/var/tmp/splash-page.html
# tmsh create ltm ifile maintenance-splash-page.html file-name maintenance-splash-page.html
The Code
when LB_FAILED {
if { [active_members [LB::server pool]] == 0 } {
HTTP::respond 503 content [ifile get maintenance-splash-page.html]
}
}
Analysis
LB_FAILED fires when the Virtual Server load-balancing decision fails. There are a number of reasons why this may occur, but we're only interested in the case where there are no active pool members available, either because all available members have been disabled, or because they are all marked down by the monitors. The
HTTP::respondtmshsource-pathtmshIn order to use the
HTTP::respondThe content could also be directly embedded in the
HTTP::respond
when LB_FAILED {
if { [active_members [LB::server pool]] == 0 } {
HTTP::respond 503 content {
<!DOCTYPE html>
<html>
<head><title>Maintenance Page</title></head>
<body>
<!-- YOUR GREAT CONTENT HERE -->
</body>
</html>
}
}
}
The iFile mechanism, however, is more flexible, because it permits changes to the file without needing to modify and reload the iRule. Perhaps more importantly, it supports a more flexible mechanism when you need to supply more than one file.
Elaboration
Why send a 503? Web search crawlers should not cache this response. You may also wish to add headers to this effect, as in:
HTTP::respond 503 content [ifile ...] Cache-Control "no-store, must-revalidate"
The recipes above work fine if all of the required assets for the response are in a single HTML page. But what if you need to send other things, like a separate css or one or more images? You need to solve two problems: 1. retrieve the file based on the requested object; and 2. set the Content-Type based on the actual contents. A Data Group can be used for this purpose:
# tmsh create ltm data-group internal splash-page-assets type string records add { "/css/maintenance.css" { data "splash-page-maintenace-css,text/css" } "/img/logo.png" { data "splash-page-logo-png,image/png" } }
Then:
when LB_FAILED {
if { [active_members [LB::server pool]] == 0 } {
set attr [class lookup [HTTP::path] splash-page-assets]
if { $attr eq "" } {
HTTP::respond 503 content [ifile get maintenance-splash-page.html]
}
else {
HTTP::respond 503 content [ifile get [getfield $attr , 1]] Content-Type [getfield $attr , 2]
}
}
}
It's worth noting that there is a slight race-condition here. Let us say that the pool member comes up while the client is pulling in the additional maintenance page assets. In that case, LB_FAILED isn't raised and the request will go through. For this reason, it is sensible to ensure these assets exist on the pool members, as well.
Version Caution
As you can see in the "Comments" section below, starting with 13.0, this method will not work when all members of a pool are disabled (as you might do during maintenance work). 13.0 changed the behavior of the BIG-IP platform such that it sends a RST to the initial SYN when the pool is disabled. This behavior is generally more sensible, but will require a different approach if you want to address this use-case.
