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 {solution-type} VM.

On the SIMPL VM, you can find the command in the resources subdirectory of any {solution-type} (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 {solution-type} 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 deletes state and configuration for a given node type from the CDS

    Note Only use this after deleting all VMs for a given node type.
  • 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 split-sdf splits an SDF definition into separate ones, one for each instance.

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

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

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

Commands that read or modify the 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.

For more information, run rvtconfig --help or rvtconfig upload-config --help.

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 {all-node-type-rvtconfig-commands}. 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 -c <{cds-name-lowercase}-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 <{cds-name-lowercase}-mgmt-addresses> value can either be any single {cds-name-uppercase} management IP address or a space-separated list of {cds-name-uppercase} management IP addresses.

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

  • --vm-version-source automatically derives 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.

Note

Whatever way you enter the version, the value obtained must match the version on 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 HTTPS key and certificate for REM.

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 and how many lines differ. If any files are different, it 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 gets created by the command.

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.

This pre-check on config can be disabled by using the -f flag.

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-name-lowercase}-mgmt-addresses> -t <node type> -i ~/yamls --output-dir <output-directory>
[(--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 version of configuration to look up will be automatically taken from the SDF. If the optional --vm-version-source or --vm-version parameter is provided, then this is used instead. This can be used to check what has changed just before running an upgrade, where the version in the SDF differs.

The files that have differences will be displayed, along with the number of different lines. The full contents of each version of these files will be put in the output directory, along with the differences found. When doing so, secrets and non-YAML files are ignored.

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 diff command run against the two showing the differences.

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 <{cds-name-lowercase}-mgmt-addresses> -d <deployment-id> [--delete-audit-history]

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

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

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

rvtconfig delete-node-type -c <{cds-name-lowercase}-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>) [-y]

The argument -i ~/yamls is only needed if sdf-version is used.

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 redeployed to restore functionality.

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 <{cds-name-lowercase}-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 <{cds-name-lowercase}-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.

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 <{cds-name-lowercase}-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.

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

Splitting an SDF by product type with split-sdf

Create partial SDFs for each VM by running the command:

rvtconfig split-sdf -i <input-directory> -o <output-directory> <sdf>

Generating a private-key for Encrypting Passwords with generate-private-key

Rhino TAS and REM require the configuration to supply passwords that are encrypted with a private key. rvtconfig can generate a private-key to encrypt a password with the following command:

rvtconfig generate-private-key

The SDF can be updated with the generated private key.

Retrieving VM logs with export-log-history

During upgrade, when a downlevel VM is removed, it uploads {vm-quiesce-logs} 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 <{cds-name-lowercase}-mgmt-addresses> -d <deployment-id> --zip-destination-dir <directory>
--private-key <private-key>

Note The --private-key must match the key used in the SDF (secrets-private-key).
Note The {vm-quiesce-logs} 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 the given node.

  • The this-vm option takes the version of the VM the commands are being run from. This can only be used when running commands 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 -t <node type(s)>]

Both optional arguments -i ~/yamls and -t <node type(s)> are required for the sdf-version value to be given. Multiple node types can be taken as arguments.

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

rvtconfig Limitations

Any paths to files given to rvtconfig must conform to the following requirements:

  • relative paths may not use .. to navigate out of the current directory, and

  • absolute paths may be used without restrictions.

RVT system configuration

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.

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

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

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
    - xcap2.site1.ims.mnc123.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

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 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. Needs to be specified in a non-MDM deployment.
    servers:
      - 10.10.10.10
      - 10.10.10.11

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.

  • ❏ If using SNMP notifications, whether or not each notification category is enabled or disabled.

Note MetaView Server only supports the alarm-notification category of Rhino SNMP notifications. Therefore, all other notification categories should be disabled.

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, but only one type of online charging can be used at a 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 Call 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

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 an 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.

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.

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
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

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 cap:

        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
                    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
                    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

Call data records

What it does

Call data records (CDR) 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:
        - "111"
        - "tel:111"
        - "sip:111"

Managing the subscriber data

Subscriber data document schemas

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.

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).

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

Setting up PS routing behaviour

I want to…​
Route the PS attempt to the subscriber’s IMS public identity
            tads-identity-for-terminating-device: IMS_PUBLIC_IDENTITY

Related section: PS routing

Route PS attempts to the SIP instance of the terminating device(s)
            tads-identity-for-terminating-device: SIP_INSTANCE

Related section: PS routing

Route PS attempts to the SIP instance path of the terminating device(s)
            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.

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
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
                release-all-legs-on-busy: true
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
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 ]
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

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"
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
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.

                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

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
            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
                default-subcription-expiry-seconds: 1800
Set the minimum allowed subscription time
                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
                 announcement:
                    announcement-id: 21
                    # anonymous-call-rejection-announcement-id: 22
Enable evaluation of incoming international barring rules
                international-rules-active: true

Setting up outbound call barring

I want to…​
Play an announcement for barred outgoing calls
                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:

            announcement:
                announcement-id: 25

Related section: Announcements

Leave media streams to the holding party unchanged while an announcement is in progress

In the communication-hold section, set the holding-party-media-mode to NO_HOLD.

            holding-party-media-mode: NO_HOLD
Direct media streams to the holding party to a black hole IP address while an announcement is in progress

