This document is the Configuration and Management guide for Rhino VoLTE TAS 4.1.

In this book

Notices

Copyright © 2014-2021 Metaswitch Networks. All rights reserved

This manual is issued on a controlled basis to a specific person on the understanding that no part of the Metaswitch Networks product code or documentation (including this manual) will be copied or distributed without prior agreement in writing from Metaswitch Networks.

Metaswitch Networks reserves the right to, without notice, modify or revise all or part of this document and/or change product features or specifications and shall not be responsible for any loss, cost, or damage, including consequential damage, caused by reliance on these materials.

Metaswitch and the Metaswitch logo are trademarks of Metaswitch Networks. Other brands and products referenced herein are the trademarks or registered trademarks of their respective holders.

Where to start

Welcome to the Configuration and Management guide for the Rhino VoLTE TAS, Metaswitch’s carrier-class VoLTE Telephony Application Server (VoLTE TAS) product.

This page will guide you through the process of getting a freshly installed Rhino VoLTE TAS up and running in your network. If this is your first time setting up a Rhino VoLTE TAS, we recommend following the steps laid out below in order.

.1. Familiarize yourself with how configuration works in the Rhino VoLTE TAS

Before getting into configuring the system, you should make sure you are familiar with how configuration in the Rhino VoLTE TAS works, and how to modify the configuration files. Read through Declarative configuration to learn about this.

While using this guide, if you come across a particular field or section in the configuration and you want to find more detailed information about it, click the link on its name in the text. This takes you to its entry in the RVT declarative configuration reference included in this guide.

.2. Set up the Rhino VoLTE TAS platform

The first step is to configure the identity of the platform and the identity of the virtual machines (VM) and VM pools for each node type, and in some cases set up user access and integration between nodes of the system.

Read through The platform for details.

.3. Set up integration with other network systems

The next step is to get the Rhino VoLTE TAS talking to other nodes in the network. Instructions for doing this for each relevant node are in Integration with other systems. Exactly which systems that need to be configured will be specific to your network and requirements.

.4. Set up charging

The next thing to do is set up the charging systems you want to use. There are several different systems for doing charging, including online and offline charging systems. This is also the place where Call Data Record (CDR) generation is configured. Exactly which systems you choose to use will depend on your particular network. See Charging for a description of each system and how to configure it.

.5. Set up home network information

Next, you need to get the Rhino VoLTE TAS up to speed with the details of your network.

This means configuring:

  • how phone numbers should be normalized

  • country codes

  • handling of international and roaming calls

  • reserved URIs and phone numbers.

See Home networks and roaming for instructions.

.6. Set up SCC services

By this point the Rhino VoLTE TAS should be ready to process a basic LTE call. The next step is to get the service centralization and continuity (SCC) services up and running. They are responsible for providing interoperability between the GSM/CDMA and LTE networks.

There are three services that you may need to configure:

  1. T-ADS, which selects whether a called subscriber will receive the call over the GSM/CDMA or the LTE (or a Wi-Fi) network.

  2. Access transfer, which keeps calls up and running when a subscriber leaves LTE coverage.

  3. Reorigination, which allows a subscriber to access and use their VoLTE services while outside of LTE coverage.

.7. Set up MMTel services

The final step for configuring call processing is to get the MultiMedia Telephony (MMTel) services set up. These services provide a variety of ways for operators and subscribers to control calls. Some of the services provided are defined by the 3GPP; others are unique to the Rhino VoLTE TAS.

Not all networks will use all of the available services. So look through the following list and go to the linked page for each service required in your network.

The available MMTel services are:

  1. Announcements, which plays announcements to subscribers. Details of all possible announcements that can be played to subscribers must be configured here. Other services count on this configuration to nominate announcements to be played at various times.

  2. Call failure announcements, which selects which announcements to play under various call failure conditions.

  3. PSAP callback, which provides special handling for return calls from emergency services to a subscriber.

  4. Dial plan enforcement, which checks the number dialed by a subscriber to ensure it is valid for the network before permitting a call.

  5. Privacy, which controls whether or not each subscriber in a call can see the other’s identity. It covers the functionality for the 3GPP defined Originating Identity Restriction (OIR), Originating Identity Presentation (OIP), Terminating Identity Restriction (TIR), and Terminating Identity Presentation (TIP) services.

  6. Conferencing, which enables calls with more than two participants. It covers the functionality for the 3GPP defined Conference (CONF) service.

  7. Call barring, which blocks incoming and/or outgoing calls for a subscriber according to set rules. It covers the functionality for the 3GPP defined Outgoing Call Barring (OCB), Incoming Call Barring (ICB), and Anonymous Call Rejection (ACR) services. It provides support for both subscriber and operator defined barring rules.

  8. Communication waiting, which notifies a subscriber when they have an incoming call while they are already on another call, and gives them a chance to answer it. It covers the functionality for the 3GPP defined Communication Waiting (CW) service.

  9. Communication hold, which manages announcements and media stream bandwidth when a call is put on hold. It covers the functionality for the 3GPP defined Communication Hold (HOLD) service.

  10. Communications diversion, which forwards calls to new destinations according to rules set by or for a called subscriber. It covers the functionality for the 3GPP defined Communications Diversion (CDIV) service.

  11. Voicemail forwarding, which forwards an incoming call to a subscriber’s nominated voicemail server.

  12. Companion device, which provides features supporting LTE connected devices besides a subscriber’s main phone (e.g. smart watches).

  13. Vertical service codes, which enables the creation of phone numbers and number prefixes/suffixes that invoke services in the network.

  14. Location based dialing, which allows for phone numbers that direct to different places depending on a subscriber’s location.

  15. Explicit communication transfer, which allows a subscriber to transfer a call to someone else. It covers the functionality for the 3GPP defined Explicit Communication Transfer (ECT) service.

  16. Flexible alerting, which allows a single phone number to be used for multiple people or devices. It covers the functionality for the 3GPP defined Flexible Alerting (FA) service.

  17. Session transfer to own device, which allows a subscriber to transfer a call from their current device to a different one without creating a new call.

.8. Set up XCAP

XCAP is an interface used to manage subscriber specific configuration. The Rhino VoLTE TAS incorporates an XCAP server which can be used by both the operator and subscriber to manage subscriber specific configuration data in the HSS. See RVT XCAP for details of how to set this up.

You will also need to set up the authentication gateway so that XCAP requests can be verified. See RVT Authentication Gateway for details.

.9. Set up the IP-SM-GW

Depending on your particular installation, the Rhino VoLTE TAS may include an IP-SM-GW (Internet Protocol Short Message Gateway). The purpose of the IP-SM-GW is to allow SMS messages to cross between GSM and LTE networks. See RVT IP Short Message Gateway (IP-SM-GW) for information about configuring the IP-SM-GW.

Declarative configuration

This section describes how to configure the Rhino VoLTE TAS - that is, the processes of making and applying configuration changes.

It is not intended as a full checklist of the steps to take during an upgrade or full installation - for example, business level change-control processes are not discussed.

The configuration process is based on modifying configuration files, which are validated and sent to a central configuration data store (CDS) using the rvtconfig tool. The nodes in the Rhino VoLTE TAS will poll the CDS, and will pull down and apply any changes.

declarative config how to

Initial setup

The initial configuration process starts with the example YAML files distributed alongside the Rhino VoLTE TAS, as described in Example configuration YAML files.

Note Metaswitch strongly recommends that the configuration files are stored in a version control system (VCS). A VCS allows version control, rollback, traceability, and reliable storage of the system’s configuration.

If a VCS is not a viable option for you, it is still required and your responsibility every time a change is needed to take backups of the configuration before making any changes. In this case, the recommended approach is to store the full set of configuration files in a reliable cloud storage system (e.g. OneDrive) and to keep the backups in different folders named with a progressive number and a timestamp of the backup date (e.g. v1-20210310T1301).

The rest of the guide is written assuming a VCS is being used to manage the configuration files.

Initially, add the full set of example YAMLs into your VCS as a baseline, alongside the solution definition files (SDFs) described in the RVT VM install guides. You should store all files (including the SDFs for all nodes) in a single directory yamls with no subdirectories.

Making changes

The first step to changing the system configuration is to edit the configuration files, making the desired changes (as described in this guide). You can do this on any machine using a text editor (one with YAML support is recommended). After you have made the changes, they should be recorded to the VCS.

Validating the changes

On the SIMPL VM, as the admin user, change to the directory /home/admin/. Check out (or copy) your yamls directory to this location, as /home/admin/yamls/.

Note If network access allows, it is recommended to retrieve the files directly from the VCS into this directory, rather than copying them. Having a direct VCS connection means that changes made at this point in the process are more likely to be committed back into the VCS, a critical part of maintaining the match between live and stored configuration.

At this point, use the rvtconfig tool to validate the configuration used for all relevant nodes.

Note For more information on the rvtconfig tool, see rvtconfig reference.

The relevant nodes depend on which configuration files have been changed. To determine the mapping between configuration files and nodes, consult Example configuration YAML files in the install guide for:

The rvtconfig tool is delivered as part of the VM image CSAR file, and unpacked into /home/admin/.local/share/csar/<csar name>/<version>/resources/rvtconfig.

Important It is important that the rvtconfig binary used to validate a node’s configuration is from a matching release. That is, if the change is being made to a mag node which is at version x.y.z-p1, the rvtconfig binary must be from a version x.y.z CSAR.

For example, assume a change has been made to the home-network-config.yaml file in a CDMA network. This would require reconfiguration of the smo, mmt-cdma and mag nodes, with all nodes at version 4.0.0. To validate this change, use the following commands from the /home/admin/ directory.

./.local/share/csar/mmt-cdma/4.0.0/resources/rvtconfig validate -t mmt-cdma -i ./yamls
./.local/share/csar/smo/4.0.0/resources/rvtconfig validate -t smo -i ./yamls
./.local/share/csar/mag/4.0.0/resources/rvtconfig validate -t mag -i ./yamls

If any of the nodes fail validation, update the files to fix the errors as reported, and record the changes in your VCS.

Uploading the changes

Once the file is validated, record the local changes in your VCS.

Next, use the rvtconfig upload-config command to upload the changes to the CDS. As described in Uploading configuration to CDS with upload-config, the upload-config command requires a number of command line arguments.

The full syntax to use for this use case is:

rvtconfig upload-config -c <cds-ip-addresses> -t <node type> -i <config-path> --vm-version <vm_version>

where:

  • <cds-ip-addresses> is the signaling IP address of a TSN node

  • <deployment-id> can be found in the relevant SDF

  • <node type> is the node being configured, as described above

  • <config-path> is the path of the directory containing the YAML and SDFs

  • <vm_version> is the version string of the node being configured

