Manage liveness tests

When you configure a GTM property, you can configure liveness tests to determine whether the data centers associated with the property are up. Once a liveness test is configured, GTM answers queries for the property with the A or AAAA records of servers in your data centers which it considers to be live (up).

📘

Liveness testing is optional and not available with all property types. These property types do not have liveness tests.

  • Map by geographic location

  • Map by AS number

  • Map by IP address (CIDR blocks)

  • IP Version Selector

  • Static Properties

Liveness tests can be configured to use one of these popular protocols: HTTP, HTTPS, DNS, FTP, POP, POPS, SMTP, and SMTPS. You can also construct custom liveness tests by specifying the protocol as TCP or TCPS. In the simplest mode, TCP/TCPS liveness testing succeeds if it can open a TCP connection on the specified port. For additional validation, you can send an optional Request String (which must include any applicable control characters, such as CR and LF, and look for a Response String. The Response string can occur in the first 8 KB of the response. If the connection succeeds, but the response string doesn't match, the liveness test fails and the server is marked down.

📘

A Liveness test to the loopback interface (127.0.0.x or ::1) always fails with a 3111 error (connection refused).

Liveness testing is done by systems called liveness testing agents, also known as servermonitors. GTM allocates a set of seven agents for each of your data centers. Servers in data centers are considered up if their liveness tests are deemed successful by a majority of the agents. The sets of liveness testing agents assigned to each of your data centers might overlap with one another. Using multiple agents to conduct liveness tests minimizes the possibility of falsely declaring your data center down due to local network issues.

GTM attempts to allocate liveness testing agents so that.

  • Agents are in the same continent as your data center

  • Agents are near your data center

  • No two agents are in the same ISP (network diversity)

  • Only live agents are assigned (sometimes agents are down for maintenance)

It is important that you enter accurate geographic information when configuring your data centers, to enable the best allocation of liveness testing agents. A data center is considered up if any of the servers in it are considered up. You can configure the Minimum Live Percentage for a property to adjust this behavior. If all the servers for a property are failing their liveness tests and there is no backup CNAME, GTM considers all the data centers to be up, as it has no basis for preferring any of them.

To verify the validity of the selected HTTP headers, click Validate HTTP Headers before you save the liveness test.

Auto-generated host headers

The HTTP protocol requires clients to send a “Host” header, which indicates the hostname of the server the client expects to be talking to. This same value is also used as the Server Name Indication (SNI) in the TLS handshake. Because the value is required, if you do not specify a Host header, one will be automatically generated from the name of the property. For example, if your GTM domain is example.com.akadns.net, and your property is named “test”, any HTTP liveness tests for that property would send the Host header “test.example.com.akadns.net”, unless you explicitly set a Host header.

Liveness test coalescing

When GTM determines that multiple liveness tests for a given IP are functionally identical, it will coalesce them into a single liveness test. This coalescing occurs across properties, as long as both properties use the same server IPs. If the test in question does not specify a Host header, an auto-generated one is used as described above. This feature, combined with test coalescing, can result in a test that sends an unexpected Host header. For example, properties “alpha” and “beta” both have HTTPs liveness tests, and both use the same server: 192.0.2.1. Neither liveness test specifies a Host header, so an auto-generated one is used. Because the tests are functionally identical, GTM will coalesce them by picking one to use. This can result in 192.0.2.1 only ever receiving a Host header of “alpha.example.com.akadns.net”, and never “beta.example.com.akadns.net”.

To avoid this problem, you should always specify a Host header for HTTP and HTTPS liveness tests.

DNS and TCP/TCPS protocol fields

These protocols have fields not shown on the Liveness Test page.

  • DNS protocol fields not shown.

    Record Type. Click and select an option from: A, AAAA, AFSDB, CNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF, SRV, SSHFP, TXT, or Other Type

    Numeric Type. This field appears only when you select the DNS protocol and select Other Type from the Record Type menu. The default is 0, which is not valid. You must change the 0 value to an integer value between 1 and 65535.

    DNS Name. Enter a single, valid DNS name. This is required.

    Answers Required. If you check this, the liveness test fails if the server returns no answers. If you leave it unchecked, the liveness test succeeds if the server returns a response with a success (status) code, even if the response contains no answers. The default is false.

    Recursion Requested. Click the checkbox if you want recursion. The default is false.

  • TCP/TCPS protocol fields not shown

    TCP and TCPS Test Strings. You can specify a request and response string to use in the liveness tests. When the servermonitor performs the test, it connects to the server at the port you specified. If no request or response string is supplied, the test succeeds at this point. If a request string is specified, servermonitor then sends the request string and waits for the server to send a response. If the response contains the response string in the first 8K characters of the response, then the liveness test succeeds, otherwise it fails.

Add liveness test to existing domain

When you configure a GTM domain, you can configure liveness tests to perform validation tests on each server. You can use these instructions to add a liveness test on an existing property type in a domain.

  1. Log in to ​Control Center​.

  2. Go to > DNS SOLUTIONS > Global Traffic Management. The Traffic Management Domains page opens.

  3. On the Traffic Management Domains page, select the domain you want to add a liveness test to. The Edit Domain Settings page appears.

  4. On the Properties tab, select the property to which you want to add a liveness test. The review page for the selected property opens.

  5. On the Liveness Tests tab, click Add New Liveness Test to access the fields. Click the right caret icon to expand the Liveness Tests field if it is not open.

  6. In the Liveness Test Details section of the page, enter the following information to create a liveness test. This example uses the HTTP protocol. Other protocols have different or fewer fields to fill out.

    • Enabled - Click this checkbox to allow (enable) the liveness test for the selected property. Uncheck the box to disable the liveness test for the selected property.

    • Test Name (required). Specify a name for the liveness test. This field is required.

    • Test Interval. Specify, in seconds, how often liveness tests are run. The default is 60 seconds.

    • Test Timeout. Specify, in seconds, how long the servermonitor waits without getting a response before declaring a timeout error. The default is 10 seconds. See Timeout back off.

    • Port. Specify the port number for requesting the test object or accept a protocol's default port. The default port varies depending on which protocol you select. You can override the default port but you get a Nonstandard Port warning in yellow next to the port number.

    • Protocol. Specify the protocol used to monitor servers. You can select from these protocols. The port defaults are in parentheses.

      • DNS (port 53)
      • DoH - DNS over HTTPS (port 443)
      • DoT - DNS over TLS (port 853)
      • FTP (port 21)
      • HTTP (the default; port 80)
      • HTTPS (port 443)
      • POP (port 110)
      • POPS (port 995)
      • SMTP (port 25)
      • SMTPS (port 465)
      • TCP (port default not specified)
      • TCPS (port default not specified)

📘

Secure protocols

If you select one of the secure protocols for a liveness test (HTTPS, POPS, SMTPS, and TCPS), you can upload an SSL certificate for that test. See Manage SSL client certificates.

📘

HTTPS protocol

If you select the HTTPS protocol, the Certificate Verification checkbox, which is enabled by default, appears below the Protocol field. Use this checkbox to verify the validity of an SSL certificate. This prevents the delivery of traffic to an origin that is operational but has an invalid or bad certificate, which can cause failure on the clients if they are sent to the origin.

If you select the HTTP protocol and the Certificate Verification checkbox is enabled (checked), you must specify a Host HTTP header.

  • Test Object Path (optional): only enter the local part of the URL for the test object (for example, /data/results/test.html)

  • HTTP Headers (optional). This option is available only when you select HTTP and HTTPs protocols. ​Akamai Technologies, Inc.​ strongly recommends that you set the Host header for HTTP and HTTPS liveness tests. If you do not specify an HTTP header, the property's fully qualified domain name is used. Choose one or more HTTP headers and their values from a standard list of HTTP headers. In the Name field pull-down menu, choose an HTTP header and specify its value. Click the green plus sign (+) next to a header row to see a new row from which you can choose additional HTTP headers. For detailed descriptions of standard HTTP headers, see https://www.w3.org/Protocols/HTTP/HTRQ_Headers.

    Optionally, you can choose Other, which allows you to specify one or more customized HTTP headers. The customized header name must contain only letters, digits, hyphens, underscores, and dots. Blank spaces causes an error when you try to submit and validate the changes. To return to the Name field pull-down menu, click the left arrow located to the left of the header text field.

    In addition, you can test the validity of the selected HTTP headers by clicking Validate HTTP Headers. A message appears only if HTTP header errors are detected.

    If the same server is being tested for more than one property, the liveness tests is coalesced and a host header is chosen from among them, unless different host headers are explicitly specified for each test.

    If you are using Cloud Server Targeting for a data center, you can enable Cloud Server Host Header Override. Akamai's liveness test agents populate the Host header with the host header value configured in the liveness test. See Configure GTM cloud-based services.

  • HTTP/FTP Errors: Select the responses you want to consider for server failures.

  • Authentication: If you are using password authentication, provide a username and password.

  1. Click Save Liveness Test to save your changes. The test's name appears in the Test Name column.

  2. Click Add to Change List.

    The review Change List Dialog opens.

  3. Click Review Change List. The Review Change List Dialog opens. Verify your changes, validate them, add a required comment, and click Activate Domain to save them. The Traffic Management Domains page opens.

See Review Change List Detail.

Disable and reenable liveness test

  1. On the Traffic Management Domains page, select the domain for which you want to disable and re-enable a liveness test. The Edit Domain Settings page appears.

  2. On the Properties tab, select the property to which you want to disable a liveness test. The review page for the selected property opens.

  3. Navigate to the Liveness Tests section. In the Test Name column, click the name of the liveness test that you want to enable or disable. The Liveness Test Details for the selected liveness test appears.

  4. Uncheck the Enabled checkbox to disable the test, or check it to enable the test.

  5. Click Save Liveness Test.

  6. Click Add to Change List to save the deleted test.

    The Properties window opens and an icon appears next to the property with the change.

  7. Click Review Change List.

  8. Review the changes in the Change List Dialog, validate them, add a required comment, and click Activate Domain to save the changes.

See Review Change List Detail.

Delete liveness test

You can delete a liveness test from a GTM domain.

🚧

If you delete a liveness test, you cannot undo the deletion.

  1. On the Traffic Management Domains page, select the domain you want to delete a liveness test from. The Edit Domain Settings page appears.

  2. On the Properties tab, select the property from which you want to delete a liveness test. The review page for the selected property appears.

  3. Navigate to the Liveness Tests section. In the Test Name column, highlight the liveness name that you want to delete, and in the Actions column, click the ellipsis icon and select Delete to delete the selected liveness test.

  4. Click Add to Change List to save the deletion. The Properties page appears and a icon appears next to the property with the change.

  5. Click Review Change List.

  6. Review the Change List dialog changes, validate them, add a required comment, and click Activate Domain to save your changes.

See Review Change List Detail.