In the communication-hold section, set the holding-party-media-mode to BLACK_HOLE_ONLY.

            holding-party-media-mode: BLACK_HOLE_ONLY
Put media streams to the holding party on a two-way hold while an announcement is in progress

In the communication-hold section, set the holding-party-media-mode to FULL_HOLD.

            holding-party-media-mode: FULL_HOLD

Communications Diversion (CDIV)

What it does

MMTel Communications Diversion (CDIV) is a service that redirects incoming calls according to rules set by the network operator and/or the subscriber. Each of these rules specifies the particular condition or conditions that should trigger it, and the destination to forward to when the rule is triggered. The rules are subscriber specific and are therefore configured in the HSS rather than the Rhino VoLTE TAS.

Forwarding rules

Each forwarding rule must correspond to one of five different types of forwarding. Each forwarding type is triggered under different circumstances. The types are:

Table 10. Forwarding types
Name Acronym Trigger Condition

Communication Forwarding Unconditional

CFU

Triggers immediately upon receipt of an incoming call.

Communication Forwarding on Busy user

CFB

Receipt of a 486 Busy Here SIP response from the called party.

Communication Forwarding on no Reply

CFNR

A 180 Ringing response followed by a 408 Request Timeout response, or the no reply timer expiring after receiving a 180 Ringing response.

Communication Forwarding on Subscriber Not Reachable

CFNRc

Receipt of a SIP response with any of these status codes: 500 Internal Server Error, 503 Service Unavailable, 408 Request Timeout, or another code configured in additional-not-reachable-status-codes. Normally these responses must be received before a 180 Ringing response to trigger CFNRc, but this can be configured in the allow-not-reachable-during-alerting field (except for 408 Request Timeout response, which always triggers CFNR after a 180 Ringing response).

Communication Forwarding on Not Logged-in

CFNL

Receipt of an incoming call when the called party is not currently registered on the network.

Additional conditions

In addition to the basic types above, additional conditions can be placed on forwarding rules:

Table 11. Additional forwarding conditions
Name Description
media

Makes a forwarding rule conditional on the specific media types appearing in the SDP for the call.

validity

Makes a forwarding rule conditional on the date and time the call is received.

Forwarding action

In addition to its conditions, each forwarding rule should have a forward-to action. This action contains a number of parameters that detail how to handle forwarding when the rule’s conditions are met. The supported fields are:

Table 12. Supported forward-to parameters
Name Description
target

The URI to forward to.

notify-caller

Determines whether to send a 181 Call is Being Forwarded response to the calling party.

reveal-identity-to-caller

Determines whether the identity of the forward-to target should be revealed to the calling party.

reveal-served-user-identity-to-caller

Determines whether the identity of the original called party should be revealed to the calling party.

reveal-identity-to-target

Determines whether the identity of the original called party should be revealed to the forward-to target.

Communication Deflection

Communication Deflection (CD) is another type of MMTel call forwarding that, unlike the others, is not triggered through forwarding rules. Instead it is triggered by receipt of a 302 Moved Temporarily SIP response from the called party. For this type of forwarding, the response itself contains the destination to forward to.

No reply timer

As described above, CFNR is triggered after a 180 Ringing response, either by a 408 Request Timeout response or by the no reply timer expiring. The no reply timer is started on receipt of the 180 Ringing response, and expires after a period of time derived from either:

  • the communication-forwarding-on-no-reply-timer setting in subscriber HSS configuration (this option takes priority) or

  • the period of time specified in global configuration in the no-reply-timeout-seconds field.

Forwarding limits

The number of times that a single call can be forwarded can be limited with the max-diversions field.

If the limit is reached, there are several options for how to handle the call. This is configured in the max-diversion-action field. The options are:

Table 13. Options for handling too many forwarding attempts
Option Behaviour
REJECT

Terminates the call.

DELIVER_TO_FIXED_DESTINATION

Makes a final attempt to forward the call to the destination given in the max-diversion-fixed-destination field.

DELIVER_TO_SUBSCRIBERS_VOICEMAIL_SERVER

Makes a final attempt to forward the call to the subscriber’s specified voicemail server. This option requires that the subscriber’s voicemail server URI has been set in their Metaswitch-TAS-Services document in the HSS.

It is also possible to specify a list of known URIs in the diversion-limit-exempt-uris field that can be forwarded to, even when the forwarding limit is reached.

Interactions with other services

Call barring

The MMTel call barring service always takes precedence over call forwarding. If an incoming call is barred, the call will be terminated without forwarding.

Voicemail forwarding

Voicemail forwarding is closely related to the MMTel call forwarding service. There are certain situations that can trigger either service, for example, if the called party is already on a call. In such cases MMTel call forwarding takes precedence, and will evaluate the provisioned forwarding rules for the called party. Voicemail forwarding will be triggered if there are no forwarding rules that result in the call being forwarded.

Warning There are certain situations where the MMTel call forwarding service may be suppressed, for example, when routing to a CS network where MSC is expected to handle call forwarding. In these situations the Voicemail Forwarding service will also be suppressed.
Terminating Access Domain Selection (T-ADS)

If T-ADS attempts to connect the call over the circuit switched (CS) network and the attempt fails, it is possible that call forwarding could be triggered twice. The first time for call forwarding behavior in the CS core network, the second time for MMTel call forwarding.