As with validation, the rvtconfig executable must match the version of software being configured. Take the example of a change to the home-network-config.yaml as above, on a CDMA network with nodes at version 4.0.0, a deployment ID of prod, and a CDS at IP 192.0.0.1. In this environment the configuration could be uploaded with the following commands (from /home/admin/:

./.local/share/csar/mmt-cdma/4.0.0/resources/rvtconfig upload-config -c 192.0.0.1 -t mmt-cdma -i ./yamls --vm-version 4.0.0
./.local/share/csar/smo/4.0.0/resources/rvtconfig upload-config -c 192.0.0.1 -t smo -i ./yamls --version--vm-version 4.0.0
./.local/share/csar/mag/4.0.0/resources/rvtconfig upload-config -c 192.0.0.1 -t mag -i ./yamls --vm-version 4.0.0

Verifying the changes

Once the upload is completed, the software on the VMs will apply the configuration from the CDS. You can verify this by monitoring the system logs on the relevant nodes.

rvtconfig reference

Overview

To apply an update to the Rhino VoLTE TAS’s declarative configuration, the rvtconfig tool is used. rvtconfig applies configuration to the Rhino VoLTE TAS’s configuration data store (CDS). The CDS distributes this configuration to the Rhino VoLTE TAS’s VMs. The rvtconfig tool is provided on the VMs that the RVT runs on and the SIMPL VM.

For further information on configuring the RVT’s virtual machines, refer to the RVT VM Install Guide (CDMA) and the RVT VM Install Guide (GSM).

rvtconfig tool

Configuration YAML files can be validated and uploaded to the CDS using the rvtconfig tool. The rvtconfig tool can be run either on the SIMPL VM or any RVT VM.

On the SIMPL VM, you can find the command in the resources subdirectory of any RVT (tsn, shcm, mag, mmt-gsm, mmt-cdma or smo) CSAR, after it has been extracted using csar unpack.

/home/admin/.local/share/csar/<csar name>/<version>/resources/rvtconfig

On any RVT VM, the rvtconfig tool is in the PATH for the sentinel user and can be run directly by running:

rvtconfig <command>

The available rvtconfig commands are:

  • rvtconfig validate validates the configuration, even before booting any VMs by using the SIMPL VM.

  • rvtconfig upload-config validates, encrypts, and uploads the configuration to the CDS.

  • rvtconfig delete-deployment deletes a deployment from the CDS.

    Note Only use this when advised to do so by a Customer Care Representative.

  • rvtconfig delete-node-type-version deletes state and configuration for a specified version of a given node type from the CDS.

    Note This should only be used when there are no VMs of that version deployed.

  • rvtconfig delete-node-type-all-versions deletes state and configuration for all versions of a given node type from the CDS.

    Note Only use this after deleting all VMs for a given node type.

  • rvtconfig delete-node-type-retain-version deletes state and configuration for a given node type from the CDS, except for the specified version.

  • rvtconfig list-config displays a summary of the configurations stored in the CDS.

  • rvtconfig dump-config dumps the current configuration from the CDS.

  • rvtconfig print-leader-seed prints the current leader seed as stored in the CDS.

  • rvtconfig generate-private-key generates a new private key for use in the SDF.

  • rvtconfig enter-maintenance-window disables VMs' scheduled tasks for a period of time.

  • rvtconfig leave-maintenance-window re-enables VMs' scheduled tasks.

  • rvtconfig calculate-maintenance-window calculates the required length of a maintenance window for rolling upgrades.

  • rvtconfig maintenance-window-status displays a message indicating whether there is an maintenance window period reserved or not.

  • rvtconfig export-log-history exports the quiesce log history from the CDS.

  • rvtconfig initconf-log retrieves initconf.log file from the specified remote RVT node.

  • rvtconfig describe-versions prints the current values of the versions of the VM found in the config and in the SDF.

  • rvtconfig compare-config compares currently uploaded config with a given set of configuration.

  • rvtconfig backup-cds creates a backup of the CDS database in tar format and retrieves it.

  • rvtconfig restore-cds uses CDS database backup taken with backup-cds to restore the CDS database to a previous state.

  • rvtconfig set-desired-running-state sets DesiredRunningState to stopped/started in MDM.

    • If --state Started or no --state is specified, all initconf processes of non-TSN VMs will pause their configuration loops.

    • If --state Stopped is specified, all initconf processes of non-TSN VMs will resume their configuration loops.

  • rvtconfig cassandra-upgrade performs a cassandra upgrade operation from {cassandra-version-three} to {cassandra-version-four}. This command can only be used after a Major TSN upgrade has been successfully executed to TSN 4.1 and the cassandra version running is {cassandra-version-three}. This operation must be done one TSN node at a time and no parallelization is allowed.

  • rvtconfig cassandra-status prints the cassandra database status of all the specified CDS IP addresses.

  • rvtconfig cassandra-upgrade-sstables upgrades sstables status once all TSN 4.1 nodes have been upgraded to Cassandra version {cassandra-version-four} with rvtconfig cassandra-upgrade

Common arguments

Commands that read or modify CDS state take a --cds-address parameter (which is also aliased as --cds-addresses, --cassandra-contact-point, --cassandra-contact-points, or simply -c). For this parameter, specify the management address(es) of at least one machine hosting the CDS database. Separate multiple addresses with a space, for example --cds-address 1.2.3.4 1.2.3.5.

The upload-config and export-audit-history commands read UNRESOLVABLE BXREF: sdf-secrets[secrets] from QSG. If you have not yet uploaded secrets to QSG, you can specify a --secrets-file <file> argument, passing in the path to your secrets file (the YAML file which you pass to csar secrets add). QSG is only available on the SIMPL VM; if running rvtconfig on a platform other than the SIMPL VM, for example on the VM itself, then you must pass the --secrets-file argument.

Commands that read or modify CDS state may also require additional parameters if the CDS endpoints are configured to use authentication and/or SSL encryption as per UNRESOLVABLE BXREF: cassandra-security[Cassandra security configuration]. If the CDS endpoints are configured to use authentication, you must pass the --cds-username argument with your configured password and either the --cds-password or --cds-password-secret-name argument with the configured password or its ID in the secrets file. If the CDS endpoints are configured to use SSL encryption, you must pass the --ssl flag and also pass either the --ssl-ca-certificate or --ssl-ca-certificate-secret-name argument containing a file with the SSL signing certificate, or its ID in the secrets file.

The various delete-node-type commands, and the report-group-status command, require an SSH private key to access the VMs. You can specify this key as either a path to the private key file with the --ssh-key argument, or as a secret ID with the --ssh-key-secret-id argument. If you are running rvtconfig on the SIMPL VM, the recommended approach is to use the secret ID of the SIMPL VM-specific private key that you specified in the SDF (see UNRESOLVABLE BXREF: solution-service-group#simpl-vm-ssh-private-key[SIMPL VM SSH private key] ). Otherwise, use the SSH private key file itself (copying it to the machine on which you are running rvtconfig, and deleting it once you have finished, if necessary).

For more information, run rvtconfig --help. You can also view help about a particular command using, for example, rvtconfig upload-config --help.

rvtconfig limitations

The following limitations apply when running rvtconfig on the SIMPL VM:

  1. All files and directories mentioned in parameter values and the secrets file must reside within the root (/) filesystem of the SIMPL VM. A good way to ensure this is the case is to store files only in directories under /home/admin.

  2. rvtconfig assumes files specified without paths are located in the current directory. If multiple directories are involved, it is recommended to use absolute paths everywhere. (Relative paths can be used, but may not use .. to navigate out of the current directory.)

Verifying and uploading configuration

  1. Create a directory to hold the configuration YAML files.

    mkdir yamls

  2. Ensure the directory contains the following:

    • configuration YAML files

    • the Solution Definition File (SDF)

    • Rhino license for nodes running Rhino.

Note Do not create any subdirectories. Ensure the file names match the example YAML files.
Verifying configuration with validate

To validate configuration, run the command:

rvtconfig validate -t <node type> -i ~/yamls

where <node type> is the node type you want to verify, which can be tsn, shcm, mag, mmt-gsm, mmt-cdma or smo. If there are any errors, fix them, move the fixed files to the yamls directory, and then re-run the above rvtconfig validate command on the yamls directory.

Once the files pass validation, store the YAML files in the CDS using the rvtconfig upload-config command.

Tip

If using the SIMPL VM, the rvtconfig validate command can be run before any of the other VMs are booted. We recommend that you validate all configuration before any of the VMs are booted.
Uploading configuration to the CDS with upload-config

To upload the YAML files to the CDS, run the command:

rvtconfig upload-config [--secrets-file <file>] -c <tsn-mgmt-addresses> -t <node type> -i ~/yamls
[(--vm-version-source [this-vm | this-rvtconfig | sdf-version] | --vm-version <vm_version>)] [--reload-resource-adaptors]

Note

The <tsn-mgmt-addresses> value can either be any single TSN management IP address or a space-separated list of TSN management IP addresses.

If you would like to specify a version, you can use:

  • --vm-version to specify the exact version of the VM to target (as configuration can differ across a VM upgrade).

  • --vm-version-source to automatically derive the VM version from the given source. Failure to determine the version will result in an error.

    • Use this-rvtconfig when running the rvtconfig tool included in the CSAR for the target VM, to extract the version information packaged into rvtconfig.

    • Use this-vm if running the rvtconfig tool directly on the VM being configured, to extract the version information from the VM.

    • Option sdf-version extracts the version value written in the SDF for the given node.

If the version is not specified, then the version in the SDF will be compared to the this-rvtconfig or this-vm version (whichever is appropriate given how the rvtconfig command is run). If they match, this value will be used. Otherwise, the command will fail.

Note

Whatever way you enter the version, the value obtained must match the version in the SDF. Otherwise, the upload will fail.

Any YAML configuration values which are specified as secrets are marked as such in the YAML files' comments. These values will be encrypted using the generated private-key created by rvtconfig generate-private-key and prior to uploading the SDF. In other words, the secrets should be entered in plain text in the SDF, and the upload-config command takes care of encrypting them. Currently this applies to the following:

  • Rhino users' passwords

  • REM users' passwords

  • SSH keys for accessing the VM

  • the SNMPv3 authentication key and privacy key

Tip

Use the rvtconfig describe-versions command to view the exact version values provided by this-vm, this-rvtconfig, and sdf-version.

If the CDS is not yet available, this will retry every 30 seconds for up to 15 minutes. As a large Cassandra cluster can take up to one hour to form, this means the command could time out if run before the cluster is fully formed. If the command still fails after several attempts over an hour, troubleshoot Cassandra on the machines hosting the CDS database.

This command first compares the configuration files currently uploaded for the target version with those in the input directory. It summarizes which files are different, how many lines differ, and if there are any configuration changes that are unsupported (for example, changing the VMs' IP addresses). If there are any unsupported configuration changes, the config will not be uploaded. Follow the instructions in the error message(s) to revert unsupported changes in the configuration, then try again.

If the changes are valid, but any files are different, rvtconfig will prompt the user to confirm the differences are as expected before continuing with the upload. If the upload is canceled, and --output-dir is specified, then full details of any files with differences will be put into the given output directory, which rvtconfig creates if it doesn’t already exist.

Changes to secrets and non-YAML files cannot be detected due to encryption; they will not appear in the summary or detailed output. Any such changes will still be uploaded.

You can disable this pre-upload check on config differences using the --skip-diff flag (also aliased as -f).

Caution
Restarting resource adaptors

Specify the --reload-resource-adaptors option whenever you upload configuration where you have changed the values of any YAML configuration fields that require a restart of one or more Rhino resource adaptors (RAs).

The --reload-resource-adaptors option instructs initconf to restart RAs where required. USE THIS OPTION WITH CAUTION, as it will cause a short service outage across all nodes in the deployment. It is strongly advised that you only make changes requiring RA restarts during a maintenance window.

If you apply configuration changes that don’t include changes to any fields marked as needing an RA restart, then you do not need to specify the --reload-resource-adaptors option to rvtconfig upload-config.

If you apply configuration changes that include changes to such fields, and do not specify the --reload-resource-adaptors option, you may see Rhino alarms stating that restarting a certain resource adaptor(s) is required for configuration to take effect. You can clear these by manually restarting the affected RA(s), or Rhino itself, on the affected nodes at a convenient time.

Comparing existing configuration in the CDS with compare-config

Compare the configuration in an input directory with the currently uploaded configuration in the CDS using the command:

rvtconfig compare-config -c <cds-mgmt-addresses> -t <node type> -i ~/yamls --output-dir <output-directory>
[--deployment-id <deployment ID>] [--site-id <site ID>] [(--vm-version-source [this-vm | this-rvtconfig | sdf-version] | --vm-version <vm_version>)]

This will compare the currently uploaded configuration in the CDS with the configuration in the local input directory.

The deployment ID, site ID, and version of configuration to look up in CDS will be automatically taken from the SDF. These can be overridden by using the --deployment-id, --site-id, and one of the --vm-version-source or --vm-version parameters respectively. For example, you can specify --vm-version <downlevel version> to check what has changed just before running an upgrade, where the version in the input SDF will be the uplevel version.

The files that have differences will be displayed, along with the number of different lines, and any errors or warnings about the changes themselves. Any errors will need to be corrected before you can run rvtconfig upload-config.

The command puts the full contents of each version of these files into the output directory, along with separate files showing the differences found. The command ignores non-YAML files and any secrets in YAML files. The files in this output directory use the suffix .local for a redacted version of the input file, .live for a redacted version of the live file, and .diff for a file showing the differences between the two.

Note The contents of the files in the output directory are reordered and no longer have comments; these won’t match the formatting of the original input files, but contain the same information.

Deleting configuration from the CDS with delete-deployment

Delete all deployment configuration from the CDS by running the command:

rvtconfig delete-deployment -c <tsn-mgmt-addresses> -d <deployment-id> [--delete-audit-history]

Warning Only use this when advised to do so by a Customer Care Representative.
Warning Only use this after deleting all VMs of the deployment within the specified site. Functionality of all nodes of this type and version within the given site will be lost. These nodes will have to be deployed again to restore functionality.

Deleting state and configuration for a specific node type and version from the CDS with delete-node-type-version

Delete all state and configuration for a given node type and version from the CDS by running the command:

rvtconfig delete-node-type-version -c <tsn-mgmt-addresses> -d <deployment-id> --site-id <site-id> --node-type <node type>
(--vm-version-source [this-vm | this-rvtconfig | sdf-version -i ~/yamls] | --vm-version <vm_version>) (--ssh-key SSH_KEY | --ssh-key-secret-id SSH_KEY_SECRET_ID) [-y]

Note The argument -i ~/yamls is only needed if sdf-version is used.
Warning Only use this after deleting all VMs of this node type and version within the specified site. Functionality of all nodes of this type and version within the given site will be lost. These nodes will have to be deployed again to restore functionality.

Deleting all state and configuration for a specific node type from the CDS with delete-node-type-all-versions

Delete all state and configuration for a given node type from the CDS by running the command:

rvtconfig delete-node-type-all-versions -c <tsn-mgmt-addresses> -d <deployment-id> --site-id <site-id>
--node-type <node type> (--ssh-key SSH_KEY | --ssh-key-secret-id SSH_KEY_SECRET_ID) [--delete-certificates] [-y]

Warning Only use this after deleting all VMs of this node type within the specified site. Functionality of all nodes of this type within the given site will be lost. These nodes will have to be deployed again to restore functionality.
Warning The --delete-certificates option should only be used when advised by a Customer Care Representative.

Deleting historical state and configuration for a given node type from the CDS with delete-node-type-retain-version

Remove all state and configuration relating to a versions of the node type other than the specified version from CDS by running the command:

rvtconfig delete-node-type-retain-version -c <tsn-mgmt-addresses> -d <deployment-id> --site-id <site-id> --node-type <node-type>
(--vm-version-source [this-vm | this-rvtconfig | sdf-version -i ~/yamls] | --vm-version <vm_version>) (--ssh-key SSH_KEY | --ssh-key-secret-id SSH_KEY_SECRET_ID) [-y]

Note The argument -i ~/yamls is only needed if sdf-version is used.
Warning The version specified in this command must be the only running VM version for this node type. i.e. do not use during an upgrade or rollback when multiple versions of the same node type may be running. All state and configuration relating to other versions will be deleted from CDS.

Removing unused Rhino-generated keyspaces

Following an upgrade or rollback, you may wish to clean up keyspaces in the Cassandra ramdisk database from version(s) that are no longer in use. This conserves memory and disk space.

To clean up unused keyspaces, use the following command:

rvtconfig remove-unused-keyspaces -c <tsn-mgmt-addresses> -d <deployment-id> -g <group-id> [-y]

Note Group ID syntax: RVT-<node type>.<site ID>
Example: RVT-tsn.DC1
Here, <node type> can be tsn, shcm, mag, mmt-gsm, mmt-cdma or smo.

Confirm that the active VM versions that the command identifies are correct. rvtconfig removes keyspaces relating to all other versions from Cassandra.

Listing configurations available in the CDS with list-config

List all currently available configurations in the CDS by running the command:

rvtconfig list-config -c <tsn-mgmt-addresses> -d <deployment-id>

This command will print a short summary of the configurations uploaded, the VM version they are uploaded for, and which VMs are commissioned in that version.

Retrieving configuration from the CDS with dump-config

Retrieve the VM group configuration from the CDS by running the command:

rvtconfig dump-config -c <tsn-mgmt-addresses> -d <deployment-id> --group-id <group-id>
(--vm-version-source [this-vm | this-rvtconfig | sdf-version -i ~/yamls -t <node type>] | --vm-version <vm_version>)
[--output-dir <output-dir>]

Note Group ID syntax: RVT-<node type>.<site ID>
Example: RVT-tsn.DC1
Here, <node type> can be tsn, shcm, mag, mmt-gsm, mmt-cdma or smo.

If the optional --output-dir <directory> argument is specified, then the configuration will be dumped as individual files in the given directory. The directory can be expressed as either an absolute or relative path. It will be created if it doesn’t exist.

If the --output-dir argument is omitted, then the configuration is printed to the terminal.

Note The arguments -i ~/yamls and -t <node type> are only needed if sdf-version is used.

Displaying the current leader seed with print-leader-seed

Display the current leader seed by running the command:

rvtconfig print-leader-seed -c <tsn-mgmt-addresses> -d <deployment-id> --group-id <group-id>
(--vm-version-source [this-vm | this-rvtconfig | sdf-version -i ~/yamls -t <node type>] | --vm-version <vm_version>)

Note Group ID syntax: RVT-<node type>.<site ID>
Example: RVT-tsn.DC1
Here, <node type> can be tsn, shcm, mag, mmt-gsm, mmt-cdma or smo.

The command will display the current leader seed for the specified deployment, group, and VM version. A leader seed may not always exist, in which case the output will include No leader seed found. Conditions where a leader seed may not exist include:

  • No deployment exists with the specified deployment, group, and VM version.

  • A deployment exists, but initconf has not yet initialized.

  • A deployment exists, but the previous leader seed has quiesced and a new leader seed has not yet been selected.

Note The arguments -i ~/yamls and -t <node type> are only needed if sdf-version is used.

Generating a secrets-private-key for Encrypting Secrets with generate-private-key

Some configuration, for example Rhino or REM users' passwords, are configured in plaintext, but stored encrypted in CDS for security. rvtconfig automatically performs this encryption using a secrets private key which you configure in the SDF. This key must be a Fernet key, in Base64 format. Use the following rvtconfig command to generate a suitable secrets private key:

rvtconfig generate-private-key

Add the generated secrets private key to your secrets input file when UNRESOLVABLE BXREF: sdf-secrets#adding-secrets[adding secrets to QSG].

Maintenance window support

The rvtconfig enter-maintenance-window and rvtconfig leave-maintenance-window commands allow you to pause and resume UNRESOLVABLE BXREF: scheduled-tasks[scheduled tasks] (Rhino restarts, SBB/activity cleanup, and Cassandra repair) on the VMs for a period of time. This is useful to avoid the scheduled tasks interfering with maintenance window activities, such as patching a VM or making substantial configuration changes.

To start a maintenance window, use

rvtconfig enter-maintenance-window -c <tsn-mgmt-addresses> -d <deployment-id> -S <site-id> [--hours <hours>]

  • The <site-id> is in the form DC1 to DC32. It can be found in the SDF.

  • The number of hours defaults to 6 if not specified, and must be between 1 and 24 hours.

Once started, the maintenance window can be extended by running the same command again (but not shortened). rvtconfig will display the end time of the maintenance window in the command output. Until this time, all scheduled tasks on all VMs in the specified site will not be run.

Warning

Any scheduled tasks which are in progress at the time the maintenance window is started will continue until they are finished. If the maintenance window is starting around the time of a scheduled task as configured in the YAML files, it is advisable to manually check that the task is complete before starting maintenance (or run the rvtconfig enter-maintenance-window command in advance of the scheduled task time).

When the maintenance window is complete, use the following command:

rvtconfig leave-maintenance-window -c <tsn-mgmt-addresses> -d <deployment-id> -S <site-id>

Scheduled tasks will now resume as per their configured schedules.

To check whether or not a maintenance window is currently active, use the following command:

rvtconfig maintenance-window-status -c <tsn-mgmt-addresses> -d <deployment-id> -S <site-id>

Calculating the required length of a maintenance window with calculate-maintenance-window

The rvtconfig calculate-maintenance-window commands allows you to estimate how long an upgrade or rollback is expected to take, so that an adequate maintenance window can be scheduled.

To calculate the recommended maintenance window duration, use

rvtconfig calculate-maintenance-window -i ~/yamls -t <node type> -s <site-id> [--index-range <index range>]

  • The <site-id> is in the form DC1 to DC32. It can be found in the SDF.

  • If --index-range is not specified, a maintenance window for upgrading all VMs will be calculated. If only some VMs are to be upgraded, specify the --index-range argument exactly as it will be specified for the csar update command to be used to upgrade the subset of VMs. For example, if only nodes with indices 0, 3, 4 and 5 are to be upgraded, the argument is --index-range 0,3-5.

Retrieving VM logs with export-log-history

During upgrade, when a downlevel VM is removed, it uploads Initconf, Rhino and SGC logs to the CDS. The log files are stored as encrypted data in the CDS.

Note Only the portions of the logs written during quiesce are stored.

Retrieve the VM logs for a deployment from the CDS by running the command:

rvtconfig export-log-history -c <tsn-mgmt-addresses> -d <deployment-id> --zip-destination-dir <directory>
--secrets-private-key-id <secrets-private-key-id>

Note The --secrets-private-key-id must match the ID used in the SDF (secrets-private-key-id).
Note The Initconf, Rhino and SGC logs are exported in unencrypted zip files. The zip file names will consist of VM hostname, version, and type of log.

Viewing the values associated with the special sdf-version, this-vm, and this-rvtconfig versions with describe-versions

Some commands, upload-config for example, can be used with the special version values sdf-version, this-vm, and this-rvtconfig.

  • Calling sdf-version extracts the version from the value given in the SDF for a given node.

  • The this-vm option takes the version of the VM the command is being run from. This can only be used when the commands are run on a node VM.

  • Using this-rvtconfig extracts the version from the rvtconfig found in the directory the command is being run from. This can only be used on a SIMPL VM.

To view the real version strings associated with each of these special values:

rvtconfig describe-versions [-i ~/yamls]

Optional argument -i ~/yamls is required for the sdf-version value to be given. If it is called, the sdf-version will be found for each node type in the SDF. If a node type is expected but not printed this may be because the config yaml files for that node are invalid or not present in the ~/yamls directory.

If a special version value cannot be found, for example if this-vm is run on a SIMPL VM or the optional argument is not called, the describe-versions command will print N/A for that special version.

Reporting group status, to help guide VM recovery

This command reports the status of each node in the given group, providing information to help inform which approach to take when recovering VMs.

It connects to each of the VMs in the group via SSH, as well as querying the CDS service. It then prints a detailed summary of status information for each VM, as well as a high level summary of the status of the group.

It does not log its output to a file. When using this command to aid in recovery operations, it’s good practice to redirect its output to a file locally on disk, which can then be used as part of any root cause analysis efforts afterwards.

On the SIMPL VM, run the command as follows, under the resources dir of the unpacked CSAR:

./rvtconfig report-group-status -c <cds-mgmt-addresses> -d <deployment-id> \
  --g <group-id> --ssh-key-secret-id <simpl-private-key-id>
Note Group ID syntax: RVT-<node type>.<site ID>
Example: RVT-tsn.DC1
Here, <node type> can be tsn, shcm, mag, mmt-gsm, mmt-cdma or smo.

Gathering diagnostics and initconf log files

It is possible to obtain diagnostic files from RVT nodes with the command rvtconfig gather-diags. These diagnostic files include system files and solution configuration files, are packaged as a tar.gz file and deposited in the given output directory. Depending on the node type there will be different kinds of solution configuration files. These files can be crucial to troubleshoot problems on the VMs.

./rvtconfig gather-diags --sdf <SDF File> -t <node type> --ssh-key-secret-id <SSH key secret ID> --ssh-username sentinel --output-dir <output-directory>

If you need to quickly check the initconf.log file from a certain VM or VMs, it is possible to do it with the command rvtconfig initconf-log. This command executes a tail on the initconf.log file of the specified VM or VMs and dumps it to the standard output.

rvtconfig initconf-log --ssh-key-secret-id <SSH key secret ID> --ssh-username sentinel --ip-addresses <Space separated VM IP address list> --tail <num lines>

Operate the TSN Cassandra Database

From RVT 4.1-3-1.0.0, the TSN nodes can be deployed with Cassandra version {cassandra-version-three} or {cassandra-version-four}. Both Cassandra versions are installed in the VM Image, but only one is active. The commands rvtconfig cassandra-upgrade and rvtconfig cassandra-upgrade-sstables allow you to perform a Cassandra upgrade from {cassandra-version-three} to {cassandra-version-four} on a running TSN VM 4.1-3-1.0.0 or higher. These two commands must only be run if the target TSNs are running Cassandra {cassandra-version-three}.

To upgrade a single TSN node from {cassandra-version-three} to {cassandra-version-four} you can run ./rvtconfig cassandra-upgrade --ssh-key-secret-id <SSH key secret ID> --ip-addresses <TSN Address> for every TSN VM, one by one, and not in parallel.

Once all TSN nodes have been upgraded to {cassandra-version-four}, we must perform a sstables upgrade operation with the following command ./rvtconfig cassandra-upgrade-sstables --ssh-key-secret-id <SSH key secret ID> --ip-addresses <TSN Addresses>

Additionally the command rvtconfig cassandra-status prints the cassandra database status for the specified CDS IP addresses. Here is a couple of examples:

  • ./rvtconfig cassandra-status --ssh-key-secret-id <SSH key secret ID> --ip-addresses <TSN Address 1> <TSN Address 2> …​

CDS Backup and Restore operations.

From RVT 4.1-3-1.0.0, the TSNs' CDS database can be backed up and restored. This provides a faster recovery procedure in case TSN upgrades go wrong.

To backup the CDS of a running TSN cluster, run ./rvtconfig backup-cds --sdf /home/admin/uplevel-config/sdf-rvt.yaml --site-id <site ID> --output-dir <backup-cds-bundle-dir> --ssh-key-secret-id <SSH key secret ID> -c <CDS address> <CDS auth args>

To restore the CDS of a running TSN cluster, run ./rvtconfig restore-cds --sdf /home/admin/uplevel-config/sdf-rvt.yaml --site-id <site ID> --snapshot-file <backup-cds-bundle-dir>/tsn_cassandra_backup.tar --ssh-key-secret-id <SSH key secret ID> -c <CDS Address> <CDS auth args>

Warning Only use restore-cds when advised to do so by a Customer Care Representative.

Control initconf configuration loop in non-TSN nodes.

During maintenance windows which involve upgrading TSN nodes, the command rvtconfig set-desired-running-state allows you stop/start the configuration tasks performed by the initconf that read from the CDS database in all non-TSN VMs. This operation does not stop the non-TSN VMs or the initconf process within it. But it instructs the initconf to pause or resume, the configuration tasks, while operating normally under traffic.

To pause initconf configuration tasks of all non-TSN VMs, run ./rvtconfig set-desired-running-state --sdf /home/admin/uplevel-config/sdf-rvt.yaml --site-id <site ID> --state Stopped.

To resume initconf configuration tasks of all non-TSN VMs, run ./rvtconfig set-desired-running-state --sdf /home/admin/uplevel-config/sdf-rvt.yaml --site-id <site ID> --state Started.

RVT system configuration

This section describes how to set up the Rhino VoLTE TAS system.

In this section

The platform

Set the platform operator name

Within common-config.yaml, in the common section, set your platform operator name:

  platform-operator-name: Metaswitch

Configure session replication

Session replication allows established calls to continue if the node that previously processed the call becomes unavailable.

Within either sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config, in the sentinel-volte section, set session-replication-enabled

      session-replication-enabled: true

If enabling on a system where session replication was previously disabled, please contact Metaswitch support.

Review the SIP session settings

Within either sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config, in the session-refresh section, check that these values are appropriate and change if necessary.

    # Configuration for the Session Refresh feature.
    session-refresh:
        # The interval of the periodic timer (in seconds).
        timer-interval-seconds: 30

        # Period of no activity for leg tp refresh (in seconds).
        refresh-period-seconds: 570

        # Whether the session should be refreshed using UPDATE requests,
        # as long as the endpoint allows UPDATE requests.
        refresh-with-update-if-allowed: true

        # Maximum allowed duration of a call (in seconds).
        max-call-duration-seconds: 86400

Configuring integration within the system

For each node type deployed, you need to configure the names of the cluster and individual virtual machines using data from the node type’s site definition files (SDF) which were created as part of the VM Install process. In some cases you also need to configure user access and node specific integration parameters.

References and example files

Node type Example YAML Reference

MAG

mag-vmpool-config.yaml

mag-virtual-machine-pool

MMT (CDMA)

mmt-cdma-vmpool-config.yaml

mmt-cdma-virtual-machine-pool

MMT (GSM)

mmt-gsm-vmpool-config.yaml

mmt-gsm-virtual-machine-pool

SHCM

shcm-vmpool-config.yaml

shcm-virtual-machine-pool

TSN

tsn-vmpool-config.yaml

tsn-virtual-machine-pool

SMO

smo-vmpool-config.yaml

smo-virtual-machine-pool

Parameters

This table cross references the node types and which parameters need configuring.

Parameter

Applicable node types

MAG

MMT GSM

MMT CDMA

SHCM

TSN

SMO

deployment-id

✔

✔

✔

✔

✔

✔

site-id

✔

✔

✔

✔

✔

✔

node-type-suffix

✔

✔

✔

✔

✔

✔

cassandra-contact-points

✔

✔

✔

✔

✔

additional-rhino-jvm-options

✔

✔

✔

✔

✔

rhino-auth

✔

✔

✔

✔

✔

rem-auth

✔

✔

✔

✔

✔

xcap-domains

✔

Per node parameters

vm-id

✔

✔

✔

✔

✔

✔

rhino-node-id

✔

✔

✔

✔

scheduled-rhino-restarts

✔

✔

✔

✔

✔

per-node-diameter-rf

✔

✔

per-node-diameter-ro

✔

✔

✔

diameter-zh-origin-host

✔

diameter-sh-origin-host

✔

sip-local-uri

✔
deployment-id and site-id

deployment-id and site-id must be set to match the parameters of the same name in the SDFs created as part of the VM Installation process.

node-type-suffix

Leave the node-type-suffix blank unless directed otherwise by Metaswitch support.

cassandra-contact-points

Leave the cassandra-contact-points blank unless directed otherwise by Metaswitch support.

additional-rhino-jvm-options

Leave the additional-rhino-jvm-options blank unless directed otherwise by Metaswitch support.

rhino-auth and rem-auth

Some node types have lists of rhino-auth and/or rem-auth authentication data. These are used to access rhino and rem respectively. See the appropriate reference for details.

Per node parameters

These parameters are in a list called virtual-machines, with one entry per VM.

vm-id

The vm-id values under virtual-machines must be the same as the name values under instances in the SDF.

rhino-node-id

For nodes supporting a Rhino cluster, specify the node-id for the Rhino rhino-node-id on each VM.

scheduled-rhino-restarts

For nodes that run Rhino, you can optionally specify that Rhino should be automatically restarted on a regular schedule. This can be useful if you observe resource leaks (memory, file handles, activities, and so on) in Rhino which require a restart to clean up the leftover resources.

The available options for scheduled restarts are daily, weekly, or monthly schedules. The following shows example configuration for each:

# a daily schedule
scheduled-rhino-restarts:
    time-of-day: "02:00"

# or, a weekly schedule
scheduled-rhino-restarts:
    time-of-day: "02:00"
    day-of-week: "Wednesday"

# or, a monthly schedule
scheduled-rhino-restarts:
    time-of-day: "02:00"
    day-of-month: 9
Note

  • day-of-week takes a full English weekday name (Sunday through to Saturday).

  • day-of-month takes a value between 1 and 28.

  • time-of-day must be specified in the 24-hour clock, with leading zeros, in the VMs' timezone.

  • Be sure to quote the time-of-day value, since it is a string value but is misinterpreted as a number by rvtconfig validation if quotes are not used.

  • All VMs of a particular type must have restarts enabled, or all must have them disabled. Likewise, they must all use the same schedule type (daily, weekly or monthly).

  • It is not permitted to schedule two VMs of the same type to restart at the same time, or within 30 minutes of each other. This is to ensure that at most one node is down at a time, and hence the cluster remains at full capacity at all times (production deployments should be sized to have at least one redundant node in the cluster).

  • Rhino will be restarted at the scheduled time regardless of whether or not it is running. If you plan to carry out maintenance involving stopping Rhino at the time of the restart, consider temporarily reconfiguring the VM to disable restarts, and re-enabling restarts again after the maintenance is complete.

To disable automatic Rhino restarts, omit the scheduled-rhino-restarts section from the configuration. By default, restarts are disabled.

per-node-diameter-rf and per-node-diameter-ro

To set the origin-host value for Diameter Rf per-node-diameter-rf and Diameter Ro per-node-diameter-ro protocols, see Charging.

diameter-zh-origin-host

To set the origin-host value for Diameter Zh protocol diameter-zh-origin-host, see Diameter Zh interface.

diameter-sh-origin-host

To set the origin-host value for Diameter diameter-sh-origin-host Sh protocol, see Diameter Sh interface.

sip-local-uri

Set a per node local URI sip-local-uri to use for SIP: protocol.

Integration with other systems

The Rhino VoLTE TAS requires integration with several other services in an IMS network to utilize its full capability. This section discusses the several configuration options to integrate Rhino VoLTE TAS operations with other parts of the network. You will usually find the information required in your network design/topology document.

In this section

What it does

Integration of the Rhino VoLTE TAS to your network involves editing interface specific addresses and values for the relevant Rhino VoLTE TAS YAML configurations that are being used. For example, a VoLTE network with GSM networking support will require configuration changes to the sentinel-volte-gsm-config.yaml file. If there is an interface that is left unused by the network, it can be disabled by deleting or commenting out the specific interface’s section.

Further information on how to specify and edit configuration YAML files is specified in the guide on how to use the declarative configuration system. In addition, there are further options available beyond system integration, such as tuning message timeouts, in the configuration reference guide.

Important The example configurations in this section use valid, but placeholder, values that will not work with your network. You will need to replace the values according to your network setup.

I-CSCF integration

The Rhino VoLTE TAS requires access to the I-CSCF (Interrogating Call Session Control Function) to integrate into the IMS network.

What you need

  • ❏ The network’s I-CSCF URI address.

Setting up the I-CSCF interface

The configuration for the I-CSCF to Rhino VoLTE TAS interface is in the icscf-config.yaml file.

In the icscf section, configure the i-cscf-uri value. The example configuration given here indicates input for what is needed for integrating the Rhino VoLTE TAS with the network’s I-CSCF.

icscf-config.yaml 
icscf:

  # The URI of the Interrogating Call Session Control Function.
  # For MMT, the Conf and ECT features will automatically add an "lr" parameter to it.
  # The hostname part should either be a resolvable name or the IP address of the I-CSCF.
  i-cscf-uri: sip:icscf@icscfhost.example:5060

ATCF integration

The Rhino VoLTE TAS requires integration with the ATCF (Access Transfer Control Function) in the IMS network for SCC AS functionality.

What you need

  • ❏ A Session Transfer Number for SRVCC (STN-SR) to allocate to the SCC AS.

Setting up the ATCF interface

The configuration for the ATCF to Rhino VoLTE TAS interface is in the sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml file.

In the service-continuity section, configure the stn-sr values. The example configuration given here indicates input for what is needed for integrating the Rhino VoLTE TAS with the network’s ATCF.

sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml 
sentinel-volte:

    scc:

        # Service continuity configuration.
        service-continuity:

            # STN-SR.
            stn-sr: "6421999999"

SS7 integration

To communicate with the SS7 protocols in a network, you need to set up the SS7 signaling gateway client (SGC).

Integration with the Rhino VoLTE TAS and IN interfaces requires an SCCP address assigned to it.

Setting up the SS7 SGC

The SS7 SGC in the Rhino VoLTE TAS provides support for communicating with the SS7 protocols in a network. The configuration for it is located in the sgc-config.yaml file.

If the SGC is being reconfigured after its initial configuration has been applied, you need to follow the steps in Reconfiguring the SGC before applying the new configuration.

M3UA interface configuration

The SGC uses the M3UA (MTP Level 3 User Adaptation Layer) interface for handling networking between the Rhino VoLTE TAS and the network’s SS7 signaling.

General configuration

This configuration determines what the SGC’s attributes are for SS7 signaling. This will be what systems outside of the Rhino VoLTE TAS require to direct SS7 signaling towards the SGC.

What you need

The following must be defined in the configuration:

  • ❏ The local-port M3UA endpoint used for SS7 signaling.

  • ❏ The sccp-variant used by the SGC. Either ITU or ANSI.

  • ❏ The Rhino VoLTE TAS’s local point-code.

The following may be defined in the configuration:

  • ❏ The value for the national indicator to use for SCMG (SCCP management) messages.

    • This would override the defaults of INTERNATIONAL for ITU-T SCCP, and NATIONAL for ANSI SCCP.

  • ❏ The value for the M3UA network-indicator field.

    • This would override the default of INTERNATIONAL

Example configuration

The example configuration given in the snippet below sets the SGC in the Rhino VoLTE TAS to:

  • Have the SGC’s local endpoint port at 2905

  • Use the ITU variant for SCCP addresses

  • Have a local point code of 5

  • The default national indicator for ITU-T SCCP messages is used — which is INTERNATIONAL

  • The default network-indicator field is used, which is INTERNATIONAL.

sgc-config.yaml 
deployment-config:sgc:
  m3ua:
    local-port: 2905
    sccp-variant: ITU
    point-code: "5"
Note The supported format of the point code depends on the sccp-variant. Contact Metaswitch support for further details if you would like to use these other forms.
If sccp-variant is…​ format of point-code is…​ Example

ANSI

- separated triplets, network-cluster-member format

0-0-5

ITU

simple numeric, quoted

"5"

Remote peer configuration

For details on how to configure remote peers in the Rhino VoLTE TAS, see SGC M3UA remote peer addresses.

Global title translation configuration

For details on how to configure global title translation in the Rhino VoLTE TAS, see SGC M3UA global title translation.

SGC properties

The Rhino VoLTE TAS supports further configuration of the SGC via the sgc-properties field. This field offers additional configuration of the SGC beyond the given declarative configuration.

For further configuration of the SGC, contact Metaswitch support for more details.

sgc-config.yaml 
deployment-config:sgc:
  sgc-properties:

Hazelcast

The Rhino VoLTE TAS supports using Hazelcast for communication in the cluster of subsystems in the SS7 SGC stack. The declarative configuration in the hazelcast section allows for:

  • the number of backup instances in the cluster to be defined.

Warning Unless specified by Metaswitch support, the backup-count must be left unspecified. If incorrectly set, the cluster can experience data loss. The Rhino VoLTE TAS’s VMs will default to a valid and working backup-count.

  • an optional password for the Hazelcast subsystem.

Note The password will be automatically encrypted using the secrets-private-key configured in the site definition file (SDF).
sgc-config.yaml 
deployment-config:sgc:
  hazelcast:
    backup-count:
    password:

For further configuration of using Hazelcast in the SGC, contact Metaswitch support for more details.

sgcenv

The declarative configuration supports configuring the port for which the internal sgc CLI in the SMO nodes is binded to. This is set in the jmx-port field.

sgc-config.yaml 
deployment-config:sgc:
  sgcenv:
    jmx-port: 55555

What you need

  • ❏ An SS7 point code for the site.

  • ❏ A unique SCCP address to be the originating address for IN signalling for the Rhino VoLTE TAS.

Setting up for IN interfaces

The configuration for the IN signaling to the Rhino VoLTE TAS is in the sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml file.

In the service-centralisation section, configure the inbound-ss7-address value. The example configuration given here indicates input for what is needed for integrating the Rhino VoLTE TAS with the SS7 network.

sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml 
sentinel-volte:

    # Service Centralisation configuration.
    service-centralisation:

      # The SCCP address of the Sentinel VoLTE AS.
      inbound-ss7-address: type=C7,ri=gt,ssn=146,nature=INTERNATIONAL,numbering=ISDN,tt=0,digits=123456
Warning If the inbound-ss7-address contains a pc= parameter, that parameter’s value must be the same as the point-code value in sgc-config.yaml. See General configuration.

The SS7 point code needs to be used consistently in other places.

  • In sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml file, if the inbound-ss7-address value contains a pc= parameter, that parameter’s value must be the same as the point-code value in sgc-config.yaml.

  • In sentinel-ipsmgw-config.yaml file, if the originating-address value contains a pc= parameter, that parameter’s value must be the same as the point-code value in sgc-config.yaml. For more details, see step 3 of IP-SM-GW Initial configuration.

Note Do not quote the point code in SCCP addresses, e.g. use pc=5, not pc="5". Quoting is only required when the point code is a standalone field value in a YAML configuration file.

There are also requirements for assigning SSNs correctly. Contact Metaswitch support for details.

SGC M3UA remote peer addresses

The Rhino VoLTE TAS SGC requires the configuration of the networking details of its remote peers. These remote peers host application servers (AS) that interact with the Rhino VoLTE TAS’s SS7 signaling.

What you need

  • ❏ The remote peer addresses that act as the signal transfer points (STP) in the network.

  • ❏ The AS(s) accessible via these remote peer addresses.

  • ❏ The AS destination point code(s) (DPC).

  • ❏ The subsystem number(s) (SSN) to monitor for each of the DPCs.

Remote peer configuration

The remote M3UA peer application servers in the network are designated in the peers section. Multiple remote peers to the Rhino VoLTE TAS’s SGC can be defined here.

What you need

For each remote M3UA AS peer, define the following:

  • ❏ A unique id for each remote peer.

  • ❏ The set of IPv4 addresses that belong to the server peer. This is defined in remote-ips.

  • ❏ Whether a specific SMO node or any SMO node in the Rhino VoLTE TAS should communicate with the peer’s set of IP addresses. This is defined in node-index.

  • ❏ At least one AS ID defined in as-id which is related to the remote peer. This is defined in application-servers.

Optional configuration may include:

  • ❏ The port for the remote peer.

  • ❏ Whether the SGC takes an active role in M3UA state maintenance or not with the peer. This is set in the state-maintenance-role field.

  • ❏ Whether the SGC connects to the remote peer (client mode) or waits for a connection from the remote peer (server mode). This is set in the conn-type field.

  • ❏ Whether the SGC is an IP server Process (IPSP) for the peer or not. This is set in the is-ipsp field.

  • ❏ Whether to define the asp-id to use in ASP-UP/DOWN messages.

  • ❏ For a specified AS as-id, whether to send Destination State Audit (DAUD) when the Application Server Process (ASP) goes active in this AS. This is set in the daud-on-asp-ac field.

Example configuration

In the following example snippet, two remote peers are configured.

They are both configured to:

  • the same port number of 2906

  • have no restriction on what SMO node in the Rhino VoLTE TAS they can communicate with

  • correspond to the same AS identifier that is defined in the application-servers example

  • each have their own distinct sets of IP addresses.

sgc-config.yaml 
deployment-config:sgc:
  m3ua:
    remote:
      peers:
        - id: 'STP-1'
          remote-ips:
            - node-index: -1
              ips:
                - 10.14.144.71
                - 10.14.144.134
          port: 2906
          application-servers:
            - as-id: 'NN-AS'

        - id: 'STP-2'
          remote-ips:
            - node-index: -1
              ips:
                - 10.14.144.81
                - 10.14.144.144
          port: 2906
          application-servers:
            - as-id: 'NN-AS'

Defined application servers

The SGC interacts with known application server(s) for routing SS7 signaling. These ASs are accessible on the remote peer addresses configured in peers. The declarative configuration defines these ASs in the application-servers list.

What you need

For each M3UA AS hosted on these remote peers, define the following:

  • ❏ A unique id for each AS that the SGC interacts with. This value is only used by the declarative configuration and is not exposed externally.

  • ❏ A default-priority for any routes for the AS.

  • ❏ The list of dpc-ids that may be accessible from the AS. This includes for each DPC:

    • ❏ The internal unique identifier for the DPC — defined in id.

    • ❏ The priority for each DPC (this is optional and overrides the default priority).

Optional configuration may include:

  • ❏ Whether the AS would assume an active or passive traffic-maintenance-role.

  • ❏ Whether the AS has a routing-context.

  • ❏ Whether to not allow the AS to be become active until there is at least one connected TCAP for each specified SSN. This is accessed in the precond-ssns field.

Example configuration

In the following example snippet, the SGC is configured to communicate with one AS.

The AS connection is configured:

  • to have the 'NN-AS' identifier, connecting it with the two remote peers as configured the peers example

  • to have a default priority integer of '5' for routing

  • that the AS itself has a DPC alias 'alias-2-233-3' as managed by the configuration in dpcs.

sgc-config.yaml 
deployment-config:sgc:
  m3ua:
    remote:
      application-servers:
        - id: 'NN-AS'
          routes:
            default-priority: 5
            dpc-ids:
              - id: 'alias-2-233-3'

Defined DPCs

The SGC interacts with known DPCs for routing SS7 signaling through application servers. Multiple DPCs can be defined in the dpcs section.

What you need

For each designated DPC in the network interacting with the SGC, we must define:

  • ❏ The dpc itself.

  • ❏ A unique identifier for the DPC which is used for the AS routing configuration in dpc-ids. This value is only used by the declarative configuration and is not exposed externally. This is defined in the id field.

Optional configuration may include the DPC’s:

  • ❏ network-appearance.

  • ❏ muss (Maximum unsegmented SCCP message size)

  • ❏ mss (Maximum user data length per segment)

  • ❏ preferred unitdata message type (pudt): either UDT or XUDT.

Example configuration

In the following example snippet, the SGC is configured to communicate with a remote DPC used by the AS.

SGC has the remote DPC configured to have:

  • an configuration specific identifier of the configured DPC 'alias-2-233-3' to connect to the AS configuration

  • an actual DPC code of 5963

  • a DPC MUSS of 252

  • a DPC MSS of 245.

Tip

For ITU variant, specify point codes as quoted integers, e.g. "5963".

For ANSI variant, specify point codes in network-cluster-member format, e.g 2-233-3.
sgc-config.yaml 
deployment-config:sgc:
  m3ua:
    remote:
      dpcs:
        - id: 'alias-2-233-3'
          dpc: "5963"
          muss: 252
          mss: 245

Concerned point code notifications

The defined Concerned Point Codes (CPCs) are specified DPCs that are notified if a local SSN status changes. Multiple CPCs can be defined in the cpcs section.

What you need

For each designated CPC in the network which we want to configure, we must define:

  • ❏ A dpc to notify

  • ❏ The ssns to monitor for that DPC.

Example configuration

In the following example snippet, the SGC is configured to communicate with a remote CPC.

SGC has the remote CPC configured to have:

  • an actual DPC code of 5963

  • the SGC is to monitor the SSNs 8 and 146 for that DPC.

sgc-config.yaml 
deployment-config:sgc:
  m3ua:
    remote:
      cpcs:
        - dpc: "5963"
          ssns:
            - 8
            - 146

Setting up SGC M3UA remote peer addresses

I want to …​

Connect any sized SGC cluster to a dual-homed dual-node STP cluster

There are two peer STP nodes to configure for the remote-peers.

An any sized SGC cluster connected to a dual-homed dual-node STP cluster

  • Add the set of IP addresses for each STP node to the ips list.

  • Ensure that any SGC instance can connect to the STP cluster by setting for each remote peer their node-index to -1.

  • Add the declarative configuration’s internal unique identifer of the STP AS to both remote peers' application-servers.

deployment-config:sgc:
  m3ua:
    remote:
      peers:
        - id: 'to-STP-1-node-1'
          remote-ips:
            # All SGCs have connections to this member of the STP pair.
            - node-index: -1
              ips:
                - 10.2.0.1
                - 10.3.0.1
          application-servers:
            # This STP is a member of AS 'STP-1'
            - as-id: 'STP-1'
        - id: 'to-STP-1-node-2'
          remote-ips:
            # All SGCs have connections to this member of the STP pair.
            - node-index: -1
              ips:
                - 10.2.0.2
                - 10.3.0.2
          application-servers:
            # This STP is a member of AS 'STP-1'
            - as-id: 'STP-1'

For configuring the STP cluster’s DPC, add:

  • The declarative configuration’s identifier for the STP’s DPC in the id field.

  • The actual DPC itself in the dpc field.

deployment-config:sgc:
  m3ua:
    remote:
      dpcs:
        - id: "DPC-2"
          dpc: "2"

There is one AS operating on the STP cluster to configure for.

For the AS’s route configuration, add:

  • The default-priority for routing messages.

  • The declarative configuration’s identifier for the STP’s DPC in the AS’s dpc-ids list.

deployment-config:sgc:
  m3ua:
    remote:
      peers:
      application-servers:
        - id: 'STP-1'
          routes:
              default-priority: 5
              dpc-ids:
                # The STP's own DPC.
                - id: 'DPC-2'
Connect an SGC cluster to two separate STPs that are connected to a remote peer used in load balancing mode

There are two peer STP nodes to configure for the remote-peers.

An SGC cluster connected to two separate STPs and via them a remote peer used for load balancing

  • Add the set of IP addresses for each STP node to the ips list.

  • Ensure that any SGC instance can connect to the STP cluster by setting for each remote peer their node-index to -1.

  • Add the declarative configuration’s internal unique identifer each STP’s AS to their respective remote peer configuration application-servers field.

deployment-config:sgc:
  m3ua:
    remote:
      peers:
        - id: 'to-STP1'
          remote-ips:
            # All SGCs have connections to this STP.
            - node-index: -1
              ips:
                - 10.2.0.1
                - 10.3.0.1
          application-servers:
            # This STP is a member of AS 'STP-1'
            - as-id: 'STP-1'
        - id: 'to-STP-1-node-2'
          remote-ips:
            # All SGCs have connections to this STP.
            - node-index: -1
              ips:
                - 10.4.0.1
                - 10.5.0.1
          application-servers:
            # This STP is a member of AS 'STP-2'
            - as-id: 'STP-2'

For configuring each STP’s DPC, add:

  • The declarative configuration’s identifier for each STP’s DPC in the id field.

  • The actual DPC itself in dpc field.

deployment-config:sgc:
  m3ua:
    remote:
      dpcs:
        - id: 'DPC-2'
          dpc: '2'
        - id: 'DPC-3'
          dpc: '3'
        - id: 'DPC-4'
          dpc: '4'

There are two application servers operating on the STP cluster to configure for.

For each AS’s route configuration, add:

  • The default-priority for routing messages.

  • The declarative configuration’s identifier for each STP’s DPC in the AS’s dpc-ids list.

deployment-config:sgc:
  m3ua:
    remote:
      application-servers:
        - id: 'STP-1'
          routes:
            default-priority: 5
            dpc-ids:
              # The STP's own DPC.
              - id: 'DPC-3'
              # Add further DPC IDs here if the SGC should send DAUD for them (accessed via this STP).
              - id: 'DPC-4'
        - id: 'STP-2'
          routes:
            default-priority: 5
            dpc-ids:
              # The STP's own DPC.
              - id: 'DPC-2'
              # Add further DPC IDs here if the SGC should send DAUD for them (accessed via this STP).
              - id: 'DPC-4'

SGC M3UA global title translation

The SGC translates global titles (GTs) in incoming and outgoing SCCP messages. The Rhino VoLTE TAS supports creating specialized rules for translating these inbound and outbound messages.

Inbound GT translation

The SGC determines how GT translation occurs for inbound SCCP messages. Multiple incoming called addresses can be configured for the SGC.

For where the incoming called address for an SCCP message is a GT, it is:

  • matched against the configuration to determine whether it should be processed, and

  • may then determine which SSN should receive it.

Configuration

The configuration for the inbound GT translation matching rules are in the inbound section.

For matching inbound called addresses, you may configure:

  • ❏ A unique id for the address for the configuration. This value is only used by the declarative configuration and is not exposed externally.

  • ❏ The called party address information to match on the inbound SCCP message digits. This is defined in the addrinfo field.

  • ❏ For matching the incoming address, whether to allow the address information to match on the prefix or have to match the entire address. This is set in the is-prefix field.

  • ❏ The SCCP message’s nature of address (natofaddr) code required for a match. The code is defined in the RFC 3868 Global Title Section.

  • ❏ The SCCP message’s numbering plan code (numplan) required for a match. The code is defined in the RFC 3868 Global Title Section.

  • ❏ The SCCP message’s translation type code (trtype) required for a match. The code is defined in the RFC 3868 Global Title Section.

  • ❏ The local ssn to route matched messages towards.

Setting up inbound GT translation

I want to …​
Send all inbound SCCP CdPA which have addressed digits=123456, in an international number format, in an ISDN numbering plan, and an unknown translation type to SSN 146

In the global-title, inbound section, add the inbound matching rule with a unique identifier.

Ensure that the following are set for the inbound rule:

  • id.

  • addrinfo is set to digits 123456.

  • is-prefix is set to false as we are only accepting an exact match.

  • natofaddr corresponds to Nature of Address for international numbers.

  • numplan corresponds to the numbering plan code for the ISDN numbering plan.

  • trtype corresponds- to the unknown translation type.

  • ssn.

deployment-config:sgc:
  m3ua:
    global-title:
      inbound:
        - id: 'to-sentinel-volte-gsm'
          addrinfo: '123456'
          is-prefix: false
          natofaddr: 4
          numplan: 1
          trtype: 0
          ssn: 146
Send inbound SCCP CdPA addressed to digits prefixed with 123456 to SSN 146

In the global-title, inbound section, add the inbound matching rule with a unique identifier.

    global-title:
      inbound:
        - id: 'inbound-rule-example'
          addrinfo: '123456'
          is-prefix: true
          ssn: 146
Send two different inbound SCCP CdPA addressed messages to different local SSNs

In the global-title, inbound section, add each inbound matching rule with their own unique identifiers.

In this case we have two inbound translation rules. For all inbound SCCP CdPA addressed to:

  • digits=1234567890, the message is sent to the local SSN 8.

      inbound:
      # All inbound SCCP CdPA addressed to digits=1234567890 will be sent to local SSN 8
        - id: 'SSN_6'
          addrinfo: '1234567890'
          is-prefix: false
          ssn: 8

  • digits=2143658709, the message is sent to the local SSN 146.

      inbound:
      # All inbound SCCP CdPA addressed to digits=2143658709 will be sent to local SSN 146
        - id: 'B'
          addrinfo: '2143658709'
          is-prefix: false
          ssn: 146

Outbound GT translation

The SGC determines how GT translation occurs for outbound SCCP messages. Multiple outgoing called addresses can be configured for the SGC.

When the outgoing SCCP called party address (SCCP CdPA) is set to ri=GT, global title translation function is invoked. The function uses the SCCP called party address to determine which destination point code (DPC) the M3UA layer should route the message to.

The parameters of the SCCP message are compared against the matcher rules defined in the configuration. If a match occurs, the message will be routed towards the DPC defined in one of the translation rules associated with that matcher.

Optionally after outbound GT translation, the GT rewriter rule(s) may modify the parameters of the SCCP called party address.

Configuration

There are three different types of rules defined for outbound GT translation.

These are:

  1. The matching rule, which decides what SCCP addresses are to be translated. This invokes specified translation rules.

  2. The translation rule, which decides the DPC to route and routing priority. This invokes specified rewriter rules.

  3. The rewriter rule, which decides what is replaced and transformed in the SCCP address.

The configuration for the outbound GT translation matching rules are in the outbound section.

The scope of these rules overlap for parts of the SCCP message and interact with each other. The following table demonstrates how each configurable rule may interact with each other and the SCCP message.

Table 1. Outbound SCCP Message GT Configurable Rules
Scope of Rule on SCCP message Matching Rule matchers Translation Rule translations Rewrite/Replace Rule rewriters

Rule ID

Matching rule id

Configuration specific translation rule id invoked by a matching rule

Configuration specific rewrite rule id invoked by a translation rule

Address Information

Match to specific addrinfo digits

Replace with addrinfo digits

Treat digits to match as a prefix

is-prefix

GT Encoding

Replace gtencoding

GTI Global Title Indicator

Replace gti

Nature of Address (code defined in RFC 3868)

Match natofaddr - may set a default for all matching rules

Replace natofaddr

Numbering Plan (code defined in RFC 3868)

Match numplan - may set a default for all matching rules

Replace numplan

Translation Type (code defined in RFC 3868)

Match trtype - may set a default for all matching rules

Replace trtype

SSN

ssn

Route on SSN, GT, or no change

Replace route-on

Message DPC

Add dpc to route messages to

Local Routing

prefer-local routing on SGC or not

Relative Rule Priority

Rule priority

Rules to Invoke

Invoke translations rule(s)

Invoke rewriter-id rule(s)

To configure outbound GT translation, you must:

  • ❏ Configure the matching rules to activate the translation rules on the outbound GTs.

  • ❏ Configure the translation rule(s).

In addition, to rewrite the outbound GT after translation, you must:

  • ❏ Ensure that the translation rule(s) activates the appropriate rewrite rule(s).

  • ❏ Configure the rewrite rule(s).

Note The declarative configuration supports several different matching, translation, and rewriter rules. This allows for different numbers to be routed to different DPCs and have their SSN rewritten.

Setting up outbound GT translation

I want to …​
Route all outbound SCCP messages to a specific DPC

In the global-title, outbound section:

  • Add an outbound matcher rule that matches with any outgoing message.

    • Add is-prefix = true to allow any dialled digits to be matched.

    • Add to the matcher rule’s list of translations the unique identifier for the translation rule to invoke it.

    global-title:
      outbound:
        matchers:
          rules:
            - id: '1'
              is-prefix: true
              translations:
                - 'all'

  • Add a translation rule that is invoked by the matcher rule to the intended DPC.

    • Add the dpc that the messages are routed to.

    • Add the priority for the translation rule.

Note The priority for a translation rule is relative to other translation rules defined in the declarative configuration. 
    global-title:
      outbound:
        translations:
          - id: 'all'
            dpc: "5963"
            priority: 5
Route all SCCP CdPA with digits starting with 44123456 to primary and backup DPCs

In the global-title, outbound section:

  • Add an outbound matcher rule that matches with any outgoing message.

    • The addrinfo is set to the digit string 44123456.

    • The is-prefix is set true so SCCP addressed digits starting with 44123456 are accepted.

    • The invoked translations rules list has the identifier for the primary DPC 'to_4' and the secondary DPC 'to_100' added.

      outbound:
        matchers:
          rules:
            # All outbound SCCP CdPA with ri=GT and digits starting with 44123456 will be sent to DPC 4 (primary) and DPC 100 (backup)
            - id: 'to_44123456*'
              addrinfo: '44123456'
              is-prefix: true
              translations:
                - 'to_4'
                - 'to_100'

  • Add a translation rule that is invoked by the matcher rule to route to the primary DPC.

    • The id is set to match the primary DPC in the matcher rule.

    • The dpc is filled with the primary DPC in the network.

    • The priority is set higher than the backup DPC’s priority.

      outbound:
        translations:
          - id: 'to_4'
            dpc: '4'
            priority: 10

  • Add a translation rule that is invoked by the matcher rule to route to the backup DPC.

    • The id is set to match the backup DPC in the matcher rule.

    • The dpc is filled with the backup DPC in the network.

    • The priority is set lower than the primary DPC’s priority.

      outbound:
        translations:
          - id: 'to_100'
            dpc: '100'
            priority: 5
Route all SCCP CdPA with digits starting with 44666 to a primary DPCs and set their SSN to 146

In the global-title, outbound section:

  • Add an outbound matcher rule that matches with any outgoing message.

    • The addrinfo is set to the digit string 44666.

    • The is-prefix is set true so SCCP addressed digits starting with 44666 are accepted.

    • The invoked translations rules list has the identifier for the translation rule 'rewrite' which will invoke the rewrite rule.

      outbound:
        matchers:
          rules:
                # All outbound SCCP CdPA with ri=GT and digits starting with 44666 will be sent to DPC 4 and have the SSN rewritten to 146
                - id: 'to_44666*'
                  addrinfo: '44666'
                  is-prefix: true
                  translations:
                    - 'rewrite'

  • Add a translation rule that is invoked by the matcher rule that will route to the primary DPC and invoke a rewrite rule.

    • The id is set to match the translation rule invoked by the matcher rule.

    • The dpc is filled with the primary DPC in the network.

    • The rewriter-id is set to invoke the rewrite_44666_to_have_ssn rewrite rule.

      outbound:
        translations:
          - id: 'rewrite'
                  dpc: '4'
                  rewriter-id: 'rewrite_44666_to_have_ssn'

  • Add a rewrite rule that is invoked by the translation rule that will make the messages route on SSN 146.

    • The id is set to match the rewriter rule invoked by the translation rule.

    • The route-on is to set SSN, replacing existing route indicator on the message.

    • The ssn is set to 146, making the message be routed towards the 146 SSN.

      outbound:
        rewriters:
          - id: 'rewrite_44666_to_have_ssn'
                  route-on: SSN
                  ssn: 146
By default, only translate outbound SCCP messages that have a telex numbering plan, and an unknown nature of address and translation type

In the matchers, defaults section:

These given number codes correspond to a telex numbering plan, and an unknown nature of address and translation type as per RFC 3868 Section 3.10.2.3.

      outbound:
        matchers:
          # All addresses we care about are natofaddr=0, numplan=4 and trtype=0 so we can save some typing
          defaults:
            natofaddr: 0
            numplan: 4
            trtype: 0

Reconfiguring the SGC

This section applies in the case where the Rhino VoLTE TAS SGC has previously received its initial configuration and now requires reconfiguration.

Tip

If only the SGC’s SNMP subsystem requires reconfiguration it is recommended to follow the procedure at Reconfiguring the SGC’s SNMP Subsystem as that process does not cause a full SGC outage.

Reconfiguration of the SGC requires a SMO or an SGC VM with version 4.0.0-9-1.0.0 or newer. Reconfiguration of the SGC component in older VMs is not supported.

Warning

Reconfiguring the SGC will cause a full SS7 outage in live deployments.

There are two stages to reconfiguring the SGC:

Even if you have reconfigured the SGC before it is essential that you follow both of these steps.

Reviewing the SGC configuration

This section applies in the case where the Rhino VoLTE TAS SGC received its initial configuration on a VM version less than or equal to 4.0.0-22-1.0.0 or was most recently reconfigured following the SGC reconfiguration procedure on a VM with version less than or equal to 4.0.0-22-1.0.0.

If the VM is part of a new deployment with VM version greater than or equal to 4.0.0-23-1.0.0 this section does not apply.

Overview

Previous VM releases have contained defects that resulted in some SGC configuration parameter values being applied incorrectly. Multiple subsequent VM releases have contained fixes for these defects and configuration is now correctly applied.

VMs retain their pre-existing SGC configuration during upgrade. This means that VMs that were initially configured using a release with the configuration defects, that were then upgraded, still retain the defective configuration. This ensures that upgrades don’t fail due to changes in how configuration is interpreted.

However, this MOP takes the SGC back to an unconfigured state, and then applies the new configuration. This means that there is a possibility that configuration parameters subject to the defect may be applied differently (correctly) compared with previously (incorrectly), resulting in the SGC behaving differently.

In some cases the difference in behavior can mean a loss of service.

Generally, this is only likely to be a problem when both:

  • The configuration YAML contains an error that sets an integer field to 0 that should have been omitted or set to null.

  • The VM configuration defect treats 0 as being absent or null, when it should be treating it as an actual 0.

The two together result in the VM exhibiting the behavior of a null or absent value.

Once the VM configuration defect is rectified and the VM reconfigured, the 0 will be treated as a 0.

To avoid this, follow these instructions to review the configuration.

Reviewing the configuration

It is strongly recommended that the existing configuration is reviewed and thoroughly tested prior to executing this MOP on the live site.

Steps to carry out:

  1. Examine m3ua configuration for any integer parameter values that are currently set to 0. Determine if and how this parameter is affected by configuration defects by consulting the table below.

    1. If you wish to implement the correct behavior then no further action is required. Do not carry out the operation in the action to retain incorrect behavior column.

    2. If you wish to retain the previous incorrect behavior, apply the action documented in the action to retain incorrect behavior column.

    3. If the parameter is not documented in this table, check that it is an integer value, and that 0 is a permitted value. Only integer values are affected. Contact support for further advice.

  2. precond-ssns were not applied prior to version 4.0.0-18-1.0.0, regardless of their value. To retain that behavior, delete all precond-ssns elements. To obtain the corrected behavior leave them configured as-is.

The configuration parameters that don’t correctly honor a value of 0 are:

Fixed in Parameter name Incorrect behavior Correct behavior Action to retain incorrect behavior

4.0.0-10-1.0.0

rewriters: gti

rewriter does not set gti

rewriter sets gti to 0

Remove the parameter and its value.

4.0.0-10-1.0.0

rewriters: gtencoding

rewriter does not set gtencoding

rewriter sets gtencoding to 0

Remove the parameter and its value.

4.0.0-10-1.0.0

rewriters: natofaddr

rewriter does not set natofaddr

rewriter sets natofaddr to 0

Remove the parameter and its value.

4.0.0-10-1.0.0

rewriters: numplan

rewriter does not set numplan

rewriter sets numplan to 0

Remove the parameter and its value.

4.0.0-10-1.0.0

rewriters: trtype

rewriter does not set trtype

rewriter sets trtype to 0

Remove the parameter and its value.

4.0.0-10-1.0.0

matchers: rules: natofaddr

matcher may match on configured defaults if use-defaults is set, or accept any natofaddr value

matcher will only match a natofaddr of 0

Remove the parameter and its value.

4.0.0-10-1.0.0

matchers: rules: numplan

matcher may match on configured defaults if use-defaults is set, or accept any numplan value

matcher will only match a numplan of 0

Remove the parameter and its value.

4.0.0-10-1.0.0

matchers: rules: trtype

matcher may match on configured defaults if use-defaults is set, or accept any trtype value

matcher will only match a trtype of 0

Remove the parameter and its value.

4.0.0-10-1.0.0

translations: priority

Initconf did not converge.

Initconf will converge, and the priority will be set to 0.

N/A

4.0.0-10-1.0.0

inbound: natofaddr

inbound rule will match any natofaddr value

inbound rule will only match a natofaddr of 0

Remove the parameter and its value.

4.0.0-10-1.0.0

inbound: numplan

inbound rule will match any numplan value

inbound rule will only match a numplan of 0

Remove the parameter and its value.

4.0.0-10-1.0.0

inbound: trtype

inbound rule will match any trtype value

inbound rule will only match a trtype of 0

Remove the parameter and its value.

4.0.0-10-1.0.0

remote: peers: asp-id

ASP management messages will be sent without an asp-id parameter

ASP management messages will be sent with the asp-id parameter set to 0. If this was previously working, it is likely that this will result in failure to communicate properly with the remote peer unless the remote peer is also configured to use an asp-id of 0.

Remove the parameter and its value.

4.0.0-10-1.0.0 and 4.0.0-23-1.0.0

dpc: network-appearance

the network-appearance parameter is set to null. This impacts the DAUD/DAVA/DUNA messages used to share information about an AS between peers. An incorrect setting may result in a network outage.

the network-appearance parameter is set to 0

Remove the parameter and its value.

4.0.0-10-1.0.0 and 4.0.0-23-1.0.0

routes: dpc-ids: priority

the routes: default-priority will be used to configure the route. This may result in the route having a lower than expected priority.

The route will be configured with a priority of 0 (the highest).

Remove the parameter and its value.

Applying the new SGC configuration

This section applies in the case where the Rhino VoLTE TAS SGC has previously received its initial configuration and now requires reconfiguration.

Reconfiguration of the SGC requires a SMO or an SGC VM with version 4.0.0-9-1.0.0 or newer. Reconfiguration of the SGC component in older VMs is not supported.

Warning

Reconfiguring the SGC will cause a full SS7 outage in live deployments.
Warning

You must carry out the process documented here exactly as documented. It should not be skipped or modified.

What you need

  • ❏ The sgctool utility (available on the SGC or SMO VM).

  • ❏ The IP address of one of the deployment’s TSN nodes (<cds_address>).

  • ❏ The deployment ID (<deployment_id>).

  • ❏ The group ID (<group_id>).

Process overview

Here is the high-level view of the required steps:

  1. Review the configuration.

  2. Stop the OCSS7 SGCs.

  3. Verify that the OCSS7 SGCs are stopped.

  4. Delete the OCSS7 SGCs.

  5. Clear OCSS7 SGC-related state from the TSN nodes (CDS).

  6. Apply the new configuration.

Process detail

1. Review the configuration

Warning

Do not skip this step. Applying the configuration without reviewing it may result in loss of service.

Previous releases of the Rhino VoLTE TAS VM contained defects that resulted in the configuration being incorrectly applied. These defects have since been corrected. The reconfiguration process removes all previous configuration, including the incorrectly applied configuration, and replaces it with correctly applied configuration. This may result in changes in behavior, which in some cases could result in loss of service if the configuration was affected by this defect and is not adjusted appropriately.

See reviewing the SGC configuration for full details.

2. Stop the OCSS7 SGCs

You need to stop every SGC in the cluster. On each SGC or SMO node, issue the following command:

$ sudo systemctl stop ocss7

Note

The following message may be safely ignored:

Warning: ocss7.service changed on disk. Run 'systemctl daemon-reload' to reload units.

3. Verify that the OCSS7 SGCs are stopped

  1. Check the systemctl status of the ocss7 service. On each SGC or SMO node issue the following command:

$ sudo systemctl status ocss7
Dec 22 15:45:28 tst-sgc-1 systemd[1]: Stopping Start the OCSS7 SGC...
Dec 22 15:45:28 tst-sgc-1 ocss7[5029]: Stopping processes:
Dec 22 15:45:28 tst-sgc-1 ocss7[5029]: SGC:2027
Dec 22 15:45:28 tst-sgc-1 ocss7[5029]: DAEMON:2017
Dec 22 15:45:28 tst-sgc-1 ocss7[5029]: Initiating graceful shutdown for [2027] ...
Dec 22 15:45:28 tst-sgc-1 ocss7[5029]: Sleeping for max 32 sec waiting for graceful shutdown to complete.
Dec 22 15:45:39 tst-sgc-1 ocss7[5029]: Graceful shutdown successful
Dec 22 15:45:39 tst-sgc-1 ocss7[5029]: Shutdown complete (graceful)
Dec 22 15:45:39 tst-sgc-1 systemd[1]: Stopped Start the OCSS7 SGC.

  1. Check the OCSS7 SGC’s view of its own status. On each SGC or SMO node issue the following command:

$ ~/ocss7/<deployment_id>/<instance_id>/current/bin/sgc status
SGC is down

4. Delete the OCSS7 SGCs

On each SGC or SMO node, remove the OCSS7 SGC installation:

$ rm -rf /home/sentinel/ocss7/<deployment_id>/
Warning

Do not delete /home/sentinel/ocss7/, as this contains the necessary packages to reinstall the OCSS7 SGC.

Remove OCSS7 SGC configuration data that was persisted to the Cassandra Data Store (CDS). This only needs to be carried out once per SGC or SMO cluster.

  1. Run the sgctool from one SGC or SMO VM:

$ /opt/tasvmruntime-py/bin/sgctool clear-config --cds-address <cds_address> --deployment-id <deployment_id> --group-id <group_id>
The CDS SGC state has been cleared
Note

The <group_id> syntax is: RVT-<node type>[-suffix].<site_id>. For example: RVT-smo.DC1.

6. Apply the new configuration

You may now apply the new configuration using rvtconfig, as documented in Declarative configuration.

Reconfiguring the SGC’s SNMP Subsystem

This section applies in the case where the Rhino VoLTE TAS SGC has previously received its initial configuration and only the SNMP subsystem requires reconfiguration.

Warning

If other SGC configuration has changed it is necessary to follow the Reconfiguring the SGC procedure.
Warning

Reconfiguring the SNMP subsystem will cause an SNMP outage in live deployments. This includes other SNMP services, such as Rhino and Initconf. Full SNMP service will resume once the procedure is complete.

There are three situations where the SGC’s SNMP subsystem may require reconfiguring:

SNMP reconfiguration without upgrade or rollback

This process should be followed when the SGC SNMP subsystem requires reconfiguration. It consists of two phases:

  1. Removal of existing SNMP configuration.

  2. Application of desired SNMP configuration.

For each affected node type (SGC or SMO) the steps to follow are:

  1. Complete Preparation for SGC SNMP reconfiguration.

  2. Modify the snmp-config.yaml to the desired final state and upload the modified configuration using rvtconfig.

Upgrading when SNMPv3 is enabled

Warning

This process is only required when both:

  • SNMPv3 is enabled; and

  • Upgrading from VM version 4.0.0-23-1.0.0 or older to VM version 4.0.0-24-1.0.0 or newer.

The process consists of two phases:

  1. Preparation and removal of the existing SNMP configuration.

  2. Performing the upgrade.

For each affected node type (SGC or SMO) the steps to follow are:

  1. Complete Preparation for SGC SNMP reconfiguration.

  2. Continue with the upgrade procedure, ensuring that the uplevel SNMP configuration reflects the desired final state. No additional steps are required; SNMP will automatically be configured and enabled as the nodes are upgraded.

Rolling back when SNMPv3 is enabled

Warning

This process is only required when both:

  • SNMPv3 is enabled; and

  • Rolling back from VM version 4.0.0-24-1.0.0 or newer to VM version 4.0.0-23-1.0.0 or older.

The process consists of two phases:

  1. Preparation and removal of the existing SNMP configuration.

  2. Performing the rollback.

For each affected node type (SGC or SMO) the steps to follow are:

  1. Complete Preparation for SGC SNMP reconfiguration

  2. Then, continue with the rollback procedure, ensuring that the downlevel SNMP configuration reflects the desired final state. No additional steps are required; SNMP will automatically be configured and enabled as the nodes are rolled back.

Preparation for SGC SNMP reconfiguration

This step is common to all SGC SNMP reconfiguration processes and must only be followed when directed by those processes. This step removes the existing SNMP configuration from the SGC in preparation for a new configuration.

Warning

Reconfiguring the SNMP subsystem will cause a full SNMP outage in live deployments for the affected node type. This includes other services that provide SNMP agents and notifications, such as Rhino and Initconf.

For the node type being prepared, the steps to follow are:

  1. Ensure that you have a backup copy of the active cluster’s original snmp-config.yaml configuration file.

  2. Modify the active cluster’s snmp-config.yaml to disable all SNMP:

    deployment-config:snmp:
  v1-enabled: false
  v2c-enabled: false
  v3-enabled: false

  3. Upload the modified configuration using rvtconfig and wait for Initconf to converge.

  4. Remove the SGC’s existing SNMP configuration.

Remove the SGC’s existing SNMP configuration

Note

Perform this process once, on one VM of the type being reconfigured. The process affects the whole SGC cluster.
Tip

When performed as part of a rollback operation this process may be performed on any uplevel or downlevel cluster member where Initconf has successfully converged (i.e. "gone Green").

Either the automatic or manual method may be used.

Automatic

The sgc_snmp_cleaner tool is included on newer VMs by default at /opt/tasvmruntime-py/bin/sgc_snmp_cleaner. If not present on your VM, request it from your support representative and follow the installation instructions provided with it.

It must be executed on an active VM in the cluster to be reconfigured

[sentinel@tst-smo-1 ~]$ /opt/tasvmruntime-py/bin/sgc_snmp_cleaner --deployment-id tst
Checking the output

The script will report on the SNMP nodes, SNMP targets and USM users that it finds and removes. Successful completion will indicate:

SNMP configuration successfully cleared

Unsuccessful completion may indicate one of the following:

  • USM user configuration still exists:

  • Target address configuration still exists:

  • SNMP node configuration still exists:

Example successful output from the script for a single node test cluster:

[sentinel@tst-smo-1 ~]$ PYTHONPATH=/opt/tasvmruntime-py/lib/python3.7/site-packages/ python3 sgc_snmp_cleaner.py --deployment-id tst
Found SNMP node: tst-smo-1_v2c
  - Removed SNMP node: tst-smo-1_v2c
Found SNMP node: tst-smo-1_v3
  - Removed SNMP node: tst-smo-1_v3
Found SNMP target: 172.30.102.143#162#v3#UdpIpv4#trap#v3user
  - Removed SNMP target: 172.30.102.143#162#v3#UdpIpv4#trap#v3user
Found SNMP target: 172.30.102.143#162#v2c#UdpIpv4#trap#tst
  - Removed SNMP target: 172.30.102.143#162#v2c#UdpIpv4#trap#tst
Found USM user: snmp_user
  - Removed USM user: snmp_user
SNMP configuration successfully cleared

In the event that execution is unsuccessful follow the manual procedure.

Manual

  1. Log into one VM of the type being reconfigured.

  2. Start the SGC CLI: /home/sentinel/ocss7/<deployment_id>/<deployment_id>-<node_id>/current/cli/sgc-cli.sh

  3. Then, view the configured SNMP nodes by executing the SGC CLI command display-snmp-node.

    172.30.102.140:55555 tst-smo-1> display-snmp-node:
Found 3 object(s):
+--------------+----------+--------+--------+---------------+---------------+---------------+----------+--------------+---------------+--------+
|oname         |dependenci|enabled |active  |node           |transport-type |host           |port      |snmp-version  |community      |extended|
|              |es        |        |        |               |               |               |          |              |               |-traps  |
+--------------+----------+--------+--------+---------------+---------------+---------------+----------+--------------+---------------+--------+
|tst-smo-1_v3  |0         |true    |true    |tst-smo-1      |UDP            |172.30.102.140 |11103     |v3            |tst            |true    |
+--------------+----------+--------+--------+---------------+---------------+---------------+----------+--------------+---------------+--------+
|tst-smo-2_v3  |0         |true    |true    |tst-smo-2      |UDP            |172.30.102.141 |11103     |v3            |tst            |true    |
+--------------+----------+--------+--------+---------------+---------------+---------------+----------+--------------+---------------+--------+
|tst-smo-3_v3  |0         |true    |true    |tst-smo-3      |UDP            |172.30.102.142 |11103     |v3            |tst            |true    |
+--------------+----------+--------+--------+---------------+---------------+---------------+----------+--------------+---------------+--------+

    For each line in the returned table, execute the following two SGC CLI commands to disable and remove those nodes:

    • disable-snmp-node: oname=<oname>

    • remove-snmp-node: oname=<oname>

      For instance:

      172.30.102.140:55555 tst-smo-1> disable-snmp-node: oname=tst-smo-1_v3
OK snmp-node disabled.
172.30.102.140:55555 tst-smo-1> remove-snmp-node: oname=tst-smo-1_v3
OK snmp-node removed.

  4. Similarly, view the configured SNMP notification targets by executing the SGC CLI command display-target-address. For each line in the returned table, execute remove-target-address: oname=<oname>.

  5. Finally, view the configured SNMP USM users by executing the SGC CLI command display-usm-user. For each line in the returned table, execute remove-usm-user: oname=<oname>.

  6. Check that no SNMP configuration remains by executing the following commands and verifying that there are no lines in the returned tables.

    • display-snmp-node

    • display-target-address

    • display-usm-user

      For instance:

      172.30.102.140:55555 tst-smo-1> display-snmp-node
Found 0 objects.

172.30.102.140:55555 tst-smo-1> display-target-address:
Found 0 objects.

172.30.102.140:55555 tst-smo-1> display-usm-user:
Found 0 objects.

In the event that manual cleanup is unsuccessful please contact your support representative.

HSS integration

The Rhino VoLTE TAS requires access to the HSS to acquire provisioned subscriber data for configuring network wide or subscriber specific functionality and options.

Diameter Sh interface

The Rhino VoLTE TAS requires integration with the HSS using the Diameter Sh interface to be able to acquire provisioned subscriber data.

What you need

  • ❏ The origin realm to use when sending Diameter Sh messages.

  • ❏ The destination realm for where sent Diameter Sh messages go. This will be the HSS’s realm.

  • ❏ The HSS destination peers' destination-hostname, port, and protocol-transport type.

  • ❏ A sample user identity to be used for performing a health check on the interface.

  • ❏ A unique origin host domain name for each VM in the pool to use when sending Diameter Sh messages.

Setting up the Diameter Sh interface

The configuration for the HSS to Rhino VoLTE TAS Diameter Sh interface is in the shcm-service-config.yaml file.

In the shcm-service section, configure the diameter-sh section. The example configuration given here indicates the format of the required configuration.

shcm-service-config.yaml 
# Service configuration for the Sh Cache Microservice
shcm-service:
    ##
    ## Diameter Sh Configuration
    ##
    diameter-sh:

        # The origin realm to use when sending messages.
        origin-realm: opencloud.com

        # The value to use as the destination realm.
        destination-realm: opencloud

        # The HSS destination peers.
        destination-peers:
            - destination-hostname: hss.opencloud.com
              port: 3868
              protocol-transport: aaa
              metric: 1

        # The user identity that is put in the diameter message to the HSS when a health check is performed
        health-check-user-identity: sip:shcm-health-check@example.com

  • The protocol-transport variable is an enum. The valid values for this field are described in the reference guide’s section on Diameter Sh protocol transport type.

  • The metric variable is an integer that determines which peer to route to.

  • The health-check-user-identity is a user identity that should also be configured in the HSS. This will allow health checks to query the HSS and confirm functionality without affecting non-test subscribers.

The configuration for the Diameter Sh origin host values is in the shcm-vmpool-config.yaml file.

shcm-vmpool-config.yaml 
# This file describes the pool of Virtual Machines that comprise a "ShCM group"
deployment-config:shcm-virtual-machine-pool:

  # needs to match the deployment_id vapp parameter
  deployment-id: example

  # needs to match the site_id vApp parameter
  site-id: DC1

  # Define one or more Rhino users and give their passwords in plain-text.
  # Passwords will be encrypted by 'rvtconfig upload-config' before this file is uploaded to CDS.
  # This user is a read-only user, they can log in and see things in Rhino but do not have permission to change configuration
  # it is discouraged to log into Rhino to modify configuration using REM, instead the declarative configuration system should be used
  rhino-auth:
    - username: readonly
      password: xxxxxxxx

  virtual-machines:
    - vm-id: example-shcm-1
      diameter-sh-origin-host: shcm1.shcm.site1.mnc123.mcc530.3gppnetwork.org
      rhino-node-id: 101

    - vm-id: example-shcm-2
      diameter-sh-origin-host: shcm2.shcm.site1.mnc123.mcc530.3gppnetwork.org
      rhino-node-id: 102

Diameter Zh interface

The Diameter Zh interface allows IMS devices to authenticate with the network without any user interaction required.

What you need

  • ❏ The origin realm to use when sending Diameter Zh messages.

  • ❏ The destination realm for where sent Diameter Zh messages go. This will be the HSS’s realm.

  • ❏ The HSS destination peers' destination-hostname, port, and protocol-transport type.

  • ❏ A unique origin host domain name for each VM in the pool to use when sending Diameter Sh messages.

Setting up the Diameter Zh interface

The configuration for the HSS to Rhino VoLTE TAS Diameter Zh interface is in the bsf-config.yaml file.

In the bsf section, configure the zh-diameter section. The example configuration given here indicates the format of the required configuration.

bsf-config.yaml 
bsf:

  zh-diameter:

    origin-realm: opencloud.com

    destination-realm: opencloud.com

    destination-peers:
      - destination-hostname: hss.opencloud.com
        port: 3868
        protocol-transport: aaa
        metric: 1

  • The protocol-transport variable is an enum. The valid values for this field are described in the reference guide’s section on Diameter Zh protocol transport type.

  • The metric variable is an integer that determines which peer to route to.

The configuration for the Diameter Zh origin host values is in the mag-vmpool-config.yaml file.

mag-vmpool-config.yaml 
# This file describes the pool of Virtual Machines that comprise a "MAG cluster"
# there are some pieces of software on this VM type that require clustering and
# knowing each other's IP addresses, for example Rhino
deployment-config:mag-virtual-machine-pool:

  # needs to match the deployment_id vapp parameter
  deployment-id: example

  # needs to match the site_id vapp parameter
  site-id: DC1

  xcap-domains:
    - xcap.site1.ims.mnc123.mcc530.pub.3gppnetwork.org
    - xcap.site1.ims.mnc124.mcc530.pub.3gppnetwork.org

  # Define one or more Rhino users and give their passwords in plain-text.
  # Passwords will be encrypted by 'rvtconfig upload-config' before this file is uploaded to CDS.
  # This user is a read-only user, they can log in and see things in Rhino but do not have permission to change configuration
  # it is discouraged to log into Rhino to modify configuration using REM, instead the declarative configuration system should be used
  rhino-auth:
    - username: readonly
      password: xxxxxxxx

  # Define one or more REM users and give their passwords in plain-text.
  # Passwords will be encrypted by 'rvtconfig upload-config' before this file is uploaded to CDS.
  # each REM user maps to a Rhino user, when REM logs into Rhino
  rem-auth:
    - username: remreadonly
      real-name: REM read only user
      password: xxxxxxxx

  virtual-machines:
    - vm-id: example-mag-1
      rhino-node-id: 101
      diameter-zh-origin-host: mag1.mag.site1.mnc123.mcc530.3gppnetwork.org

    - vm-id: example-mag-2
      rhino-node-id: 102
      diameter-zh-origin-host: mag2.mag.site1.mnc123.mcc530.3gppnetwork.org

    - vm-id: example-mag-3
      rhino-node-id: 103
      diameter-zh-origin-host: mag3.mag.site1.mnc123.mcc530.3gppnetwork.org

  # DO NOT ENABLE IN PRODUCTION
  # Enable extensive logging for verification and issue diagnosis during acceptance testing
  rem-debug-logging-enabled: false

HLR integration

Integration with an HLR allows the Rhino VoLTE TAS to gather subscriber data for circuit switched (CS) domain calls.

What you need

For GSM or CDMA networks:

  • ❏ The SCCP address of the HLR in the network.

  • ❏ A unique SCCP address for the Rhino VoLTE TAS in the network.

For GSM networks:

  • ❏ An MLC SCCP address for the Rhino VoLTE TAS for outgoing MAP requests to the HLR.

  • ❏ If a separate address for the MSC is required, an MSC SCCP address for the Rhino VoLTE TAS for outgoing MAP requests to the HLR.

  • ❏ Whether to use the configured destination hlr-address as the exact HLR address when establishing a MAP dialog, or to replace the digits in the address with the subscriber MSISDN.

For CDMA networks:

  • ❏ The Market ID and Switch Number to be set on the MSCID of outgoing requests to the HLR.

Setting up the HLR interface

The Rhino VoLTE TAS to HLR interface configuration is in three files:

  • hlr-config.yaml details the destination configuration of messages sent to the HLR Rhino VoLTE TAS.

  • sentinel-volte-gsm-config.yaml details the origin configuration of GSM compatible messages sent from the Rhino VoLTE TAS.

  • sentinel-volte-cdma-config.yaml details the origin configuration of CDMA compatible messages sent from the Rhino VoLTE TAS.

The GSM and CDMA YAML files share an overlap of configuration scope.

Destination configuration

The destination configuration specifies the HLR SCCP address for where messages are sent from the Rhino VoLTE TAS to the HLR.

In the hlr section, configure the hlr-address value. The example configuration given here indicates the required SCCP address format.

hlr-config.yaml 
hlr:
    hlr-address: "type=C7,ri=pcssn,pc=5,ssn=6"

Origin configuration

The origin configuration specifies details of the Rhino VoLTE TAS that are communicated to the HLR.

In the hlr-connectivity-origin section, configure the originating-address value. The example configuration given here indicates the format of the required configuration for either CDMA or GSM with:

  • The SCCP originating address of the Rhino VoLTE TAS.

  • The timeout value for opening a dialog with the HLR.

sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml 
sentinel-volte:

  # Origin configuration for this application when connecting to the HLR.
  # The actual HLR SCCP address (destination) is in the hlr-configuration.yaml file
    hlr-connectivity-origin:

      # The SCCP address of the Sentinel VoLTE AS.
      originating-address: type=C7,ri=pcssn,pc=7,ssn=146

      # The timeout value for opening the MAP dialog with the HLR (in milliseconds).
      map-invoke-timeout-milliseconds: 5000
GSM network configuration

There is a GSM specific configuration required for networking with an HLR for the GSM network.

In the hlr-connectivity-origin section, configure the mlc-address value. The example configuration given here indicates what is needed for integrating with an HLR used in a GSM network with:

  • The Rhino VoLTE TAS’s MLC originating address.

  • The destination HLR address has the digits replaced with the Subscriber MSISDN rather than the exact destination address as configured in hlr-address.

  • A dedicated MSC originating address that is different to the MLC address.

sentinel-volte-gsm-config.yaml 
sentinel-volte:

    hlr-connectivity-origin:

      # GSM specific configuration.
      gsm:
        # The address of the MLC (Sentinel).
        mlc-address: address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN

        # Indicates if 'hlr-config/hlr-address' should be used as the actual HLR address, or have
        # its digits replaced with the MSISDN of the subscriber.
        use-msisdn-as-hlr-address: true

        # Originating SCCP address when acting as an MSC, used when
        # establishing the MAP dialog. Will default to the value of
        # 'originating-address' when not present. Typically used to set a
        # different originating SSN when sending a SendRoutingInformation
        # message to the HLR.
        msc-originating-address: address=654444444,nature=INTERNATIONAL,numberingPlan=ISDN
CDMA network configuration

There is a CDMA specific configuration required for networking with an HLR for the CDMA network.

In the hlr-connectivity-origin section, configure the market-id and switch-number values. The example configuration given here indicates input for what is needed for integrating with an HLR used in a CDMA network. This example designates for the MSCID set on outgoing CDMA requests to the HLR using:

  • The market ID value.

  • The switch number value.

sentinel-volte-cdma-config.yaml 
sentinel-volte:

    hlr-connectivity-origin:

      # CDMA specific configuration.
      cdma:
        # The market ID value to be used in the MSCID set on outgoing CDMA requests to the HLR
        market-id: 1

        # The switch number value to be used in the MSCID set on outgoing CDMA requests to the HLR
        switch-number: 1

Diagnostics systems integration

SAS integration

The Rhino VoLTE TAS supports Metaswitch’s SAS (Service Assurance Service) integration.

What you need

  • ❏ To chose whether or not to activate SAS tracing.

  • ❏ The IP addresses or DNS hostnames of SAS servers to connect the Rhino VoLTE TAS to.

Setting up the SAS interface

The configuration for the SAS to Rhino VoLTE TAS interface is in the sas-config.yaml file.

In the sas section, configure the servers list. The example configuration given here indicates input for what is needed for integrating the Rhino VoLTE TAS with SAS servers in a network.

sas-config.yaml 
sas:

  # Whether SAS is enabled ('true') or disabled ('false')
  enabled: true

  # Parameters for connecting to SAS
  sas-connection:
    # List of SAS servers. Either IP addresess or DNS hostnames.
    # Needs to be specified in a non-MDM deployment.
    servers:
      - 10.10.10.10
      - 10.10.10.11
      - sas.example.com

SNMP integration

The Rhino VoLTE TAS supports integration with SNMP based systems.

What you need

  • ❏ The version of SNMP to be used.

  • ❏ If using SNMP v2c, the SNMP community value.

  • ❏ The SNMP agent details such as location and contact address.

  • ❏ If using SNMP notifications, each notification target’s host, port, and specifc SNMP version.

Setting up the SNMP interface

The configuration for the SNMP to Rhino VoLTE TAS interface is in the snmp-config.yaml file.

In the snmp section, configure the targets list. The example configuration given here indicates input for what is needed for integrating the Rhino VoLTE TAS with SNMP services in the network.

snmp-config.yaml 
snmp:

  # Enable SNMP v1 (not recommended)
  v1-enabled: false

  # Enable SNMP v2c
  v2c-enabled: true

  # Enable SNMP v3
  v3-enabled: false

  # SNMP Community. Required for SNMP v2c
  community: clearwater

  # SNMP agent details
  agent-details:
    location: Unknown location
    contact: support.contact@invalid.com

  # SNMP Notifications
  notifications:

    # Enable SNMP Notifications
    enabled: true

    # SNMP notification targets. Normally this is the address of your MVS
    targets:
      - version: v2c
        host: 127.0.0.1
        port: 162

Media server integration

Announcement server integration

To play announcement media to a user, the Rhino VoLTE TAS requires the URI of the announcement media server.

What you need

  • ❏ The URI for the network’s announcement media server.

Setting up the announcement server interface

The configuration for the announcement server to Rhino VoLTE TAS interface is in the sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml file.

In the announcement section, configure the announcements-media-server-uri value, as shown in the example.

sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml 
sentinel-volte:

    mmtel:

        announcement:

            # Media server URI, used when playing announcements
            # This is distinct from mrf-uri for Conferencing
            announcements-media-server-uri: sip:annc-audio@localhost:5260;lr;transport=tcp

Conferencing media server integration

To utilize conferencing functionality in the Rhino VoLTE TAS, a media server that specializes in handling conferencing needs to be specified.

What you need

  • ❏ The URI for the MRF used for conferencing.

Setting up the conferencing media server interface

The configuration for the conferencing media server server to Rhino VoLTE TAS interface is in the sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml file.

In the conferencing section, configure the conference-mrf-uri value, as shown in the example.

sentinel-volte-gsm-config.yaml or sentinel-volte-cdma-config.yaml 
sentinel-volte:

    mmtel:

        # Configuration for conferencing.
        conferencing:

            # The URI of the Media Resource Function used for Conferencing.
            # This is distinct from the media-server-uri used for Announcements
            # The hostname part should either be a resolvable name or the IP address of the MRF.
            conference-mrf-uri: sip:mrf@mrfhost.example:5060

IP-SM-GW specific integration

MSC integration

There is a MAP interface between the IP Short Message Gateway (IP-SM-GW) in the Rhino VoLTE TAS and the MSC.

What you need

  • ❏ A template default SMSC address for MAP messaging.

  • ❏ A unique SCCP address for the Rhino VoLTE TAS in the network.

  • ❏ An international address for the Rhino VoLTE TAS in the network.

Setting up the MSC interface

The Rhino VoLTE TAS to MSC interface configuration is in the sentinel-ipsmgw-config.yaml file.

In the map-messaging section, configure the template-smsc-address, originating-address and ipsmgw-as-msc-address values. The example configuration given here indicates input for what is needed for integrating with the MSC for SMS.

sentinel-ipsmgw-config.yaml 
sentinel-ipsmgw:

    # MAP messaging configuration
    map-messaging:

        # Template SMSC address. The digits are replaced by those of the received SMSC address.
        template-smsc-address: "type=C7,ri=gt,digits=0,ssn=8,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0"

        # IPSMGW SCCP address.
        originating-address: "type=C7,ri=pcssn,pc=6,ssn=147"

        # IPSMGW international address.
        ipsmgw-as-msc-address: "address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN"

Charging

What it does

The charging service communicates with a number of possible systems to charge subscribers for making and receiving calls. The Rhino VoLTE TAS supports three different charging methods:

  • offline charging using Diameter Rf to send reports to a Charging Data Function (CDF)

  • online charging using Diameter Ro protocol to communicate with an Online Charging Server (OCS)

  • online charging using SIP to CAP translation to communicate with a charging Service Control Point (SCP) in a GSM network.

Online and offline charging can be used simultaneously. It is also possible to use both types of supported online charging at the same time. The Rhino VoLTE TAS does not support CDMA based charging systems, so for those networks only Diameter based charging is available.

Additionally, the Rhino VoLTE TAS writes Charging Data Records (CDRs) for every call. These contain metadata about the call suitable to use for charging purposes.

In this section

Diameter Rf offline charging

What it does

When Diameter Rf charging is in use, the Rhino VoLTE TAS communicates with a CDF to deliver interim CDRs using Accounting Request (ACR) messages. If the communication with the CDF fails, ACR messages are held locally until it is restored.

Interim CDRs must be enabled to use Diameter Rf offline charging.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to Diameter Rf offline charging in the sentinel-volte/charging/rf-charging section.

What you need

  • ❏ The release version of Diameter Rf to use with the offline charging system.

  • ❏ The origin realm to use when sending Diameter Rf messages. This is the TAS’s realm.

  • ❏ The destination realm to use when sending Diameter Rf messages. This is the offline charging system’s realm.

  • ❏ The CDF peers' hostnames, ports, and transport protocols.

Setting up Diameter Rf based offline charging

I want to…​
Use Diameter Rf offline charging
Warning Enable interim CDR generation first.

In the charging section, add an rf-charging section with:

        rf-charging:
            diameter-rf:
                diameter-rf-release: Vcb0
                origin-realm: metaswitch.com
                destination-realm: metaswitch.com
                destination-peers:
                    -   destination-hostname: peer.metaswitch.com
                        port: 3868
                        protocol-transport: sctp
                        metric: 1

You must ensure that all per-node-diameter-rf sections in the MMT cluster configuration are present and not commented out. The sections are located:

          # Remove this if diameter-rf is disabled
          per-node-diameter-rf:
              diameter-rf-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org
Disable Diameter Rf offline charging

In the charging section, remove or comment out the entire rf-charging section:

#        rf-charging:
#            diameter-rf:
#                diameter-rf-release: Vcb0
#                origin-realm: metaswitch.com
#                destination-realm: metaswitch.com
#                destination-peers:
#                    -   destination-hostname: peer.metaswitch.com
#                        port: 3868
#                        protocol-transport: sctp
#                        metric: 1

You must comment out any per-node-diameter-rf sections in the MMT cluster configuration, which are located:

          # Remove this if diameter-rf is disabled
#          per-node-diameter-rf:
#              diameter-rf-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org

Diameter Ro online charging

What it does

When Diameter Ro charging is in use, the Rhino VoLTE TAS communicates with one or more online charging systems (OCS) in real time to authorize credit for calls. While a call is in progress, Diameter Ro messages are exchanged with the OCS whenever more credit is required, or when there are significant changes in the call that could impact the cost (e.g. video is enabled). If at any point the OCS refuses to grant credit, the call is ended.

While the method for enabling Diameter Ro charging differs between GSM and CDMA based deployments, there is no functional difference in charging behavior as the GSM and CDMA parts of the network are not involved.

Diameter Ro charging announcements

When using Diameter Ro online charging, the Rhino VoLTE TAS supports playing announcements when:

  • the subscriber attempts to make a call when they are running low on credit

  • the subscriber attempts to make a call without having any credit

  • the subscriber begins to run low on credit during a call

  • the subscriber runs out of credit during the call

  • the OCS instructs the TAS to do so.

Low credit announcements are played when the OCS’s response to a credit check includes a low balance indicator. After playing a low credit announcement, the Rhino VoLTE TAS waits for a time before doing another credit check. The time period is set in the charging-reauth-delay-milliseconds field.

Out of credit announcements are played when the OCS sends an "Out of Credit" response to a credit check. The call is terminated after playing an out of credit announcement.

The OCS instructs announcements to be played by including announcement information in its response to a credit check. These announcements will take precedence over the low and out of credit announcements configured in the Rhino VoLTE TAS. If the announcement information came in a "Out of Credit" response, the call will end after the announcement has been played.

When configuring the charging service to play an announcement, you only provide the ID of the announcement that should be played. This ID must correspond to an announcement that has been configured in the announcement service. See Announcements for instruction about how to do this.

Multiple OCS Support

The Rhino VoLTE TAS supports communicating with multiple different Diameter Ro online charging systems. Each OCS must have its own Diameter realm, and those realms must be configured as destination realms in the Rhino VoLTE TAS’s Diameter Ro configuration.

The particular OCS to use for a given call is determined from the ecf parameter of the P-Charging-Function-Addresses header on the initial SIP request for the call. The value of the ecf parameter that identifies a particular OCS is its realm name by default, but can be configured to be any arbitrary value by specifying a charging-function-address when configuring the destination realm for an OCS.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to Diameter Ro online charging in the sentinel-volte/charging/ro-charging section.

What you need

  • ❏ The release version of Diameter Ro to use with the online charging system.

  • ❏ The origin realm to use when sending Diameter Ro messages. This is the TAS’s realm.

  • ❏ The destination realm to use when sending Diameter Ro messages. This is the online charging system’s realm.

  • ❏ The OCS peers' hostnames, ports, and transport protocols.

For low balance announcements:

  • ❏ The ID of the low balance announcement to play in call setup.

  • ❏ The ID of the low balance announcement to play in an active call.

  • ❏ The time to wait after playing an announcement before doing another credit check.

For out of credit announcements:

  • ❏ The ID of the out of credit announcement to play in call setup.

  • ❏ The ID of the out of credit announcement to play in an active call.

For multiple OCS support:

  • ❏ The destination realm of each OCS.

  • ❏ A list of which peers are associated with which realms.

  • ❏ (Optional) An identifier for each OCS that will be used to select it with a P-Charging-Function-Addresses header.

Setting up Diameter Ro online charging

I want to…​
Use Diameter Ro online charging on a GSM based deployment
        gsm-online-charging-type: ro
          # Remove this if diameter-ro is disabled
          per-node-diameter-ro:
              diameter-ro-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org
Disable Diameter Ro charging on a GSM based deployment
        gsm-online-charging-type: disabled
#        ro-charging:
#            diameter-ro:
#                diameter-ro-release: Vcb0
#                origin-realm: metaswitch.com
#                destination-realm: metaswitch.com
#                destination-peers:
#                    -   destination-hostname: peer.metaswitch.com
#                        port: 3868
#                        protocol-transport: aaa
#                        metric: 1
#                continue-session-on-ocs-failure: false
#
#            charging-announcements:
#                low-credit-announcements:
#                    call-setup-announcement-id: 100
#                    mid-call-announcement-id: 100
#                    charging-reauth-delay-milliseconds: 30000
#                out-of-credit-announcements:
#                    call-setup-announcement-id: 101
#                    mid-call-announcement-id: 102
          # Remove this if diameter-ro is disabled
#          per-node-diameter-ro:
#              diameter-ro-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org
Use Diameter Ro online charging on a CDMA based deployment
        cdma-online-charging-enabled: true
          # Remove this if diameter-ro is disabled
          per-node-diameter-ro:
              diameter-ro-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org
Disable Diameter Ro charging on a CDMA based deployment
        cdma-online-charging-enabled: false

  • Remove or comment out the entire ro-charging section:

#        ro-charging:
#            diameter-ro:
#                diameter-ro-release: Vcb0
#                origin-realm: metaswitch.com
#                destination-realm: metaswitch.com
#                destination-peers:
#                    -   destination-hostname: peer.metaswitch.com
#                        port: 3868
#                        protocol-transport: aaa
#                        metric: 1
#                continue-session-on-ocs-failure: false
#
#            charging-announcements:
#                low-credit-announcements:
#                    call-setup-announcement-id: 100
#                    mid-call-announcement-id: 100
#                    charging-reauth-delay-milliseconds: 30000
#                out-of-credit-announcements:
#                    call-setup-announcement-id: 101
#                    mid-call-announcement-id: 102
          # Remove this if diameter-ro is disabled
#          per-node-diameter-ro:
#              diameter-ro-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org
Configure Diameter Ro online charging

In the charging section, ensure that the ro-charging section is present and not commented out:

        ro-charging:
            diameter-ro:
                diameter-ro-release: Vcb0
                origin-realm: metaswitch.com
                destination-realm: metaswitch.com
                destination-peers:
                    -   destination-hostname: peer.metaswitch.com
                        port: 3868
                        protocol-transport: aaa
                        metric: 1
Play an announcement to subscribers when they run low on credit
Warning Ensure the announcement IDs you want to use have been set up in the announcement service. See Announcements.

In charging, ro-charging, ensure that the charging-announcements section is present.:

            charging-announcements:
                low-credit-announcements:
                    call-setup-announcement-id: 100
                    mid-call-announcement-id: 100
                    charging-reauth-delay-milliseconds: 30000

Related section: Diameter Ro charging announcements

Play an announcement to subscribers when they run out of credit
Warning Ensure the announcement IDs you want to use have been set up in the announcement service. See Announcements.

In charging, ro-charging, ensure that the charging-announcements section is present:

            charging-announcements:
                out-of-credit-announcements:
                    call-setup-announcement-id: 101
                    mid-call-announcement-id: 102

Related section: Diameter Ro charging announcements

Configure multiple destination realms

In charging, ro-charging:

            diameter-ro:
                diameter-ro-release: Vcb0
                origin-realm: metaswitch.com
                destination-realms:
                    -   destination-realm: ocs1.metaswitch.com
                        peers:
                            - peer1.metaswitch.com
                    -   destination-realm: ocs2.metaswitch.com
                        peers:
                            - peer2.metaswitch.com
                            - peer3.metaswitch.com
                destination-peers:
                    -   destination-hostname: peer1.metaswitch.com
                        port: 3868
                        protocol-transport: aaa
                        metric: 1
                    -   destination-hostname: peer2.metaswitch.com
                        port: 3868
                        protocol-transport: aaa
                        metric: 1
                    -   destination-hostname: peer3.metaswitch.com
                        port: 3868
                        protocol-transport: aaa
                        metric: 2
Set an identifier for an OCS for selecting it with a P-Charging-Function-Addresses header

In charging, ro-charging, diameter-ro:

                destination-realms:
                    -   destination-realm: ocs1.metaswitch.com
                        charging-function-address: ocs_1
                        peers:
                            - peer1.metaswitch.com
                    -   destination-realm: ocs2.metaswitch.com
                        peers:
                            - peer2.metaswitch.com
                            - peer3.metaswitch.com

Mixed Diameter Ro and CAP online charging

What it does

Operators may have a mixed Diameter Ro and CAP online charging environment. This is typically seen when an Operator is migrating off their SCP. To support this deployment the cap-ro gsm-online-charging-type is used, which instructs the installer to deploy both CAP and Diameter Ro configurations.

Charging Mode Selection

When a call triggers RVT the online charging mode (either Diameter Ro or CAP) is determined by inspecting the top-most route header for the oc-charge-mode uri parameter which is set to either ro, cap, or offline. If ro is set then Diameter Ro is used for charging, if cap is set then CAP online charging is used.

Note Check the Sentinel VoLTE Administration Guide for more details on the oc-charge-mode.

For more details on the Diameter Ro and CAP online charging check these links.

Configuration

When using the mixed environment set the gsm-online-charging-type to cap-ro. Both Diameter Ro and CAP online charging configuration needs to be present.

What you need for CAP Online Charging

  • ❏ The SCCP address of the GSM charging SCP.

  • ❏ The TDP(s) to use when retrieving IM-CSI data from the HLR.

  • ❏ Whether or not to send location information to the SCP.

If sending location information to the SCP:

  • ❏ The format to sent the information in (see Location information).

  • ❏ A default value to send when a subscriber’s location cannot be determined.

What you need for Diameter Ro Charging

  • ❏ The release version of Diameter Ro to use with the online charging system.

  • ❏ The origin realm to use when sending Diameter Ro messages. This is the TAS’s realm.

  • ❏ The destination realm to use when sending Diameter Ro messages. This is the online charging system’s realm.

  • ❏ The OCS peers' hostnames, ports, and transport protocols.

For low balance announcements:

  • ❏ The ID of the low balance announcement to play in call setup.

  • ❏ The ID of the low balance announcement to play in an active call.

  • ❏ The time to wait after playing an announcement before doing another credit check.

For out of credit announcements:

  • ❏ The ID of the out of credit announcement to play in call setup.

  • ❏ The ID of the out of credit announcement to play in an active call.

I want to…​

Use both Diameter Ro and CAP online charging on a GSM based deployment
        gsm-online-charging-type: cap-ro

Also in the charging section:

        cap-charging:
            imssf:
                scf-address: "type=C7,ri=pcssn,pc=6,ssn=156"
          # Remove this if diameter-ro is disabled
          per-node-diameter-ro:
              diameter-ro-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org

CAP online charging

What it does

When CAP online charging is in use, the Rhino VoLTE TAS functions as an IM-SSF (IP Multimedia Service Switching Function) and communicates with an SCP in a GSM network. At various points in the SIP signalling for the call the Rhino VoLTE TAS will translate the SIP to the equivalent CAP signalling towards the SCP, to give it the opportunity to intervene in call processing. Through this the SCP can provide a charging service. The exact details of how and when the Rhino VoLTE TAS will signal the SCP is determined by subscriber specific IM-CSI data in the HLR.

CAP online charging requires that integration with an SCP is set up. To do this, the SCCP (Signalling Connection Control Part) address of the SCP must be set in the scf-address field.

Note CAMEL Application Part (CAP) is a GSM protocol, so naturally can only be used with GSM networks.

The Rhino VoLTE TAS supports CAP phase 2 and phase 3 triggers.

IM-CSI

The IM-CSI (IP multimedia CAMEL subscription information) is subscriber data retrieved from the HLR that is used to determine when and how to do SIP to CAP translation. There are different versions of the IM-CSI for the originating and terminating legs of the call; they are the O-IM-CSI and the VT-IM-CSI respectively. The Rhino VoLTE TAS can be configured to retrieve either the O-IM-CSI or the VT-IM-CSI independently of whether it is acting as an originating or terminating TAS.

The IM-CSI that is fetched on:

Both fields can take the same values, which are numbers that correspond to CAP TDPs (trigger detection points).

The following values are valid for these fields.

Table 2. TDPs for IM-CSI retrieval
TDP number TDP name IM-CSI retrieved

2

 
Collected_Info

O-IM-CSI

3

 
Analysed_Info

O-IM-CSI

12

 
Terminating_Attempt_Authorised

VT-IM-CSI
Location information

Information about a subscriber’s current country and access network can be sent to the SCP in the form of a charging GT (global title).

The format of the charging GT is configured in the format field, and it is made up from any combination of: fixed digits, the mobile country code (MCC), the mobile network code (MNC), and/or the two letter ISO country code. The value of the field should match any fixed digits to be included in the charging GT, with {mcc}, {mnc}, and/or {iso} tags inserted where those values should be substituted in. For example, 12345{mcc}{mnc} results in a charging GT that always starts with 12345 and has the current MCC and MNC for the subscriber appended on the end.

The unknown-location field can be used to set a default charging GT, which is used when a subscriber’s location cannot be determined.

When a subscriber receives a call, the CAP charging service is always invoked. This can be changed so that the service is only used for terminating calls when the charging GT data indicates that the subscriber is roaming in a foreign country.

Configuration

Note CAP based charging is only available on GSM networks.

The example for sentinel-volte-gsm-config.yaml shows example configuration relevant to CAP charging in the sentinel-volte/charging section.

What you need

  • ❏ The SCCP address of the GSM charging SCP.

  • ❏ The TDP(s) to use when retrieving IM-CSI data from the HLR.

  • ❏ Whether or not to send location information to the SCP.

If sending location information to the SCP:

  • ❏ The format to sent the information in (see Location information).

  • ❏ A default value to send when a subscriber’s location cannot be determined.

Setting up CAP based online charging

I want to…​
Enable CAP charging

In the charging section, set the gsm-online-charging-type to either cap or cap-ro for mixed CAMEL/Ro deployments:

        gsm-online-charging-type: cap

Also in the charging section:

        cap-charging:
            imssf:
                scf-address: "type=C7,ri=pcssn,pc=6,ssn=156"

  • Ensure there is a cap-charging section.

  • Ensure there is an imssf section.

  • Set the scf-address to the SCCP address of the SCP that the Rhino VoLTE TAS should communicate with.

Disable CAP charging

In the charging section, set the gsm-online-charging-type to disabled:

        gsm-online-charging-type: disabled

Comment out the entire cap-charging section:

#        cap-charging:
#            imssf:
#                imcsi-fetching:
#                    originating-tdp: 2
#                    terminating-tdp: 12
#                charging-gt:
#                    format: "6422142{iso}"
#                    unknown-location: "64221429090"
#                    only-charge-terminating-call-if-international-roaming: false
#                scf-address: "type=C7,ri=pcssn,pc=6,ssn=156"
Change the SCP that the CAP charging service communicates with

In the imssf section, set the scf-address to the SCCP address of the new SCP:

                scf-address: "type=C7,ri=pcssn,pc=6,ssn=156"
Generate and send a charging GT containing location information for a subscriber to the SCP

In the imssf section:

                charging-gt:
                    format: "6422142{iso}"
                    unknown-location: "64221429090"

  • Add a charging-gt section. Inside it add:

    • a format field specifying how the location information should be delivered. It can be made up from fixed digits and any of these tags: {mcc}, {mnc}, and/or {iso}; which will substitute in the MCC, MNC, and ISO two letter country code respectively.

    • a unknown-location field indicating what to send to the SCP if location information cannot be obtained.

Related section: Location information

Disable sending of the charging GT to the SCP

In the imssf section, comment out the entire charging-gt section:

#                charging-gt:
#                    format: "6422142{iso}"
#                    unknown-location: "64221429090"

Related section: Location information

Only invoke the CAP charging service for terminating subscribers when they are roaming in a foreign country

In the charging-gt section, set the only-charge-terminating-call-if-international-roaming to true:

                    only-charge-terminating-call-if-international-roaming: true

Related section: Location information

Always invoke the CAP charging service for terminating subscribers regardless of their location

In the charging-gt section, set the only-charge-terminating-call-if-international-roaming to false:

                    only-charge-terminating-call-if-international-roaming: false

Related section: Location information

Use O-IM-CSI data from the HLR on originating calls

In the charging section:

        cap-charging:
            imssf:
                imcsi-fetching:
                    originating-tdp: 2

Related section: IM-CSI

Use VT-IM-CSI data from the HLR on originating calls

In the charging section:

        cap-charging:
            imssf:
                imcsi-fetching:
                    originating-tdp: 12

Related section: IM-CSI

Use O-IM-CSI data from the HLR on terminating calls

In the charging section:

        cap-charging:
            imssf:
                imcsi-fetching:
                    terminating-tdp: 2

Related section: IM-CSI

Use VT-IM-CSI data from the HLR on terminating calls

In the charging section:

        cap-charging:
            imssf:
                imcsi-fetching:
                    terminating-tdp: 12

Related section: IM-CSI

Disable retrieval of IM-CSI data from the HLR

In the imssf section, remove or comment out the entire imcsi-fetching section:

            imssf:
#               imcsi-fetching:
#                   originating-tdp: 2
#                   terminating-tdp: 12

To disable retrieval for only:

Related section: IM-CSI

Charging Data Records

What it does

Charging Data Records (CDRs) can be generated by the Rhino VoLTE TAS to record information about each call it processes. There are two types of CDRs: Interim CDRs and Session CDRs.

Interim CDRs

Interim CDRs are generated while a call is in progress, with multiple CDRs being generated during a single call. The Rhino VoLTE TAS can write the CDRs to the file system, send them to a CDF using Diameter Rf offline charging, or both.

There are two ways to control when interim CDRs should be generated:

  • You can change the maximum time to wait between creating each CDR.

  • You can instruct that a new CDR is created whenever the SDP for a call is modified.

In addition, one interim CDR is always generated when the call is answered and another when the call ends.

If you want to use Diameter Rf offline charging, interim CDR generation must be enabled.

Session CDRs

Session CDRs are generated at the completion of a call, with only one being produced for each call. They are written out to the file system.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to CDRs in the sentinel-volte/charging/cdr section.

What you need

  • ❏ Whether to generate a session CDR at the end of each call.

  • ❏ Whether to generate interim CDRs during a call.

When you are using interim CDRs:

  • ❏ Whether an interim CDR should be created any time the SDP in a call changes.

  • ❏ The maximum period to wait between creating interim CDRs.

  • ❏ Whether the Rhino VoLTE TAS should write copies of each interim CDR to the file system.

Setting up CDRs

I want to…​
Enable session CDR generation

In the charging, cdr section, set session-cdrs-enabled to true:

        session-cdrs-enabled: true

Related section: Session CDRs

Disable session CDR generation

In the charging, cdr section, set session-cdrs-enabled to false:

        session-cdrs-enabled: false

Related section: Session CDRs

Enable interim CDR generation

In the charging, cdr section, add an interim-cdrs section:

            interim-cdrs:
                write-cdrs-in-filesystem: true
                write-cdr-on-sdp-change: true
                interim-cdrs-period-seconds: 300

Related section: Interim CDRs

Disable interim CDR generation

In the charging, cdr section, remove or comment out the entire interim-cdrs section:

#            interim-cdrs:
#                write-cdrs-in-filesystem: true
#                write-cdr-on-sdp-change: true
#                interim-cdrs-period-seconds: 300

Related section: Interim CDRs

Generate an interim CDR whenever the SDP for a call changes

In the interim-cdrs section, set write-cdr-on-sdp-change to true:

                write-cdr-on-sdp-change: true

Related section: Interim CDRs

Prevent generation of interim CDRs when the SDP for a call changes

In the interim-cdrs section, set write-cdr-on-sdp-change to false:

                write-cdr-on-sdp-change: false

Related section: Interim CDRs

Change the maximum time to wait between generating interim CDRs

In the interim-cdrs section, set interim-cdrs-period-seconds to the desired maximum wait time in seconds:

                interim-cdrs-period-seconds: 350

Related section: Interim CDRs

Write copies of interim CDRs to the file system

In the interim-cdrs section, set write-cdrs-in-filesystem to true:

                write-cdrs-in-filesystem: true

Related section: Interim CDRs

Stop writing copies of interim CDRs to the file system

In the interim-cdrs section, set write-cdrs-in-filesystem to false:

                write-cdrs-in-filesystem: false

Related section: Interim CDRs

Home networks and roaming

The Rhino VoLTE TAS requires configuration of its home network details in order to handle number normalization and roaming properly. This section describes how to set the home network information for the Rhino VoLTE TAS. Furthermore, there are details on how to handle behavior concerning home network configuration, such as number normalization and roaming determination.

Setting the address handling and home network information for the Rhino VoLTE TAS requires editing of specific YAML configuration files.

For further information on how to edit YAML configuration files, see Declarative configuration.

In this section

Home network dialing

The Rhino VoLTE TAS requires information about the home network to correctly run number analysis.

How it works

The home network dialing configuration is composed of:

  • The home network’s domain name.

  • The country code dialing code, which is the home network’s code for dialing from external international networks.

  • The country’s ISO country code, which specifies the home network’s country in the two letter ISO 3166-1 alpha-2 format.

  • The home PLMN (Public Land Mobile Network) IDs, which defines the operator’s home network codes in a country.

Using the home network dialing configuration, the Rhino VoLTE TAS runs number analysis to support:

  • designating multiple home PLMN IDs in the home network

  • normalization of international, national, unknown, or subscriber NADI format addresses into either national or international formats

  • determining a call’s roaming status.

Number normalization requires additional configuration to operate. More details on this configuration is in Number normalization.

Roaming determination has additional configurability available. More details of this configuration is in Roaming and international status determination.

Configuration

What you need

  • ❏ The home network’s home domain.

  • ❏ The home network’s country dialing code.

  • ❏ The home network’s two letter ISO country code.

  • ❏ The home network’s PLMN ID(s).

Setting up home network dialing

I want to …​
Set my home network domain name

In the home-network section, set home-domain to your home network’s home domain:

    home-domain: example.com
Set my country dialing code for my network

In the home-network section, set home-network-country-dialing-code to your home network’s country dialing code:

    home-network-country-dialing-code: "64"
Set the ISO country code for my network

In the home-network section, set home-network-iso-country-code to your home network’s ISO country code:

    home-network-iso-country-code: NZ
Set the PLMN IDs for my network
    home-plmn-ids:
      - mcc: "001"
        mncs:
          - "01"
          - "001"
    correlation-ra-plmnid:
        mcc: "001"
        mnc: "01"

Number normalization

The Rhino VoLTE TAS supports number normalization to either the international format or the national format. The Rhino VoLTE TAS invokes the normalization process for number comparison, normalizing numbers on outgoing requests, checking if numbers are normalizable.

How it works

The Rhino VoLTE TAS may normalize numbers into the international format or the national format. The original number may be in one of the following formats:

  • International

  • National

  • Subscriber NADI format

  • an unknown format

When normalizing numbers to the international format:

When normalizing numbers to the national format:

Interactions with other services

Number normalization in used by several features of the Rhino VoLTE TAS for number comparison, checking if numbers are normalizable, or determining the status of a call. Since normalization is widespread in the Rhino VoLTE TAS, this section discusses only a selection of features that interact with number normalization.

MMTel services

MMTel services use the normalization to make URIs comparable and for call retarget destination.

For call barring services (ICB and OCB), normalization occurs for both an originating/terminating URI and the provisioned URI it is compared against.

For Communications Diversion (CDIV), normalization is used to check if a forwarding destination is valid by running a comparison. In addition, the forwarded target is set in the specified normalized format.

XCAP service

The XCAP service uses the configured normalization process to normalize numbers in MMTel CDIV rule targets and ICB/OCB conditions.

Short codes and vertical service codes

Request URIs may include short codes or vertical service codes. For an international format number prefixed by the home country code, the Rhino VoLTE TAS will normalize the number to remove the country code prefix before acting on the code. Normalization will not occur if the dialed string’s length is less than the configured min-normalizable-length value.

Configuration

The example number-analysis-config.yaml file shows example configuration for the home network’s number normalization rules in the normalization section.

The normalize-to variable is an enum. The valid values for this field are described in the reference guide’s section on normalize-to.

What you need

  • ❏ The home network’s country dialing code.

  • ❏ A minimum normalizable length for dialed numbers.

  • ❏ The national prefix number (escape code) for dialed national numbers.

  • ❏ The international prefix number (escape code) of dialed international numbers.

  • ❏ The network’s dialing code — this will act as the MNC for normalizing from the subscriber NADI format.

  • ❏ Whether to normalize numbers to an international or national format in the home network.

Setting up number normalization

I want to …​
Set up the home network settings for normalization

The normalization process in the Rhino VoLTE TAS requires details about the home network for it to work properly. These apply for normalizing for both national and international formats.

To configure the home network specific settings for number normalization:

        network-dialing-code: "6"
        international-prefix: "00"
        national-prefix: "0"
        min-normalizable-length: "0"
Normalize numbers to the international format

To set the Rhino VoLTE TAS to normalize numbers into the international format, in the normalization section, set normalize-to to international:

        normalize-to: international
Normalize numbers to the national format

To set the Rhino VoLTE TAS to normalize numbers into the national format, in the normalization section, set normalize-to to national:

        normalize-to: national

Roaming and international status determination

The Rhino VoLTE TAS requires configuration of how it determines whether addresses are international and/or roaming on the home network.

How it works

The Rhino VoLTE TAS determines if a session is roaming and if it represents an international call based on:

  • the location of the calling party, and

  • the destination address.

Determining international status

The Rhino VoLTE TAS uses the home network configuration to determine the international status of a subscriber.

If the checked address is not in an international format and non-international-format-number-is-national is set to true, the Rhino VoLTE TAS determines the number is not an international or international-exHC number.

Otherwise, the Rhino VoLTE TAS analyzes the call alongside the home network information to determine international status.

The Rhino VoLTE TAS determines the call’s international status according to the definitions given by 3GPP 24.611:

international: This condition evaluates to true when the request URI of the outgoing SIP request:

  • corresponds to a telephone number, i.e. a SIP URI with a “user” URI parameter set to “phone” or a tel URI; and

  • does not point to a destination served by a network within the country where the originating user is located when initiating the call.

international-exHC: This condition for international barring, excluding the home country, evaluates to true when the request URI of the outgoing SIP request:

  • corresponds to a telephone number, i.e. a SIP URI with a “user” URI parameter set to “phone” or a tel URI;

  • does not point to a destination served by a network within the country where the originating user is located when initiating the call; and

  • does not point to a destination served within the served users home network.

Determining roaming status

The Rhino VoLTE TAS determines roaming status of a subscriber by checking the following:

  • Firstly, the home-plmn-ids MCCs and MNCs are checked with the subscriber address’s respective MCC and MNC.

    • If a home network MCC and MNC (PLMN ID) match with the address’s MCC and MNC respectively, the call is NOT-ROAMING.

    • If a home network MCC and address’s MCC match, but there is no MNC match, the call is NATIONAL roaming.

    • If a home network MCC does not match with the address’s MCC, the call is INTERNATIONAL roaming.

  • If the address has no MCC present, the ISO country code of the party is compared with the network’s configured home-network-iso-country-code.

    • If the ISO country codes match, the call is NOT-ROAMING, otherwise, it is INTERNATIONAL roaming.

  • If there is no ISO country code present, the Visited Network ID of the party is compared with the network’s configured home-domain.

    • If the network IDs match, the call is NOT-ROAMING, otherwise it is INTERNATIONAL roaming.

  • Finally, if the call’s visited MCC nor visited network are not present, the roaming status is UNKNOWN.

Using the visited network ID

The Rhino VoLTE TAS determines the visited network ID on an incoming request with the following techniques:

  • Firstly, if the Rhino VoLTE TAS has already loaded on the visited network ID for the session, it uses that.

  • Otherwise, the Rhino VoLTE TAS uses the P-Visited-Network-Id header for originating sessions or OC-Term-P-Visited-Network-Id for terminating sessions on the incoming request.

  • Finally, the Rhino VoLTE TAS will query for the third party registration data stored in subscriber data.

Interactions with other services

Call Barring

The Rhino VoLTE TAS uses the roaming and international status for MMTel communication barring features. For further information on barring feature configuration, see Call barring.

International Call Management

The outcome of international status determination is used to decide whether the International Call Management service should run.

Configuration

Roaming determination depends on number normalization and home network dialing configurations.

It is possible to configure a list of addresses that will have roaming determination skipped. Contact Metaswitch support for more information on how to configure roaming determination skip lists.

What you need

  • ❏ Whether to treat non-international numbers as national numbers.

  • ❏ Whether to end a call if there is no visited network information on the incoming call request.

  • ❏ The minimum length of the destination address required to set international and roaming status.

  • ❏ For a GSM network, whether to use the HLR to determine roaming.

Setting up roaming and international status

I want to …​
Treat any non-international format number as a national number

To set the Rhino VoLTE TAS to treat any non-international format number as a national number for roaming, in the international-and-roaming section, set non-international-format-number-is-national to true:

            non-international-format-number-is-national: true
End a call if no visited network can be determined

To set the Rhino VoLTE TAS to end an incoming call if the P-Visited-Network-Id cannot be determined, in the international-and-roaming section, set end-call-if-no-visited-network to true:

            end-call-if-no-visited-network: true
Not determine roaming and international status for dialed digits below a certain length

To set the Rhino VoLTE TAS to not determine roaming or international status for short dialed digit strings (such as any length below 7 for example), in the international-and-roaming section, set min-length to 7:

            min-length: 7
Use the HLR for determining roaming with the GSM network

To set the Rhino VoLTE TAS to query the HLR for determining roaming using GSM network information, in the mmtel section, set determine-roaming-from-hlr to true:

        determine-roaming-from-hlr: true

Non-provisionable URIs

There will be URIs in the network that should not be provisioned for a subscriber.

How it works

The non-provisionable URIs specified in the Rhino VoLTE TAS are used for denying a call forward. If a non-provisionable URI matches a target URI (after normalization), any call forwarding rules related to this are ignored. For further information on call forwarding, see Communications Diversion (CDIV).

In addition, any XCAP request to create a forwarding rule which contains a non-provisonable URI is rejected.

Interactions with other services

The configured non-provisionable URIs interacts with call forwarding and limits what call forwarding rules can be provisioned.

Configuration

The non-provisionable-uris field designates what the Rhino VoLTE TAS will not provision, as shown in the example number-analysis-config.yaml file.

Setting up non-provisionable URIs configuration

I want to …​
Specify a series of URIs that the Rhino VoLTE TAS will reject call forwarding rules for

To set the Rhino VoLTE TAS to disable provisioning for certain URIs, in the number-analysis section, set non-provisionable-uris with a list of non-provisionable URIs.

    non-provisionable-uris:
        - "tel:111"
        - "sip:111@example.com"

Managing the subscriber data

The Rhino VoLTE TAS uses subscriber data to specify the behavior of services for provisioned subscribers.

In this section

Subscriber data document schemas

Subscriber data document schemas supported by the Rhino VoLTE TAS:

In this section

MMTel supplementary services schema

The Rhino VoLTE TAS supports all of GSMA IR.92 MMTel supplementary services except for Message Waiting Indication 3GPP TS 24.606.

The details of the MMTel-Services Schema are detailed in 3GPP 29.364 Section 7.2.

Supported services

The supported services in the MMTel Services schema for the Rhino VoLTE TAS are detailed in the following table.

Table 3. Supported Services in MMTel Services Document
Service XPath

Originating Identity Presentation (OIP)

/MMTELServices/complete-originating-identity-presentation/originating-identity-presentation

Originating Identity Restriction (OIR)

/MMTELServices/complete-originating-identity-restriction/originating-identity-presentation-restriction

Terminating Identity Presentation (TIP)

/MMTELServices/complete-terminating-identity-presentation/terminating-identity-presentation

Terminating Identity Restriction (TIR)

/MMTELServices/complete-terminating-identity-restriction/terminating-identity-presentation-restriction

Incoming Call Barring (ICB)

/MMTELServices/complete-communication-barring/incoming-communication-barring

Outgoing Call Barring (OCB)

/MMTELServices/complete-communication-barring/outgoing-communication-barring

Communications Diversion (CDIV)

/MMTELServices/complete-communication-diversion/communication-diversion

Conferencing (CONF)

/MMTELServices/complete-conference/operator-conference

Communication Waiting (CW)

/MMTELServices/complete-communication-waiting/communication-waiting

Communication Hold (HOLD)

/MMTELServices/complete-communication-hold/operator-communication-hold

Flexible Alerting (FA)

/MMTELServices/complete-flexible-alerting/operator-flexible-alerting-group

Explicit Communication Transfer (ECT)

/MMTelServices/complete-explicit-communication-transfer/operator-explicit-communication-transfer

IMS-ODB-Information schema

The IMS-ODB-Information document allows for Operator Determined Barring rules to be defined in the network.

The IMS-ODB-Information Schema is detailed in 3GPP 29.364 Section 10.2.

Metaswitch-TAS-Services schema

The Rhino VoLTE TAS uses a non-standard user document to support additional functionality beyond the MMTel supplementary services. This user document has the service indicator Metaswitch-TAS-Services.

This page details the schema for the Metaswitch-TAS-Services document.

Document overview

The Metaswitch-TAS-Services document stores non-standard subscriber service data for certain Rhino VoLTE TAS functionality.

The services that use this non-standard user document are described in:

Schema structure

The schema for the Metaswitch-TAS-Services document is defined in several xsd files.

There are two types of files that define the schema. These files establish the components such as elements and types that are either:

  • shared across the schema

  • specific for each service that is configured in the document

General schema files

The Metaswitch-TAS-Services document defines elements and types that are shared across the Rhino VoLTE TAS’s services that require non-standard subscriber data. These are defined in the following files:

  • metaswitch-tas-services.xsd

  • basic-settings.xsd

  • additional-attributes.xsd

metaswitch-tas-services.xsd

The metaswitch-tas-services.xsd file serves as the basis of the schema definition. It includes within its definition the xsd files for the basic-settings.xsd and each of the service specific schema definitions.

metaswitch-tas-services.xsd 
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:cp="urn:ietf:params:xml:ns:common-policy"
           xmlns:ocp="urn:oma:xml:xdm:common-policy"
           xmlns:mt="http://metaswitch.com/XMLSchema/tas"
           targetNamespace="http://metaswitch.com/XMLSchema/tas"
           elementFormDefault="qualified" attributeFormDefault="unqualified">

    <!-- the standardised schemas are in another namespace, so use xs:import -->
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../XCAP.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-common-data.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../originating-identity-presentation.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../terminating-identity-presentation.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../communication-diversion.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../communication-waiting.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../communication-barring.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-originating-identity-presentation.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-terminating-identity-presentation.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-malicious-communication-identification.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-communication-diversion.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-communication-waiting.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-communication-hold.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-communication-barring.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-completion-of-communication.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-message-waiting-indication.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-conference.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-advice-of-charge.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-explicit-communication-transfer.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-customized-alerting-tone.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-flexible-alerting.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../flexible-alerting.xsd" />

    <!-- tas-types is the same namespace, so use xs:include -->
    <xs:include schemaLocation="basic-settings.xsd" />
    <xs:include schemaLocation="location-based-dialling.xsd" />
    <xs:include schemaLocation="forward-to-voicemail.xsd" />
    <xs:include schemaLocation="companion-device.xsd" />

    <xs:element name="metaswitch-services" type="mt:metaswitch-services-type"/>

    <xs:complexType name="metaswitch-services-type">
        <xs:sequence>
            <xs:element name="complete-basic-settings" type="mt:completeBasicSettingsType" minOccurs="0"/>
            <xs:element name="complete-location-based-dialling" type="mt:completeLocationBasedDiallingType" minOccurs="0"/>
            <xs:element name="complete-forward-to-voicemail" type="mt:completeForwardToVoicemailType" minOccurs="0"/>
            <xs:element name="complete-companion-device" type="mt:completeCompanionDeviceType" minOccurs="0"/>

            <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

</xs:schema>

basic-settings.xsd

The basic-settings.xsd file includes the non-standard additional-attributes.xsd file.

basic-settings.xsd 
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:mt="http://metaswitch.com/XMLSchema/tas"
           targetNamespace="http://metaswitch.com/XMLSchema/tas"
           elementFormDefault="qualified" attributeFormDefault="unqualified">

    <!-- the standardised schemas are in another namespace, so use xs:import -->
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../XCAP.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-common-data.xsd" />

    <xs:include schemaLocation="additional-attributes.xsd" />

    <xs:complexType name="completeBasicSettingsType">
        <xs:sequence>
            <xs:element name="basic-settings" type="mt:basicSettingsType" minOccurs="0"/>
            <xs:element name="operator-basic-settings" type="mt:operatorBasicSettingsType" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="basicSettingsType">
        <xs:complexContent>
            <xs:extension base="ss:simservType">
                <xs:sequence>
                    <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                    <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="operatorBasicSettingsType">
        <xs:complexContent>
            <xs:extension base="ss:operatorServiceConfigType">
                <xs:sequence>
                    <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                    <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

</xs:schema>

additional-attributes.xsd

The additional-attributes.xsd file defines a key-value pair type to store additional attributes.

additional-attributes.xsd 
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:mt="http://metaswitch.com/XMLSchema/tas"
           targetNamespace="http://metaswitch.com/XMLSchema/tas"
           elementFormDefault="qualified" attributeFormDefault="unqualified">

    <xs:element name="additional-attributes">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="attribute" type="mt:keyValuePairType" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:complexType name="keyValuePairType">
        <xs:sequence>
            <xs:element name="key" type="xs:string"/>
            <xs:element name="value" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>

</xs:schema>

Service specific schema files

companion-device.xsd

See Companion device subscriber data for more information on managing the subscriber data for the companion device service.

companion-device.xsd 
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:mt="http://metaswitch.com/XMLSchema/tas"
           targetNamespace="http://metaswitch.com/XMLSchema/tas"
           elementFormDefault="qualified" attributeFormDefault="unqualified">

    <!-- the standardised schemas are in another namespace, so use xs:import -->
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../XCAP.xsd"/>
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
               schemaLocation="../operator-common-data.xsd"/>

    <xs:include schemaLocation="additional-attributes.xsd"/>

    <xs:complexType name="completeCompanionDeviceType">
        <xs:sequence>
            <xs:element name="companion-device" type="mt:companionDeviceType" minOccurs="0"/>
            <xs:element name="operator-companion-device" type="mt:operatorCompanionDeviceType" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="companionDeviceType">
        <xs:complexContent>
            <xs:extension base="ss:simservType">
                <xs:sequence>
                    <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                    <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="operatorCompanionDeviceType">
        <xs:complexContent>
            <xs:extension base="ss:operatorServiceConfigType">
                <xs:sequence>
                    <!-- The shared identity of the subscriber, this maybe a SIP or TEL URI, or both -->
                    <xs:element name="shared-identity-sip" type="xs:anyURI"/>
                    <xs:element name="shared-identity-tel" type="xs:anyURI"/>
                    <!-- Whether or not to hide/block undisclosed numbers -->
                    <xs:element name="hide-companion-identity" type="xs:boolean" minOccurs="0"/>
                    <xs:element name="devices" type="mt:devicesType"/>
                    <!-- Add additional-attributes to keep consistent with other metaswitch xml schema types -->
                    <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                    <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="devicesType">
        <xs:sequence>
            <xs:element name="device" minOccurs="0" maxOccurs="unbounded" type="mt:deviceType"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="deviceType">
        <xs:complexContent>
          <xs:extension base="ss:simservType">
            <xs:sequence>
                <xs:element name="model" type="xs:string"/>
                <xs:element name="radio-access" type="mt:radioAccessType"/>
                <xs:element name="impi" type="xs:string" minOccurs="0" />
                <xs:element name="imsi" type="xs:string" minOccurs="0" />
                <xs:element name="imei" type="xs:string" minOccurs="0" />
                <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
            </xs:sequence>
          </xs:extension>
        </xs:complexContent>
    </xs:complexType>


    <xs:complexType name="radioAccessType">
        <xs:all>
            <xs:element name="PS" type="mt:networkTypePS"/>
            <xs:element name="CS" type="mt:networkTypeCS"/>
        </xs:all>
    </xs:complexType>

    <xs:complexType name="networkType">
        <xs:sequence>
            <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="networkTypePS">
        <xs:complexContent>
            <xs:extension base="mt:networkType"/>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="networkTypeCS">
        <xs:complexContent>
            <xs:extension base="mt:networkType">
                <xs:attribute name="msisdn" type="xs:string" use="required"/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

</xs:schema>

location-based-dialling.xsd

See Location based dialing subscriber data for more information on managing the subscriber data for the location based dialing service.

location-based-dialling.xsd 
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:mt="http://metaswitch.com/XMLSchema/tas"
           targetNamespace="http://metaswitch.com/XMLSchema/tas"
           elementFormDefault="qualified" attributeFormDefault="unqualified">

    <!-- the standardised schemas are in another namespace, so use xs:import -->
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../XCAP.xsd"/>
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
               schemaLocation="../operator-common-data.xsd"/>

    <xs:include schemaLocation="additional-attributes.xsd"/>

    <xs:complexType name="completeCompanionDeviceType">
        <xs:sequence>
            <xs:element name="companion-device" type="mt:companionDeviceType" minOccurs="0"/>
            <xs:element name="operator-companion-device" type="mt:operatorCompanionDeviceType" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="companionDeviceType">
        <xs:complexContent>
            <xs:extension base="ss:simservType">
                <xs:sequence>
                    <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                    <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="operatorCompanionDeviceType">
        <xs:complexContent>
            <xs:extension base="ss:operatorServiceConfigType">
                <xs:sequence>
                    <!-- The shared identity of the subscriber, this maybe a SIP or TEL URI, or both -->
                    <xs:element name="shared-identity-sip" type="xs:anyURI"/>
                    <xs:element name="shared-identity-tel" type="xs:anyURI"/>
                    <!-- Whether or not to hide/block undisclosed numbers -->
                    <xs:element name="hide-companion-identity" type="xs:boolean" minOccurs="0"/>
                    <xs:element name="devices" type="mt:devicesType"/>
                    <!-- Add additional-attributes to keep consistent with other metaswitch xml schema types -->
                    <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                    <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="devicesType">
        <xs:sequence>
            <xs:element name="device" minOccurs="0" maxOccurs="unbounded" type="mt:deviceType"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="deviceType">
        <xs:complexContent>
          <xs:extension base="ss:simservType">
            <xs:sequence>
                <xs:element name="model" type="xs:string"/>
                <xs:element name="radio-access" type="mt:radioAccessType"/>
                <xs:element name="impi" type="xs:string" minOccurs="0" />
                <xs:element name="imsi" type="xs:string" minOccurs="0" />
                <xs:element name="imei" type="xs:string" minOccurs="0" />
                <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
            </xs:sequence>
          </xs:extension>
        </xs:complexContent>
    </xs:complexType>


    <xs:complexType name="radioAccessType">
        <xs:all>
            <xs:element name="PS" type="mt:networkTypePS"/>
            <xs:element name="CS" type="mt:networkTypeCS"/>
        </xs:all>
    </xs:complexType>

    <xs:complexType name="networkType">
        <xs:sequence>
            <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="networkTypePS">
        <xs:complexContent>
            <xs:extension base="mt:networkType"/>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="networkTypeCS">
        <xs:complexContent>
            <xs:extension base="mt:networkType">
                <xs:attribute name="msisdn" type="xs:string" use="required"/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

</xs:schema>

forward-to-voicemail.xsd

See Forward to voicemail subscriber data for more information on managing the subscriber data for the forward to voicemail service.

forward-to-voicemail.xsd 
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:mt="http://metaswitch.com/XMLSchema/tas"
           targetNamespace="http://metaswitch.com/XMLSchema/tas"
           elementFormDefault="qualified" attributeFormDefault="unqualified">

    <!-- the standardised schemas are in another namespace, so use xs:import -->
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../XCAP.xsd" />
    <xs:import namespace="http://uri.etsi.org/ngn/params/xml/simservs/xcap" schemaLocation="../operator-common-data.xsd" />

    <xs:include schemaLocation="additional-attributes.xsd" />

    <xs:complexType name="completeForwardToVoicemailType">
        <xs:sequence>
            <xs:element name="forward-to-voicemail" type="mt:forwardToVoicemailType" minOccurs="0"/>
            <xs:element name="operator-forward-to-voicemail" type="mt:operatorForwardToVoicemailType" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="forwardToVoicemailType">
        <xs:complexContent>
            <xs:extension base="ss:simservType">
                <xs:sequence>
                    <xs:element name="voicemail-server" type="xs:string" minOccurs="0"/>
                    <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                    <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="operatorForwardToVoicemailType">
        <xs:complexContent>
            <xs:extension base="ss:operatorServiceConfigType">
                <xs:sequence>
                    <xs:element name="allow-subscriber-update" type="xs:boolean" default="false"/>
                    <xs:element ref="mt:additional-attributes" minOccurs="0"/>
                    <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

</xs:schema>

Companion device subscriber data

The companion device service uses data configured in the subscriber’s Metaswitch-TAS-Services document. To see what operator-wide service configuration is available for the companion device service, check Companion device.

Example document

This example subscriber data document specifies that:

  • The companion device service is active for the subscriber and authorized by the operator.

  • The shared identities of all companion devices declared is sip:bob@home1.opencloud.co.nz

  • A PS-only companion device is configured for the subscriber.

<metaswitch-services xmlns="http://metaswitch.com/XMLSchema/tas">
    <complete-basic-settings>
        <basic-settings active="true"/>
        <operator-basic-settings authorized="true"/>
    </complete-basic-settings>
    <complete-companion-device>
        <companion-device active="true"/>
        <operator-companion-device authorized="true">
            <shared-identity-sip>sip:bob@home1.opencloud.co.nz</shared-identity-sip>
            <devices>
                <device active="true">
                    <model>companion-device-1</model>
                    <impi/>
                    <imsi/>
                    <imei/>
                    <radio-access>
                        <PS/>
                    </radio-access>
                </device>
            </devices>
        </operator-companion-device>
    </complete-companion-device>
</metaswitch-services>

Setting up the companion device service

I want to …​

Authorize and activate the companion device service for the subscriber

In the element at /metaswitch-services/complete-companion-device/operator-companion-device, set the authorized attribute to true:

<operator-companion-device authorized="true">

In the element at /metaswitch-services/complete-companion-device/companion-device, set the active attribute to true:

 <companion-device active="true"/>
Set the shared SIP identity for the subscriber’s companion devices

In the element at /metaswitch-services/complete-companion-device/operator-companion-device/shared-identity-sip, set the shared-identity-sip element to the SIP identity for the subscriber’s companion devices:

<shared-identity-sip>sip:bob@home1.opencloud.co.nz</shared-identity-sip>
Add a PS domain only companion device

In the element at /metaswitch-services/complete-companion-device/operator-companion-device/devices, add the following device type element to it:

<devices>
    <device active="true">
        <model>companion-device-1</model>
        <impi/>
        <imsi/>
        <imei/>
        <radio-access>
            <PS/>
        </radio-access>
    </device>
</devices>
Add a PS and CS domain capable companion device

In the element at /metaswitch-services/complete-companion-device/operator-companion-device/devices, add the following device type element to it:

<devices>
    <device active="true">
        <model>companion-device-1</model>
        <impi/>
        <imsi/>
        <imei/>
        <radio-access>
            <PS/>
            <CS msisdn="641234567"/>
        </radio-access>
    </device>
</devices>
Add a PS and CS domain capable companion device with a defined IMPI, IMSI, and IMEI

In the element at /metaswitch-services/complete-companion-device/operator-companion-device/devices, add the following device type element to it:

<devices>
    <device active="true">
        <model>companion-device-1</model>
        <impi>234150999999999@ims.mnc015.mcc234.3gppnetwork.org</impi>
        <imsi>234150999999999</imsi>
        <imei>90420156-025763-0</imei>
        <radio-access>
            <PS/>
            <CS msisdn="1234567"/>
        </radio-access>
    </device>
</devices>

Schema

The schema definition dedicated to the companion device service is stored in the companion-device.xsd.

Location based dialing subscriber data

The location based dialing service uses data configured in the subscriber’s Metaswitch-TAS-Services document. To see what operator-wide service configuration is available for the location based dialing service, check Location based dialing (LBD).

Example document

This example subscriber data document specifies that:

  • The location based dialing service is active for the subscriber and authorized by the operator.

  • The location based dialing configured group ID for the subscriber is PremiumGroup. This configured group ID may affect the destination address the subscriber is redirected to by the location based dialing service.

<metaswitch-services xmlns="http://metaswitch.com/XMLSchema/tas">
    <complete-basic-settings>
        <basic-settings active="true"/>
        <operator-basic-settings authorized="true"/>
    </complete-basic-settings>
    <complete-location-based-dialling>
        <location-based-dialling active="true"/>
        <operator-location-based-dialling authorized="true">
            <group-id>PremiumGroup</group-id>
        </operator-location-based-dialling>
    </complete-location-based-dialling>
</metaswitch-services>

Setting up the location based dialing service

I want to …​

Authorize and activate the location based dialing service for the subscriber

In the element at /metaswitch-services/location-based-diallingl/operator-location-based-dialling set the authorized attribute to true:

<operator-location-based-dialling authorized="true">

In the element at /metaswitch-services/complete-location-based-dialling/location-based-dialling set the active attribute to true:

<location-based-dialling active="true"/>
Set the subscriber’s group ID used to decide location based dialing behavior

The configured group ID may affect the destination address the subscriber is redirected to by the location based dialing service. Contact Metaswitch support for more information on configuring the location based dialing service.

In the element at /metaswitch-services/location-based-diallingl/operator-location-based-dialling/group-id set the element content to the group ID configured for the location based dialing service:

<group-id>PremiumGroup</group-id>

Schema

The schema definition dedicated to the location based dialing service is stored in the location-based-dialling.xsd.

Forward to voicemail subscriber data

The forward to voicemail service uses data configured in the subscriber’s Metaswitch-TAS-Services document. To see what operator-wide service configuration is available for the forward to voicemail service, check Voicemail forwarding.

Configuring the voicemail server URI

All subscribers using the Voicemail Forwarding service need to be configured with a voicemail server URI in the metaswitch-services section of their subscriber profile. This would normally be the single entry from the list of known voicemail servers.

Rhino VoLTE TAS has configuration to allow a subscriber to change their voicemail server URI. This is controlled by setting Allow Subscriber Update to true or false in the metaswitch-services section of their subscriber profile. The default deployment does not support subscribers being allowed to change their voicemail server URI. This is because there are policing and network routing issues related to user supplied URIs, especially Internet and email style URIs without user=phone.

Example document

This example subscriber data document specifies that:

  • The forward to voicemail service is active for the subscriber and authorized by the operator.

  • The voicemail server for which calls to the subscriber are forwarded to is sip:vms@home1.opencloud.co.nz

  • The subscriber is permitted to update and set their own voicemail server URI to forward calls to.

<metaswitch-services xmlns="http://metaswitch.com/XMLSchema/tas">
    <complete-basic-settings>
        <basic-settings active="true"/>
        <operator-basic-settings authorized="true"/>
    </complete-basic-settings>
    <complete-forward-to-voicemail>
        <forward-to-voicemail active="true">
            <voicemail-server>sip:vms@home1.opencloud.co.nz</voicemail-server>
        </forward-to-voicemail>
        <operator-forward-to-voicemail authorized="true">
            <allow-subscriber-update>true</allow-subscriber-update>
        </operator-forward-to-voicemail>
    </complete-forward-to-voicemail>
</metaswitch-services>

Setting up the forward to voicemail service

I want to …​

Authorize and activate the companion device service for the subscriber

In the element at /metaswitch-services/complete-forward-to-voicemail/operator-forward-to-voicemail, set the authorized attribute to true:

<operator-forward-to-voicemail authorized="true">

In the element at /metaswitch-services/complete-forward-to-voicemail/forward-to-voicemail, set the active attribute to true:

<forward-to-voicemail active="true">
Set the subscriber’s forwarding destination voicemail server URI

In the element at /metaswitch-services/complete-forward-to-voicemail/forward-to-voicemail/voicemail-server, set it to the destination voicemail server URI:

<voicemail-server>sip:vms@home1.opencloud.co.nz</voicemail-server>
Permit subscribers to update and set their own voicemail server URI to forward calls to

In the element at /metaswitch-services/complete-forward-to-voicemail/operator-forward-to-voicemail/allow-subscriber-update, set it to true:

<allow-subscriber-update>true</allow-subscriber-update>

Schema

The schema definition dedicated to the forward to voicemail device service is stored in the forward-to-voicemail.xsd.

Accessing subscriber data

This page discusses the different parts of the Rhino VoLTE TAS that may access subscriber data stored in the network’s HSS and/or HLR.

Data stored on the HSS

The HSS stores the subscribers' service and subscription data used by the Rhino VoLTE TAS for IMS networking.

For running services that are dependent on the subscriber’s configuration profile, the Rhino VoLTE TAS accesses the HSS through the Diameter Sh interface.

What accesses the subscriber data

The Rhino VoLTE TAS retrieves a subscriber’s data via the internal Sh Cache Microservice (ShCM) node. Configuration of the Sh interface and ShCM is detailed in HSS integration.

Through the ShCM node, the following Rhino VoLTE TAS nodes access the HSS subscriber data:

  • The MMT node for data used by services on the MMTel TAS and SCC-AS.

  • The SMO node for data used by services on the IP-SM-GW.

  • The MAG node for features that manage subscriber data such as the XCAP server, REST API, or an internal web user interface. Provisioning subscriber data describes these features in further detail.

A UE may use the XCAP protocol to manage service specific data through the Rhino VoLTE TAS.

Data stored on the HLR

Service data used by the Rhino VoLTE TAS for GSM or CDMA networking is stored on the HLR. The Rhino VoLTE TAS uses the MAP protocol to access the HLR.

Access to service data in the HLR is necessary for many services to operate using GSM and CDMA networking.

Configuration of the MAP interface is detailed in HLR integration.

Provisioning subscriber data

IMS-defined subscriber data

The subscriber’s IMS subscription in the HSS needs to be provisioned to utilize IMS subscription data. This is not something that the Rhino VoLTE TAS can do. This must be performed by the operator using the tools or APIs provided by the HSS vendor.

Service-specific subscriber data

Service-specific subscriber data determines a subscriber’s service profile, services enabled for the subscribers, and calls they are allowed to make.

The following tools are available for managing service specific subscriber data.

Subscriber access via XCAP

The Rhino VoLTE TAS allows a UE to configure subscriber service data via the XCAP protocol on the Ut interface. This includes support for bootstrap authentication and NAF XCAP interactions on the Rhino VoLTE TAS’s MAG nodes. For detailed information on configuring the interfaces that use XCAP, see RVT XCAP.

Rhino TAS REST API framework

The Rhino TAS REST API allows for managing per-subscriber service data configurations. This supports the operations to Create, Read, Modify and Delete a subscriber’s service data.

For further information, see the Sentinel VoLTE Provisioning REST API documentation.

Web GUI provisioning and editing

There is support for an operator to manually manage subscriber data with the Rhino VoLTE TAS via a Web GUI. Contact Metaswitch support for more details.

HSS or HLR vendor’s tools

The service-specific subscriber data may be provisioned by an operator using the HSS or HLR vendor’s supplied tools and APIs given a service template.

Using the alternate Cassandra schema

This section describes the procedures for changing the schema that Sentinel Registrar components of MMT and SMO nodes use.

The default schema for storing third-party registration data in the TSN may have high disk usage. This disk usage is a consequence of decisions about table schema used by Registrar components and data handling in the Cassandra database engine. Under some circumstances disk usage may become unpredicatable.

To reduce overall disk space usage and to improve predictablility an alternative Cassandra schema is provided. The instructions here allow you to change the MMT and SMO nodes to use the alternative schema.

Both the MMT and SMO nodes store third-party registration data on the TSN node. Separate instructions are provided for the MMT and SMO nodetypes. Parts of the proceedure require a maintenance window. Each nodetype may be done in a separate maintenance window.

Change the schema for MMT nodes

The default schema uses the first-party REGISTER callID field as a part of the primary key. RFC 3261 Section 10.2 states that User Equipment (UE) should use the same callID for the duration of the time it is registered. As the specification allows UE to use different CALLID values for the same registration, this requires proper handling.

As the callID is a part of the primary key, one row is used per unique callID, which may result in multiple rows representing the same logical registration. In cases where a significant proportion of UE on the network do not reuse their callID significantly more disk space is required to hold registration records. This contributes to the disk space for registration records being unpredictable under some circumstances.

The alternate schema uses the IMS private identity (hereafter deviceID) in place of callID in the schema. Per 3gpp 24.229 specification this must be set on all REGISTER attempts. As the deviceID does not change from registration attempt to registration attempt, the size of the database is more predictable.

See Data Schema for details of the Registrar schemas.

The following sections provide instructions for switching to the alternate schema on the MMT node. The required tables already exist on the TSN. You will change MMT configuration to use the alternate tables.

Impacts

During the change of the schema, the system may be affected as follows:

  1. There will be an increase in the number of HSS queries. This is because the third-party registrations serve as a cache, and in their absence, devices can only be verified through queries to the HSS. After the procedure is complete, the number of HSS queries should gradually return to the pre-maintenance window level.

    Note The speed at which the number of HSS queries returns to normal depends on the registration validity period. It can be very quick or fairly slow. It is anticipated to be very quick on average.

  2. When you run the TRUNCATE command, disk usage will not drop immediately. Disk usage will only drop after the nodetool clearsnapshot command is run. This is because the TRUNCATE command moves the data to a snapshot instead of deleting. The snapshot is only removed when the nodetool clearsnapshot command is run.

Note If you encounter any impacts that are not listed, contact Metaswitch technical support.

Pre-maintenance window steps for changing the Cassandra schema

Before entering the maintenance window you need to take some steps to get prepared. Performing these beforehand ensures that changing the Cassandra schema is a smooth exercise. Some steps can be done well in advance. Other steps need to bedone immediately before entering the maintenance window, as they are a final check to ensure everything is ready for the change.

Pre-maintenance window steps that can be done in advance

Verify the deployed MMT version

Make sure that the MMT VMs have already been upgraded to at least the maintenance version of RVT 4.1-1-1.0.0. The configuration changes that are being made will only work if the MMT is at least this version.

Create file with commands to run

There are commands that will need to be run in preparation for and during the Cassandra schema change. These commands requires specific arguments that need to be prepared beforehand. Creating a file of commands ready to be copy/pasted and run beforehand ensures smooth running of the steps. Placeholder values are of the form <…​>. <a|b> means a choice of either a or b. For example, mmt-<gsm|cdma> means mmt-gsm or mmt-cdma.

The file of commands can be stored anywhere that is convenient.

Many of the commands are rvtconfig commands. Further information can be found in the rvtconfig reference.

Determine the following arguments:

  1. tsn-mgmt-address - The management IP address of at least one TSN node. The TSN management IP addresses can be found in the TSN section of the SDF. If multiple addresses are used, they should be formatted as -c <address1> <address2>…​.

  2. deployment-id - This can be found in the SDF under the key deployment-id.

  3. site-id - The site-id of the site you are changing config for. This can be found in the SDF as site-id.

  4. group-id - Either RVT-mmt-gsm.<site-id> or RVT-mmt-cdma.<site-id> depending on whether the MMTs are of the GSM or CDMA variant. If you are unsure, this can be determined from the rvtconfig-path below.

  5. sdf-path - The path to the SDF file on your SIMPL VM.

  6. rvtconfig-path - The path to the rvtconfig on your SIMPL VM. This is expected to be something like: /home/admin/.local/share/csar/mmt-gsm/<version>/resources

If Cassandra authentication is enabled, then two additional arguments will be required for every rvtconfig command.

  1. cds-username - Username to authenticate with Cassandra. You can find it in the SDF under cassandra-username.

  2. cds-password-secret-name - Password identifier to authenticate with Cassandra. You can find it in the SDF under cassandra-password-id.

They are added in the format --cds-username <cds-username> --cds-password-secret-name <cds-password-secret-name> as the last two arguments to every rvtconfig command.

Create a text file containing all the subsequent commands with substitutions completed.

Take a backup of the current configuration

In case you need to roll back later, prepare a copy of the current configuration. Otherwise, you may have to recreate your configuration files manually.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

    $ cd <rvtconfig-path>
$ rvtconfig dump-config -c <tsn-mgmt-address> -d <deployment-id> --group-id <group-id> --vm-version-source this-rvtconfig --output-dir ~/yamls-rollback
    Note --output-dir is the output directory for the rvtconfig dump-config command. Any easily accessible directory can be chosen and the command will create the directory if it does not exist. The recommendation is to maintain ~/yamls-rollback, as this value is referenced in the rollback procedure. In the event that a different folder is used, substitute that value for ~/yamls-rollback in the rollback procedure.
Create the new configuration file

The new configuration needs to be written for upload. The configuration points to change are located in the mmt-<gsm|cdma>-overrides.yaml file in ~/yamls. Create the file if it does not exist.

MMT configuration change
Caution Contact Metaswitch technical support for assistance with writing the new configuration.
Warning Yaml uses semantic whitespace. The resulting file must be valid yaml that rvtconfig can accept.

If mmt-<gsm|cdma>-overrides.yaml does not exist, create it with the following content:

rhino-config:rhino-configuration:
  namespaces:
  - name: ''
    profile-tables:
    - name: RegistrarConfigurationTable
      profiles:
        - name: 'Metaswitch::::'
          present: true
          attributes:
            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

If mmt-<gsm|cdma>-overrides.yaml exists and does not contain the string RegistrarConfigurationTable, insert the following contents immediately below the line profile-tables::

    - name: RegistrarConfigurationTable
      profiles:
        - name: 'Metaswitch::::'
          present: true
          attributes:
            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

If mmt-<gsm|cdma>-overrides.yaml exists and contains the string RegistrarConfigurationTable, insert the following into the attributes key of RegistrarConfigurationTable:

            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

Pre-maintenance window steps to be done immediately prior to entering the maintenance window

Caution Before performing these steps, ensure that you have:

  1. A file with all the commands that need to be run for changing the Cassandra schema. The commands will have all the required arguments substituted.

  2. Two sets of .yaml configuration files - the new configuration (~/yamls), the current config (~/yamls-rollback).

  3. Verified that the deployment consists of the right version of the VMs.

Compare live configuration on MMTs with configuration on SIMPL

  1. Use SSH to access the SIMPL VM.

  2. Verify that the directory /tmp/checkdiff does not exist. If the directory does exist, remove it.

  3. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig compare-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls-rollback --output-dir /tmp/checkdiff --vm-version-source this-rvtconfig
Caution --output-dir is the output directory for the rvtconfig compare-config command. The command will create the directory if it does not exist and will return an error if the directory does exist.

  1. Verify that the command completes with:

No differences found in yaml files.
Uploading this configuration will have no effect unless secrets, certificates or licenses have changed, or --reload-resource-adaptors is specified.

If the output returned does not include "No differences found in yaml files.", contact Metaswitch technical support.

Perform health checks on MMTs in the deployment

The deployment needs to be in a healthy state. To verify that the deployment is healthy, run the following tests.

Run validation tests with CSAR validate

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ csar validate --vnf mmt-<gsm|cdma> --sdf <sdf-path>

  1. Verify that the command completes with:

All tests passed for CSAR 'mmt-<gsm|cdma>/<version-number>'!
Enter the maintenance window

If all the healthchecks above pass, start a maintenance window and then run through the steps for changing the Cassandra schema. To enter a maintenance window:

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig enter-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

Procedure

This section describes the steps for changing the primary key for MMT nodes. These steps are expected to take 30 minutes to complete.

Note Before beginning these steps, ensure that the placeholder values in commands listed here have been substituted with the required values. Placeholder values are of the form <…​>.

Truncate the registrations and assocuris tables on Cassandra

The existing registrations and assocuris tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.

  1. Use SSH to access the TSN as the primary user (sentinel).

  2. Start the Cassandra CLI by running the command:

$ cqlsh

  1. Truncate the tables by running the command:

TRUNCATE opencloud_thirdparty_reg.REGISTRATIONDATA;
TRUNCATE opencloud_thirdparty_reg.ASSOCURIS;

  1. Verify that there are no messages printed to the console after running the TRUNCATE command.

  2. Exit the Cassandra CLI by running:

$ exit
Note If the TRUNCATE command fails, run the next command (nodetool clearsnapshot), before attempting to run the TRUNCATE command and the nodetool command again.

Clear snapshots on all TSN nodes

  1. SSH as the primary user (sentinel) into each of the TSNs sequentially and run the command:

$ nodetool clearsnapshot opencloud_thirdparty_reg --all

Verify that the truncation has been successful

  1. Run the command:

$ df -h

  1. Verify that for the following two rows in the output, the <use>% values are less than 50%:

Filesystem                             Size    Used      Avail  Use% Mounted on
[...]
/dev/sda3                             <size>  <used>   <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size>  <used>   <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
Caution If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support.

  1. Exit the TSN by running:

$ exit

Upload the configuration

The new configuration written during the pre-maintenance window steps, is required to change the schema that is in use.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls --vm-version-source this-rvtconfig
Verify that the configuration has uploaded successfully

  1. Verify that the output after the command has completed running includes the following sentence:

Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>

  1. Exit the SIMPL VM by running:

$ exit

  1. Use SSH as the primary user (sentinel) to access each of the MMTs.

  2. From the home directory, run the command:

$ report-initconf status

until the following is displayed in the output:

status=vm_converged
Note If after 15 minutes, the status of the VMs is not converged, proceed to Rollback.

Test the new tables

  1. Perform a test call to force a registration.

Note If the test call does not succeed, proceed to Rollback.

Exit the maintenance window

Take the deployment out of maintenance window mode.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

  1. verify the command output includes the following:

Maintenance window has been terminated.
The VMs will resume running scheduled tasks as per their configured schedules.

Rollback

This section describes the steps for rolling back the change of primary key for MMT nodes. These steps are expected to take 30 minutes to complete.

Truncate the registrations_v2 and assocuris_v2 tables on Cassandra

The existing registrations_v2 and assocuris_v2 tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.

  1. Use SSH to access the TSN as the primary user (sentinel).

  2. Start the Cassandra CLI by running the command:

$ cqlsh

  1. Truncate the tables by running the command:

    TRUNCATE opencloud_thirdparty_reg.REGISTRATIONDATA_V2;
TRUNCATE opencloud_thirdparty_reg.ASSOCURIS_V2;

  2. Verify that there are no messages printed to the console after running the TRUNCATE command.

  3. Exit the Cassandra CLI by running:

$ exit
Note If the TRUNCATE command fails, run the next command (nodetool clearsnapshot), before attempting to run the TRUNCATE command and the nodetool command again.

Clear snapshots on all TSN nodes

  1. SSH as the primary user (sentinel) into each of the TSNs sequentially and run the command:

$ nodetool clearsnapshot opencloud_thirdparty_reg --all

Verify that the truncation has been successful

  1. Run the command:

$ df -h

  1. Verify that for the following two rows in the output, the <use>% values are less than 50%:

Filesystem                             Size    Used      Avail  Use% Mounted on
[...]
/dev/sda3                             <size>  <used>   <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size>  <used>   <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
Caution If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support.

  1. Exit the TSN by running:

$ exit

Upload the config

The backup config, which was taken during the pre-maintenance window steps, is required to change the schema that is in use.

  1. Use SSH to access the SIMPL VM.

  2. Copy the backup over ~/yamls:

    cp -f ~/yamls-rollback/* ~/yamls/

  3. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls --vm-version-source this-rvtconfig
Verify that the configuration has uploaded successfully

  1. Verify that the output after the command has completed running includes the following sentence:

Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>

  1. Exit the SIMPL VM by running:

$ exit

  1. Use SSH as the primary user (sentinel) to access each of the MMTs.

  2. From the home directory, run the command:

$ report-initconf status

until the following is displayed in the output:

status=vm_converged
Note If after 15 minutes, the status of the VMs is not converged, contact Metaswitch technical support.

Test the rollback

  1. Perform a test call to force a registration.

Note If the test call does not succeed, contact Metaswitch technical support.

Exit the maintenance window

Take the deployment out of maintenance window mode.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

    $ cd <rvtconfig-path>
$ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

  3. verify the command output includes the following:

Maintenance window has been terminated.
The VMs will resume running scheduled tasks as per their configured schedules.

Change the schema for SMO nodes

The default schema uses the first-party REGISTER callID field as a part of the primary key. RFC 3261 Section 10.2 states that User Equipment (UE) should use the same callID for the duration of the time it is registered. As the specification allows UE to use different CALLID values for the same registration, this requires proper handling.

As the callID is a part of the primary key, one row is used per unique callID, which may result in multiple rows representing the same logical registration. In cases where a significant proportion of UE on the network do not reuse their callID significantly more disk space is required to hold registration records. This contributes to the disk space for registration records being unpredictable under some circumstances.

The alternate schema uses the IMS private identity (hereafter deviceID) in place of callID in the schema. Per 3gpp 24.229 specification this must be set on all REGISTER attempts. As the deviceID does not change from registration attempt to registration attempt, the size of the database is more predictable.

See Data Schema for details of the Registrar schemas.

The following sections provide instructions for switching to the alternate schema on the SMO node. The required tables already exist on the TSN. You will change SMO configuration to use the alternate tables.

Impacts

During the change of the schema, the system may be affected as follows:

  1. There will be an increase in the number of HSS queries. This is because the third-party registrations serve as a cache, and in their absence, devices can only be verified through queries to the HSS. After the procedure is complete, the number of HSS queries should gradually return to the pre-maintenance window level.

    Note The speed at which the number of HSS queries returns to normal depends on the registration validity period. It can be very quick or fairly slow. It is anticipated to be very quick on average.

  2. When you run the TRUNCATE command, disk usage will not drop immediately. Disk usage will only drop after the nodetool clearsnapshot command is run. This is because the TRUNCATE command moves the data to a snapshot instead of deleting. The snapshot is only removed when the nodetool clearsnapshot command is run.

Note If you encounter any impacts that are not listed, contact Metaswitch technical support.

Pre-maintenance window steps for changing the Cassandra schema

Before entering the maintenance window you need to take some steps to get prepared. Performing these beforehand ensures that changing the Cassandra schema is a smooth exercise. Some steps can be done well in advance. Other steps need to bedone immediately before entering the maintenance window, as they are a final check to ensure everything is ready for the change.

Pre-maintenance window steps that can be done in advance

Verify the deployed SMO version

Make sure that the SMO VMs have already been upgraded to at least the maintenance version of RVT 4.1-1-1.0.0. The configuration changes that are being made will only work if the SMO is at least this version.

Create file with commands to run

There are commands that will need to be run in preparation for and during the Cassandra schema change. These commands requires specific arguments that need to be prepared beforehand. Creating a file of commands ready to be copy/pasted and run beforehand ensures smooth running of the steps. Placeholder values are of the form <…​>. <a|b> means a choice of either a or b. For example, mmt-<gsm|cdma> means mmt-gsm or mmt-cdma.

The file of commands can be stored anywhere that is convenient.

Many of the commands are rvtconfig commands. Further information can be found in the rvtconfig reference.

Determine the following arguments:

  1. tsn-mgmt-address - The management IP address of at least one TSN node. The TSN management IP addresses can be found in the TSN section of the SDF. If multiple addresses are used, they should be formatted as -c <address1> <address2>…​.

  2. deployment-id - This can be found in the SDF under the key deployment-id.

  3. site-id - The site-id of the site you are changing config for. This can be found in the SDF as site-id.

  4. group-id - The group-id of the SMO vnf, RVT-smo.<site-id>.

  5. sdf-path - The path to the SDF file on your SIMPL VM.

  6. rvtconfig-path - The path to the rvtconfig on your SIMPL VM. This is expected to be something like: /home/admin/.local/share/csar/smo/<version>/resources

If Cassandra authentication is enabled, then two additional arguments will be required for every rvtconfig command.

  1. cds-username - Username to authenticate with Cassandra. You can find it in the SDF under cassandra-username.

  2. cds-password-secret-name - Password identifier to authenticate with Cassandra. You can find it in the SDF under cassandra-password-id.

They are added in the format --cds-username <cds-username> --cds-password-secret-name <cds-password-secret-name> as the last two arguments to every rvtconfig command.

Create a text file containing all the subsequent commands with substitutions completed.

Take a backup of the current configuration

In case you need to roll back later, prepare a copy of the current configuration. Otherwise, you may have to recreate your configuration files manually.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

    $ cd <rvtconfig-path>
$ rvtconfig dump-config -c <tsn-mgmt-address> -d <deployment-id> --group-id <group-id> --vm-version-source this-rvtconfig --output-dir ~/yamls-rollback
    Note --output-dir is the output directory for the rvtconfig dump-config command. Any easily accessible directory can be chosen and the command will create the directory if it does not exist. The recommendation is to maintain ~/yamls-rollback, as this value is referenced in the rollback procedure. In the event that a different folder is used, substitute that value for ~/yamls-rollback in the rollback procedure.
Create the new configuration file

The new configuration needs to be written for upload. The configuration points to change are located in the smo-overrides.yaml file in ~/yamls. Create the file if it does not exist.

SMO configuration change
Caution Contact Metaswitch technical support for assistance with writing the new configuration.
Warning Yaml uses semantic whitespace. The resulting file must be valid yaml that rvtconfig can accept.

If smo-overrides.yaml does not exist, create it with the following content:

rhino-config:rhino-configuration:
  namespaces:
  - name: ''
    profile-tables:
    - name: RegistrarConfigurationTable
      profiles:
        - name: 'Metaswitch::::'
          present: true
          attributes:
            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

If smo-overrides.yaml exists and does not contain the string RegistrarConfigurationTable, insert the following contents immediately below the line profile-tables::

    - name: RegistrarConfigurationTable
      profiles:
        - name: 'Metaswitch::::'
          present: true
          attributes:
            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

If smo-overrides.yaml exists and contains the string RegistrarConfigurationTable, insert the following into the attributes key of RegistrarConfigurationTable:

            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

Pre-maintenance window steps to be done immediately prior to entering the maintenance window

Caution Before performing these steps, ensure that you have:

  1. A file with all the commands that need to be run for changing the Cassandra schema. The commands will have all the required arguments substituted.

  2. Two sets of .yaml configuration files - the new configuration (~/yamls), the current config (~/yamls-rollback).

  3. Verified that the deployment consists of the right version of the VMs.

Compare live configuration on SMOs with configuration on SIMPL

  1. Use SSH to access the SIMPL VM.

  2. Verify that the directory /tmp/checkdiff does not exist. If the directory does exist, remove it.

  3. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig compare-config -c <tsn-mgmt-address> -t smo -i ~/yamls-rollback --output-dir /tmp/checkdiff --vm-version-source this-rvtconfig
Caution --output-dir is the output directory for the rvtconfig compare-config command. The command will create the directory if it does not exist and will return an error if the directory does exist.

  1. Verify that the command completes with:

No differences found in yaml files.
Uploading this configuration will have no effect unless secrets, certificates or licenses have changed, or --reload-resource-adaptors is specified.

If the output returned does not include "No differences found in yaml files.", contact Metaswitch technical support.

Perform health checks on SMOs in the deployment

The deployment needs to be in a healthy state. To verify that the deployment is healthy, run the following tests.

Run validation tests with CSAR validate

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ csar validate --vnf smo --sdf <sdf-path>

  1. Verify that the command completes with:

All tests passed for CSAR 'smo/<version-number>'!
Enter the maintenance window

If all the healthchecks above pass, start a maintenance window and then run through the steps for changing the Cassandra schema. To enter a maintenance window:

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig enter-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

Procedure

This section describes the steps for changing the primary key for SMO nodes. These steps are expected to take 30 minutes to complete.

Note Before beginning these steps, ensure that the placeholder values in commands listed here have been substituted with the required values. Placeholder values are of the form <…​>.

Truncate the registrations and assocuris tables on Cassandra

The existing registrations and assocuris tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.

  1. Use SSH to access the TSN as the primary user (sentinel).

  2. Start the Cassandra CLI by running the command:

$ cqlsh

  1. Truncate the tables by running the command:

TRUNCATE opencloud_ipsmgw_thirdparty_reg.REGISTRATIONDATA;
TRUNCATE opencloud_ipsmgw_thirdparty_reg.ASSOCURIS;

  1. Verify that there are no messages printed to the console after running the TRUNCATE command.

  2. Exit the Cassandra CLI by running:

$ exit
Note If the TRUNCATE command fails, run the next command (nodetool clearsnapshot), before attempting to run the TRUNCATE command and the nodetool command again.

Clear snapshots on all TSN nodes

  1. SSH as the primary user (sentinel) into each of the TSNs sequentially and run the command:

$ nodetool clearsnapshot opencloud_ipsmgw_thirdparty_reg --all

Verify that the truncation has been successful

  1. Run the command:

$ df -h

  1. Verify that for the following two rows in the output, the <use>% values are less than 50%:

Filesystem                             Size    Used      Avail  Use% Mounted on
[...]
/dev/sda3                             <size>  <used>   <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size>  <used>   <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
Caution If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support.

  1. Exit the TSN by running:

$ exit

Upload the configuration

The new configuration written during the pre-maintenance window steps, is required to change the schema that is in use.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t smo -i ~/yamls --vm-version-source this-rvtconfig
Verify that the configuration has uploaded successfully

  1. Verify that the output after the command has completed running includes the following sentence:

Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>

  1. Exit the SIMPL VM by running:

$ exit

  1. Use SSH as the primary user (sentinel) to access each of the SMOs.

  2. From the home directory, run the command:

$ report-initconf status

until the following is displayed in the output:

status=vm_converged
Note If after 15 minutes, the status of the VMs is not converged, proceed to Rollback.

Test the new tables

  1. Perform a test SMS to force a registration.

Note If the test SMS does not succeed, proceed to Rollback.

Exit the maintenance window

Take the deployment out of maintenance window mode.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

  1. verify the command output includes the following:

Maintenance window has been terminated.
The VMs will resume running scheduled tasks as per their configured schedules.

Rollback

This section describes the steps for rolling back the change of primary key for SMO nodes. These steps are expected to take 30 minutes to complete.

Truncate the registrations_v2 and assocuris_v2 tables on Cassandra

The existing registrations_v2 and assocuris_v2 tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.

  1. Use SSH to access the TSN as the primary user (sentinel).

  2. Start the Cassandra CLI by running the command:

$ cqlsh

  1. Truncate the tables by running the command:

    TRUNCATE opencloud_ipsmgw_thirdparty_reg.REGISTRATIONDATA_V2;
TRUNCATE opencloud_ipsmgw_thirdparty_reg.ASSOCURIS_V2;

  2. Verify that there are no messages printed to the console after running the TRUNCATE command.

  3. Exit the Cassandra CLI by running:

$ exit
Note If the TRUNCATE command fails, run the next command (nodetool clearsnapshot), before attempting to run the TRUNCATE command and the nodetool command again.

Clear snapshots on all TSN nodes

  1. SSH as the primary user (sentinel) into each of the TSNs sequentially and run the command:

$ nodetool clearsnapshot opencloud_ipsmgw_thirdparty_reg --all

Verify that the truncation has been successful

  1. Run the command:

$ df -h

  1. Verify that for the following two rows in the output, the <use>% values are less than 50%:

Filesystem                             Size    Used      Avail  Use% Mounted on
[...]
/dev/sda3                             <size>  <used>   <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size>  <used>   <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
Caution If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support.

  1. Exit the TSN by running:

$ exit

Upload the config

The backup config, which was taken during the pre-maintenance window steps, is required to change the schema that is in use.

  1. Use SSH to access the SIMPL VM.

  2. Copy the backup over ~/yamls:

    cp -f ~/yamls-rollback/* ~/yamls/

  3. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t smo -i ~/yamls --vm-version-source this-rvtconfig
Verify that the configuration has uploaded successfully

  1. Verify that the output after the command has completed running includes the following sentence:

Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>

  1. Exit the SIMPL VM by running:

$ exit

  1. Use SSH as the primary user (sentinel) to access each of the SMOs.

  2. From the home directory, run the command:

$ report-initconf status

until the following is displayed in the output:

status=vm_converged
Note If after 15 minutes, the status of the VMs is not converged, contact Metaswitch technical support.

Test the rollback

  1. Perform a test SMS to force a registration.

Note If the test SMS does not succeed, contact Metaswitch technical support.

Exit the maintenance window

Take the deployment out of maintenance window mode.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

    $ cd <rvtconfig-path>
$ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

  3. verify the command output includes the following:

Maintenance window has been terminated.
The VMs will resume running scheduled tasks as per their configured schedules.

RVT service centralization and continuity configuration

This section describes how to set up the service centralization and continuity (SCC) services.

In this section

Terminating Access Domain Selection (T-ADS)

What it does

Terminating Access Domain Selection (T-ADS) is a component of the terminating SCC AS that determines whether a call should be delivered over the circuit-switched (CS) or the packet-switched (PS) network. It adjusts the SIP signaling as required to deliver the call over the CS or PS network.

Routing mode

T-ADS supports several different modes which determine how it will prioritize its attempts to connect to the CS and/or PS networks. The mode to use for any given call is not determined by T-ADS configuration, but instead by a parameter on the Route header of the incoming SIP INVITE request. The parameter’s name is oc-tads-routing. It can have the following values:

Table 4. T-ADS routing modes
Parameter value Behavior 
ps-cs

T-ADS first attempts to connect the call over the PS network, and falls back to the CS network if that fails.

 
cs-ps

T-ADS first attempts to connect the call over the CS network, and falls back to the PS network if that fails.

 
ps-only

T-ADS only attempts to connect the call over the PS network.

 
cs-only

T-ADS only attempts to connect the call over the CS network.

 
parallel

T-ADS forks the call and attempts to connect the call over the CS and PS networks simultaneously; the first fork to be successfully answered is selected.

If the parameter is absent, the ps-cs behavior is used.

All modes other than parallel are collectively known as "sequential" modes.

Note Route header parameters can be set in the subscriber’s initial filter criteria (iFC) on the HSS.
Request disposition

In one particular case, the Request-Disposition header (defined in RFC 3841) can alter the behavior selected by the oc-tads-routing parameter. If the Request-Disposition header contains the value no-fork and does not also contain the value redirect, then:

  • ps-cs and parallel use the ps-only behavior

  • cs-ps uses the cs-only behavior.

CS routing

When T-ADS attempts to route the call over the CS network, it will generate a CS Domain Routing Number (CSRN). This number is used in the Request-URI of the outbound INVITE request. There are a few options for how T-ADS should generate the CSRN.

The basic number can be taken from any of the following numbers:

  • Correlation Mobile Station International Subscriber Directory Number (C-MSISDN), which is retrieved from the HSS

  • Mobile Station Roaming Number (MSRN), which is retrieved from the HLR (for GSM networks only)

  • Temporary Local Directory Number (TLDN), which is retrieved from the HLR (for CDMA networks only).

An optional prefix can be specified that will be added to that number to create the final CSRN.

Routing via the I-CSCF

When routing to the CS network, it may be desirable to send the outbound INVITE request directly to the I-CSCF, bypassing the S-CSCF and thus any further IMS services that it might try to invoke. This can be configured with the cs-routing-via-icscf field.

PS routing

T-ADS supports three different modes for determining where to route requests to the PS network. It may route to:

  • the subscriber’s IMS public identity

  • the SIP instance(s) that are recorded in pub-gruu information in the subscriber’s registration data

  • the SIP instance(s) that are recorded in pub-gruu and Path information in the subscriber’s registration data.

Both modes that use SIP instances can result in multiple different attempts to connect the call over the PS network (one attempt for each acceptable SIP instance).

Route validation and voice over PS support

Unless there is an oc-blindpsrouting parameter present on the Route header of the initial INVITE request for a call, T-ADS will do additional validation on each PS route before deciding to use it.

The method for doing this validation depends on the setting for voice-over-ps-support.

If voice over PS support is required, the route will be validated by explicitly asking the HSS if voice over PS is supported for that route. If voice over PS support is not required, the route will be validated by checking access network information in the subscriber’s registration data.

When querying the HSS for voice over PS support, there are several different options for which subscriber identity to query the information for. The option to use varies depending on the network. The options are listed here.

Table 5. Subscriber identities for HSS queries
Setting Description 
IMPU

The IMS public identity

 
MSISDN

The C-MSISDN

 
IMPU_IMPI

A combination of the IMS public and private identities

 
MSISDN_IMPI

A combination of the C-MSISDN and the IMS private identity
Voice over Wi-Fi

By default, T-ADS will select PS routes that go through the PS cellular network. The system also supports PS routes that go through the internet and Wi-Fi. You can configure this with the wlan-allowed field.

Deciding on a route

This section describes the approach T-ADS uses to decide whether a particular routing attempt has been successful. The routing mode determines the order in which routes are attempted (or whether they should all be attempted at the same time in the case of parallel mode). It is important to note that even if a particular route receives a SIP error response, T-ADS may still determine it was a successful routing attempt and forward the response to the caller, thus ending the call.

In sequential routing modes

Usually, a route is selected and T-ADS completes once a non-100 SIP response is received from a connection attempt on that route (which is true even if the response is an error response that will cause the call to be terminated). A route is usually only rejected if no response is received within the maximum wait time period specified in the tads-timer-max-wait-milliseconds setting. However, there are exceptions to this:

  • If a provisional SIP response is received that has an SDP body with a disabled audio stream and the subscriber is known to have multiple devices on the current route, the response will be ignored and the maximum wait time will be reset.

  • If a SIP error response with a 488 status code is received, the route is rejected.*

  • If attempting a PS route and a SIP error response is received with a status code matching a code in ps-fallback-response-codes, the route is rejected.*

* If all PS routes have been exhausted and the error response has an SDP body with no PSTN audio streams, the call will be terminated instead.

When a route is rejected, T-ADS aborts the connection attempt and attempts to connect the call on the next available route. If all available routes have been rejected, the call is terminated.

In parallel routing mode

The first route to receive a SIP success response is selected. If all routes respond with a SIP error response or the maximum wait time period specified in the parallel-timer-max-wait-milliseconds setting is exceeded, the call is terminated.

As a special case when the companion device service is in use, if a 486 Busy SIP response is received from any route it is possible to end the call immediately. You can configure this with the release-all-legs-on-busy setting.

Interactions with other services

Communications Diversion (CDIV)

If an attempt to connect the call over the CS network fails, it is possible that communication forwarding could be triggered twice; the first time downstream of the SCC AS in the CS core network, the second time in the IMS core upstream in the MMTel AS.

T-ADS can be configured to suppress communication forwarding services in the CS network. It does this by imposing a limit on the number of times the call may be forwarded, then indicating that the limit has been reached. SIP Diversion headers are used to send this information to the CS network, with limit parameters used to set the limit. One of the following methods is used to indicate that the limit has been reached:

  • including a pair of Diversion headers that each have a counter parameter which, between the two, sums to the diversion limit, or

  • including a number of Diversion headers that matches the limit.

For configuration instructions, see Suppress call forwarding services in the CS network.

For details of how to suppress forwarding in the MMTel AS, see Communications Diversion (CDIV).

Companion device

The companion device service may force T-ADS to ignore the requested routing mode and use parallel instead. Restrictions imposed by the Request-Disposition header will still apply in this case.

The companion device service may also provide its own set of CSRNs for T-ADS to use when attempting to connect the call over the CS network.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to T-ADS in the sentinel-volte/tads section.

What you need

  • ❏ The source for generating the CSRN for CS delivery; one of: C-MSISDN, MSRN, or TLDN.

  • ❏ The source for generating potential PS routes; one of: IMS_PUBLIC_IDENTITY, SIP_INSTANCE, or PATH_FROM_SIP_INSTANCE.

  • ❏ If checking for Voice Over PS support before routing over PS to a subscriber, the identity to use when querying the HSS; one of: IMPU, MSISDN, IMPU_IMPI, or MSISDN_IMPI

  • ❏ Whether or not calls outbound to the CS network should bypass the S-CSCF and go directly to the I-CSCF.

  • ❏ Whether or not calls are allowed to be delivered over a Wi-Fi network.

  • ❏ What error code to send to the caller if the call is terminated due to no routes being found.

If using the parallel routing mode:

  • ❏ The maximum time to wait for a call to be answered.

  • ❏ Whether or not to abort the call if any routing attempt receives a 486 Busy response.

If using any sequential routing modes:

  • ❏ The maximum time to wait for a response during a particular routing attempt.

  • ❏ Any SIP error codes that you would like to trigger an attempt on the next available route, instead of ending the call.

Setting up CS routing behavior

I want to…​
Generate the CSRN from the C-MSISDN when routing to the CS network
Warning Ensure that HSS integration has been configured.

In the tads section, set address-source-for-scc-tads to CMSISDN:

            address-source-for-scc-tads: CMSISDN

Related section: CS routing

Generate the CSRN from the MSRN when routing to the CS network
Warning Ensure that HLR integration has been configured.
Note Be aware that the MSRN is only available on GSM networks.

In the tads section, set address-source-for-scc-tads to MSRN:

            address-source-for-scc-tads: MSRN

Related section: CS routing

Generate the CSRN from the TLDN when routing to the CS network
Warning Ensure that HLR integration has been configured.

Be aware that the TLDN is only available on CDMA networks.

In the tads section, set address-source-for-scc-tads to TLDN:

            address-source-for-scc-tads: TLDN

Related section: CS routing

Include a number prefix (steering digits) on the generated CSRN

In this example 00 is used as the prefix.

In the tads section, set csrn-prefix to "00":

            csrn-prefix: "00"

Related section: CS routing

Have no prefix (steering digits) on the generated CSRN

In the tads section, set csrn-prefix to "":

            csrn-prefix: ""

Related section: CS routing

Prevent T-CSI information from being requested from the HLR
Note This is only relevant on GSM networks when using the MSRN to generate the CSRN.

In the tads section, in sri-requests-to-hlr, set set-suppress-tcsi-flag to true:

            sri-requests-to-hlr:
                set-suppress-tcsi-flag: true
Prevent announcement information from being requested from the HLR

This is only relevant on GSM networks when using the MSRN to generate the CSRN.

In the tads section, in sri-requests-to-hlr, set set-suppress-announcement-flag to true:

            sri-requests-to-hlr:
                set-suppress-announcement-flag: true
Route calls to the CS network directly through the I-CSCF
Warning Ensure that I-CSCF integration has been configured.

In the tads section, set cs-routing-via-icscf to true:

            cs-routing-via-icscf: true

Related section: Routing via the I-CSCF

Route calls to the CS network through the S-CSCF

In the tads section, set cs-routing-via-icscf to false:

            cs-routing-via-icscf: false

Related section: Routing via the I-CSCF

Suppress call forwarding services in the CS network

In the tads section, ensure that the suppress-cs-domain-call-diversion section is present and not commented out.

            suppress-cs-domain-call-diversion:
                use-diversion-counter-parameter: true
                cs-domain-diversion-limit: 1

  • Set use-diversion-counter-parameter to:

    • true to indicate that the limit has been reached using the counter parameter on the SIP Diversion header, or

    • false to indicate that the limit has been reached using the number of Diversion headers present.

  • Set cs-domain-diversion-limit to the maximum number of times you want to indicate that call forwarding was allowed (note that no matter what this setting is, T-ADS will still indicate that the limit has been reached).

Related section: Interaction with call forwarding

Allow call forwarding services in the CS network

In the tads section, remove or comment out the entire suppress-cs-domain-call-diversion section.

 #           suppress-cs-domain-call-diversion:
 #               use-diversion-counter-parameter: true
 #               cs-domain-diversion-limit: 1

Related section: Interaction with call forwarding

Setting up PS routing behaviour

I want to…​
Route the PS attempt to the subscriber’s IMS public identity

In the tads section, set tads-identity-for-terminating-device:

            tads-identity-for-terminating-device: IMS_PUBLIC_IDENTITY

Related section: PS routing

Route PS attempts to the SIP instance of the terminating device(s)

In the tads section, set tads-identity-for-terminating-device:

            tads-identity-for-terminating-device: SIP_INSTANCE

Related section: PS routing

Route PS attempts to the SIP instance path of the terminating device(s)

In the tads section, set tads-identity-for-terminating-device:

            tads-identity-for-terminating-device: PATH_FROM_SIP_INSTANCE

Related section: PS routing

Check that a subscriber has support for Voice Over PS before attempting to route over the PS network
Warning Ensure that HSS integration has been configured.

In the tads section, ensure that the voice-over-ps-support section is present and not commented out.

            voice-over-ps-support:
                request-user-identity-type: IMPU

Set which subscriber identity to use when querying the HSS for the voice over PS support information. See request-user-identity-type for the list of options.

Related section: Route validation and voice over PS support

Skip the check that the subscriber has voice over PS support before attempting to route the call over the PS network

In the tads section, remove or comment out the entire voice-over-ps-support section.

#            voice-over-ps-support:
#                request-user-identity-type: IMPU

Related section: Route validation and voice over PS support

Allow calls to be connected over Wi-Fi networks

In the tads section, set wlan-allowed:

            wlan-allowed: true

Related section: Voice over Wi-Fi

Setting up route selection behavior

I want to…​
Change the SIP response code used to end the call if no valid route to the called party can be found

In this example the call will be ended with a 410 Gone response.

In the tads section, set end-session-error-code:

            end-session-error-code: 410
End all companion device connection attempts if any one of them returns a 486 Busy response

In the tads, on-parallel-routing section, set release-all-legs-on-busy:

                release-all-legs-on-busy: true

Related section: Deciding on a route in parallel routing mode

Change the maximum time to wait to get a final response from any parallel connection attempt

This example sets the maximum wait time to 15 seconds.

In the tads , on-parallel-routing section, set parallel-timer-max-wait-milliseconds to the desired value in milliseconds:

                parallel-timer-max-wait-milliseconds: 15000

Related section: Deciding on a route in parallel routing mode

Try the next available route if a PS attempt results in a particular SIP response status code or codes
Note A 488 response will always cause the next available route to be attempted, and does not need to be included in this field.

This example lists 408, 480, and 481 as the codes that should trigger the next routing attempt.

In the tads, on-sequential-routing section, set ps-fallback-response-codes with the list of desired response codes:

                ps-fallback-response-codes: [ 408, 480, 481 ]

Related section: Deciding on a route in sequential routing modes

Change the maximum time to wait for a response before trying the next route
Note This setting is only relevant when using a sequential routing mode and is subject to the provisional response condition described in Deciding on a route in sequential routing modes.

In the tads, on-sequential-routing section, set tads-timer-max-wait-milliseconds to the value in milliseconds:

                tads-timer-max-wait-milliseconds: 5000

Access transfer

What it does

Access transfer is a Rhino VoLTE TAS SCC service that is responsible for managing the handover of a call from a packet switched (PS) network to a circuit switched (CS) network when a subscriber moves out of PS network coverage. It works by replacing the existing access leg (that is, the SIP leg between the Rhino VoLTE TAS and the served user) with a new one.

Access transfer is initiated on receipt of a new initial INVITE request that has a Request-URI which aligns with either the configured ATU-STI or STN-SR. Initially this request is not directly associated with the call it applies to, and initially may not even be processed by the same Rhino VoLTE TAS node that is handling the original call. Information in the new INVITE request is used to correlate it with the original call so that it can be injected into that call, where it is used to establish the new access leg.

Supported cases

The Rhino VoLTE TAS supports Single Radio Voice Call Continuity (SRVCC) for PS to CS transfer of sessions in the following cases:

  • a single active session with media anchored in the Access Transfer Gateway (eSRVCC)

  • a single active session with media not anchored in the Access Transfer Gateway (standard SRVCC)

  • a single alerting session (aSRVCC)

  • a single originating session in the pre-alerting state (bSRVCC).

If a device initiates access transfer while it has multiple sessions in progress (for example, if the subscriber has someone on hold while talking on another call), only the most recently active session will be transferred. All other sessions are treated as superfluous and are ended as part of the transfer procedure.

Enabling access transfer

Access transfer is not enabled through configuration. Instead, it is enabled per-call if both of the following requirements are met:

  • The served subscriber’s registration data indicates that their device has UE-SRVCC-Capability.

  • The served subscriber has an assigned C-MSISDN in the HSS.

There are additional requirements for alerting and pre-alerting access transfer. These take the form of media feature tags in the SIP Contact header from the subscriber. For the calling subscriber this head will be checked on the initial INVITE request, for the called subscriber the first SIP 18x response will be checked. To enable alerting access transfer there must be a +g.3gpp.srvcc-alerting tag, and for pre-alerting access transfer there must be a +g.3gpp.ps2cs-srvcc-orig-pre-alerting tag. Note that pre-alerting access transfer is only applicable to the calling subscriber.

Access Transfer Control Function

Access Transfer Control Function (ATCF) is a signalling anchor that is used for eSRVCC procedures. It is responsible for initiating access transfer procedures in the Rhino VoLTE TAS by sending a INVITE request using the ATU-STI as the Request-URI.

To determine where to send access transfer requests, the ATCF must know the ATU-STI to use for a given subscriber. The Rhino VoLTE TAS is responsible for notifying the ATCF of the ATU-STI, which it does by sending it in a SIP MESSAGE request when the subscriber registers with the network. The maximum time that the Rhino VoLTE TAS should wait for a response to the MESSAGE request can be configured in the atcf-update-timeout-milliseconds field.

STN-SR and ATU-STI

The STN-SR (Session Transfer Number for SRVCC) and ATU-STI (Access Transfer Update - Session Transfer Identifier) serve the same purpose of identifying that an incoming request is for access transfer. The main difference between the two is that they are used to trigger different versions of the access transfer procedure.

The STN-SR is used for access transfer as defined in the Rel-8 3GPP specifications, where signalling is not anchored in the ATCF, therefore the Rhino VoLTE TAS receives the transfer request directly from the MSC (Mobile Switching Center, part of the CS core network). It takes the form of a number prefix on the Request-URI of the incoming access transfer request. The only requirement for picking an STN-SR is that it must cause messages to be delivered to the Rhino VoLTE TAS. When a subscriber registers with the network, the Rhino VoLTE TAS will update their STN-SR in the HSS to match what is configured here.

The ATU-STI is used for access transfer, as defined in the Rel-10 3GPP specifications, where signalling is anchored in the ATCF, therefore the transfer request comes from the ATCF. It is a fixed URI that is used as the Request-URI on access transfer requests. As the Rhino VoLTE TAS tells the ATCF what ATU-STI to use for a subscriber, the only requirement for its value is that it resolves to the Rhino VoLTE TAS.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to access transfer in the sentinel-volte/scc/service-continuity section.

What you need

  • ❏ The STN-SR that will trigger Rel-8 access transfer.

  • ❏ Optionally, a custom timeout period to wait for a response from the ATCF when updating the ATU-STI for a subscriber.

Setting up access transfer

I want to…​
Set the STN-SR for triggering Rel-8 access transfer

In the service-continuity section, set stn-sr with the desired number prefix:

            stn-sr: "123456"

Related section: STN-SR and ATU-STI

Change how long to wait for the ATCF to respond to a request to update a subscriber’s ATU-STI

In the service-continuity section, set atcf-update-timeout-milliseconds with the desired time period, in milliseconds:

            atcf-update-timeout-milliseconds: 5000

Related section: Access Transfer Control Function

Reorigination

What it does

Reorigination enables CS calls to be processed in the SCC-AS. SS7 triggers received by the Rhino VoLTE TAS are forwarded to a number within a pre-defined range, which causes the call to be rerouted into the IMS. The SCC-AS then acts as a B2BUA between the I-CSCF and the subscriber’s assigned S-CSCF.

Routing through the I-CSCF

The SCC-AS will add a CSCF address to the route header of the outgoing INVITE message. This address can be either the calling party’s S-CSCF address retrieved from the HSS, or it can be the I-CSCF address configured in i-cscf-uri.

Anti-fraud measures

To guard against fraud, the P-Asserted-Identity from the incoming INVITE can be compared to the normalized calling party number from the InitialDP. If they do not match, the request is rejected with a 403 response.

The P-Visited-Network-Information header

The SCC-AS will add a P-Visited-Network-Information header to the outgoing INVITE. It is recommended that this is set according to IR.65, section 6.2.1, that is, that the format for this is epc.ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org if the version followed is 12 or less, or ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org if a later version is used. The values of <MCC> and <MNC> are extracted from the triggering SS7 message.

The IP Multimedia Routing Number pool

The number used as the interchange between the SS7 and IP networks (the IMRN) must belong to a pre-allocated, reserved range of values. These numbers must be reserved to prevent overlap with numbers in use by subscribers. The pre-allocated range must be configured within the Rhino VoLTE TAS.

The pool of values does not need to be overly large, as values will only be reserved for the time between the receipt of the SS7 trigger and the processing of the INVITE. As an approximation, with normal error rates and a 20 ms interval between IMRN reservation (on the SS7 end) and IMRN return-to-pool, a range of 1000 values will accommodate 50,000 calls per second. Adjust the pool sizings to meet network requirements accordingly.

The simple-imrn-pool defines the digit string, with the cdma-imrn-formation and gsm-imrn-formation sections defining the protocol-specific digit formatting details.

Bypass reorigination for unregistered subscribers

If a subscriber is not registered in the IMS network, reorigination from SS7 to IMS can be skipped to avoid unnecessary processing. This bypass can be enabled for all unregistered subscribers, or for only non-roaming subscribers (to support terminating charging of roaming subscribers through the IMS).

Interactions with other services

The reoriginated call will be subjected to standard SCC call processing.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to reorigination in the sentinel-volte/scc/service-centralisation section.

What you need

  • ❏ The expected format of the P-Visited-Network-Information header.

  • ❏ The range of numbers available to be used as the IMRN.

  • ❏ The expected format of the IMRN.

Setting up reorigination

I want to…​
Use the configured I-CSCF address and prevent the HSS from being queried

To include the configured I-CSCF address in the route header of the outgoing INVITE, in the service-centralisation section, set use-direct-icscf-routing:

            use-direct-icscf-routing: true

Related section: Routing through the I-CSCF

Set the format of the PVNI header to the later standard

To set the P-Visited-Network-Information header template to the later format, in the service-centralisation section, set generated-pvni-template:

            generated-pvni-template: "ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org"

Related section: The P-Visited-Network-Information header

Reject messages sent to an IMRN where the P-Asserted-Identity does not match the recorded calling party digits

To enable comparing the P-Asserted-Identity header to the normalized calling party number, in the service-centralisation section, set police-originating-requests:

            police-originating-requests: true

Related section: Anti-fraud measures

Set a 1000 element IMRN range

To create a 1000 element range with 10-digit numbers from 5550000000 to 5550000999, in the service-centralisation section, set the values in simple-imrn-pool as follows:

            simple-imrn-pool:
                minimum-correlation-id: 5550000000
                maximum-correlation-id: 5550000999
                number-of-digits-in-correlation-id: 10

Related section: The IP Multimedia Routing Number pool

Configure the CDMA responses sent in error conditions

In CDMA networks, the responses sent in error conditions are configured in the scc-cdma-actions section.

                scc-cdma-actions:
                    action-on-unsupported-trigger: accessDeniedReason_terminationDenied
                    action-on-failed-to-allocate-routing-number: accessDeniedReason_busy
                    default-failure-action: accessDeniedReason_serviceDenied

To configure the error response:

Set the format of the GSM IMRN

In GSM networks, the non-digitstring section of the IMRN is configured in the scc-gsm-service-centralisation, gsm-imrn-formation section.

                gsm-imrn-formation:
                    routing-to-internal-network-number-allowed: true
                    nature: NATIONAL
                    numbering-plan: ISDN

To configure the GSM IMRN information:

Set the format of the CDMA IMRN

In CDMA networks, the non-digitstring section of the IMRN is configured in the scc-cdma-service-centralisation, cdma-imrn-formation section.

                cdma-imrn-formation:
                    imrn-type-of-digits: DIALED_OR_CALLED_PARTY_NUMBER
                    imrn-nature-of-number: INTERNATIONAL
                    imrn-numbering-plan: TELEPHONY

To configure the CDMA IMRN information, set:

Bypass terminating reorigination for unregistered subscribers on GSM networks

In GSM networks, the terminating reorigination trigger can be bypassed for subscribers that are not registered in the IMS.

To enable this, in the scc-gsm-service-centralisation section, set bypass-terminating-forwarding-if-served-user-not-ims-registered:

                bypass-terminating-forwarding-if-served-user-not-ims-registered: true
Bypass terminating reorigination for unregistered, non-roaming subscribers on GSM networks

In GSM networks, the terminating reorigination bypass can be enabled for all unregistered subscribers, or for only non-roaming subscribers.

To bypass reorigination for unregistered subscribers while still reoriginating roaming traffic, in the scc-gsm-service-centralisation section, set bypass-terminating-forwarding-if-served-user-not-ims-registered and always-term-reoriginate-if-served-user-is-roaming:

This will result in only unregistered, non-roaming subscribers bypassing reorigination. Registered subscribers and roaming subscribers will still reoriginate to the IMS.

                bypass-terminating-forwarding-if-served-user-not-ims-registered: true
                always-term-reoriginate-if-served-user-is-roaming: true
Bypass reorigination for unregistered subscribers on CDMA networks

In CDMA networks, to bypass reorigination for subscribers that are not registered in the IMS, in the scc-cdma-service-centralisation section, set bypass-forwarding-if-served-user-not-ims-registered:

                bypass-forwarding-if-served-user-not-ims-registered: true

RVT MMTel configuration

This section describes how to configure MultiMedia Telephony (MMTel) services.

In this section

Announcements

What it does

Defines the announcements that are available to be played by the MMTel services.

The announcements themselves are played on the Media Resource Function (MRF) node, which should already be provisioned with the announcements before they are configured here.

Interactions with other services

Other services can use the announcements defined here by referencing them using their ID value.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to announcements in the sentinel-volte/mmtel/announcement section.

What you need

  • ❏ The SIP: or Tel: URI of the media server (MRF) that plays the announcements.

  • ❏ Details of the announcements available on that media server:

    • ❏ their URI

    • ❏ their mime type

    • ❏ which locales are available for each announcement.

  • ❏ Details of how those announcements will be used:

    • ❏ Whether to repeat the announcement:

      • ❏ and if so, the maximum number of times to repeat

      • ❏ and the delay between repetitions.

    • ❏ Whether or not the announcement can be interrupt by user actions.

    • ❏ Whether or not the media stream should be forced to be one way between the MRF and the user during the announcement.

    • ❏ Whether to suspend charging while the announcement is playing.

    • ❏ Whether to end the call if the announcement cannot be played.

Setting up the MRF connection

I want to…​
Specify the address of the MRF to use for announcements

In the mmtel, announcement section, set announcements-media-server-uri.

            announcements-media-server-uri: sip:annc-audio@mrf-announcements:5260;lr;transport=tcp
Change the timeout when signaling the MRF

The default timeout is 1000 ms.

To set a new value, in the mmtel, announcement section, ensure that the announcements-no-response-timeout-milliseconds parameter is present and not commented out. Set the desired value, in milliseconds.

            announcements-no-response-timeout-milliseconds: 1500

Setting up each announcement

I want to…​
Repeat an announcement indefinitely until interrupted by user actions

For the desired announcement in the mmtel, announcement section, announcements list:

              - id: 20
                description: "MMTel - Outgoing Call Barring"
                announcement-url: "file://mmtel_ocb.3gp"
                duration-milliseconds: 13000
                repeat: -1
                delay-milliseconds: 1000
                mimetype: "audio/3gpp"
                interruptable: true
                end-session-on-failure: false
                enforce-one-way-media: false
                suspend-charging: false

  • Set the repeat value to -1, which will send a repeat=forever parameter to the MRF.

  • Set interruptable to true.

Let the MRF determine how often to repeat the announcement

For the desired announcement in the mmtel, announcement section, announcements list, set the repeat value to 0, so it is not sent to the MRF.

              - id: 20
                description: "MMTel - Outgoing Call Barring"
                announcement-url: "file://mmtel_ocb.3gp"
                duration-milliseconds: 13000
                repeat: 0
                delay-milliseconds: 1000
                mimetype: "audio/3gpp"
                interruptable: false
                end-session-on-failure: false
                enforce-one-way-media: false
                suspend-charging: false
Let the MRF determine the delay between announcement repetitions

For the desired announcement in the mmtel, announcement section, announcements list, set the delay-milliseconds value to 0, so it is not sent to the MRF.

              - id: 20
                description: "MMTel - Outgoing Call Barring"
                announcement-url: "file://mmtel_ocb.3gp"
                duration-milliseconds: 13000
                repeat: 2
                delay-milliseconds: 0
                mimetype: "audio/3gpp"
                interruptable: false
                end-session-on-failure: false
                enforce-one-way-media: false
                suspend-charging: false
Let the MRF determine the duration of the announcement

For the desired announcement in the mmtel, announcement section, announcements list, set the duration-milliseconds value to 0, so it is not sent to the MRF.

              - id: 20
                description: "MMTel - Outgoing Call Barring"
                announcement-url: "file://mmtel_ocb.3gp"
                duration-milliseconds: 0
                repeat: 2
                delay-milliseconds: 1000
                mimetype: "audio/3gpp"
                interruptable: false
                end-session-on-failure: false
                enforce-one-way-media: false
                suspend-charging: false
Let the MRF determine the media type of the announcement

For the desired announcement in the mmtel, announcement section, announcements list, comment out or delete the mimetype entry.

              - id: 20
                description: "MMTel - Outgoing Call Barring"
                announcement-url: "file://mmtel_ocb.3gp"
                duration-milliseconds: 13000
                repeat: 2
                delay-milliseconds: 1000
                # mimetype: "audio/3gpp"
                interruptable: false
                end-session-on-failure: false
                enforce-one-way-media: false
                suspend-charging: false
Reuse an existing announcement which does not suspend charging, but suspend charging

Duplicate an entire announcement definition in the mmtel, announcement section, announcements list, then change the appropriate values in the new announcement.

              - id: 20
                description: "MMTel - Outgoing Call Barring"
                announcement-url: "file://mmtel_ocb.3gp"
                duration-milliseconds: 13000
                repeat: 2
                delay-milliseconds: 1000
                mimetype: "audio/3gpp"
                interruptable: false
                end-session-on-failure: false
                enforce-one-way-media: false
                suspend-charging: false

              - id: 201
                description: "MMTel - Outgoing Call Barring - uncharged"
                announcement-url: "file://mmtel_ocb.3gp"
                duration-milliseconds: 13000
                repeat: 2
                delay-milliseconds: 1000
                mimetype: "audio/3gpp"
                interruptable: false
                end-session-on-failure: false
                enforce-one-way-media: false
                suspend-charging: true

  • Change the id of the copy to a previously unused value, for example, 201.

  • Change the description as appropriate.

  • Change suspend-charging to true.

Announcements on call failure

What it does

When a call fails with an error response code (a SIP response code in the range 400 …​ 699), an announcement may be played to the caller, and the status code may be changed to 487 to hide the true status code.

Interactions with other services

This service will only play an announcement if no other announcements are to be played, because all other service announcements will take priority.

This feature can add an announcement when a call is terminated with an error code by another service.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to call failure announcements in the sentinel-volte/mmtel/announcement/announcements/ section.

What you need

  • ❏ A status code for which you want to play an announcement.

  • ❏ The announcement ID of the announcement you wish to play.

  • ❏ Whether you want to hide the true status code.

  • ❏ Default handling of error codes.

Setting up each announcement

I want to…​
Play an announcement when a call fails with a response code 404

Within the mmtel, announcement section, error-code-announcements list, add a new error code announcement entry like this:

            error-code-announcements:
                - error-code: 404
                  announcement-id: 24
                  end-call-with-487-response: false
Play a default announcement for all other failure response codes

Within the mmtel, announcement section:

            default-error-code-announcement:
                announcement-id: 22
                end-call-with-487-response: false
Only play an announcement for the specified error codes

In the mmtel, announcement section, remove or comment out the entire default-error-code-announcement section.

            #default-error-code-announcement:
            #    announcement-id: 22
            #    end-call-with-487-response: false
Play an announcement when a call fails with a response code 488 and change it to a 487 response

Within the mmtel, announcement section, error-code-announcements list, add a new announcement entry like this:

            error-code-announcements:
                - error-code: 488
                  announcement-id: 22
                  end-call-with-487-response: true
Not play any announcements triggered solely by an error code

Directly under the mmtel, announcement section, completely remove or comment out both the default-error-code-announcement and error-code-announcements list sections.

        announcement:
            #default-error-code-announcement:
            #    announcement-id: 22
            #    end-call-with-487-response: false
            #error-code-announcements:
            #    - error-code: 486
            #      announcement-id: 24
            #      end-call-with-487-response: false
            #    - error-code: 488
            #      announcement-id: 22
            #      end-call-with-487-response: true
Play the same announcement for all error codes except for 404, which has no announcement

In the mmtel, announcement section, set up a default-error-code-announcement as described in Play a default announcement for all other failure response codes, then set up an error-code-announcements list entry for error code 404 with disable-announcement set to true.

        announcement:
            default-error-code-announcement:
                announcement-id: 22
                end-call-with-487-response: false
            error-code-announcements:
                - error-code: 404
                  # announcement-id: 24
                  disable-announcement: true
                  end-call-with-487-response: false

PSAP callback

What it does

Public Safety Answering Point (PSAP) callback is a service that helps emergency services call back a subscriber after an emergency call has ended. On the Rhino VoLTE TAS, the PSAP callback service ensures that none of a subscriber’s terminating MMTel TAS services (for example, Incoming Call Barring) hinder the callback attempt.

PSAP callback detection

There are two mechanisms available for detecting when a PSAP callback could be occurring:

  • direct notification from the Emergency Call Session Control Function (E-CSCF), or

  • analysis of the Priority header on incoming initial INVITE requests.

Both mechanisms can be used simultaneously. If either mechanism indicates a PSAP callback attempt, then the call will be handled as such.

E-CSCF notification

The Rhino VoLTE TAS can be configured to receive SIP MESSAGE requests from the E-CSCF when a subscriber calls an emergency number. If this behavior is enabled, upon receiving a such a request, the TAS makes a record of the subscriber’s identity that expires after a period of time determined by the expiry-time-seconds configuration field. Until the record expires, all incoming calls to the subscriber are handled as if they are a PSAP callback attempt and many MMTel services will be disabled.

Depending on network requirements, the SIP MESSAGE from the E-CSCF can either be allowed to continue on to its next destination, or the Rhino VoLTE TAS can stop the MESSAGE and generate a final response to the E-CSCF.

Priority header analysis

The Rhino VoLTE TAS can be configured to check for the presence of a Priority header on all incoming SIP initial INVITE requests. If the header is found with the value psap-callback, that call is handled as a PSAP callback attempt and many MMTel services will be disabled.

Interactions with other services

MMTel terminating services in general

The PSAP callback service’s purpose is to bypass any terminating MMTel TAS services that could potentially prevent emergency services from calling back a subscriber.

When a call is handled as a PSAP callback, the following terminating MMTel services are disabled:

  • Announcements

  • All types of call barring

  • Communication diversion

  • Voicemail forwarding

  • Explicit communication transfer

  • Communication hold

The following terminating MMTel services remain active for PSAP callbacks:

  • Session transfer to own device

  • Flexible alerting

  • Privacy (OIP and TIR)

  • Communication waiting

Online charging

Online charging is handled as a special case. The Rhino VoLTE TAS continues to communicate with the online charging server as normal for the duration of the call, but if the subscriber requires credit to receive the call and it cannot be allocated, the call is still allowed to continue.

Companion device

Certain functions of the companion device service that could interfere with emergency calls are disabled when an emergency call is detected:

  • When a companion device initiates an emergency call, its undisclosed identity will not be hidden.

  • When a PSAP callback attempt is made to the undisclosed identity, the companion device service will not block the call.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to PSAP callback in the sentinel-volte/mmtel/psap-callback section.

What you need

  • ❏ Whether or not to use the Priority header to detect PSAP callback attempts.

  • ❏ Whether or not to use the notifications from the E-CSCF to detect PSAP callback attempts.

If using notifications from the E-CSCF:

  • ❏ How long after receiving a notification from the E-CSCF to handle incoming calls for a subscriber as PSAP callbacks.

  • ❏ Whether or not to forward the notification onwards after processing it.

Setting up PSAP callback

I want to…​
Use the Priority header to detect PSAP callbacks

In the psap-callback section, set use-priority-header to true:

            use-priority-header: true

Related section: PSAP callback detection

Disable use of the Priority header to detect PSAP callbacks

In the psap-callback section, set use-priority-header to false:

            use-priority-header: false

Related section: PSAP callback detection

Use notifications from the E-CSCF to detect PSAP callbacks

In the psap-callback section, add a sip-message-options section:

            sip-message-options:
                expiry-time-seconds: 86400
                terminate-message: true

  • The expiry-time-seconds field must be set to the period of time in seconds that incoming calls for a subscriber should be treated as PSAP callback attempts.

  • The terminate-message field must be set to indicate whether the notification message should be answered by the Rhino VoLTE TAS or forwarded on.

Related section: PSAP callback detection

Disable use of notifications from the E-CSCF to detect PSAP callbacks

In the psap-callback section, remove or comment out the sip-message-options section:

#            sip-message-options:
#                expiry-time-seconds: 86400
#                terminate-message: true

Related section: PSAP callback detection

Change how long after receiving an E-CSCF notification that incoming calls for a subscriber should be handled as PSAP callbacks

In the sip-message-options section, set the expiry-time-seconds to the desired time period in seconds:

                expiry-time-seconds: 10000

Related section: E-CSCF notification

Forward E-CSCF notifications onwards to their destination after processing them

In the sip-message-options section, set the terminate-message to false.

                terminate-message: false

Related section: E-CSCF notification

Not forward E-CSCF notifications onwards and instead send a final response for them

In the sip-message-options section, set the terminate-message to true.

                terminate-message: true

Related section: E-CSCF notification

Dial plan enforcement (DPE)

What it does

The dial plan enforcement (DPE) service ensures that a subscriber has dialed a valid number before allowing a call to proceed.

Number analysis

The service works by confirming that the length of the dialed number is within an expected range. The allowed range can vary based on prefixes that the service detects on the number.

For example, the configuration for the service might specify that:

  • a number starting with 087 can be between 4 and 9 digits long (not including the prefix itself), and

  • all other numbers must be between 4 and 7 digits long.

In this case:

  • 12345678 would be rejected by the DPE service for having more than 7 digits, but

  • 08712345678 would be allowed since the 087 prefix means the number can have up to 9 digits after the prefix.

The service may be configured to detect any number of different prefixes with different ranges for each one. If a single number has multiple potential prefix matches, the service will choose the longest matching prefix.

There is a special case for numbers that are in international format. If one begins with either the configured national-prefix or the configured international-prefix, then the DPE service is bypassed. All other international format numbers will be subject to the same enforcement checks as non-international numbers. See the Number normalization section for information about configuring the national and international prefixes.

Call handling

If a number is allowable according to the DPE service configuration, then the call proceeds as normal.

If a number is rejected, then the call will be refused with a SIP error response. It is possible to configure an announcement to play to the calling party when this happens.

Interactions with other services

Vertical service codes (VSC)

If the VSC service modifies the dialed number by stripping certain prefixes from it, the DPE service will do its analysis on the modified version of the dialed number.

Configuration

Currently, the declarative configuration for the DPE service is only available through low-level overrides, which require the guidance of Metaswitch support.

To configure the service, contact your Metaswitch customer care representative.

Note Full declarative configuration support for this service may become available in a later version.

MMTel privacy settings

MMTel privacy is a set of services that allow for a calling party identity to be presented and/or restricted.

  • The Originating Identity Restriction (OIR) service adjusts the privacy restrictions for the originating user to restrict its identity.

  • The Originating Identity Presentation (OIP) service enforces the privacy presentation restrictions of the originating user to the terminating user.

  • The Terminating Identity Restriction (TIR) service adjusts the privacy restrictions for the terminating user.

  • The Terminating Identity Presentation (TIP) service enforces the privacy presentation restrictions of the terminating user to the originating user.

These services are subscriber specific and are configured in the HSS inside the MMTel-Services XML document for the subscriber.

System wide defaults are configured for OIR and OIP services using declarative configuration for when the subscriber’s services are not defined/active in the MMTel-Services XML document. No configuration is required for TIR and TIP services.

In this section

Originating Identification Restriction (OIR)

What it does

Originating Identification Restriction (OIR) service enables the originating user to prevent presentation of its identity to the terminating user. This allows the network to insert a privacy header field into the originating user’s SIP messages.

The declarative configuration for the OIR applies calling party identity restriction rules network wide for all OIR subscribed parties. Whether the OIR service is active and if it may diverge from this network default is determined by how the subscribers involved are provisioned in the MMTel Services document. The OIR service depends on the originating user’s provisioned settings for OIR.

Interactions with other services

Originating Identity Presentation (OIP)

OIP is directly impacted by the configuration and subscriber provisioning for the OIR service. The OIP service uses the privacy header adjustments made by the OIR service to remove data accordingly.

Setting identity restrictions

The OIR service adjusts the privacy header of the originating party’s outgoing requests. The privacy header designates to the OIP service what should be removed from the request before it reaches the terminating user. The OIP service configuration determines how the privacy header is interpreted and used to remove identifying information.

The provisioned OIR settings for the originating user stored in the HSS MMTel Service document take precedence where relevant. Otherwise, the default network configuration given in the declarative configuration of the Rhino VoLTE TAS is used for all OIR subscribers.

The provided table OIR configurability describes how the user’s provisioned settings and the network wide configuration interact with each other.

Table 6. Configurability of the OIR service
Configurable option Network configurable options Subscriber configurable options

When identity restriction occurs for an OIR subscriber

Specific details of when identity restriction occurs are given in 3GPP 24.607 Section 4.5.2.4

Mode

  • Permanent mode

    OIR processes all outgoing requests

  • Temporary mode

    OIP processes only outgoing requests that include a Privacy header

N/A

Temporary Mode Default Action

N/A

For when temporary mode is active:

  • Presentation Restricted

    Enact restriction unless the Privacy header contains 'none'

  • Presentation Not Restricted

    Enact restriction if and only if the outgoing request’s Privacy header contains 'id' or 'header'

What is restricted by OIR on a subscriber’s outgoing requests

Presentation Restriction

  • Restrict ONLY-IDENTITY

    • OIR adds 'id' to the Privacy header

      • Therefore, OIP to anonymize the network associated id

  • Restrict ALL-PRIVATE-INFORMATION

    • OIR adds 'header' to Privacy header

      • Therefore, OIP to anonymize possible identifying fields

  • Restrict ONLY-IDENTITY

    • OIR adds 'id' to the Privacy header

      • Therefore, OIP set to anonymize the network associated id

  • Restrict ALL-PRIVATE-INFORMATION

    • OIR adds 'header' to Privacy header

      • Therefore, OIP set to anonymize possible identifying fields

User Policy

  • NONE

  • ANONYMIZE_FROM

    • OIR anonymizes the From field on the outgoing request

  • ADD_USER_PRIVACY

    • OIR adds 'user' to the Privacy header

      • Therefore, OIP to anonymize user configurable fields

    • OIR anonymizes the From field on the outgoing request

N/A

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to OIR in the sentinel-volte/mmtel/privacy/originating-identification-restriction section.

What you need

  • ❏ Whether to set the default presentation restriction for an OIR subscriber to:

    • restrict all private information (Privacy:header), or

    • only restrict the identity (Privacy:id) of the originating party.

  • ❏ Whether to set the default OIR subscriber’s OIR user policy to:

    • anonymize the from header in the originating party’s requests,

    • restrict all user data in a request (Privacy:user) and anonymize the from in the originating party’s requests, or

    • to specify no default user policy.

You will also need to configure the OIP service as well to enforce these identity restrictions to the terminating user.

Setting up subscriber data

There are subscriber provisioned restriction rules configured in the HSS inside the MMTel-Services XML document for the subscriber.

The presentation-restriction-type subscriber defined restriction rule directly overrides the network’s default configuration.

Setting up service codes

The Rhino VoLTE TAS standard deployment includes service code actions for subscribers to activate OIR.

Table 7. Supplied service code actions
Display name Action

Set Dialled Caller ID Restriction Type

Used to override the OIR service’s PRESENTATION_RESTRICTION for a subscriber.

There are 3 valid values:

* OIR_AS_CONFIGURED — use OIR as configured by the network configuration and the subscriber provisioned configuration.

* OIR_CALLER_ID_BLOCK — override configured OIR to restrict identity.

* OIR_CALLER_ID_UNBLOCK — override configured OIR to not restrict identity.

For more information, see Vertical service codes.

Setting up OIR

I want to…​
Restrict only network defined user identity information for OIR subscribers
Note If a subscriber has provisioned the presentation-restriction-type in the MMTel Services Document, their setting will override this configuration.

In the privacy, originating-identification-restriction section, set presentation-restriction-type to ONLY_IDENTITY:

                presentation-restriction-type: ONLY_IDENTITY
Restrict all network defined private user information for OIR subscribers
Note If a subscriber has provisioned the presentation-restriction-type in the MMTel Services Document, their setting will override this configuration.

In the privacy, originating-identification-restriction section, set presentation-restriction-type to ALL_PRIVATE_INFORMATION:

                presentation-restriction-type: ALL_PRIVATE_INFORMATION
Anonymize the from for OIR subscribers by default

In the privacy, originating-identification-restriction section, set user-policy to ANONYMIZE_FROM:

                user-policy: ANONYMIZE_FROM
Remove all user configurable identifying information for OIR subscribers
Note This includes anonymizing the from header for OIR subscribers.

In the privacy, originating-identification-restriction section, set user-policy to ADD_USER_PRIVACY:

                user-policy: ADD_USER_PRIVACY

Originating Identification Presentation (OIP)

What it does

Originating Identification Presentation (OIP) service allows the terminating user to receive identity information from the originating user. The OIP service removes and anonymizes headers based on the originating user’s SIP message privacy header.

The declarative configuration for the OIP applies calling party identity presentation rules network wide for all OIP subscribed subscribers. Whether the OIP service is active and if it may diverge from this network default is determined by how the subscribers are provisioned in the MMTel Services document. The OIP service depends on the terminating user’s provisioned settings for OIP.

Applying identification presentation rules

The OIP service uses the privacy header on the originating user’s requests and responses to decide what is presented to the terminating subscriber.

If the privacy header field is set to:

  • id, the privacy header will not be removed. The Rhino VoLTE TAS does not anonymize anything, the S-CSCF would remove the P-Asserted-Identity header.

  • header, all headers containing private information are anonymized per RFC 3323 Section 5.1.

  • user, all user configurable headers are anonymized per RFC 3323 Section 5.3.

There are other privacy headers supported, they are enforced as per RFC 3323.

Also, if the terminating subscriber does not subscribe to the OIP service, then:

  • any P-Asserted-Identity or Privacy header is removed from the originating user’s request

  • if anonymize-from-header is set true, the from header is anonymized

Interactions with other services

Originating Identity Presentation (OIR)

The OIR service directly impacts on how the OIP applies presentation restrictions to the terminating user. The OIR adjusts the privacy header from the originating user’s request that is used to apply privacy changes to that request.

B2BUA

The Rhino VoLTE TAS B2BUA functionality automatically anonymizes the Call-Id, Record-Route, and Via headers on the originating user’s request.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to OIP in the sentinel-volte/mmtel/privacy/originating-identification-presentation section.

What you need

  • ❏ Whether to anonymize the originating user’s from header when OIP is not active for a subscriber.

  • ❏ Whether to allow the History-Info header to be deleted when using OIP.

You will also need to configure the OIR service as well to determine how the privacy header may be pre-processed when OIR is active.

Setting up subscriber data

There are subscriber provisioned OIP settings configured in the HSS inside the MMTel-Services XML document for the subscriber.

Setting up OIP

I want to…​
Anonymize the from header for non-active OIP subscribers

In the originating-identification-presentation, originating-identification-presentation section, set anonymize-from-header to true:

                anonymize-from-header: true
Allow deletion of the History-Info header

In the originating-identification-presentation, originating-identification-presentation section, set allow-history-info-header-deletion to true:

                allow-history-info-header-deletion: true

Conference (CONF)

What it does

The ad-hoc conferencing (CONF) functionality in Rhino VoLTE TAS allows a subscriber to add multiple parties to a voice or video session. The conference is initiated by a subscriber (the conference moderator) making a call toward the conference factory Public Service Identity (PSI). The Rhino VoLTE TAS will process this call and begin a session with the media server (MRFC/MRFP). As the moderator adds more participants to the conference, the Rhino VoLTE TAS instructs the media server to join or mix the media of the new participant with the conference session media. The moderator controls the conference, and sessions are terminated when the moderator disconnects.

Participants 'subscribe' to the conference to be notified of changes, such as members joining or leaving. Each subscription is valid for a specified length of time.

Operators can control whether the MRF is contacted directly from the Rhino VoLTE TAS, or whether the I-CSCF is added to the route header of messages sent to the MRF.

Conference media

Every conference participant establishes signaling and media sessions with the media server, facilitated by the Rhino VoLTE TAS. The specifics of the media sessions (and of the message flows used during conferencing) are dependent on the endpoints in use and on the MRF itself, so there are a number of configuration options to control details of the conference media settings. Operators can also control value-add features such as the maximum number of conference participants and whether video-conferencing is allowed.

Interactions with other services

Each participant’s session is treated by the Rhino VoLTE TAS as a regular call, subject to normal call processing in addition to conference treatment. This means that standard Rhino VoLTE TAS functionality, such as access transfer, mid-call announcements, and hold-and-resume functionality, are all supported during conferencing.

Online charging

Charging is correlated to the moderator session.

Configuration

What you need

  • ❏ The URI of the conference MRF.

  • ❏ A list of conference factory PSIs to use in addition to the PSIs defined in 3GPP TS 23.003.

  • ❏ The vendor of the Media Server Markup Language in use.

  • ❏ Whether the root element in the MSML is a child of the selector element or of the videolayout element.

  • ❏ The maximum number of participants in the call.

  • ❏ Whether video conferences are allowed.

Setting up conferencing

Warning Ensure that conferencing media server integration has been configured.

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to conferencing in the sentinel-volte/mmtel/conferencing section.

I want to…​
Set the URI of the Media Resource Function

In the conferencing section, set conference-mrf-uri to the URI:

                conference-mrf-uri: sip:mrf@mrfhost.example.com:5060
Route messages to the MRF via the IMS

In the conferencing section, set route-to-mrf-via-ims to true:

                route-to-mrf-via-ims: true
Set the MSML schema vendor name

In the conferencing section, set msml-vendor to the vendor name:

                msml-vendor: Dialogic
Attach the MSML root element as a child of videolayout

In the conferencing section, set root-on-selector to false:

                root-on-selector: false
Add a conference PSI alias

In the conferencing section, add the conference PSI alias to the list of conference-factory-psi-aliases:

                conference-factory-psi-aliases:
                    -   sip:conf-factory@ims.mnc<MNC>.mcc<MCC>.com
Set the maximum number of participants in a conference

In the conferencing section, set maximum-participants:

                maximum-participants: 4
Allow video-conferencing

In the conferencing section, set allow-video-conference-calls to true:

                allow-video-conference-calls: true
Set the default expiry time on conference subscriptions

In the subscription section, set default-subscription-expiry-seconds:

                default-subcription-expiry-seconds: 1800
Set the minimum allowed subscription time

In the subscription section, set min-subscription-expiry-seconds:

                min-subscription-expiry-seconds: 10
Notify participants about subscription changes every 10 seconds

In the subscription section, set polling-interval-seconds:

                polling-interval-seconds: 10

Call barring

What it does

Call barring is a set of MMTel services that conditionally bar calls using a combination of system-wide and per subscriber rules.

  • Incoming Call Barring (ICB) bars incoming calls based on per subscriber rules written using common-policy schema (for example, a subscriber may set up Do Not Disturb, to bar all calls).

    • Anonymous Call Rejection (ACR) bars incoming calls from anonymous callers.

  • Outgoing Call Barring (OCB) bars outgoing calls based on per subscriber rules written using common-policy schema.

  • Operator Determined Barring (ODB) is a fixed set of barring conditions, each enabled or not per subscriber.

    • Operator Specific Barring (OSB) is a subset of ODB containing four rules each enabled or not per subscriber, but where the system-wide conditions and actions are configured using common-policy schema. Additionally, the action when these rules trigger may be augmented to retarget the call, with an ability to disable charging, and/or use a rule-specific announcement in this case.

    • Prefix barring uses dialed number rules to either explicitly allow or bar an outgoing call, or to effectively force a match condition for some of the ODB conditions, including the OSB rules.

Announcements may be set to be played to the caller when a call is barred.

Interactions with other services

Communications Diversion (CDIV)

Call barring for incoming calls is applied before MMTel CDIV, so any barred incoming call will not be subject to forwarding.

However, an inbound call which is not barred but then forwarded will have outbound barring processing applied to the outbound forwarded call.

Vertical service codes with XCAP data update

Vertical service codes in combination with XCAP data update may change subscriber data, affecting subscriber ICB and OCB rules, and enabling or disabling ODB rules for a subscriber.

ODB rules may prevent changes to subscriber data, both via vertical service codes with XCAP data update, and when using XCAP directly from user equipment.

International Call Management (ICM)

Call barring takes precedence over the ICM service. This means that if the call barring service does bar the call, the ICM service announcements will not be played.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to call barring in the sentinel-volte/mmtel/communication-barring section.

What you need

  • ❏ Whether the system should process or ignore international and international-exHC barring rules based on the reliability of determining that an incoming call is international.

  • ❏ The ID of an optional announcement to play when an incoming call is barred due to an anonymous caller.

  • ❏ The ID of an optional announcement to play when an incoming call is barred otherwise.

  • ❏ The ID of an optional announcement to play when an outgoing call is barred.

  • ❏ For up to four operator specific barring rules:

    • ❏ The common policy ruleset which defines the conditions and action for the rule.

    • ❏ Whether to retarget the call and if so:

      • ❏ the URL target

      • ❏ the ID of an optional announcement to play

      • ❏ whether to disable charging.

Setting up announcements

Call barring configuration only needs the announcement ID of the announcements that should be played. The details of those announcements should be configured beforehand. For details about how to do this, see Announcements.

Setting up call barring

I want to…​
Enable ODB

In the hss-queries-enabled section, set odb to true:

            odb: true
Disable ODB

In the hss-queries-enabled section, set odb to false:

            odb: false

Setting up incoming call barring

I want to…​
Use the same announcement for all incoming barred calls

In the incoming-communication-barring, announcement section, set the same announcement ID for both announcements:

                 announcement:
                    announcement-id: 21
                    anonymous-call-rejection-announcement-id: 21
Use a different announcement for barred incoming anonymous calls

In the incoming-communication-barring, announcement section, set separate announcement IDs for the two announcements:

                 announcement:
                    announcement-id: 21
                    anonymous-call-rejection-announcement-id: 22
For barred incoming calls, only play an announcement when it is anonymously barred

In the incoming-communication-barring, announcement section, remove or comment out the announcement-id.

                 announcement:
                    # announcement-id: 21
                    anonymous-call-rejection-announcement-id: 22
For barred incoming calls, only play an announcement when it is not anonymously barred

In the incoming-communication-barring, announcement section, remove or comment out the anonymous-call-rejection-announcement-id.

                 announcement:
                    announcement-id: 21
                    # anonymous-call-rejection-announcement-id: 22
Enable evaluation of incoming international barring rules

In the incoming-communication-barring section, set international-rules-active to true.

                international-rules-active: true

Setting up outbound call barring

I want to…​
Play an announcement for barred outgoing calls

In the outgoing-communication-barring, announcement section, set the announcement-id:

                announcement:
                    announcement-id: 20
Not play an announcement for barred outgoing calls

In the outgoing-communication-barring section, delete or comment out the whole announcement section.

                # announcement:
                #    announcement-id: 20
Bar a suspended subscriber from making any calls, redirecting them to a specific number

  • Ensure ODB is enabled. See Enable ODB above.

  • Choose an OSB rule number to use.

    (considering what types are spare and the desired priority of this and existing rules)

  • Ensure this OSB rule is disabled for all subscribers.

    out of scope of this document

  • Set the OSB rule to:

    • bar all outbound calls

    • retarget any outbound call to the call center

    • optionally set up a specific announcement to play to the subscriber before retargeting the call

    • disable online charging for the call.

            operator-communication-barring:
                operator-barring-rules:
                    type1:
                        rule: # Bar outgoing calls
                            <cp:ruleset
                                xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
                                xmlns:cp="urn:ietf:params:xml:ns:common-policy"
                            >
                                <cp:rule id="bar-outgoing--enabled-when-out-of-credit">
                                    <cp:conditions>
                                        <outgoing/>
                                    </cp:conditions>
                                    <cp:actions>
                                        <allow>false</allow>
                                    </cp:actions>
                                </cp:rule>
                            </cp:ruleset>
                        retarget:
                            retarget-uri: sip:payments@pay.your.bill.com
                            disable-online-charging-on-retarget: true
                            announcement:
                                announcement-id: 23

  • Enable this OSB rule in subscriber data for suspended subscribers.

    out of scope of this document

Setting up prefix based barring

Prefix based barring provides a mechanism for an operator to augment the implicit or explicit condition of a MMTel OCB barring rule, so that the rule will also apply when the called party number matches some prefix with optional length criteria.

Because the same prefix can be treated differently (for example, depending on whether it is national or international), and multiple prefixes may all need to be treated the same way, the configuration is split into a list of prefixes and a list of classifications.

Each prefix has a list of classifications that may apply.

Each classification has further predicates to see if the classification is applicable to the call (minimum-number-length, maximum-number-length and match-international). If it is, the classification specifies the barring treatment of that call, and can optionally override the normal barring announcements.

Prefix barring interactions with other OCB features

There are different types of OCB rules, in the following overall order of priority:

  • Prefix based OperatorAllow

  • Operator-specific ODB rules that allow a call, regardless whether applied by matching their defined condition, or by prefix based treatment

  • Prefix based OperatorBar

  • Operator-specific ODB rules that bar a call, regardless whether applied by matching their defined condition, or by prefix based treatment

  • Prefix based premium-rate communication barring

  • Standard ODB rules

  • OCB rules

Within rules of the same type, an allow action will always take precedence over a barring or retargeting action.

If multiple operator-specific ODB rules apply and have conflicting retarget or barring actions, then the rule with the lower number will take precedence. (There are four slots available for operator-specific ODB rules, numbered one through four).

I want to…​
Treat 90077xxxxx numbers as premium rate entertainment for barring purposes and use a custom announcement when barred

In outgoing-prefix-barring, add a classification and map that prefix to it. In this case we use the maximum value for maximum-number-length to prevent this barring rule being circumvented by overdialing.

              outgoing-prefix-barring:
                  prefixes:
                      - prefix: '90077'
                        classifications:
                            - 'premium rate entertainment'
                  classifications:
                      - name: 'premium rate entertainment'
                        minimum-number-length: 10
                        maximum-number-length: 20
                        match-international: false
                        barring-treatment: 'PremiumRateEntertainment'
                        announcement:
                          announcement-id: 27
Treat all other 9007xxxxxx numbers as premium rate information services for barring purposes

In outgoing-prefix-barring, extend the above scenario by adding a new prefix and a new classification. This works because a call will match the longest prefix.

              outgoing-prefix-barring:
                  prefixes:
                      - prefix: '90077'
                        classifications:
                            - 'premium rate entertainment'
                      - prefix: '9007'
                        classifications:
                            - 'premium rate info'
                  classifications:
                      - name: 'premium rate entertainment'
                        minimum-number-length: 10
                        maximum-number-length: 20
                        match-international: false
                        barring-treatment: 'PremiumRateEntertainment'
                      - name: 'premium rate info'
                        minimum-number-length: 10
                        maximum-number-length: 20
                        match-international: false
                        barring-treatment: 'PremiumRateInformation'
Bar all calls to 8xx numbers without playing an announcement, but with no prefix barring handling for calls to 801

In outgoing-prefix-barring, we need to be explicit about all the 80x prefixes excluding 801, and all the remaining 8x prefixes, mapping them all to the same classification.

              outgoing-prefix-barring:
                  prefixes:
                      - prefix: '800'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '802'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '803'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '804'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '805'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '806'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '807'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '808'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '809'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '81'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '82'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '83'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '84'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '85'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '86'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '87'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '88'
                        classifications:
                            - 'barred shortcodes'
                      - prefix: '89'
                        classifications:
                            - 'barred shortcodes'
                  classifications:
                      - name: 'barred shortcodes'
                        minimum-number-length: 3
                        maximum-number-length: 3
                        match-international: false
                        barring-treatment: 'OperatorBar'
                        disable-ocb-announcement: true
Override any other barring rules to always allow calls to one specific number

In outgoing-prefix-barring, add a classification with barring-treatment set to OperatorAllow and matching exact number length, and map this from the complete number to that classification.

              outgoing-prefix-barring:
                  prefixes:
                      - prefix: '900123456'
                        classifications:
                            - 'explicit allowed 9 digit numbers'
                  classifications:
                      - name: 'explicit allowed 9 digit numbers'
                        minimum-number-length: 9
                        maximum-number-length: 9
                        match-international: false
                        barring-treatment: 'OperatorAllow'
Bar calls to 60000 whether or not the call is international

In outgoing-prefix-barring, add two classifications, one for national and one for international, but otherwise the same, then map the prefix to both classifications.

              outgoing-prefix-barring:
                  prefixes:
                      - prefix: '60000'
                        classifications:
                            - 'bar me'
                            - 'bar me - intl'
                  classifications:
                      - name: 'bar me'
                        minimum-number-length: 5
                        maximum-number-length: 5
                        match-international: false
                        barring-treatment: 'OperatorBar'
                      - name: 'bar me - intl'
                        minimum-number-length: 5
                        maximum-number-length: 5
                        match-international: true
                        barring-treatment: 'OperatorBar'

Communication Waiting (CW)

What it does

MMTel Communication Waiting (CW) is a service that alerts the subscriber when a new call arrives while a call is already in progress. The called party can accept, ignore, or reject the call. If accepted, the existing call can be put on hold.

This service can also play an announcement to the caller. See Announcements.

Interactions with other services

Call barring

The MMTel call barring services always take precedence over call waiting. If an incoming call is barred, the call will be terminated without waiting. See Call barring.

Communications Diversion (CDIV)

The MMTel CDIV takes precedence over communication waiting. If the called subscriber is already on a call, the call will be forwarded without waiting. See Communications Diversion (CDIV).

Communication Hold (HOLD)

If the subscriber accepts the new call, the call of current caller can be put on hold.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to call waiting in the sentinel-volte/mmtel/communication-waiting section.

What you need

  • ❏ The ID of the announcement to play to the caller.

  • ❏ The time in seconds to give the called party to answer the call before giving up and tearing down the call.

Setting up call waiting

I want to…​
Play an announcement to the caller that the call is waiting

Call waiting configuration only needs the announcement ID of the announcement to be played. The details of that announcement should be configured beforehand. For details about how to do this, see Announcements.

        communication-waiting:

            announcement:
                announcement-id: 24
Change the number of seconds to give the called party to answer the call

In the communication-waiting section, set timer-seconds to the desired limit:

                timer-seconds: 30

Communication Hold (HOLD)

What it does

MMTel Communication Hold (HOLD) is a service that lets a user suspend reception of the media stream(s) of an established IP multimedia session, and resume the media stream(s) at a later time.

This service provides a way for the operator to:

  • restrict bandwidth for held calls

  • play announcements to the held party

  • determine how media streams for the holding party are handled while an announcement to the held party is in progress.

Bandwidth controls

Bandwidth controls allow the Rhino VoLTE TAS to restrict the bandwidth available to media streams to the holding party for the duration of the hold. The call hold service allows you to set three different bandwidth parameters. The values for all of these parameters are set in kilobits per second.

Table 8. Bandwidth parameters
Parameter Config field Description

AS

b-as-parameter

Sets the bandwidth available for application specific data. It is safe to set this to 0.

RS

b-rs-parameter

Sets the bandwidth available for RTCP (Real-time Transport Control Protocol) for participants that are sending data. This should be set high enough to allow RTCP messages to continue while the call is on hold.

RR

b-rr-parameter

Sets the bandwidth available for RTCP for participants that are not sending data. This should be set high enough to allow RTCP messages to continue while the call is on hold.

Announcements

The call hold service can play an announcement to the party that has been put on hold. Call hold configuration only needs the announcement ID of the announcement that should be played. For instructions on how to configure the details of the announcement, see announcements.

Media handling during announcement

While an announcement to the held party is in progress, there are three options on how to deal with the media streams to the holding party. The behavior is configured in the holding-party-media-mode field with the following options.

Table 9. Holding party media modes
Field value Behavior 
NO_HOLD

No change is made to the media streams to the holding party.

 
BLACK_HOLE_ONLY

The media streams to the holding party are directed to a black hole IP address (0.0.0.0 for IPv4 and :: for IPv6) for the duration of the announcement.

 
FULL_HOLD

The media streams to the holding party are put on a two-way hold for the duration of the announcement.

Interactions with other services

Conference (CONF)

If a participant of a conference invokes the HOLD service, it is not desirable to provide an announcement to the conference.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to call hold in the sentinel-volte/mmtel/communication-hold section.

What you need

  • ❏ The ID of the announcement to play when the session is held.

Setting up call hold

I want to…​
Set the bandwidth for held media streams

In the communication-hold section, change the values, in kilobits per second, of the bandwidth-adjustment parameters.

           bandwidth-adjustment:
                b-as-parameter: 0
                b-rr-parameter: 500
                b-rs-parameter: 500

Related section: Bandwidth controls

Play an announcement to the held party that the call is on hold
        communication-hold: