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::respond
sends an HTTP Response message with a 503 status code, then the contents of the so-called ifile. This is a file that has been uploaded into the BIG-IP configuration filestore. The first 
tmsh
command loads a file from the BIG-IP local filesystem into the configuration filestore. We could have imported a file via http using the appropriate 
source-path
url. The second 
tmsh
command makes the file visible to the LTM module.

In order to use the 

HTTP::respond
, an http profile must be applied to the Virtual Server.

The content could also be directly embedded in the 

HTTP::respond
command by doing this:

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.

Updated Jun 06, 2023
Version 2.0
application delivery
iRules
LTM
  • ekaleido's avatar
    ekaleido
    Icon for Cirrus rankCirrus
    Nov 16, 2016

    Would probably be better still to just exclude the if statement and return the maintenance page on LB_FAILED. Although there could be a use case for acting differently based on why LB_FAILED was triggered.

     

    As Lloyd Christmas would say, "I like it a lot."

     

  • JG's avatar
    JG
    Icon for Cumulonimbus rankCumulonimbus
    Nov 18, 2016

    There are limitations with LB_FAILED, for the ifile must be short enough to fit in one data packet (sol9456: Using the HTTP::respond iRule command in the LB_FAILED event may result in truncated responses).

     

    Also it might be appropriate to use the "503" HTTP status code in the response; search engines will not index the maintenance message with that.

     

  • rlou_299501's avatar
    rlou_299501
    Icon for Nimbostratus rankNimbostratus
    Nov 22, 2016

    I am trying to implement this recipe but I'm having syntax issues with the code you have under the "Elaboration" section (send other things like images). Specifically, I am getting syntax error related to:

     

    set attr [class lookup [HTTP::path]] <- error: [wrong args][class lookup [HTTP::path]]

     

    and

     

    HTTP::respond 200 content [ifile get [getfield $attr 1 ,]] Content-Type [getfield $attr 2,] <- error: [wrong args][getfield $attr 1,], error: [wrong args][getfield $attr 2,]

     

    For the 'getfield' errors, I believe it should be this instead:

     

    HTTP::respond 200 content [ifile get [getfield $attr , 1]] Content-Type [getfield $attr , 2]

     

    Can you confirm the syntax you've provided for both items I've listed above?

     

    Thanks.

     

  • VernonWells's avatar
    VernonWells
    Icon for Employee rankEmployee
    Nov 22, 2016

    For the first, I failed to include the data-group name. This should be:

        set attr [class lookup [HTTP::path] splash-page-assets]

    You are also correct on the 

    getfield
    argument order. It turns out the error was cascading. I forgot to include the data-group name, but the parser complained instead about the 
    getfield
    order. That sometimes happens on parsing. I will attempt to fix this article with the corrected code. Thank you for pointing this out.

  • VernonWells's avatar
    VernonWells
    Icon for Employee rankEmployee
    Nov 22, 2016

    Thanks for the suggestions! Keep them coming. I've incorporated @Jie's response code recommendation and corrected the code based on @rlou's findings.

     

  • JG's avatar
    JG
    Icon for Cumulonimbus rankCumulonimbus
    Dec 05, 2016

    No a fastl4 profile does not allow L7 processing.

     

  • JG's avatar
    JG
    Icon for Cumulonimbus rankCumulonimbus
    Dec 05, 2016

    What we have done here is to have the CSS and images embedded in a single HTML ifile, with the images encoded in the base64 format. As mentioned above, do not get carried away with the content as this is just a functional maintenance notice and need not to be fancy; limit the size of the content to as small as possible.

     

  • cjbarr1234's avatar
    cjbarr1234
    Icon for Altostratus rankAltostratus
    Jan 04, 2017

    I've used very similar to this. Did the syntax change though? LB_FAILED always was the case for all down?

     

  • VernonWells's avatar
    VernonWells
    Icon for Employee rankEmployee
    Jan 04, 2017

    LB_FAILED does not mean "all pool members are down". Rather, it means "a load-balancing decision cannot be made, or an attempt to proxy the traffic failed". Usually, the first happens when all members are down, but the second can occur for a variety of reasons. For example, if the pool members becomes overloaded and TCP connections timeout, then LB_FAILED will be raised.