For this reason it is possible to disable MMTel call forwarding for calls that are terminating in a CS network, see below.

Terminating SCC services in general

When a call is forwarded, the terminating SCC service will be skipped for the forwarded SIP INVITE request. This is because the forwarded call is treated as a new originating call.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to call forwarding in the sentinel-volte/mmtel/call-diversion/mmtel-call-diversion section.

What you need

  • ❏ The maximum limit for the number of forwards that should be allowed for a single call.

  • ❏ The preferred option for handling a call that has reached the maximum number of forwards.

  • ❏ Any URIs that can be forwarded to, even when forwarding limits have been reached.

  • ❏ Optionally, a default URI to forward to if a rule without an explicit target is triggered.

  • ❏ The default length of time to allow the call to ring before triggering CFNR.

  • ❏ Whether MMTel call forwarding should be disabled for calls that terminate in a CS network.

  • ❏ Whether subscribers' forwarding rules should take precedence over the operator’s rules.

  • ❏ Whether CFNRc should be allowed to trigger after the call starts ringing.

  • ❏ Any SIP response status codes that should trigger CFNRc besides the standard ones.

  • ❏ Whether an orig tag should be added to outbound forwarded SIP INVITE requests.

  • ❏ Whether a hi-target-param of type mp should be included in the History-Info for a forwarded message.

Setting up subscriber data

Both subscriber and operator defined forwarding rules, along with a subscriber specific setting for the no reply timer are configured in the HSS inside the MMTel-Services XML document for the subscriber.

You can find a detailed description of what this configuration looks like in the 3GPP technical specification for the MMTel call forwarding service, see section 4.9 of 3GPP TS 24.604.

Not all of the rule conditions listed in the technical specification are supported by the Rhino VoLTE TAS. Only the following conditions may be used: busy, not-registered, cp:validity, media, no-answer, rule-deactivated, and not-reachable.

Similarly there are also forward-to action parameters listed in the specification that are not supported by the Rhino VoLTE TAS. The following parameters may be used: target, notify-caller, reveal-identity-to-caller, reveal-served-user-identity-to-caller, and reveal-identity-to-target.

Setting up call forwarding

I want to…​
Set the limit for how many times a call can be forwarded

In the mmtel-call-diversion section, set max-diversions to the desired limit:

                max-diversions: 10
Reject calls that exceed the forwarding limit

In the mmtel-call-diversion section, set max-diversion-action to reject the call:

                max-diversion-action: REJECT
Forward calls that exceed the forwarding limit to a fixed URI
                max-diversion-action: DELIVER_TO_FIXED_DESTINATION
                max-diversion-fixed-destination: tel:+123456789
Allow forwarding to special URIs even when forwarding limits have been reached

In the mmtel-call-diversion section, add the desired SIP and/or tel URIs to the list of diversion-limit-exempt-uris:

                diversion-limit-exempt-uris:
                    - sip:voicemail@example.com
                    - tel:+123456789
Add to the set of SIP error response codes that trigger the CFNRc

In the mmtel-call-diversion section, add the desired codes to the list of additional-not-reachable-status-codes:

                additional-not-reachable-status-codes:
                    - 404
                    - 480
Allow CFNRc to still be triggered after receiving an 180 Ringing response
                allow-not-reachable-during-alerting: true
Set a default destination to use if a subscriber’s forwarding rule does not specify a destination

In the mmtel-call-diversion section, set default-target-uri to the desired SIP or tel URI:

                default-target-uri: sip:default-target@example.com
Set the default timeout for triggering CFNR

In the mmtel-call-diversion section, set no-reply-timeout-seconds to the desired timeout:

                no-reply-timeout-seconds: 15
Disable the MMTel call forwarding service when the call is being delivered over a circuit-switched network
                suppress-for-cs-terminating-domain: true
Allow the subscriber’s forwarding rules to override the operator’s rules

In the mmtel-call-diversion section, set prefer-subscriber to true:

                prefer-subscriber: true
Play an announcement to the caller when the call is forwarded

MMTel call forwarding 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.

        call-diversion:

            announcement:
                announcement-id: 12
Add the 'orig' tag to the Route header of forwarded SIP INVITE requests

In the mmtel-call-diversion section, set add-orig-tag to true:

                add-orig-tag: true
Prevent the 'orig' tag from being added to the Route header of forwarded SIP INVITE requests

In the mmtel-call-diversion section, set add-orig-tag to false:

                add-orig-tag: false
Include a 'hi-target-param' of type 'mp' in the History-Info header that is added to forwarded SIP INVITE requests

In the mmtel-call-diversion section, set add-mp-param to true:

                add-mp-param: true

Voicemail forwarding

What it does

When enabled for a subscriber, the voicemail forwarding service can forward an incoming call to a voicemail server. Depending on the selected configuration, this can happen under any of these conditions:

  • The call has waited longer than a specified timeout for a successful response.

  • The called subscriber is unavailable and has no provisioned diversion rules for the MMTel call forwarding service.

  • The called subscriber has provisioned diversion rules, but none of them cause the call to be forwarded.

  • The called subscriber uses online charging and credit cannot be allocated.

For details about diversion rules, see Communications Diversion (CDIV).

