1. Configuration Guide
  2. STIR/SHAKEN Client
  3. STI Server Heartbeat

STI Server Heartbeat

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

A STIR server supports multiple addresses, and establishes circuit breaker state for each one. This is also true for server groups. The SBC refers to the circuit breaker state to determine when to use this heartbeat function. When you enable this function, either globally or on a given server, the SBC performs this 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 this heartbeat function to test availability and bring that server back into the service rotation faster. When a connection responds to this heartbeat test, the SBC marks that circuit breaker as CLOSED and starts using that server in its rotation.

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

Additional operational detail includes:

  • 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, 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 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.

You can configure an individual sti-server to ignore the sti-heartbeat-profile by setting the sti-heartbeat-state option under that sti-server to disabled. This sti-heartbeat-state option under sti-server takes precedence over the sti-heartbeat-config setting. 

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

By default, this option is not set for any STI server. You can however, enable this option, resulting in the system applying the feature to this STI server even if you have left the sti-heartbeat-config disabled. This allows you to apply the feature to a single or a small group of servers only. In this case, the transaction would include the default or configured values of the other sti-heartbeat-config parameters. Conversely, if you set this feature to disabled and enable the sti-heartbeat-config, the system applies the feature to all servers except those with the option disabled. This flexibility allows you to easily apply the feature to a majority or a minority of your servers.

This feature works for all STI servers whether configured as single stir-server elements or configured within a sti-server-group.

Configuration

The sti-heartbeat-config includes a parameter to enable the function, a timing parameter that specifies how often it tries to reach each server, and parameters to specify dummy orig, dest and div TNs for inclusion in the request. Specific profile parameters include:

  • sti-heartbeat-state—Enables/disables the heartbeat functionality for all STIR/SHAKEN servers at the system level.
  • 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.

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 further 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 recevieved from AS              0          0           0
HB Request sent to VS                       0          29          6
HB Response received from AS                0          3           1

Explanations for each heartbeat output line includes:

  • HB Request sent to AS—Displays the count of STIR AS/Div-AS heartbeat request sent to check the server availability.
  • HB Response received from AS—Displays the count of STIR AS/Div-AS heartbeat response received from STIR server.
  • HB Request sent to VS—Displays the count of STIR VS/Div-VS heartbeat request sent to check the server availability.
  • HB Response received from VS—Displays the count of STIR VS/Div-VS heartbeat response received from STIR server.

In addition, you can use the reset command to set all statistic values to zero, again for all servers or for your specific server.

Applicable ACLI syntax for these commands includes:

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