STI Server Heartbeat

You can configure the SBC to check the state of the server without using live signaling traffic by using the sti-heartbeat-config element. This feature works for both ATIS and 3GPP deployments and is disabled by default.

The heartbeat check sends JSON requests made up of dummy data to applicable servers. These requests use the correct format for authentication and verification requests, and can optionally include a dummy identity header. This allows the test to verify connectivity and service availability without using live call data. If the server sends a response, the SBC recognizes its dummy data and the source of the response, identifies that the response is to the heartbeat feature and, therefore, makes the server available for service requests for real calls.

You can optionally configure the SBC to check whether the response contains valid JSON, or to check for specific response codes before adding the server to the rotation. These additional configurations can help ensure that the server is truly available. Without them, when the SBC receives any response from the server, it assumes this means that the server is available, even if the response is a timeout or a 500 response indicating an internal server error.

Note:

The SBC does not validate the actual content of the response body, it only checks for the presence of JSON and whether the format is valid.

You can enable the heartbeat check globally, or for specific servers only. You can also configure when the SBC performs the heartbeat check:

  • According to circuit breaker state: The STIR server establishes a circuit breaker state for each address that it supports. This is also true for server groups. The SBC performs a heartbeat check for all circuit breakers in either the HALF_OPEN or OPEN state.

    When a STIR server is in OPEN state, the SBC does not send any live traffic to it, preferring to send that traffic to a server known to be available. For servers with connectivity issues, you can use the heartbeat function to test availability and bring that server back into the service rotation faster. When a connection responds to the heartbeat test, the SBC marks that circuit breaker as CLOSED and starts using that server in its rotation.

  • At startup: As soon as a server is configured, before any messages with real data are exchanged, the SBC performs a heartbeat check. If the server does not respond, the circuit breaker functionality is engaged, performing heartbeat checks until the circuit breaker state is CLOSED.

Additional operational details include:

  • The SBC does not apply this sti-heartbeat-config function to any server that is currently in the closed state.
  • For ATIS deployments, if all IP addresses for an AS root on a STIR server are down, meaning each circuit breaker is in the OPEN state, the SBC does not perform authentication service with that server. The means the SBC does not send an authentication request for any INVITE, instead sending only heartbeat requests to all of that server's IP addresses that have their circuit breaker state as OPEN or HALF_OPEN.

    Within this context, the SBC sends heartbeat requests periodically. If it receives a heartbeat response from any STIR server address, and any additional checks for a valid JSON response or specific response code are passed, it changes the circuit breaker state of that IP from OPEN to CLOSED and performs authentication service with that server.

  • For 3GPP deployments, the SBC uses the same behavior as the bullet above, referring to the circuit breaker state of both AS and DIV AS root addresses.

    Note:

    The applicable configuration fields are as-server-root and div-as-server-root.
  • For ATIS and 3GPP deployments, the SBC uses the same behavior as the two bullets above for verification services.

    Note:

    The applicable configuration fields are vs-server-root and div-vs-server-root.
  • When accessing a service using a sti-server-group, the SBC uses the behavior described in the three bullets above based on the circuit breaker status for all addresses in that sti-server-group.
  • This feature works for all STI servers whether configured as single stir-server elements or configured within a sti-server-group.

Global Configuration

You configure heartbeat checks in the sti-heartbeat-config element, which includes the following parameters:

  • sti-heartbeat-state: Enables or disables the heartbeat functionality for all STIR/SHAKEN servers at the system level.

    Note:

    You can override this setting for individual servers by setting the sti-heartbeat-state option under that sti-server. See below for more information.
  • sti-heartbeat-msg-interval-time: Specifies, in seconds, the time-interval to send the heartbeat message to STIR/SHAKEN servers. The default is 5, and the range is 0 - 3600 seconds.
  • sti-orig-tn-number: Specifies the calling party TN number when sending heartbeat messages to STIR/SHAKEN servers. The value is a string, and the default is 9999999999.
  • sti-dest-tn-number: Specifies the called party TN number when sending heartbeat messages to STIR/SHAKEN servers. The value is a string, and the default is 7777777777.
  • sti-div-tn-number: Specifies the called party diverted TN number when sending heartbeat messages to STIR/SHAKEN servers. The value is a string, and the default is 3333333333.
  • mode: Specifies whether to run the heartbeat check as soon as the server starts up, or only according to the circuit breaker state. Valid values are Default and HbAtStartup.
  • sti-identity: Specifies the dummy identity header for verification service requests. The value is a string, and there is no default value. This value is not validated; you are responsible for entering a valid header.
  • sti-json-mandate: Enables or disables requiring JSON in the response body for the server to be considered available. Values are enabled or disabled, and the default is disabled.
  • sti-in-service-response-code: Specifies the list of response codes for which the server is considered available. If this is set, and the response code is not in this list, the server will not be added to the rotation. The value is a comma-separated list of integers. There is no default.

Enabling or Disabling Heartbeat Checks for Individual Servers

Although you enable or disabled sti-heartbeat-config globally, you can configure an individual sti-server to ignore the global configuration by setting the sti-heartbeat-state option under that sti-server. This option takes precedence over the sti-heartbeat-config setting, allowing you to easily apply the heartbeat check to a majority or minority of servers.

By default, this option is not set for any STI server.

If you set this option to disabled for some servers when sti-heartbeat-config is enabled, the SBC performs the heartbeat check on all servers except those where the option is set to disabled. This allows you to exclude a single or small group of servers from the heartbeat check.

If you set this option to enabled for some servers when sti-heartbeat-config is disabled, the SBC performs the heartbeat check only on the servers where the option is set to enabled. This allows you to apply the heartbeat check to a single or a small group of servers only. The heartbeat check for this set of servers uses the default or configured values of the other sti-heartbeat-config parameters, even though it is disabled. 

ORACLE(sti-server)#options +sti-heartbeat-state=disabled

Reporting on Heartbeat Statistics

The show stir command supports the heartbeat argument to display heartbeat feature statistics. Without further argument, the command displays statistics on all STI servers. You can refine this command with specific server names to narrow the command output to your specific server. 

ORACLE#show stir heartbeat MyStiServer
06:36:02-44
Server: MyStiServer
STIR/SHAKEN Heartbeat Statistics        –------------LIFETIME----------
                                          Recent     Total      Permax
HB Request sent to AS                       0          0           0
HB Response received from AS                0          0           0
HB Request sent to VS                       0          29          6
HB Response received from AS                0          3           1

The output shows:

  • HB Request sent to AS: The count of STIR AS/Div-AS heartbeat requests sent to check the server availability.
  • HB Response received from AS: The count of STIR AS/Div-AS heartbeat responses received from STIR server.
  • HB Request sent to VS: The count of STIR VS/Div-VS heartbeat requests sent to check the server availability.
  • HB Response received from VS: The count of STIR VS/Div-VS heartbeat responses received from STIR server.

You can also use the reset command to reset all statistic values to zero, either for all servers or for a specific server.

The ACLI syntax for these commands is:

  • show stir heartbeat all
  • show stir heartbeat -all
  • show stir heartbeat <sti-server-name>
  • reset stir heartbeat <sti-server-name>