The URI of the voicemail server to forward to is provisioned per subscriber. It is possible to allow a subscriber to choose their own voicemail server.

The voicemail forwarding configuration includes a list of URIs for known voicemail servers on the network.

Important If a subscriber’s chosen voicemail server does not appear in this list, it can change which announcement they will hear before the call is forwarded. It can also potentially disable voicemail forwarding when credit cannot be allocated.

The voicemail forwarding service only runs on the terminating instance of the Rhino VoLTE TAS, and can be triggered at any time during call setup.

Voicemail forwarding can be used with the Metaswitch Voicemail Server. See the VMS product documentation for details of how to set up the server.

Playing announcements

The Rhino VoLTE TAS supports playing an operator specified announcement to the calling party before forwarding to voicemail. If a subscriber’s voicemail server is on the list of known voicemail servers, the announcement can be specified for voicemail forwarding. If not, the standard Communications Diversion (CDIV) announcement will play instead.

These announcements are distinct from any announcement that the voicemail server itself might play to the calling party.

Forwarding to voicemail without credit

If the subscriber is using Diameter Ro based online charging and they will be charged for the incoming call, forwarding to voicemail can be invoked if credit could not be allocated. The policy for when this is allowed is part of the Voicemail Forwarding configuration.

Voicemail service codes

The Rhino VoLTE TAS supports a subscriber dialing a service code (for example *123) to retrieve voicemail by forwarding the originating call to their configured voicemail server. This function uses the same voicemail server URI in subscriber config as the voicemail forwarding service, but it runs on the originating Rhino VoLTE TAS instance.

There is also support for setting up a service code that a subscriber can use to set their voicemail server URI (if they are permitted to do so).

Interactions with other services

Call barring

The MMTel call barring services (ICB and OCB) always take precedence over voicemail forwarding. If barring is triggered, the call will be terminated without forwarding to voicemail.

Communications Diversion (CDIV)

Voicemail forwarding is closely related to the MMTel CDIV service. There are certain situations that can trigger either service, for example, if the called subscriber is already on a call. In such cases MMTel call forwarding takes precedence, and will evaluate the provisioned diversion rules for the called subscriber. Voicemail forwarding will be triggered if there are no diversion rules that result in the call being forwarded.

If a subscriber is allowed to provision their own diversion rules for the MMTel call forwarding service, they can use that functionality to forward the call to their own voicemail server. This is true even when they are not permitted to choose their own voicemail server for the voicemail forwarding service.

Important There are certain situations where the MMTel CDIV service may be suppressed, for example, when routing to a CS network where MSC is expected to handle call forwarding. In these situations the voicemail forwarding service will also be suppressed.
Online charging

When using online charging, voicemail forwarding can be configured to activate when credit cannot be allocated for the call (for any reason). If this behavior is triggered, voicemail forwarding will finalize the online charging session. After this, there will be no further communication with the online charging system.

Configuration

What you need

  • ❏ The wait time for a call to be successfully connected before it is forwarded to voicemail.

  • ❏ A list of URIs for known voicemail servers on the network.

  • ❏ Whether to allow forwarding to voicemail if credit cannot be allocated for a subscriber that uses online charging. If allowed, forwarding can either be restricted to URIs on the known voicemail servers list or permitted for any URI.

  • ❏ Optionally, the ID of the announcement to be played before forwarding to any of the known voicemail servers.

  • ❏ Subscriber configuration set up with the Metaswitch-TAS-Services section enabled and the voicemail server URI field populated.

Setting up announcements

Voicemail forwarding configuration only needs the announcement ID of the announcement that should be played. The details of that announcement should be configured beforehand. For details about how to do this, see Announcements.

Setting up subscriber configuration

All subscribers using the Voicemail Forwarding service need to be configured with a voicemail server URI in the Metaswitch-TAS-Services section of their subscriber profile. Further information on configuring the subscriber data for the voicemail forwarding service is given in Forward to voicemail subscriber data.

Note

For standard Rhino VoLTE TAS deployments, the Metaswitch-TAS-Services document is disabled. This must be enabled to activate voicemail forwarding using subscriber data.

Setting up service codes

The Rhino VoLTE TAS standard deployment includes service code actions for subscribers to retrieve voicemail and update their voicemail server URI (if permitted to do so).

Table 14. Supplied service code actions
Display name Action

Connect Subscriber To Voicemail Provider

Execute dialing for voicemail.

Set Default Forward Voicemail Server Number

Update the default forward voicemail number for the subscriber data (MetaswitchForwardToVoicemail.voicemailServer).

For more information, see Vertical service codes.

Setting up voicemail forwarding

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to voicemail forwarding in the sentinel-volte/mmtel/call-diversion/forward-to-voicemail section.

I want to…​
Activate voicemail forwarding

Ensure the entire forward-to-voicemail section is present and not commented out in the configuration file.

            forward-to-voicemail:
                voicemail-uris:
                    - sip:vms1@example.com
                    - sip:vms2@example.com
                forward-to-voicemail-timeout-seconds: 0
                forward-to-voicemail-without-ocs-credit: NEVER_ALLOW
Set time to forward calls to voicemail after processing the initial INVITE
                forward-to-voicemail-timeout-seconds: 30
Disable forwarding to voicemail due to timeout
                forward-to-voicemail-timeout-seconds: 0
Disallow forwarding to voicemail if unable to allocate credit to the subscriber
Important This only applies to subscribers using Diameter Ro based online charging.

In the forward-to-voicemail section, set forward-to-voicemail-without-ocs-credit to never allow forwarding:

                forward-to-voicemail-without-ocs-credit: NEVER_ALLOW
Allow forwarding to voicemail regardless of being able to allocate credit to subscriber
Important This only applies to subscribers using Diameter Ro based online charging.

In the forward-to-voicemail section, set forward-to-voicemail-without-ocs-credit to always allow forwarding:

                forward-to-voicemail-without-ocs-credit: ALWAYS_ALLOW
Allow forwarding to a known voicemail server regardless of the credit status of a subscriber using online charging
Important This only applies to subscribers using Diameter Ro based online charging.

In the forward-to-voicemail section, set the following:

                forward-to-voicemail-without-ocs-credit: ALLOW_ONLY_FOR_WELL_KNOWN_SERVERS
                voicemail-uris:
                    - sip:vms1@example.com
Play a voicemail announcement (announcement id=7) to the calling party when voicemail forwarding occurs
                voicemail-uris:
                    - sip:vms1@example.com
                    voicemail-announcement-id: 7
Play the default forwarding announcement to the calling party when voicemail forwarding occurs

In the call-diversion, announcement section, remove or comment out voicemail-announcement-id:

                    # voicemail-announcement-id: 7

Companion device

What it does

Companion devices are VoLTE UEs that are linked to a primary device such as a smart phone. Smart watches are a common type of companion device. The companion device service enables companion devices to share a phone number with the primary device. This means:

  • calls to the shared number will cause both devices to ring, and

  • calls from the companion device will appear to come from the shared number.

This type of service is sometimes referred to as "One Number", "Multi-SIM", or "Multi-Device".

The companion device will still have its own number called the "undisclosed identity". Depending on service configuration, it may still be possible to use this number to contact the companion device, but the Rhino VoLTE TAS will always attempt to hide and replace it with the shared number.

The companion device service can function for devices connecting over both packet switched (PS) and circuit switched (CS) networks.

Outbound calls

For outbound calls, the companion device will usually use the shared number to identify itself. However, if it uses its undisclosed identity instead, the companion device service will replace it with the shared number before allowing the call to proceed.

Inbound calls

When an incoming call is targeted at the shared number, the companion device service will force the T-ADS service to use parallel routing mode. This ensures that both the primary and companion device will ring at the same time, regardless of whether they are connected to a PS or CS network. When the subscriber answers the call on either device, the other device will stop ringing.

When companion devices are in use, T-ADS may use special handling if one of the devices indicates the subscriber is busy. If the release-all-legs-on-busy field in the T-ADS configuration is set to true, a single busy response from either device will cause the call to be terminated. If the field is false, T-ADS will wait for a response from the other device as per normal behavior.

The companion device service can also be configured to block incoming calls to the undisclosed identity.

Companion device provisioning

Per-subscriber companion device data is provisioned in two places:

  • IMS subscription data in the HSS, and

  • the Metaswitch-TAS-Services document stored in HSS transparent data.

Provisioning of IMS subscription data is not done using the Rhino VoLTE TAS. Contact your HSS provider for more information.

Note

For standard Rhino VoLTE TAS deployments, the Metaswitch-TAS-Services document is disabled. This must be enabled to activate the companion device service.

Further information on configuring the companion device service subscriber data is given in the managing companion device subscriber data page.

Interactions with other services

Terminating Access Domain Selection (T-ADS)

When a companion device is in use, the companion device service will force the T-ADS service to use its parallel routing mode. However, restrictions imposed by the Request-Disposition header will still apply. See Request disposition in the T-ADS section for details.

The companion device service may also provide CS routing numbers (CSRNs) for the T-ADS service to use on its CS network connection attempts.

CAP charging

If CAP charging is in use, on inbound calls there will be a separate session between the Rhino VoLTE TAS and the service control point (SCP) providing the charging service for each forked PS and CS leg for each device. The leg that is answered by the called subscriber will be charged, and the other legs will be recorded as zero length calls with the SCP.

PSAP callback

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

Currently, the declarative configuration for the companion device 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.

Vertical service codes (VSC)

What it does

The vertical service code (VSC) service provides support for carrying out a wide variety of actions based on the number dialed by a subscriber.

Number analysis

The VSC service is capable of invoking other services based on matching either a prefix on the dialed number or the full number.

In the event that there are multiple possible matches for the same number, the longest match takes priority. So for example, if two VSC prefixes were specified:

  • 520 to hide the caller’s identity for this call, and

  • 52 to reveal the caller’s identity for this call.

For the dialed number 5205551234, the caller’s identity would be hidden for the call. This also means that a full number match will always take precedence over any possible prefix match.

When a prefix is found on a dialed number, it can optionally be stripped from the number before invoking its corresponding service. Using the numbers for the privacy example above, this would cause 5205551234 to become 5551234 on the outbound leg of the call.

It is also possible to seek further matches in the remaining part of a number after a prefix has been matched. This can be done regardless of whether the prefix is stripped from the outbound number. So if 1234 was a full number vertical service code that invoked the Location based dialing service to call a nearby visitor information center, then again using the numbers from the privacy example above, a caller dialing 5201234 would call the information center and have their identity hidden.

Vertical service codes are only supported for numbers in the network’s home country. If a dialed number is in international format but has the home country code, it will be removed prior to matching.

Service code actions

The Rhino VoLTE TAS comes preconfigured with a number of actions that can be assigned to a vertical service code. It is also possible to set up an announcement to be played before the action is carried out.

The available actions are:

  • Enable identity restriction for the current call.

  • Disable identity restriction for the current call.

  • Enable identity restriction permanently.

  • Disable identity restriction permanently.

  • Enable identity presentation.

  • Disable identity presentation.

  • Enable call forwarding for busy and no answer.

  • Disable call forwarding for busy and no answer.

  • Enable unconditional forwarding to specified number.

  • Disable unconditional forwarding.

  • Enable busy call forwarding to specified number.

  • Disable busy call forwarding.

  • Enable no answer call forwarding to specified number.

  • Disable no answer call forwarding.

  • Enable not logged in call forwarding to specified number.

  • Disable not logged in call forwarding.

  • Enable not reachable call forwarding to specified number.

  • Disable not reachable call forwarding.

  • Enable the call forwarding service.

  • Disable the call forwarding service.

  • Execute location based dialling.

  • Connect the subscriber to their voicemail server.

  • Set the subscriber’s voicemail server number.

  • Continue searching for more service codes.

  • Stop searching for more service codes.

  • Strip this service code and continue searching for others.

  • Strip this service code and stop searching for others.

  • Reject the call with 603 decline response.

It is also possible to create custom actions. For guidance on how to do this, contact Metaswitch support.

Interactions with other services

The VSC service finds a service code in a dialed number, so it can have broad reaching effects that can impact other services.

There are two key points to note:

  • The VSC service can be used to invoke other services outside of their usual operating procedures or to override their usual behavior.

  • When the VSC service strips a prefix from a dialed number, other services that analyze the dialed number will not see that prefix. This is different from most services that manipulate the outbound dialed number, and is of particular note for the call barring service.

Configuration

Currently, the declarative configuration for the VSC 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.

International Call Management

What it does

The International Call Management service provides support for barring and playing announcements for international calls based on the format of the dialed digits, and the identified country of the destination address.

Outbound calls can be barred if a call is determined to be international and the international dialing prefix is not explicitly present in the dialed digits. An announcement can be played before the call is barred. Additionally, if a call is determined to be international a pre-call announcement can be played to the calling party. The default options can be overridden based on the destination country.

Note

The international dialing prefix refers to either the + character or to the international-prefix.

Restrictions

The destination country can only be identified if the country uses the North American Numbering Plan (ie international prefix is 1). Countries outside the NANP will be treated with the default handling.

Interactions with other services

Roaming and international status determination

If North American Numbering Plan (NANP) analysis is enabled, the details determined by NANP will be used to establish the international and roaming status of the call (by comparing the access network country code, the home network country code, and the destination country code).

Call Barring

The MMTel Outgoing call barring service (OCB) always takes precedence over international call management. If barring is triggered, the call will be terminated without playing an international call management announcement.

Number translation services in general

International Call Management looks at the original dialed number as received by the RVT when doing its analysis. This means that changes to the number by services that provide number translation (such as Location Based Dialing) will not be considered by this service.

Configuration

The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to international call management in the sentinel-volte/mmtel/international-call-management and sentinel-volte/mmtel/north-american-numbering-plan sections.

What you need

  • ❏ Whether the system should bar international calls dialed without an international prefix.

  • ❏ Optionally, the ID of the announcement to be played before barring calls.

  • ❏ Optionally, the ID of the announcement to be played before international calls are connected.

  • ❏ Optionally, per-country overrides for the above, along with the 2 digit upper case ISO country code for countries to be overridden.

Setting up announcements

International Call Management configuration only needs the announcement ID of the announcement that should be played. The details of that announcement should be configured beforehand. For details about how to do this, see Announcements.

I want to…​
Bar and play an announcement to international calls dialed without the international call prefix

In the default-international-call-management section, set bar-calls-with-missing-prefix to true and set bar-calls-with-missing-prefix-announcement-id to the ID of the selected announcement.

    international-call-management:
      default-international-call-management:
        bar-calls-with-missing-prefix: true
        bar-calls-with-missing-prefix-announcement-id: 200
Play an announcement before international calls

In the default-international-call-management section, set international-call-announcement-id to the ID of the selected announcement.

    international-call-management:
      default-international-call-management:
        international-call-announcement-id: 200
Bar international calls dialed without the international call prefix, except calls to Canada

Ensure the call-management-by-country-code list is present and uncommented.

Add a list item with an iso-country-code of CA and a bar-calls-with-missing-prefix value of false.

    north-american-numbering-plan-analysis:
      enable-nanp-analysis: true

    international-call-management:
      default-international-call-management:
        bar-calls-with-missing-prefix: true
      call-management-by-country-code:
        - iso-country-code: "CA"
          bar-calls-with-missing-prefix: false
Play an announcement before international calls, except calls to Canada

In the default-international-call-management section, set international-call-announcement-id to the ID of the selected announcement.

Ensure the call-management-by-country-code list is present and uncommented.

Add a list item with an iso-country-code of CA. Ensure that the international-call-announcement-id within the country code list is unset.

The unset value in the CA profile will not fall back to the default value - a missing international-call-announcement-id at any level means that no announcement will be played at that level.

    north-american-numbering-plan-analysis:
      enable-nanp-analysis: true

    international-call-management:
      default-international-call-management:
        international-call-announcment-id: 200
      call-management-by-country-code:
        - iso-country-code: "CA"
Allow international calls dialed without the international call prefix, except calls to the US,

Ensure the call-management-by-country-code list is present and uncommented.

Add a list item with an iso-country-code of US and a bar-calls-with-missing-prefix value of true.

    north-american-numbering-plan-analysis:
      enable-nanp-analysis: true

    international-call-management:
      default-international-call-management:
        bar-calls-with-missing-prefix: false
      call-management-by-country-code:
        - iso-country-code: "US"
          bar-calls-with-missing-prefix: true
          bar-calls-with-missing-prefix-announcement-id: 101
          international-call-announcement-id: 102

Location based dialing (LBD)

What it does

Location based dialing (LBD) is a service that allows a subscriber to dial a number that redirects to a different number depending on the subscriber’s location.

LBD is invoked when the Vertical service codes service detects that a subscriber has dialed a number that requires it. When invoked, LBD retrieves the dialed number and attempts to determine the subscriber’s location. Using this information, it consults a database to get a new number. If one is found, the call will be redirected to it.

If the service can’t determine the subscriber’s location or the database doesn’t have an entry for their location, the service can instead take any of the following actions:

  • play an announcement to the subscriber

  • end the call

  • redirect the call to a default destination.

Subscriber data

Per-subscriber location based dialing service data is provisioned in the Metaswitch-TAS-Services document stored in HSS transparent data.

Note

For standard Rhino VoLTE TAS deployments, the Metaswitch-TAS-Services document is disabled. This must be enabled to activate the location based dialing service.

Further information on configuring the location based dialing service subscriber data is given in Location based dialing subscriber data.

Interactions with other services

Vertical service codes (VSC)

LBD depends on the vertical service code service to identify when a number requiring LBD has been dialed.

Call barring

Call barring operates based on the original number dialed by the subscriber, not the new number targeted by the LBD service.

International Call Management

When it does number analysis the International Call Management service will look at the original dialed number, not the new number targeted by the LBD service. This means that if the LBD service directs the call to an international number, International Call Management may bar the call if the original number was not dialed with a country code.

Configuration

Currently, the declarative configuration for the location based dialing 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.

Explicit Communication Transfer (ECT)

What it does

Explicit Communication Transfer (ECT) is an MMTel service that enables a party involved in a communication to transfer their role to a third party.

For this service there are three actors involved:

  • The transferor initiates the call transfer

  • The transferee is the other party on the call

  • The transfer target is the party that replaces the transferor in a call transfer.

The transferor invokes the ECT and the transferee replies back accordingly to transfer to the transfer target. The Rhino VoLTE TAS processes these messages to handle the call transfer while maintaining charging.

The Rhino VoLTE TAS’s ECT service supports either a consultative transfer or a blind transfer:

  • A consultative transfer is where the transferor has consultative communication with the transfer target before a transfer. This may involve an existing session between the transferor and transfer target before a call transfer.

  • A blind transfer is where the transferor has no consultative communication with the transfer target. The transferor invokes a call transfer with no current session between the transferor and the transfer target.

The Rhino VoLTE TAS supports a response timeout for requests generated by the transfer service.

If the parties' dialog is interrupted or removed during a call transfer, the Rhino VoLTE TAS’s ECT service initiates a new dialog to continue the transfer using third party call control procedures.

Interactions with other services

Charging

The use of an ECT triggers charging action for CDR generation and online charging. This charging occurs for all parties involved in the call transfer.

Configuration

Currently, the declarative configuration for the ECT 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.

Flexible Alerting (FA)

What it does

The MMTel Flexible Alerting (FA) service allows the creation of a group of member identities bound to a single number, called the Pilot Number.

When a call to the pilot number is identified, the service will alert all the members of the group and the caller is bound to the first member of the group that answers the call.

When a member answers the call with 200 (OK), the service cancels all other sessions towards the other members and finishes the call setup procedures between the calling party and the member that answered.

The service can be set to alert the group members:

  • sequentially - sequentially alerts the group members in order, with each member sending a final response or timing out before the next is alerted.

  • in parallel - alerts all the group members at once.

3GPP defines flexible alerting in TS 24.239 and the flexible alerting subscriber data schema is defined in TS 24.239 and TS 29.364.

Group members

The group of identities that may be contacted by the Flexible Alerting feature is called the FA Group.

There can be two types of FA Group:

  • single-user - one user, who may have one or more devices.

  • multiple-users - more than one user. An example would be the devices of more than person in the same office.

Interactions with other services

CAP charging

If CAP charging is in use, on inbound calls there will be a separate session between the Rhino VoLTE TAS and the service control point (SCP) providing the charging service for each forked PS and CS leg for each device. The leg that is answered by the called subscriber will be charged, and the other legs will be recorded as zero length calls with the SCP.

PSAP callback

Certain functions of the flexible alerting service that could interfere with emergency calls are disabled when an emergency call is detected:

  • When a PSAP callback attempt is made to the undisclosed identity, the flexible alerting service will not block the call.

Communications Diversion (CDIV)
Communication Forwarding Unconditional (CFU)

If CFU is active for the Pilot Identity, the procedures will be applied and no group member will be alerted.

Communication Forwarding on Busy user (CFB)

If CFB is active for the Pilot Identity, the procedures will be applied if the pilot number is considered busy.

The definition of Busy for the pilot number depends on the group type:

  • For single-user, when one member is busy the pilot number is busy.

  • For multiple-uses all group members have to be busy for the pilot number to be considered busy.

Communication Forwarding on no Reply (CFNR) and Communication Forwarding on Subscriber Not Reachable (CFNRc)

If the FA Pilot Identity is considered in a state of CFNR or CFNRc, the procedures for those MMTel services will be applied.

The pilot number is considered in a state of:

  • No Reply when all group members are in a state of no reply.

  • Not Reachable when all group members are in a state of not reachable.

Communication Forwarding on Not Logged-in (CFNL)

If the FA Pilot Identity has CFNL active, the procedures will be applied.

Privacy settings
Originating Identification Presentation (OIP)

If OIP is active for the FA Pilot Identity, OIP is applied to any FA group member.

Terminating Identity Presentation (TIP)

If the FA Pilot Identity did not apply TIR, the termination identification is the FA Pilot Identity.

Terminating Identity Restriction (TIR)

If the FA Pilot Identity has TIR activated, the termination identification is not presented.

Call barring
Incoming Call Barring (ICB)

If the FA Pilot Identity has ICB activated, the procedures for ICB will be applied.

Outgoing Call Barring (OCB)

If any FA group member has OCB activated, the procedures for OCB will be applied for that member.

Configuration

Currently, the declarative configuration for the flexible alerting 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.

Session transfer to own device

What it does

The Rhino VoLTE TAS allows a subscriber to transfer an active call from their current active registered device (UE1) to another of their registered devices (UE2). This active call is maintained while the communication session between the A and B party’s devices has changed. Sessions can be transferred between devices that share the same IMS Public User Identity (IMPU). This service is supported for either originating or terminating users.

In the originating case, The A party subscriber can initiate a session transfer during an active session by pulling the call on to the UE2 device. For example, the calling party may transfer a call from a phone (UE1) to a tablet (UE2).

The Rhino VoLTE TAS verifies that the UE2 device is configured for a session transfer for the A party subscriber. If the configuration is verified, then the Rhino VoLTE TAS pulls the UE2 device into the call with the B party. Once the connection has been established, the UE1 device is disconnected from the session.

The service makes an SDP remote update on the existing called leg to guarantee SDP integrity and correctness on all involved dialogs.

The terminating case is also supported. This would be where the B party subscriber can use another registered device with the same IMPU to pull the call. The service makes an SDP remote update on the existing calling leg to ensure SDP integrity.

Interactions with other services

Charging

The charging vector of the call is updated due to the change in the transfer party’s new device on the session.

Configuration

Currently, the declarative configuration for the session transfer to own device 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.

RVT XCAP

What it does

The Rhino VoLTE TAS XCAP server is a web application that implements the XCAP (XML Configuration Access Protocol) towards the UE, and supports the XML schemas for user and operator data defined in TS 29.364. It stores and retrieves this information in the HSS using Sh Transparent Data, according to TS 29.364.

A subscriber can use the XCAP Ut interface from their UE to retrieve and modify their MMTel call settings, such as diversion and blocking, stored in the HSS.

Configuration

For configuration details, see XCAP domains.

Shared configuration

The XCAP server takes the rest of its configuration from some of the shared system configuration files.

Number analysis

To validate that all URIs updated via XCAP are normalizable, the XCAP server uses:

Additionally, when a UE updates call diversion rules, the XCAP server checks the target URIs against the list of non-provisionable URIs from number-analysis-config.yaml.

BSF and NAF configuration

The BSF (Bootstrapping Server Function) and NAF (Network Application Function) must be configured to allow UEs to authenticate requests to the XCAP server. See RVT Authentication Gateway for details.

To configure any parts of the XCAP server not mentioned here, contact Metaswitch support.

XCAP domains

The list of domains in the mag-vmpool-config.yaml file is the complete set of domains that the XCAP server should handle for UEs making XCAP requests in the network.

How it works

The XCAP domains specified in the Rhino VoLTE TAS are used by the XCAP server to decide if it should handle a given XCAP request from a UE. If an XCAP request is received by the XCAP server with a request URI containing a domain not in this list it will be rejected with a 404 Not Found error response.

Configuration

The xcap-domains field lists the domains for which the Rhino VoLTE TAS XCAP server will accept requests, as shown in the Example for mag-vmpool-config.yaml

You will likely have at least one domain per mcc-mnc in your network, as configured in the PLMN IDs for my network.

Setting up XCAP domains configuration

I want to …​
Specify a set of domains the Rhino VoLTE TAS XCAP server will accept request for

To configure the Rhino VoLTE TAS XCAP server to accept request for a set of domains, in the mag-virtual-machine-pool section, set the xcap-domains list to a list of domain names.

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