This document is the Configuration and Management guide for Rhino VoLTE TAS 4.1.
- Notices
- Where to start
- Declarative configuration
- RVT system configuration
- RVT service centralization and continuity configuration
- RVT MMTel configuration
- Announcements
- Announcements on call failure
- PSAP callback
- Dial plan enforcement (DPE)
- MMTel privacy settings
- Conference (CONF)
- Call barring
- Communication Waiting (CW)
- Communication Hold (HOLD)
- Communications Diversion (CDIV)
- Voicemail forwarding
- Companion device
- Vertical service codes (VSC)
- International Call Management
- Location based dialing (LBD)
- Explicit Communication Transfer (ECT)
- Flexible Alerting (FA)
- Session transfer to own device
- RVT XCAP
- RVT Authentication Gateway
- RVT IP Short Message Gateway (IP-SM-GW)
- RVT USSD over IM CN subsystem (USSI)
- RVT declarative configuration reference
- Example configuration and schemas
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:
-
T-ADS, which selects whether a called subscriber will receive the call over the GSM/CDMA or the LTE (or a Wi-Fi) network.
-
Access transfer, which keeps calls up and running when a subscriber leaves LTE coverage.
-
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:
-
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.
-
Call failure announcements, which selects which announcements to play under various call failure conditions.
-
PSAP callback, which provides special handling for return calls from emergency services to a subscriber.
-
Dial plan enforcement, which checks the number dialed by a subscriber to ensure it is valid for the network before permitting a call.
-
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.
-
Conferencing, which enables calls with more than two participants. It covers the functionality for the 3GPP defined Conference (CONF) service.
-
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.
-
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.
-
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.
-
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.
-
Voicemail forwarding, which forwards an incoming call to a subscriber’s nominated voicemail server.
-
Companion device, which provides features supporting LTE connected devices besides a subscriber’s main phone (e.g. smart watches).
-
Vertical service codes, which enables the creation of phone numbers and number prefixes/suffixes that invoke services in the network.
-
Location based dialing, which allows for phone numbers that direct to different places depending on a subscriber’s location.
-
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.
-
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.
-
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.
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.
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/
.
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.
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
.
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
rvtconfig reference
Overview
To apply an update to the Rhino VoLTE TAS’s declarative configuration, the rvtconfig
tool is used. rvtconfig
applies configuration to the Rhino VoLTE TAS’s configuration data store (CDS). The CDS distributes this configuration to the Rhino VoLTE TAS’s VMs. The rvtconfig
tool is provided on the VMs that the RVT runs on and the SIMPL VM.
For further information on configuring the RVT’s virtual machines, refer to the RVT VM Install Guide (CDMA) and the RVT VM Install Guide (GSM).
rvtconfig
tool
Configuration YAML files can be validated and uploaded to the CDS using the rvtconfig
tool. The rvtconfig
tool can be run either on the SIMPL VM or any RVT VM.
On the SIMPL VM, you can find the command in the resources
subdirectory of any RVT (tsn
, shcm
, mag
, mmt-gsm
, mmt-cdma
or smo
) CSAR, after it has been extracted using csar unpack
.
/home/admin/.local/share/csar/<csar name>/<version>/resources/rvtconfig
On any RVT VM, the rvtconfig
tool is in the PATH
for the sentinel
user and can be run directly by running:
rvtconfig <command>
The available rvtconfig
commands are:
-
rvtconfig validate
validates the configuration, even before booting any VMs by using the SIMPL VM. -
rvtconfig upload-config
validates, encrypts, and uploads the configuration to the CDS. -
rvtconfig delete-deployment
deletes a deployment from the CDS.Only use this when advised to do so by a Customer Care Representative. -
rvtconfig delete-node-type-version
deletes state and configuration for a specified version of a given node type from the CDS.This should only be used when there are no VMs of that version deployed. -
rvtconfig delete-node-type-all-versions
deletes state and configuration for all versions of a given node type from the CDS.Only use this after deleting all VMs for a given node type. -
rvtconfig delete-node-type-retain-version
deletes state and configuration for a given node type from the CDS, except for the specified version. -
rvtconfig list-config
displays a summary of the configurations stored in the CDS. -
rvtconfig dump-config
dumps the current configuration from the CDS. -
rvtconfig print-leader-seed
prints the current leader seed as stored in the CDS. -
rvtconfig generate-private-key
generates a new private key for use in the SDF. -
rvtconfig enter-maintenance-window
disables VMs' scheduled tasks for a period of time. -
rvtconfig leave-maintenance-window
re-enables VMs' scheduled tasks. -
rvtconfig calculate-maintenance-window
calculates the required length of a maintenance window for rolling upgrades. -
rvtconfig maintenance-window-status
displays a message indicating whether there is an maintenance window period reserved or not. -
rvtconfig export-log-history
exports the quiesce log history from the CDS. -
rvtconfig initconf-log
retrievesinitconf.log
file from the specified remote RVT node. -
rvtconfig describe-versions
prints the current values of the versions of the VM found in the config and in the SDF. -
rvtconfig compare-config
compares currently uploaded config with a given set of configuration. -
rvtconfig backup-cds
creates a backup of the CDS database intar
format and retrieves it. -
rvtconfig restore-cds
uses CDS database backup taken withbackup-cds
to restore the CDS database to a previous state. -
rvtconfig set-desired-running-state
setsDesiredRunningState
to stopped/started in MDM.-
If
--state Started
or no--state
is specified, all initconf processes of non-TSN VMs will pause their configuration loops. -
If
--state Stopped
is specified, all initconf processes of non-TSN VMs will resume their configuration loops.
-
-
rvtconfig cassandra-upgrade
performs a cassandra upgrade operation from {cassandra-version-three} to {cassandra-version-four}. This command can only be used after a Major TSN upgrade has been successfully executed to TSN 4.1 and the cassandra version running is {cassandra-version-three}. This operation must be done one TSN node at a time and no parallelization is allowed. -
rvtconfig cassandra-status
prints the cassandra database status of all the specified CDS IP addresses. -
rvtconfig cassandra-upgrade-sstables
upgradessstables
status once all TSN 4.1 nodes have been upgraded to Cassandra version {cassandra-version-four} withrvtconfig cassandra-upgrade
Common arguments
Commands that read or modify CDS state take a --cds-address
parameter (which is also aliased as --cds-addresses
, --cassandra-contact-point
, --cassandra-contact-points
, or simply -c
). For this parameter, specify the management address(es) of at least one machine hosting the CDS database. Separate multiple addresses with a space, for example --cds-address 1.2.3.4 1.2.3.5
.
The upload-config
and export-audit-history
commands read UNRESOLVABLE BXREF: sdf-secrets[secrets] from QSG. If you have not yet uploaded secrets to QSG, you can specify a --secrets-file <file>
argument, passing in the path to your secrets file (the YAML file which you pass to csar secrets add
). QSG is only available on the SIMPL VM; if running rvtconfig
on a platform other than the SIMPL VM, for example on the VM itself, then you must pass the --secrets-file
argument.
Commands that read or modify CDS state may also require additional parameters if the CDS endpoints are configured to use authentication and/or SSL encryption as per UNRESOLVABLE BXREF: cassandra-security[Cassandra security configuration]. If the CDS endpoints are configured to use authentication, you must pass the --cds-username
argument with your configured password and either the --cds-password
or --cds-password-secret-name
argument with the configured password or its ID in the secrets file. If the CDS endpoints are configured to use SSL encryption, you must pass the --ssl
flag and also pass either the --ssl-ca-certificate
or --ssl-ca-certificate-secret-name
argument containing a file with the SSL signing certificate, or its ID in the secrets file.
The various delete-node-type
commands, and the report-group-status
command, require an SSH private key to access the VMs. You can specify this key as either a path to the private key file with the --ssh-key
argument, or as a secret ID with the --ssh-key-secret-id
argument. If you are running rvtconfig
on the SIMPL VM, the recommended approach is to use the secret ID of the SIMPL VM-specific private key that you specified in the SDF (see UNRESOLVABLE BXREF: solution-service-group#simpl-vm-ssh-private-key[SIMPL VM SSH private key] ). Otherwise, use the SSH private key file itself (copying it to the machine on which you are running rvtconfig
, and deleting it once you have finished, if necessary).
For more information, run rvtconfig --help
. You can also view help about a particular command using, for example, rvtconfig upload-config --help
.
rvtconfig
limitations
The following limitations apply when running rvtconfig
on the SIMPL VM:
-
All files and directories mentioned in parameter values and the secrets file must reside within the root (
/
) filesystem of the SIMPL VM. A good way to ensure this is the case is to store files only in directories under/home/admin
. -
rvtconfig
assumes files specified without paths are located in the current directory. If multiple directories are involved, it is recommended to use absolute paths everywhere. (Relative paths can be used, but may not use..
to navigate out of the current directory.)
Verifying and uploading configuration
-
Create a directory to hold the configuration YAML files.
mkdir yamls
-
Ensure the directory contains the following:
-
configuration YAML files
-
the Solution Definition File (SDF)
-
Rhino license for nodes running Rhino.
-
Do not create any subdirectories. Ensure the file names match the example YAML files. |
Verifying configuration with validate
To validate configuration, run the command:
rvtconfig validate -t <node type> -i ~/yamls
where <node type>
is the node type you want to verify, which can be tsn
, shcm
, mag
, mmt-gsm
, mmt-cdma
or smo
. If there are any errors, fix them, move the fixed files to the yamls
directory, and then re-run the above rvtconfig validate
command on the yamls
directory.
Once the files pass validation, store the YAML files in the CDS using the rvtconfig upload-config
command.
If using the SIMPL VM, the |
Uploading configuration to the CDS with upload-config
To upload the YAML files to the CDS, run the command:
rvtconfig upload-config [--secrets-file <file>] -c <tsn-mgmt-addresses> -t <node type> -i ~/yamls
[(--vm-version-source [this-vm | this-rvtconfig | sdf-version] | --vm-version <vm_version>)] [--reload-resource-adaptors]
The |
If you would like to specify a version, you can use:
-
--vm-version
to specify the exact version of the VM to target (as configuration can differ across a VM upgrade). -
--vm-version-source
to automatically derive the VM version from the given source. Failure to determine the version will result in an error.-
Use
this-rvtconfig
when running thervtconfig
tool included in the CSAR for the target VM, to extract the version information packaged intorvtconfig
. -
Use
this-vm
if running thervtconfig
tool directly on the VM being configured, to extract the version information from the VM. -
Option
sdf-version
extracts the version value written in the SDF for the given node.
-
If the version is not specified, then the version in the SDF will be compared to the this-rvtconfig
or this-vm
version (whichever is appropriate given how the rvtconfig
command is run). If they match, this value will be used. Otherwise, the command will fail.
Whatever way you enter the version, the value obtained must match the version in the SDF. Otherwise, the upload will fail. |
Any YAML configuration values which are specified as secrets are marked as such in the YAML files' comments. These values will be encrypted using the generated private-key created by rvtconfig generate-private-key
and prior to uploading the SDF. In other words, the secrets should be entered in plain text in the SDF, and the upload-config
command takes care of encrypting them. Currently this applies to the following:
-
Rhino users' passwords
-
REM users' passwords
-
SSH keys for accessing the VM
-
the SNMPv3 authentication key and privacy key
Use the |
If the CDS is not yet available, this will retry every 30 seconds for up to 15 minutes. As a large Cassandra cluster can take up to one hour to form, this means the command could time out if run before the cluster is fully formed. If the command still fails after several attempts over an hour, troubleshoot Cassandra on the machines hosting the CDS database.
This command first compares the configuration files currently uploaded for the target version with those in the input directory. It summarizes which files are different, how many lines differ, and if there are any configuration changes that are unsupported (for example, changing the VMs' IP addresses). If there are any unsupported configuration changes, the config will not be uploaded. Follow the instructions in the error message(s) to revert unsupported changes in the configuration, then try again.
If the changes are valid, but any files are different, rvtconfig
will prompt the user to confirm the differences are as expected before continuing with the upload. If the upload is canceled, and --output-dir
is specified, then full details of any files with differences will be put into the given output directory, which rvtconfig
creates if it doesn’t already exist.
Changes to secrets and non-YAML files cannot be detected due to encryption; they will not appear in the summary or detailed output. Any such changes will still be uploaded.
You can disable this pre-upload check on config differences using the --skip-diff
flag (also aliased as -f
).
Restarting resource adaptors
Specify the The 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 If you apply configuration changes that include changes to such fields, and do not specify the |
Comparing existing configuration in the CDS with compare-config
Compare the configuration in an input directory with the currently uploaded configuration in the CDS using the command:
rvtconfig compare-config -c <cds-mgmt-addresses> -t <node type> -i ~/yamls --output-dir <output-directory>
[--deployment-id <deployment ID>] [--site-id <site ID>] [(--vm-version-source [this-vm | this-rvtconfig | sdf-version] | --vm-version <vm_version>)]
This will compare the currently uploaded configuration in the CDS with the configuration in the local input directory.
The deployment ID, site ID, and version of configuration to look up in CDS will be automatically taken from the SDF. These can be overridden by using the --deployment-id
, --site-id
, and one of the --vm-version-source
or --vm-version
parameters respectively. For example, you can specify --vm-version <downlevel version>
to check what has changed just before running an upgrade, where the version in the input SDF will be the uplevel version.
The files that have differences will be displayed, along with the number of different lines, and any errors or warnings about the changes themselves. Any errors will need to be corrected before you can run rvtconfig upload-config
.
The command puts the full contents of each version of these files into the output directory, along with separate files showing the differences found. The command ignores non-YAML files and any secrets in YAML files. The files in this output directory use the suffix .local
for a redacted version of the input file, .live
for a redacted version of the live file, and .diff
for a file showing the differences between the two.
The contents of the files in the output directory are reordered and no longer have comments; these won’t match the formatting of the original input files, but contain the same information. |
Deleting configuration from the CDS with delete-deployment
Delete all deployment configuration from the CDS by running the command:
rvtconfig delete-deployment -c <tsn-mgmt-addresses> -d <deployment-id> [--delete-audit-history]
Only use this when advised to do so by a Customer Care Representative. |
Only use this after deleting all VMs of the deployment within the specified site. Functionality of all nodes of this type and version within the given site will be lost. These nodes will have to be deployed again to restore functionality. |
Deleting state and configuration for a specific node type and version from the CDS with delete-node-type-version
Delete all state and configuration for a given node type and version from the CDS by running the command:
rvtconfig delete-node-type-version -c <tsn-mgmt-addresses> -d <deployment-id> --site-id <site-id> --node-type <node type>
(--vm-version-source [this-vm | this-rvtconfig | sdf-version -i ~/yamls] | --vm-version <vm_version>) (--ssh-key SSH_KEY | --ssh-key-secret-id SSH_KEY_SECRET_ID) [-y]
The argument -i ~/yamls is only needed if sdf-version is used. |
Only use this after deleting all VMs of this node type and version within the specified site. Functionality of all nodes of this type and version within the given site will be lost. These nodes will have to be deployed again to restore functionality. |
Deleting all state and configuration for a specific node type from the CDS with delete-node-type-all-versions
Delete all state and configuration for a given node type from the CDS by running the command:
rvtconfig delete-node-type-all-versions -c <tsn-mgmt-addresses> -d <deployment-id> --site-id <site-id>
--node-type <node type> (--ssh-key SSH_KEY | --ssh-key-secret-id SSH_KEY_SECRET_ID) [--delete-certificates] [-y]
Only use this after deleting all VMs of this node type within the specified site. Functionality of all nodes of this type within the given site will be lost. These nodes will have to be deployed again to restore functionality. |
The --delete-certificates option should only be used when advised by a Customer Care Representative. |
Deleting historical state and configuration for a given node type from the CDS with delete-node-type-retain-version
Remove all state and configuration relating to a versions of the node type other than the specified version from CDS by running the command:
rvtconfig delete-node-type-retain-version -c <tsn-mgmt-addresses> -d <deployment-id> --site-id <site-id> --node-type <node-type>
(--vm-version-source [this-vm | this-rvtconfig | sdf-version -i ~/yamls] | --vm-version <vm_version>) (--ssh-key SSH_KEY | --ssh-key-secret-id SSH_KEY_SECRET_ID) [-y]
The argument -i ~/yamls is only needed if sdf-version is used. |
The version specified in this command must be the only running VM version for this node type. i.e. do not use during an upgrade or rollback when multiple versions of the same node type may be running. All state and configuration relating to other versions will be deleted from CDS. |
Removing unused Rhino-generated keyspaces
Following an upgrade or rollback, you may wish to clean up keyspaces in the Cassandra ramdisk database from version(s) that are no longer in use. This conserves memory and disk space.
To clean up unused keyspaces, use the following command:
rvtconfig remove-unused-keyspaces -c <tsn-mgmt-addresses> -d <deployment-id> -g <group-id> [-y]
Group ID syntax: RVT-<node type>.<site ID> Example: RVT-tsn.DC1 Here, <node type> can be tsn , shcm , mag , mmt-gsm , mmt-cdma or smo . |
Confirm that the active VM versions that the command identifies are correct. rvtconfig
removes keyspaces relating to all other versions from Cassandra.
Listing configurations available in the CDS with list-config
List all currently available configurations in the CDS by running the command:
rvtconfig list-config -c <tsn-mgmt-addresses> -d <deployment-id>
This command will print a short summary of the configurations uploaded, the VM version they are uploaded for, and which VMs are commissioned in that version.
Retrieving configuration from the CDS with dump-config
Retrieve the VM group configuration from the CDS by running the command:
rvtconfig dump-config -c <tsn-mgmt-addresses> -d <deployment-id> --group-id <group-id>
(--vm-version-source [this-vm | this-rvtconfig | sdf-version -i ~/yamls -t <node type>] | --vm-version <vm_version>)
[--output-dir <output-dir>]
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 <tsn-mgmt-addresses> -d <deployment-id> --group-id <group-id>
(--vm-version-source [this-vm | this-rvtconfig | sdf-version -i ~/yamls -t <node type>] | --vm-version <vm_version>)
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. |
Generating a secrets-private-key
for Encrypting Secrets with generate-private-key
Some configuration, for example Rhino or REM users' passwords, are configured in plaintext, but stored encrypted in CDS for security. rvtconfig
automatically performs this encryption using a secrets private key
which you configure in the SDF. This key must be a Fernet key, in Base64 format. Use the following rvtconfig
command to generate a suitable secrets private key:
rvtconfig generate-private-key
Add the generated secrets private key to your secrets input file when UNRESOLVABLE BXREF: sdf-secrets#adding-secrets[adding secrets to QSG].
Maintenance window support
The rvtconfig enter-maintenance-window
and rvtconfig leave-maintenance-window
commands allow you to pause and resume UNRESOLVABLE BXREF: scheduled-tasks[scheduled tasks] (Rhino restarts, SBB/activity cleanup, and Cassandra repair) on the VMs for a period of time. This is useful to avoid the scheduled tasks interfering with maintenance window activities, such as patching a VM or making substantial configuration changes.
To start a maintenance window, use
rvtconfig enter-maintenance-window -c <tsn-mgmt-addresses> -d <deployment-id> -S <site-id> [--hours <hours>]
-
The <site-id> is in the form
DC1
toDC32
. It can be found in the SDF. -
The number of hours defaults to 6 if not specified, and must be between 1 and 24 hours.
Once started, the maintenance window can be extended by running the same command again (but not shortened). rvtconfig
will display the end time of the maintenance window in the command output. Until this time, all scheduled tasks on all VMs in the specified site will not be run.
Any scheduled tasks which are in progress at the time the maintenance window is started will continue until they are finished. If the maintenance window is starting around the time of a scheduled task as configured in the YAML files, it is advisable to manually check that the task is complete before starting maintenance (or run the |
When the maintenance window is complete, use the following command:
rvtconfig leave-maintenance-window -c <tsn-mgmt-addresses> -d <deployment-id> -S <site-id>
Scheduled tasks will now resume as per their configured schedules.
To check whether or not a maintenance window is currently active, use the following command:
rvtconfig maintenance-window-status -c <tsn-mgmt-addresses> -d <deployment-id> -S <site-id>
Calculating the required length of a maintenance window with calculate-maintenance-window
The rvtconfig calculate-maintenance-window
commands allows you to estimate how long an upgrade or rollback is expected to take, so that an adequate maintenance window can be scheduled.
To calculate the recommended maintenance window duration, use
rvtconfig calculate-maintenance-window -i ~/yamls -t <node type> -s <site-id> [--index-range <index range>]
-
The <site-id> is in the form
DC1
toDC32
. It can be found in the SDF. -
If
--index-range
is not specified, a maintenance window for upgrading all VMs will be calculated. If only some VMs are to be upgraded, specify the--index-range
argument exactly as it will be specified for thecsar update
command to be used to upgrade the subset of VMs. For example, if only nodes with indices 0, 3, 4 and 5 are to be upgraded, the argument is--index-range 0,3-5
.
Retrieving VM logs with export-log-history
During upgrade, when a downlevel VM is removed, it uploads Initconf, Rhino and SGC logs to the CDS. The log files are stored as encrypted data in the CDS.
Only the portions of the logs written during quiesce are stored. |
Retrieve the VM logs for a deployment from the CDS by running the command:
rvtconfig export-log-history -c <tsn-mgmt-addresses> -d <deployment-id> --zip-destination-dir <directory>
--secrets-private-key-id <secrets-private-key-id>
The --secrets-private-key-id must match the ID used in the SDF (secrets-private-key-id ). |
The Initconf, Rhino and SGC logs are exported in unencrypted zip files. The zip file names will consist of VM hostname, version, and type of log. |
Viewing the values associated with the special sdf-version
, this-vm
, and this-rvtconfig
versions with describe-versions
Some commands, upload-config
for example, can be used with the special version values sdf-version
, this-vm
, and this-rvtconfig
.
-
Calling
sdf-version
extracts the version from the value given in the SDF for a given node. -
The
this-vm
option takes the version of the VM the command is being run from. This can only be used when the commands are run on a node VM. -
Using
this-rvtconfig
extracts the version from the rvtconfig found in the directory the command is being run from. This can only be used on a SIMPL VM.
To view the real version strings associated with each of these special values:
rvtconfig describe-versions [-i ~/yamls]
Optional argument -i ~/yamls
is required for the sdf-version
value to be given. If it is called, the sdf-version
will be found for each node type in the SDF. If a node type is expected but not printed this may be because the config yaml files for that node are invalid or not present in the ~/yamls
directory.
If a special version value cannot be found, for example if this-vm
is run on a SIMPL VM or the optional argument is not called, the describe-versions
command will print N/A
for that special version.
Reporting group status, to help guide VM recovery
This command reports the status of each node in the given group, providing information to help inform which approach to take when recovering VMs.
It connects to each of the VMs in the group via SSH, as well as querying the CDS service. It then prints a detailed summary of status information for each VM, as well as a high level summary of the status of the group.
It does not log its output to a file. When using this command to aid in recovery operations, it’s good practice to redirect its output to a file locally on disk, which can then be used as part of any root cause analysis efforts afterwards.
On the SIMPL VM, run the command as follows, under the resources dir of the unpacked CSAR:
./rvtconfig report-group-status -c <cds-mgmt-addresses> -d <deployment-id> \
--g <group-id> --ssh-key-secret-id <simpl-private-key-id>
Group ID syntax: RVT-<node type>.<site ID> Example: RVT-tsn.DC1 Here, <node type> can be tsn , shcm , mag , mmt-gsm , mmt-cdma or smo . |
Gathering diagnostics and initconf
log files
It is possible to obtain diagnostic files from RVT nodes with the command rvtconfig gather-diags
. These diagnostic files include system files and solution configuration files, are packaged as a tar.gz
file and deposited in the given output directory. Depending on the node type there will be different kinds of solution configuration files. These files can be crucial to troubleshoot problems on the VMs.
./rvtconfig gather-diags --sdf <SDF File> -t <node type> --ssh-key-secret-id <SSH key secret ID> --ssh-username sentinel --output-dir <output-directory>
If you need to quickly check the initconf.log
file from a certain VM or VMs, it is possible to do it with the command rvtconfig initconf-log
. This command executes a tail on the initconf.log
file of the specified VM or VMs and dumps it to the standard output.
rvtconfig initconf-log --ssh-key-secret-id <SSH key secret ID> --ssh-username sentinel --ip-addresses <Space separated VM IP address list> --tail <num lines>
Operate the TSN Cassandra Database
From RVT 4.1-3-1.0.0, the TSN nodes can be deployed with Cassandra version {cassandra-version-three} or {cassandra-version-four}. Both Cassandra versions are installed in the VM Image, but only one is active. The commands rvtconfig cassandra-upgrade
and rvtconfig cassandra-upgrade-sstables
allow you to perform a Cassandra upgrade from {cassandra-version-three} to {cassandra-version-four} on a running TSN VM 4.1-3-1.0.0 or higher. These two commands must only be run if the target TSNs are running Cassandra {cassandra-version-three}.
To upgrade a single TSN node from {cassandra-version-three} to {cassandra-version-four} you can run ./rvtconfig cassandra-upgrade --ssh-key-secret-id <SSH key secret ID> --ip-addresses <TSN Address>
for every TSN VM, one by one, and not in parallel.
Once all TSN nodes have been upgraded to {cassandra-version-four}, we must perform a sstables
upgrade operation with the following command ./rvtconfig cassandra-upgrade-sstables --ssh-key-secret-id <SSH key secret ID> --ip-addresses <TSN Addresses>
Additionally the command rvtconfig cassandra-status
prints the cassandra database status for the specified CDS IP addresses. Here is a couple of examples:
-
./rvtconfig cassandra-status --ssh-key-secret-id <SSH key secret ID> --ip-addresses <TSN Address 1> <TSN Address 2> …
CDS Backup and Restore operations.
From RVT 4.1-3-1.0.0, the TSNs' CDS database can be backed up and restored. This provides a faster recovery procedure in case TSN upgrades go wrong.
To backup the CDS of a running TSN cluster, run ./rvtconfig backup-cds --sdf /home/admin/uplevel-config/sdf-rvt.yaml --site-id <site ID> --output-dir <backup-cds-bundle-dir> --ssh-key-secret-id <SSH key secret ID> -c <CDS address> <CDS auth args>
To restore the CDS of a running TSN cluster, run ./rvtconfig restore-cds --sdf /home/admin/uplevel-config/sdf-rvt.yaml --site-id <site ID> --snapshot-file <backup-cds-bundle-dir>/tsn_cassandra_backup.tar --ssh-key-secret-id <SSH key secret ID> -c <CDS Address> <CDS auth args>
Only use restore-cds when advised to do so by a Customer Care Representative. |
Control initconf
configuration loop in non-TSN nodes.
During maintenance windows which involve upgrading TSN nodes, the command rvtconfig set-desired-running-state
allows you stop/start the configuration tasks performed by the initconf
that read from the CDS database in all non-TSN VMs. This operation does not stop the non-TSN VMs or the initconf
process within it. But it instructs the initconf
to pause or resume, the configuration tasks, while operating normally under traffic.
To pause initconf
configuration tasks of all non-TSN VMs, run ./rvtconfig set-desired-running-state --sdf /home/admin/uplevel-config/sdf-rvt.yaml --site-id <site ID> --state Stopped
.
To resume initconf
configuration tasks of all non-TSN VMs, run ./rvtconfig set-desired-running-state --sdf /home/admin/uplevel-config/sdf-rvt.yaml --site-id <site ID> --state Started
.
RVT system configuration
This section describes how to set up the Rhino VoLTE TAS system.
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 |
|
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
|
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
|
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
|
✔ |
✔ |
✔ |
✔ |
✔ |
||
✔ |
✔ |
✔ |
✔ |
✔ |
||
✔ |
✔ |
✔ |
✔ |
✔ |
||
✔ |
✔ |
✔ |
✔ |
✔ |
||
✔ |
||||||
Per node parameters |
||||||
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
|
✔ |
✔ |
✔ |
✔ |
|||
✔ |
✔ |
✔ |
✔ |
✔ |
||
✔ |
✔ |
|||||
✔ |
✔ |
✔ |
||||
✔ |
||||||
✔ |
||||||
✔ |
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.
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
|
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.
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.
- I-CSCF integration
- ATCF integration
- SS7 integration
- HSS integration
- HLR integration
- Diagnostics systems integration
- Media server integration
- IP-SM-GW specific integration
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.
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.
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:
# 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.
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:
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. EitherITU
orANSI
. -
❏ 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, andNATIONAL
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
.
deployment-config:sgc:
m3ua:
local-port: 2905
sccp-variant: ITU
point-code: "5"
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 |
---|---|---|
|
|
|
|
simple numeric, quoted |
|
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.
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.
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.
The password will be automatically encrypted using the secrets-private-key configured in the site definition file (SDF). |
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.
deployment-config:sgc:
sgcenv:
jmx-port: 55555
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:
# 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
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
orsentinel-volte-cdma-config.yaml
file, if theinbound-ss7-address
value contains apc=
parameter, that parameter’s value must be the same as thepoint-code
value insgc-config.yaml
. -
In
sentinel-ipsmgw-config.yaml
file, if theoriginating-address
value contains apc=
parameter, that parameter’s value must be the same as thepoint-code
value insgc-config.yaml
. For more details, see step 3 of IP-SM-GW Initial configuration.
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 inapplication-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 thedaud-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.
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:
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.
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:
Optional configuration may include the DPC’s:
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.
For ITU variant, specify point codes as quoted integers, e.g. For ANSI variant, specify point codes in |
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.
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.
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.
-
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:
deployment-config:sgc:
m3ua:
remote:
dpcs:
- id: "DPC-2"
dpc: "2"
There is one AS operating on the STP cluster to configure for.
-
Add an AS instance with the same
id
as used in both remote peers'application-servers
.
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.
-
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:
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.
-
Add an AS instance
id
corresponding to each remote peer’sapplication-servers
.
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 digits123456
. -
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:
-
The matching rule, which decides what SCCP addresses are to be translated. This invokes specified translation rules.
-
The translation rule, which decides the DPC to route and routing priority. This invokes specified rewriter rules.
-
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.
Scope of Rule on SCCP message | Matching Rule matchers |
Translation Rule translations |
Rewrite/Replace Rule rewriters |
---|---|---|---|
Rule ID |
Matching rule |
Configuration specific translation rule |
Configuration specific rewrite rule |
Address Information |
Match to specific |
Replace with |
|
Treat digits to match as a prefix |
|||
GT Encoding |
Replace |
||
GTI Global Title Indicator |
Replace |
||
Nature of Address (code defined in RFC 3868) |
Match |
Replace |
|
Numbering Plan (code defined in RFC 3868) |
Match |
Replace |
|
Translation Type (code defined in RFC 3868) |
Match |
Replace |
|
SSN |
|||
Route on SSN, GT, or no change |
Replace |
||
Message DPC |
Add |
||
Local Routing |
|
||
Relative Rule Priority |
Rule |
||
Rules to Invoke |
Invoke |
Invoke |
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).
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.
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 string44123456
. -
The
is-prefix
is set true so SCCP addressed digits starting with44123456
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.
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.
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 string44666
. -
The
is-prefix
is set true so SCCP addressed digits starting with44666
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 therewrite_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.
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
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.
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.
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 tonull
. -
The VM configuration defect treats
0
as being absent ornull
, when it should be treating it as an actual0
.
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:
-
Examine
m3ua
configuration for any integer parameter values that are currently set to0
. Determine if and how this parameter is affected by configuration defects by consulting the table below.-
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. -
If you wish to retain the previous incorrect behavior, apply the action documented in the
action to retain incorrect behavior
column. -
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.
-
-
precond-ssns
were not applied prior to version4.0.0-18-1.0.0
, regardless of their value. To retain that behavior, delete allprecond-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 |
|
rewriter does not set |
rewriter sets |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
rewriter does not set |
rewriter sets |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
rewriter does not set |
rewriter sets |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
rewriter does not set |
rewriter sets |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
rewriter does not set |
rewriter sets |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
matcher may match on configured defaults if |
matcher will only match a |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
matcher may match on configured defaults if |
matcher will only match a |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
matcher may match on configured defaults if |
matcher will only match a |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
Initconf did not converge. |
Initconf will converge, and the priority will be set to |
N/A |
4.0.0-10-1.0.0 |
|
inbound rule will match any |
inbound rule will only match a |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
inbound rule will match any |
inbound rule will only match a |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
inbound rule will match any |
inbound rule will only match a |
Remove the parameter and its value. |
4.0.0-10-1.0.0 |
|
ASP management messages will be sent without an |
ASP management messages will be sent with the |
Remove the parameter and its value. |
4.0.0-10-1.0.0 and 4.0.0-23-1.0.0 |
|
the |
the |
Remove the parameter and its value. |
4.0.0-10-1.0.0 and 4.0.0-23-1.0.0 |
|
the |
The route will be configured with a priority of |
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.
Reconfiguring the SGC will cause a full SS7 outage in live deployments. |
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:
-
Review the configuration.
-
Stop the OCSS7 SGCs.
-
Verify that the OCSS7 SGCs are stopped.
-
Delete the OCSS7 SGCs.
-
Clear OCSS7 SGC-related state from the TSN nodes (CDS).
-
Apply the new configuration.
Process detail
1. Review the configuration
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
The following message may be safely ignored:
|
3. Verify that the OCSS7 SGCs are stopped
-
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.
-
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>/
Do not delete |
5. Clear OCSS7 SGC-related state from the TSN nodes (CDS)
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.
-
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
The |
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.
If other SGC configuration has changed it is necessary to follow the Reconfiguring the SGC procedure. |
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:
-
Removal of existing SNMP configuration.
-
Application of desired SNMP configuration.
For each affected node type (SGC or SMO) the steps to follow are:
-
Complete Preparation for SGC SNMP reconfiguration.
-
Modify the
snmp-config.yaml
to the desired final state and upload the modified configuration usingrvtconfig
.
Upgrading when SNMPv3 is enabled
This process is only required when both:
|
The process consists of two phases:
-
Preparation and removal of the existing SNMP configuration.
-
Performing the upgrade.
For each affected node type (SGC or SMO) the steps to follow are:
-
Complete Preparation for SGC SNMP reconfiguration.
-
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
This process is only required when both:
|
The process consists of two phases:
-
Preparation and removal of the existing SNMP configuration.
-
Performing the rollback.
For each affected node type (SGC or SMO) the steps to follow are:
-
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.
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:
-
Ensure that you have a backup copy of the active cluster’s original
snmp-config.yaml
configuration file. -
Modify the active cluster’s
snmp-config.yaml
to disable all SNMP:deployment-config:snmp: v1-enabled: false v2c-enabled: false v3-enabled: false
-
Upload the modified configuration using
rvtconfig
and wait for Initconf to converge. -
Remove the SGC’s existing SNMP configuration.
Remove the SGC’s existing SNMP configuration
Perform this process once, on one VM of the type being reconfigured. The process affects the whole SGC cluster. |
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"). |
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
-
Log into one VM of the type being reconfigured.
-
Start the SGC CLI:
/home/sentinel/ocss7/<deployment_id>/<deployment_id>-<node_id>/current/cli/sgc-cli.sh
-
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.
-
-
Similarly, view the configured SNMP notification targets by executing the SGC CLI command
display-target-address
. For each line in the returned table, executeremove-target-address: oname=<oname>
. -
Finally, view the configured SNMP USM users by executing the SGC CLI command
display-usm-user
. For each line in the returned table, executeremove-usm-user: oname=<oname>
. -
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.
# 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 Shprotocol 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.
# This file describes the pool of Virtual Machines that comprise a "ShCM group"
deployment-config:shcm-virtual-machine-pool:
# needs to match the deployment_id vapp parameter
deployment-id: example
# needs to match the site_id vApp parameter
site-id: DC1
# Define one or more Rhino users and give their passwords in plain-text.
# Passwords will be encrypted by 'rvtconfig upload-config' before this file is uploaded to CDS.
# This user is a read-only user, they can log in and see things in Rhino but do not have permission to change configuration
# it is discouraged to log into Rhino to modify configuration using REM, instead the declarative configuration system should be used
rhino-auth:
- username: readonly
password: xxxxxxxx
virtual-machines:
- vm-id: example-shcm-1
diameter-sh-origin-host: shcm1.shcm.site1.mnc123.mcc530.3gppnetwork.org
rhino-node-id: 101
- vm-id: example-shcm-2
diameter-sh-origin-host: shcm2.shcm.site1.mnc123.mcc530.3gppnetwork.org
rhino-node-id: 102
-
For each virtual machine, set the
diameter-sh-origin-host
to a unique value.
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:
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 Zhprotocol 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.
# This file describes the pool of Virtual Machines that comprise a "MAG cluster"
# there are some pieces of software on this VM type that require clustering and
# knowing each other's IP addresses, for example Rhino
deployment-config:mag-virtual-machine-pool:
# needs to match the deployment_id vapp parameter
deployment-id: example
# needs to match the site_id vapp parameter
site-id: DC1
xcap-domains:
- xcap.site1.ims.mnc123.mcc530.pub.3gppnetwork.org
- xcap.site1.ims.mnc124.mcc530.pub.3gppnetwork.org
# Define one or more Rhino users and give their passwords in plain-text.
# Passwords will be encrypted by 'rvtconfig upload-config' before this file is uploaded to CDS.
# This user is a read-only user, they can log in and see things in Rhino but do not have permission to change configuration
# it is discouraged to log into Rhino to modify configuration using REM, instead the declarative configuration system should be used
rhino-auth:
- username: readonly
password: xxxxxxxx
# Define one or more REM users and give their passwords in plain-text.
# Passwords will be encrypted by 'rvtconfig upload-config' before this file is uploaded to CDS.
# each REM user maps to a Rhino user, when REM logs into Rhino
rem-auth:
- username: remreadonly
real-name: REM read only user
password: xxxxxxxx
virtual-machines:
- vm-id: example-mag-1
rhino-node-id: 101
diameter-zh-origin-host: mag1.mag.site1.mnc123.mcc530.3gppnetwork.org
- vm-id: example-mag-2
rhino-node-id: 102
diameter-zh-origin-host: mag2.mag.site1.mnc123.mcc530.3gppnetwork.org
- vm-id: example-mag-3
rhino-node-id: 103
diameter-zh-origin-host: mag3.mag.site1.mnc123.mcc530.3gppnetwork.org
# DO NOT ENABLE IN PRODUCTION
# Enable extensive logging for verification and issue diagnosis during acceptance testing
rem-debug-logging-enabled: false
-
For each virtual machine, set the
diameter-zh-origin-host
to a unique value.
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:
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:
# 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:
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:
hlr-connectivity-origin:
# CDMA specific configuration.
cdma:
# The market ID value to be used in the MSCID set on outgoing CDMA requests to the HLR
market-id: 1
# The switch number value to be used in the MSCID set on outgoing CDMA requests to the HLR
switch-number: 1
Diagnostics systems integration
SAS integration
The Rhino VoLTE TAS supports Metaswitch’s SAS (Service Assurance Service) integration.
What you need
-
❏ To chose whether or not to activate SAS tracing.
-
❏ The IP addresses or DNS hostnames of SAS servers to connect the Rhino VoLTE TAS to.
Setting up the SAS interface
The configuration for the SAS to Rhino VoLTE TAS interface is in the sas-config.yaml
file.
In the sas
section, configure the servers list
. The example configuration given here indicates input for what is needed for integrating the Rhino VoLTE TAS with SAS servers in a network.
sas:
# Whether SAS is enabled ('true') or disabled ('false')
enabled: true
# Parameters for connecting to SAS
sas-connection:
# List of SAS servers. Either IP addresess or DNS hostnames.
# Needs to be specified in a non-MDM deployment.
servers:
- 10.10.10.10
- 10.10.10.11
- sas.example.com
SNMP integration
The Rhino VoLTE TAS supports integration with SNMP based systems.
What you need
-
❏ The version of SNMP to be used.
-
❏ If using SNMP v2c, the SNMP community value.
-
❏ The SNMP agent details such as location and contact address.
-
❏ If using SNMP notifications, each notification target’s host, port, and specifc SNMP version.
Setting up the SNMP interface
The configuration for the SNMP to Rhino VoLTE TAS interface is in the snmp-config.yaml
file.
In the snmp
section, configure the targets list
. The example configuration given here indicates input for what is needed for integrating the Rhino VoLTE TAS with SNMP services in the network.
snmp:
# 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.
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:
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.
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:
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:
# MAP messaging configuration
map-messaging:
# Template SMSC address. The digits are replaced by those of the received SMSC address.
template-smsc-address: "type=C7,ri=gt,digits=0,ssn=8,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0"
# IPSMGW SCCP address.
originating-address: "type=C7,ri=pcssn,pc=6,ssn=147"
# IPSMGW international address.
ipsmgw-as-msc-address: "address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN"
Charging
What it does
The charging service communicates with a number of possible systems to charge subscribers for making and receiving calls. The Rhino VoLTE TAS supports three different charging methods:
-
offline charging using Diameter Rf to send reports to a Charging Data Function (CDF)
-
online charging using Diameter Ro protocol to communicate with an Online Charging Server (OCS)
-
online charging using SIP to CAP translation to communicate with a charging Service Control Point (SCP) in a GSM network.
Online and offline charging can be used simultaneously. It is also possible to use both types of supported online charging at the same time. The Rhino VoLTE TAS does not support CDMA based charging systems, so for those networks only Diameter based charging is available.
Additionally, the Rhino VoLTE TAS writes Charging Data Records (CDRs) for every call. These contain metadata about the call suitable to use for charging purposes.
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
-
The
diameter-rf-release
to use. -
The Diameter
origin-realm
for the Rhino VoLTE TAS. -
The Diameter
destination-realm
for the offline charging system. -
A Diameter
destination-peers
list that correspond to CDF servers. There must be at least one entry, and for each entry the following values must be set:-
the
destination-hostname
for the CDF -
the
port
for the CDF -
the
protocol-transport
to use with the CDF. -
the
metric
to use for this CDF peer.
-
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:
-
for GSM deployments, in
mmt-gsm-vmpool-config.yaml
-
for CDMA deployments, in
mmt-cdma-vmpool-config.yaml
# 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:
-
for GSM deployments, in
mmt-gsm-vmpool-config.yaml
-
for CDMA deployments, in
mmt-cdma-vmpool-config.yaml
# Remove this if diameter-rf is disabled
# per-node-diameter-rf:
# diameter-rf-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org
Diameter Ro online charging
What it does
When Diameter Ro charging is in use, the Rhino VoLTE TAS communicates with one or more online charging systems (OCS) in real time to authorize credit for calls. While a call is in progress, Diameter Ro messages are exchanged with the OCS whenever more credit is required, or when there are significant changes in the call that could impact the cost (e.g. video is enabled). If at any point the OCS refuses to grant credit, the call is ended.
While the method for enabling Diameter Ro charging differs between GSM and CDMA based deployments, there is no functional difference in charging behavior as the GSM and CDMA parts of the network are not involved.
Diameter Ro charging announcements
When using Diameter Ro online charging, the Rhino VoLTE TAS supports playing announcements when:
-
the subscriber attempts to make a call when they are running low on credit
-
the subscriber attempts to make a call without having any credit
-
the subscriber begins to run low on credit during a call
-
the subscriber runs out of credit during the call
-
the OCS instructs the TAS to do so.
Low credit announcements are played when the OCS’s response to a credit check includes a low balance indicator. After playing a low credit announcement, the Rhino VoLTE TAS waits for a time before doing another credit check. The time period is set in the charging-reauth-delay-milliseconds
field.
Out of credit announcements are played when the OCS sends an "Out of Credit" response to a credit check. The call is terminated after playing an out of credit announcement.
The OCS instructs announcements to be played by including announcement information in its response to a credit check. These announcements will take precedence over the low and out of credit announcements configured in the Rhino VoLTE TAS. If the announcement information came in a "Out of Credit" response, the call will end after the announcement has been played.
When configuring the charging service to play an announcement, you only provide the ID of the announcement that should be played. This ID must correspond to an announcement that has been configured in the announcement service. See Announcements for instruction about how to do this.
Multiple OCS Support
The Rhino VoLTE TAS supports communicating with multiple different Diameter Ro online charging systems. Each OCS must have its own Diameter realm, and those realms must be configured as destination realms in the Rhino VoLTE TAS’s Diameter Ro configuration.
The particular OCS to use for a given call is determined from the ecf
parameter of the P-Charging-Function-Addresses header on the initial SIP request for the call. The value of the ecf
parameter that identifies a particular OCS is its realm name by default, but can be configured to be any arbitrary value by specifying a charging-function-address
when configuring the destination realm for an OCS.
Configuration
The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to Diameter Ro online charging in the sentinel-volte/charging/ro-charging
section.
What you need
-
❏ The release version of Diameter Ro to use with the online charging system.
-
❏ The origin realm to use when sending Diameter Ro messages. This is the TAS’s realm.
-
❏ The destination realm to use when sending Diameter Ro messages. This is the online charging system’s realm.
-
❏ The OCS peers' hostnames, ports, and transport protocols.
For low balance announcements:
-
❏ The ID of the low balance announcement to play in call setup.
-
❏ The ID of the low balance announcement to play in an active call.
-
❏ The time to wait after playing an announcement before doing another credit check.
For out of credit announcements:
-
❏ The ID of the out of credit announcement to play in call setup.
-
❏ The ID of the out of credit announcement to play in an active call.
For multiple OCS support:
-
❏ The destination realm of each OCS.
-
❏ A list of which peers are associated with which realms.
-
❏ (Optional) An identifier for each OCS that will be used to select it with a P-Charging-Function-Addresses header.
Setting up Diameter Ro online charging
I want to…
Use Diameter Ro online charging on a GSM based deployment
-
In the
charging
section, set thegsm-online-charging-type
toro
orcap-ro
for mixed CAMEL/Ro deployments:
gsm-online-charging-type: ro
-
In the
charging
section, configure thero-charging
section. See Configure Diameter Ro online charging. -
In
mmt-gsm-vmpool-config.yaml
, you must ensure that allper-node-diameter-ro
sections in the MMT cluster configuration are present and not commented out.
# 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
-
In the
charging
section, set thegsm-online-charging-type
todisabled
:
gsm-online-charging-type: disabled
-
Remove or comment out the
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
-
In
mmt-gsm-vmpool-config.yaml
, you must comment out allper-node-diameter-ro
sections in the MMT cluster configuration.
# 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
-
In the
charging
section, setcdma-online-charging-enabled
totrue
:
cdma-online-charging-enabled: true
-
In the
charging
section, configure thero-charging
section. See Configure Diameter Ro online charging. -
In
mmt-cdma-vmpool-config.yaml
, you must ensure that all per-node-diameter-ro sections in the MMT cluster configuration are present and not commented out.
# 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
-
In the
charging
section, setcdma-online-charging-enabled
tofalse
:
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
-
In
mmt-cdma-vmpool-config.yaml
, you must comment out allper-node-diameter-ro
sections in the MMT cluster configuration.
# 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
-
The
diameter-ro-release
of Diameter Ro to use. -
The Diameter
origin-realm
for the Rhino VoLTE TAS. -
The Diameter
destination-realm
for the online charging system. -
A Diameter
destination-peers
list that correspond to OCS servers. There must be at least one entry, and for each entry the following values must be set:-
the
destination-hostname
for the OCS server -
the
port
for the OCS server -
the
protocol-transport
to use with the OCS server. -
the
metric
to use with this OCS server peer.
-
Play an announcement to subscribers when they run low on credit
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
-
Add a
low-credit-announcements
section.-
Set the
call-setup-announcement-id
of the announcement to play when a subscriber is low on credit at the beginning of a call. -
Set the
mid-call-announcement-id
of the announcement to play when a subscriber becomes low on credit during a call. -
Set the
charging-reauth-delay-milliseconds
time to wait (in milliseconds) before doing another credit check after playing a low balance announcement.
-
Related section: Diameter Ro charging announcements
Play an announcement to subscribers when they run out of credit
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
-
Add an
out-of-credit-announcements
section.-
Set the
call-setup-announcement-id
of the announcement to play when a subscriber tries to make a call without having enough credit. -
Set the
mid-call-announcement-id
of the announcement to play when a subscriber runs out of credit during a call.
-
Related section: Diameter Ro charging announcements
Configure multiple destination realms
In charging
, ro-charging
:
diameter-ro:
diameter-ro-release: Vcb0
origin-realm: metaswitch.com
destination-realms:
- destination-realm: ocs1.metaswitch.com
peers:
- peer1.metaswitch.com
- destination-realm: ocs2.metaswitch.com
peers:
- peer2.metaswitch.com
- peer3.metaswitch.com
destination-peers:
- destination-hostname: peer1.metaswitch.com
port: 3868
protocol-transport: aaa
metric: 1
- destination-hostname: peer2.metaswitch.com
port: 3868
protocol-transport: aaa
metric: 1
- destination-hostname: peer3.metaswitch.com
port: 3868
protocol-transport: aaa
metric: 2
-
Under
diameter-ro
, add adestination-realms
list.-
If there is already a
destination-realm
listed underro-charging
, remove it.
-
-
For each realm you want to add, create a new entry in the
destination-realms
list with:-
a
destination-realm
giving the realm name. -
a
peers
list giving the destination-hostnames of peers associated with the realm.
-
-
Ensure all the peers referenced by the realms are configured in the
destination-peers
list.
Set an identifier for an OCS for selecting it with a P-Charging-Function-Addresses header
In charging
, ro-charging
, diameter-ro
:
destination-realms:
- destination-realm: ocs1.metaswitch.com
charging-function-address: ocs_1
peers:
- peer1.metaswitch.com
- destination-realm: ocs2.metaswitch.com
peers:
- peer2.metaswitch.com
- peer3.metaswitch.com
-
Find the destination realm for the OCS you want to add an identifier for in the
destination-realms
list. -
Add a
charging-function-address
to the list entry with the identifier to use for the OCS.
Mixed Diameter Ro and CAP online charging
What it does
Operators may have a mixed Diameter Ro and CAP online charging environment. This is typically seen when an Operator is migrating off their SCP. To support this deployment the cap-ro
gsm-online-charging-type is used, which instructs the installer to deploy both CAP and Diameter Ro configurations.
-
For more details on what CAP online charging does refer to what CAP online charging does
-
For more details on what Ro online charging does refer to what Ro online chargines does
Charging Mode Selection
When a call triggers RVT the online charging mode (either Diameter Ro or CAP) is determined by inspecting the top-most route header for the oc-charge-mode
uri parameter which is set to either ro
, cap
, or offline
. If ro
is set then Diameter Ro is used for charging, if cap
is set then CAP online charging is used.
Check the Sentinel VoLTE Administration Guide for more details on the oc-charge-mode . |
For more details on the Diameter Ro and CAP online charging check these links.
Configuration
When using the mixed environment set the gsm-online-charging-type to cap-ro
. Both Diameter Ro
and CAP online charging
configuration needs to be present.
What you need for CAP Online Charging
-
❏ The SCCP address of the GSM charging SCP.
-
❏ The TDP(s) to use when retrieving IM-CSI data from the HLR.
-
❏ Whether or not to send location information to the SCP.
If sending location information to the SCP:
-
❏ The format to sent the information in (see Location information).
-
❏ A default value to send when a subscriber’s location cannot be determined.
What you need for Diameter Ro Charging
-
❏ The release version of Diameter Ro to use with the online charging system.
-
❏ The origin realm to use when sending Diameter Ro messages. This is the TAS’s realm.
-
❏ The destination realm to use when sending Diameter Ro messages. This is the online charging system’s realm.
-
❏ The OCS peers' hostnames, ports, and transport protocols.
For low balance announcements:
-
❏ The ID of the low balance announcement to play in call setup.
-
❏ The ID of the low balance announcement to play in an active call.
-
❏ The time to wait after playing an announcement before doing another credit check.
For out of credit announcements:
-
❏ The ID of the out of credit announcement to play in call setup.
-
❏ The ID of the out of credit announcement to play in an active call.
I want to…
Use both Diameter Ro and CAP online charging on a GSM based deployment
-
In the
charging
section, set thegsm-online-charging-type
tocap-ro
for mixed Diameter Ro/CAP deployments:
gsm-online-charging-type: cap-ro
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. -
Configure the
ro-charging
section. See Configure Diameter Ro online charging. -
In
mmt-gsm-vmpool-config.yaml
, you must ensure that allper-node-diameter-ro
sections in the MMT cluster configuration are present and not commented out.
# Remove this if diameter-ro is disabled
per-node-diameter-ro:
diameter-ro-origin-host: mmt1.mmt.site1.mnc123.mcc530.3gppnetwork.org
CAP online charging
What it does
When CAP online charging is in use, the Rhino VoLTE TAS functions as an IM-SSF (IP Multimedia Service Switching Function) and communicates with an SCP in a GSM network. At various points in the SIP signalling for the call the Rhino VoLTE TAS will translate the SIP to the equivalent CAP signalling towards the SCP, to give it the opportunity to intervene in call processing. Through this the SCP can provide a charging service. The exact details of how and when the Rhino VoLTE TAS will signal the SCP is determined by subscriber specific IM-CSI data in the HLR.
CAP online charging requires that integration with an SCP is set up. To do this, the SCCP (Signalling Connection Control Part) address of the SCP must be set in the scf-address
field.
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:
-
an originating TAS instance is determined by the
originating-tdp
field. -
the terminating TAS instance is determined by the
terminating-tdp
field.
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.
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
CAP based charging is only available on GSM networks. |
The example for sentinel-volte-gsm-config.yaml shows example configuration relevant to CAP charging in the sentinel-volte/charging
section.
What you need
-
❏ The SCCP address of the GSM charging SCP.
-
❏ The TDP(s) to use when retrieving IM-CSI data from the HLR.
-
❏ Whether or not to send location information to the SCP.
If sending location information to the SCP:
-
❏ The format to sent the information in (see Location information).
-
❏ A default value to send when a subscriber’s location cannot be determined.
Setting up CAP based online charging
I want to…
Enable CAP charging
In the charging
section, set the gsm-online-charging-type
to either cap
or cap-ro
for mixed CAMEL/Ro deployments:
gsm-online-charging-type: cap
Also in the charging
section:
cap-charging:
imssf:
scf-address: "type=C7,ri=pcssn,pc=6,ssn=156"
-
Ensure there is a
cap-charging
section. -
Ensure there is an
imssf
section. -
Set the
scf-address
to the SCCP address of the SCP that the Rhino VoLTE TAS should communicate with.
Disable CAP charging
In the charging
section, set the gsm-online-charging-type
to disabled
:
gsm-online-charging-type: disabled
Comment out the entire cap-charging
section:
# cap-charging:
# imssf:
# imcsi-fetching:
# originating-tdp: 2
# terminating-tdp: 12
# charging-gt:
# format: "6422142{iso}"
# unknown-location: "64221429090"
# only-charge-terminating-call-if-international-roaming: false
# scf-address: "type=C7,ri=pcssn,pc=6,ssn=156"
Change the SCP that the CAP charging service communicates with
In the imssf
section, set the scf-address
to the SCCP address of the new SCP:
scf-address: "type=C7,ri=pcssn,pc=6,ssn=156"
Generate and send a charging GT containing location information for a subscriber to the SCP
In the imssf
section:
charging-gt:
format: "6422142{iso}"
unknown-location: "64221429090"
-
Add a
charging-gt
section. Inside it add:-
a
format
field specifying how the location information should be delivered. It can be made up from fixed digits and any of these tags:{mcc}
,{mnc}
, and/or{iso}
; which will substitute in the MCC, MNC, and ISO two letter country code respectively. -
a
unknown-location
field indicating what to send to the SCP if location information cannot be obtained.
-
Related section: Location information
Disable sending of the charging GT to the SCP
In the imssf
section, comment out the entire charging-gt
section:
# charging-gt:
# format: "6422142{iso}"
# unknown-location: "64221429090"
Related section: Location information
Only invoke the CAP charging service for terminating subscribers when they are roaming in a foreign country
In the charging-gt
section, set the only-charge-terminating-call-if-international-roaming
to true
:
only-charge-terminating-call-if-international-roaming: true
Related section: Location information
Always invoke the CAP charging service for terminating subscribers regardless of their location
In the charging-gt
section, set the only-charge-terminating-call-if-international-roaming
to false
:
only-charge-terminating-call-if-international-roaming: false
Related section: Location information
Use O-IM-CSI data from the HLR on originating calls
In the charging
section:
cap-charging:
imssf:
imcsi-fetching:
originating-tdp: 2
-
Ensure that a
cap-charging
section is present. -
Ensure that a
imssf
section is present. -
Ensure that a
imcsi-fetching
section is present.-
Set the
originating-tdp
to2
or3
.
-
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
-
Ensure that a
cap-charging
section is present. -
Ensure that a
imssf
section is present. -
Ensure that a
imcsi-fetching
section is present.-
Set the
originating-tdp
to12
.
-
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
-
Ensure that a
cap-charging
section is present. -
Ensure that a
imssf
section is present. -
Ensure that a
imcsi-fetching
section is present.-
Set the
terminating-tdp
to2
or3
.
-
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
-
Ensure that a
cap-charging
section is present. -
Ensure that a
imssf
section is present. -
Ensure that a
imcsi-fetching
section is present.-
Set the
terminating-tdp
to12
.
-
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:
-
originating calls, remove the
originating-tdp
. -
terminating calls, remove the
terminating-tdp
.
Related section: IM-CSI
Charging Data Records
What it does
Charging Data Records (CDRs) can be generated by the Rhino VoLTE TAS to record information about each call it processes. There are two types of CDRs: Interim CDRs and Session CDRs.
Interim CDRs
Interim CDRs are generated while a call is in progress, with multiple CDRs being generated during a single call. The Rhino VoLTE TAS can write the CDRs to the file system, send them to a CDF using Diameter Rf offline charging, or both.
There are two ways to control when interim CDRs should be generated:
-
You can change the maximum time to wait between creating each CDR.
-
You can instruct that a new CDR is created whenever the SDP for a call is modified.
In addition, one interim CDR is always generated when the call is answered and another when the call ends.
If you want to use Diameter Rf offline charging, interim CDR generation must be enabled.
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.
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
-
The Example for home-network-config.yaml file shows example configuration for the home network’s codes and PLMN IDs in the
home-network
section. -
The Example for sentinel-ipsmgw-config.yaml file shows example configuration for the PLMN ID used for correlation by the IP-SMGW, in the
correlation-ra-plmnid
section.
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
-
In the
home-network
section, sethome-plmn-ids
to your home network’s home PLMN IDs:
home-plmn-ids:
- mcc: "001"
mncs:
- "01"
- "001"
-
If the IP-SM-GW is in use, in the
sentinel-ipsmgw
section, setcorrelation-ra-plmnid
to the home network’s primary PLMN ID:
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:
-
If the original number is in the national format, the
home-network-country-dialing-code
will be prepended to the address. -
If the original number is in the subscriber format, the
home-network-country-dialing-code
andnetwork-dialing-code
will be prepended to the address. -
If the original number format is unknown, it is detected against the
international-prefix
and thenational-prefix
. If neither prefix matches, the number is unchanged.
When normalizing numbers to the national format:
-
If the original number is in the international format, the length of the
home-network-country-dialing-code
will be removed from the start of the address. -
If the original number is in the subscriber format,
network-dialing-code
will be prepended to the address. -
If the original number format is unknown, it is detected against the
international-prefix
and thenational-prefix
. If neither prefix matches, the number is unchanged.
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:
-
Ensure that the home networking country dialing code is set in the home network configuration section - see I want to set my country dialing code for my network.
-
In the
normalization
section:
network-dialing-code: "6"
international-prefix: "00"
national-prefix: "0"
min-normalizable-length: "0"
-
Set
network-dialing-code
to the home network’s dialing code. -
Set
international-prefix
to the home network’s international call prefix (escape code). -
Set
national-prefix
to the home network’s national call prefix (escape code). -
Set
min-normalizable-length
to the home network’s minimum normalizable length used to prevent short dialed strings from being normalized.
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:
international-exHC: This condition for international barring, excluding the home country, evaluates to true when the request URI of the outgoing SIP request:
|
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 isINTERNATIONAL
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 isINTERNATIONAL
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 orOC-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.
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.
-
The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration for roaming determination logic in the Rhino VoLTE TAS in the
international-and-roaming
section. -
For a GSM network, there is an additional option to query the HLR for determining a number’s roaming status. The example for sentinel-volte-gsm-config.yaml shows example configuration in the
mmtel
section.
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.
Configuration
The non-provisionable-uris
field designates what the Rhino VoLTE TAS will not provision, as shown in the example number-analysis-config.yaml file.
Setting up non-provisionable URIs configuration
I want to …
Specify a series of URIs that the Rhino VoLTE TAS will reject call forwarding rules for
To set the Rhino VoLTE TAS to disable provisioning for certain URIs, in the number-analysis
section, set non-provisionable-uris
with a list of non-provisionable URIs.
non-provisionable-uris:
- "tel:111"
- "sip:111@example.com"
Managing the subscriber data
The Rhino VoLTE TAS uses subscriber data to specify the behavior of services for provisioned subscribers.
Subscriber data document schemas
Subscriber data document schemas supported by the Rhino VoLTE TAS:
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.
Service | XPath |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
<?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.
<?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.
<?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.
<?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.
<?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.
<?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">
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.
Using the alternate Cassandra schema
This section describes the procedures for changing the schema that Sentinel Registrar components of MMT and SMO nodes use.
The default schema for storing third-party registration data in the TSN may have high disk usage. This disk usage is a consequence of decisions about table schema used by Registrar components and data handling in the Cassandra database engine. Under some circumstances disk usage may become unpredicatable.
To reduce overall disk space usage and to improve predictablility an alternative Cassandra schema is provided. The instructions here allow you to change the MMT and SMO nodes to use the alternative schema.
Both the MMT and SMO nodes store third-party registration data on the TSN node. Separate instructions are provided for the MMT and SMO nodetypes. Parts of the proceedure require a maintenance window. Each nodetype may be done in a separate maintenance window.
Change the schema for MMT nodes
The default schema uses the first-party REGISTER
callID
field as a part of the primary key. RFC 3261 Section 10.2 states that User Equipment (UE) should use the same callID
for the duration of the time it is registered. As the specification allows UE to use different CALLID
values for the same registration, this requires proper handling.
As the callID
is a part of the primary key, one row is used per unique callID
, which may result in multiple rows representing the same logical registration. In cases where a significant proportion of UE on the network do not reuse their callID
significantly more disk space is required to hold registration records. This contributes to the disk space for registration records being unpredictable under some circumstances.
The alternate schema uses the IMS private identity (hereafter deviceID
) in place of callID
in the schema. Per 3gpp 24.229 specification this must be set on all REGISTER
attempts. As the deviceID
does not change from registration attempt to registration attempt, the size of the database is more predictable.
See Data Schema for details of the Registrar schemas.
The following sections provide instructions for switching to the alternate schema on the MMT node. The required tables already exist on the TSN. You will change MMT configuration to use the alternate tables.
Impacts
During the change of the schema, the system may be affected as follows:
-
There will be an increase in the number of HSS queries. This is because the third-party registrations serve as a cache, and in their absence, devices can only be verified through queries to the HSS. After the procedure is complete, the number of HSS queries should gradually return to the pre-maintenance window level.
The speed at which the number of HSS queries returns to normal depends on the registration validity period. It can be very quick or fairly slow. It is anticipated to be very quick on average. -
When you run the
TRUNCATE
command, disk usage will not drop immediately. Disk usage will only drop after thenodetool clearsnapshot
command is run. This is because theTRUNCATE
command moves the data to a snapshot instead of deleting. The snapshot is only removed when thenodetool clearsnapshot
command is run.
If you encounter any impacts that are not listed, contact Metaswitch technical support. |
Pre-maintenance window steps for changing the Cassandra schema
Before entering the maintenance window you need to take some steps to get prepared. Performing these beforehand ensures that changing the Cassandra schema is a smooth exercise. Some steps can be done well in advance. Other steps need to bedone immediately before entering the maintenance window, as they are a final check to ensure everything is ready for the change.
Pre-maintenance window steps that can be done in advance
Verify the deployed MMT version
Make sure that the MMT VMs have already been upgraded to at least the maintenance version of RVT 4.1-1-1.0.0. The configuration changes that are being made will only work if the MMT is at least this version.
Create file with commands to run
There are commands that will need to be run in preparation for and during the Cassandra schema change. These commands requires specific arguments that need to be prepared beforehand. Creating a file of commands ready to be copy/pasted and run beforehand ensures smooth running of the steps. Placeholder values are of the form <…>
. <a|b>
means a choice of either a or b. For example, mmt-<gsm|cdma>
means mmt-gsm
or mmt-cdma
.
The file of commands can be stored anywhere that is convenient.
Many of the commands are rvtconfig
commands. Further information can be found in the rvtconfig reference.
Determine the following arguments:
-
tsn-mgmt-address
- The management IP address of at least one TSN node. The TSN management IP addresses can be found in theTSN
section of the SDF. If multiple addresses are used, they should be formatted as-c <address1> <address2>…
. -
deployment-id
- This can be found in the SDF under the keydeployment-id
. -
site-id
- The site-id of the site you are changing config for. This can be found in the SDF assite-id
. -
group-id
- EitherRVT-mmt-gsm.<site-id>
orRVT-mmt-cdma.<site-id>
depending on whether the MMTs are of the GSM or CDMA variant. If you are unsure, this can be determined from thervtconfig-path
below. -
sdf-path
- The path to the SDF file on your SIMPL VM. -
rvtconfig-path
- The path to the rvtconfig on your SIMPL VM. This is expected to be something like:/home/admin/.local/share/csar/mmt-gsm/<version>/resources
If Cassandra authentication is enabled, then two additional arguments will be required for every rvtconfig
command.
-
cds-username
- Username to authenticate with Cassandra. You can find it in the SDF undercassandra-username
. -
cds-password-secret-name
- Password identifier to authenticate with Cassandra. You can find it in the SDF undercassandra-password-id
.
They are added in the format --cds-username <cds-username> --cds-password-secret-name <cds-password-secret-name>
as the last two arguments to every rvtconfig
command.
Create a text file containing all the subsequent commands with substitutions completed.
Take a backup of the current configuration
In case you need to roll back later, prepare a copy of the current configuration. Otherwise, you may have to recreate your configuration files manually.
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path> $ rvtconfig dump-config -c <tsn-mgmt-address> -d <deployment-id> --group-id <group-id> --vm-version-source this-rvtconfig --output-dir ~/yamls-rollback
--output-dir
is the output directory for thervtconfig dump-config
command. Any easily accessible directory can be chosen and the command will create the directory if it does not exist. The recommendation is to maintain~/yamls-rollback
, as this value is referenced in the rollback procedure. In the event that a different folder is used, substitute that value for~/yamls-rollback
in the rollback procedure.
Create the new configuration file
The new configuration needs to be written for upload. The configuration points to change are located in the mmt-<gsm|cdma>-overrides.yaml
file in ~/yamls
. Create the file if it does not exist.
MMT configuration change
Contact Metaswitch technical support for assistance with writing the new configuration. |
Yaml uses semantic whitespace. The resulting file must be valid yaml that rvtconfig can accept. |
If mmt-<gsm|cdma>-overrides.yaml
does not exist, create it with the following content:
rhino-config:rhino-configuration:
namespaces:
- name: ''
profile-tables:
- name: RegistrarConfigurationTable
profiles:
- name: 'Metaswitch::::'
present: true
attributes:
- name: usePrivateIdAsRegistrarDataPrimaryKey
content: 'true'
If mmt-<gsm|cdma>-overrides.yaml
exists and does not contain the string RegistrarConfigurationTable
, insert the following contents immediately below the line profile-tables:
:
- name: RegistrarConfigurationTable
profiles:
- name: 'Metaswitch::::'
present: true
attributes:
- name: usePrivateIdAsRegistrarDataPrimaryKey
content: 'true'
If mmt-<gsm|cdma>-overrides.yaml
exists and contains the string RegistrarConfigurationTable
, insert the following into the attributes key of RegistrarConfigurationTable
:
- name: usePrivateIdAsRegistrarDataPrimaryKey
content: 'true'
Pre-maintenance window steps to be done immediately prior to entering the maintenance window
Before performing these steps, ensure that you have: |
-
A file with all the commands that need to be run for changing the Cassandra schema. The commands will have all the required arguments substituted.
-
Two sets of
.yaml
configuration files - the new configuration (~/yamls
), the current config (~/yamls-rollback
). -
Verified that the deployment consists of the right version of the VMs.
Compare live configuration on MMTs with configuration on SIMPL
-
Use SSH to access the SIMPL VM.
-
Verify that the directory
/tmp/checkdiff
does not exist. If the directory does exist, remove it. -
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig compare-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls-rollback --output-dir /tmp/checkdiff --vm-version-source this-rvtconfig
--output-dir is the output directory for the rvtconfig compare-config command. The command will create the directory if it does not exist and will return an error if the directory does exist. |
-
Verify that the command completes with:
No differences found in yaml files.
Uploading this configuration will have no effect unless secrets, certificates or licenses have changed, or --reload-resource-adaptors is specified.
If the output returned does not include "No differences found in yaml files.", contact Metaswitch technical support.
Perform health checks on MMTs in the deployment
The deployment needs to be in a healthy state. To verify that the deployment is healthy, run the following tests.
Enter the maintenance window
If all the healthchecks above pass, start a maintenance window and then run through the steps for changing the Cassandra schema. To enter a maintenance window:
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig enter-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>
Procedure
This section describes the steps for changing the primary key for MMT nodes. These steps are expected to take 30 minutes to complete.
Before beginning these steps, ensure that the placeholder values in commands listed here have been substituted with the required values. Placeholder values are of the form <…> . |
Truncate the registrations
and assocuris
tables on Cassandra
The existing registrations
and assocuris
tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.
-
Use SSH to access the TSN as the primary user (
sentinel
). -
Start the Cassandra CLI by running the command:
$ cqlsh
-
Truncate the tables by running the command:
TRUNCATE opencloud_thirdparty_reg.REGISTRATIONDATA;
TRUNCATE opencloud_thirdparty_reg.ASSOCURIS;
-
Verify that there are no messages printed to the console after running the TRUNCATE command.
-
Exit the Cassandra CLI by running:
$ exit
If the TRUNCATE command fails, run the next command (nodetool clearsnapshot ), before attempting to run the TRUNCATE command and the nodetool command again. |
Clear snapshots on all TSN nodes
-
SSH as the primary user (
sentinel
) into each of the TSNs sequentially and run the command:
$ nodetool clearsnapshot opencloud_thirdparty_reg --all
Verify that the truncation has been successful
-
Run the command:
$ df -h
-
Verify that for the following two rows in the output, the
<use>%
values are less than 50%:
Filesystem Size Used Avail Use% Mounted on
[...]
/dev/sda3 <size> <used> <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size> <used> <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support. |
-
Exit the TSN by running:
$ exit
Upload the configuration
The new configuration written during the pre-maintenance window steps, is required to change the schema that is in use.
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls --vm-version-source this-rvtconfig
Verify that the configuration has uploaded successfully
-
Verify that the output after the command has completed running includes the following sentence:
Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>
-
Exit the SIMPL VM by running:
$ exit
-
Use SSH as the primary user (
sentinel
) to access each of the MMTs. -
From the home directory, run the command:
$ report-initconf status
until the following is displayed in the output:
status=vm_converged
If after 15 minutes, the status of the VMs is not converged, proceed to Rollback. |
Test the new tables
-
Perform a test call to force a registration.
If the test call does not succeed, proceed to Rollback. |
Exit the maintenance window
Take the deployment out of maintenance window mode.
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>
-
verify the command output includes the following:
Maintenance window has been terminated. The VMs will resume running scheduled tasks as per their configured schedules.
Rollback
This section describes the steps for rolling back the change of primary key for MMT nodes. These steps are expected to take 30 minutes to complete.
Truncate the registrations_v2
and assocuris_v2
tables on Cassandra
The existing registrations_v2
and assocuris_v2
tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.
-
Use SSH to access the TSN as the primary user (
sentinel
). -
Start the Cassandra CLI by running the command:
$ cqlsh
-
Truncate the tables by running the command:
TRUNCATE opencloud_thirdparty_reg.REGISTRATIONDATA_V2; TRUNCATE opencloud_thirdparty_reg.ASSOCURIS_V2;
-
Verify that there are no messages printed to the console after running the
TRUNCATE
command. -
Exit the Cassandra CLI by running:
$ exit
If the TRUNCATE command fails, run the next command (nodetool clearsnapshot ), before attempting to run the TRUNCATE command and the nodetool command again. |
Clear snapshots on all TSN nodes
-
SSH as the primary user (
sentinel
) into each of the TSNs sequentially and run the command:
$ nodetool clearsnapshot opencloud_thirdparty_reg --all
Verify that the truncation has been successful
-
Run the command:
$ df -h
-
Verify that for the following two rows in the output, the
<use>%
values are less than 50%:
Filesystem Size Used Avail Use% Mounted on
[...]
/dev/sda3 <size> <used> <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size> <used> <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support. |
-
Exit the TSN by running:
$ exit
Upload the config
The backup config, which was taken during the pre-maintenance window steps, is required to change the schema that is in use.
-
Use SSH to access the SIMPL VM.
-
Copy the backup over
~/yamls
:cp -f ~/yamls-rollback/* ~/yamls/
-
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls --vm-version-source this-rvtconfig
Verify that the configuration has uploaded successfully
-
Verify that the output after the command has completed running includes the following sentence:
Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>
-
Exit the SIMPL VM by running:
$ exit
-
Use SSH as the primary user (
sentinel
) to access each of the MMTs. -
From the home directory, run the command:
$ report-initconf status
until the following is displayed in the output:
status=vm_converged
If after 15 minutes, the status of the VMs is not converged, contact Metaswitch technical support. |
Test the rollback
-
Perform a test call to force a registration.
If the test call does not succeed, contact Metaswitch technical support. |
Exit the maintenance window
Take the deployment out of maintenance window mode.
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path> $ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>
-
verify the command output includes the following:
Maintenance window has been terminated. The VMs will resume running scheduled tasks as per their configured schedules.
Change the schema for SMO nodes
The default schema uses the first-party REGISTER
callID
field as a part of the primary key. RFC 3261 Section 10.2 states that User Equipment (UE) should use the same callID
for the duration of the time it is registered. As the specification allows UE to use different CALLID
values for the same registration, this requires proper handling.
As the callID
is a part of the primary key, one row is used per unique callID
, which may result in multiple rows representing the same logical registration. In cases where a significant proportion of UE on the network do not reuse their callID
significantly more disk space is required to hold registration records. This contributes to the disk space for registration records being unpredictable under some circumstances.
The alternate schema uses the IMS private identity (hereafter deviceID
) in place of callID
in the schema. Per 3gpp 24.229 specification this must be set on all REGISTER
attempts. As the deviceID
does not change from registration attempt to registration attempt, the size of the database is more predictable.
See Data Schema for details of the Registrar schemas.
The following sections provide instructions for switching to the alternate schema on the SMO node. The required tables already exist on the TSN. You will change SMO configuration to use the alternate tables.
Impacts
During the change of the schema, the system may be affected as follows:
-
There will be an increase in the number of HSS queries. This is because the third-party registrations serve as a cache, and in their absence, devices can only be verified through queries to the HSS. After the procedure is complete, the number of HSS queries should gradually return to the pre-maintenance window level.
The speed at which the number of HSS queries returns to normal depends on the registration validity period. It can be very quick or fairly slow. It is anticipated to be very quick on average. -
When you run the
TRUNCATE
command, disk usage will not drop immediately. Disk usage will only drop after thenodetool clearsnapshot
command is run. This is because theTRUNCATE
command moves the data to a snapshot instead of deleting. The snapshot is only removed when thenodetool clearsnapshot
command is run.
If you encounter any impacts that are not listed, contact Metaswitch technical support. |
Pre-maintenance window steps for changing the Cassandra schema
Before entering the maintenance window you need to take some steps to get prepared. Performing these beforehand ensures that changing the Cassandra schema is a smooth exercise. Some steps can be done well in advance. Other steps need to bedone immediately before entering the maintenance window, as they are a final check to ensure everything is ready for the change.
Pre-maintenance window steps that can be done in advance
Verify the deployed SMO version
Make sure that the SMO VMs have already been upgraded to at least the maintenance version of RVT 4.1-1-1.0.0. The configuration changes that are being made will only work if the SMO is at least this version.
Create file with commands to run
There are commands that will need to be run in preparation for and during the Cassandra schema change. These commands requires specific arguments that need to be prepared beforehand. Creating a file of commands ready to be copy/pasted and run beforehand ensures smooth running of the steps. Placeholder values are of the form <…>
. <a|b>
means a choice of either a or b. For example, mmt-<gsm|cdma>
means mmt-gsm
or mmt-cdma
.
The file of commands can be stored anywhere that is convenient.
Many of the commands are rvtconfig
commands. Further information can be found in the rvtconfig reference.
Determine the following arguments:
-
tsn-mgmt-address
- The management IP address of at least one TSN node. The TSN management IP addresses can be found in theTSN
section of the SDF. If multiple addresses are used, they should be formatted as-c <address1> <address2>…
. -
deployment-id
- This can be found in the SDF under the keydeployment-id
. -
site-id
- The site-id of the site you are changing config for. This can be found in the SDF assite-id
. -
group-id
- The group-id of the SMO vnf,RVT-smo.<site-id>
. -
sdf-path
- The path to the SDF file on your SIMPL VM. -
rvtconfig-path
- The path to the rvtconfig on your SIMPL VM. This is expected to be something like:/home/admin/.local/share/csar/smo/<version>/resources
If Cassandra authentication is enabled, then two additional arguments will be required for every rvtconfig
command.
-
cds-username
- Username to authenticate with Cassandra. You can find it in the SDF undercassandra-username
. -
cds-password-secret-name
- Password identifier to authenticate with Cassandra. You can find it in the SDF undercassandra-password-id
.
They are added in the format --cds-username <cds-username> --cds-password-secret-name <cds-password-secret-name>
as the last two arguments to every rvtconfig
command.
Create a text file containing all the subsequent commands with substitutions completed.
Take a backup of the current configuration
In case you need to roll back later, prepare a copy of the current configuration. Otherwise, you may have to recreate your configuration files manually.
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path> $ rvtconfig dump-config -c <tsn-mgmt-address> -d <deployment-id> --group-id <group-id> --vm-version-source this-rvtconfig --output-dir ~/yamls-rollback
--output-dir
is the output directory for thervtconfig dump-config
command. Any easily accessible directory can be chosen and the command will create the directory if it does not exist. The recommendation is to maintain~/yamls-rollback
, as this value is referenced in the rollback procedure. In the event that a different folder is used, substitute that value for~/yamls-rollback
in the rollback procedure.
Create the new configuration file
The new configuration needs to be written for upload. The configuration points to change are located in the smo-overrides.yaml
file in ~/yamls
. Create the file if it does not exist.
SMO configuration change
Contact Metaswitch technical support for assistance with writing the new configuration. |
Yaml uses semantic whitespace. The resulting file must be valid yaml that rvtconfig can accept. |
If smo-overrides.yaml
does not exist, create it with the following content:
rhino-config:rhino-configuration:
namespaces:
- name: ''
profile-tables:
- name: RegistrarConfigurationTable
profiles:
- name: 'Metaswitch::::'
present: true
attributes:
- name: usePrivateIdAsRegistrarDataPrimaryKey
content: 'true'
If smo-overrides.yaml
exists and does not contain the string RegistrarConfigurationTable
, insert the following contents immediately below the line profile-tables:
:
- name: RegistrarConfigurationTable
profiles:
- name: 'Metaswitch::::'
present: true
attributes:
- name: usePrivateIdAsRegistrarDataPrimaryKey
content: 'true'
If smo-overrides.yaml
exists and contains the string RegistrarConfigurationTable
, insert the following into the attributes key of RegistrarConfigurationTable
:
- name: usePrivateIdAsRegistrarDataPrimaryKey
content: 'true'
Pre-maintenance window steps to be done immediately prior to entering the maintenance window
Before performing these steps, ensure that you have: |
-
A file with all the commands that need to be run for changing the Cassandra schema. The commands will have all the required arguments substituted.
-
Two sets of
.yaml
configuration files - the new configuration (~/yamls
), the current config (~/yamls-rollback
). -
Verified that the deployment consists of the right version of the VMs.
Compare live configuration on SMOs with configuration on SIMPL
-
Use SSH to access the SIMPL VM.
-
Verify that the directory
/tmp/checkdiff
does not exist. If the directory does exist, remove it. -
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig compare-config -c <tsn-mgmt-address> -t smo -i ~/yamls-rollback --output-dir /tmp/checkdiff --vm-version-source this-rvtconfig
--output-dir is the output directory for the rvtconfig compare-config command. The command will create the directory if it does not exist and will return an error if the directory does exist. |
-
Verify that the command completes with:
No differences found in yaml files.
Uploading this configuration will have no effect unless secrets, certificates or licenses have changed, or --reload-resource-adaptors is specified.
If the output returned does not include "No differences found in yaml files.", contact Metaswitch technical support.
Perform health checks on SMOs in the deployment
The deployment needs to be in a healthy state. To verify that the deployment is healthy, run the following tests.
Enter the maintenance window
If all the healthchecks above pass, start a maintenance window and then run through the steps for changing the Cassandra schema. To enter a maintenance window:
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig enter-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>
Procedure
This section describes the steps for changing the primary key for SMO nodes. These steps are expected to take 30 minutes to complete.
Before beginning these steps, ensure that the placeholder values in commands listed here have been substituted with the required values. Placeholder values are of the form <…> . |
Truncate the registrations
and assocuris
tables on Cassandra
The existing registrations
and assocuris
tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.
-
Use SSH to access the TSN as the primary user (
sentinel
). -
Start the Cassandra CLI by running the command:
$ cqlsh
-
Truncate the tables by running the command:
TRUNCATE opencloud_ipsmgw_thirdparty_reg.REGISTRATIONDATA;
TRUNCATE opencloud_ipsmgw_thirdparty_reg.ASSOCURIS;
-
Verify that there are no messages printed to the console after running the TRUNCATE command.
-
Exit the Cassandra CLI by running:
$ exit
If the TRUNCATE command fails, run the next command (nodetool clearsnapshot ), before attempting to run the TRUNCATE command and the nodetool command again. |
Clear snapshots on all TSN nodes
-
SSH as the primary user (
sentinel
) into each of the TSNs sequentially and run the command:
$ nodetool clearsnapshot opencloud_ipsmgw_thirdparty_reg --all
Verify that the truncation has been successful
-
Run the command:
$ df -h
-
Verify that for the following two rows in the output, the
<use>%
values are less than 50%:
Filesystem Size Used Avail Use% Mounted on
[...]
/dev/sda3 <size> <used> <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size> <used> <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support. |
-
Exit the TSN by running:
$ exit
Upload the configuration
The new configuration written during the pre-maintenance window steps, is required to change the schema that is in use.
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t smo -i ~/yamls --vm-version-source this-rvtconfig
Verify that the configuration has uploaded successfully
-
Verify that the output after the command has completed running includes the following sentence:
Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>
-
Exit the SIMPL VM by running:
$ exit
-
Use SSH as the primary user (
sentinel
) to access each of the SMOs. -
From the home directory, run the command:
$ report-initconf status
until the following is displayed in the output:
status=vm_converged
If after 15 minutes, the status of the VMs is not converged, proceed to Rollback. |
Test the new tables
-
Perform a test SMS to force a registration.
If the test SMS does not succeed, proceed to Rollback. |
Exit the maintenance window
Take the deployment out of maintenance window mode.
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>
-
verify the command output includes the following:
Maintenance window has been terminated. The VMs will resume running scheduled tasks as per their configured schedules.
Rollback
This section describes the steps for rolling back the change of primary key for SMO nodes. These steps are expected to take 30 minutes to complete.
Truncate the registrations_v2
and assocuris_v2
tables on Cassandra
The existing registrations_v2
and assocuris_v2
tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.
-
Use SSH to access the TSN as the primary user (
sentinel
). -
Start the Cassandra CLI by running the command:
$ cqlsh
-
Truncate the tables by running the command:
TRUNCATE opencloud_ipsmgw_thirdparty_reg.REGISTRATIONDATA_V2; TRUNCATE opencloud_ipsmgw_thirdparty_reg.ASSOCURIS_V2;
-
Verify that there are no messages printed to the console after running the
TRUNCATE
command. -
Exit the Cassandra CLI by running:
$ exit
If the TRUNCATE command fails, run the next command (nodetool clearsnapshot ), before attempting to run the TRUNCATE command and the nodetool command again. |
Clear snapshots on all TSN nodes
-
SSH as the primary user (
sentinel
) into each of the TSNs sequentially and run the command:
$ nodetool clearsnapshot opencloud_ipsmgw_thirdparty_reg --all
Verify that the truncation has been successful
-
Run the command:
$ df -h
-
Verify that for the following two rows in the output, the
<use>%
values are less than 50%:
Filesystem Size Used Avail Use% Mounted on
[...]
/dev/sda3 <size> <used> <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size> <used> <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support. |
-
Exit the TSN by running:
$ exit
Upload the config
The backup config, which was taken during the pre-maintenance window steps, is required to change the schema that is in use.
-
Use SSH to access the SIMPL VM.
-
Copy the backup over
~/yamls
:cp -f ~/yamls-rollback/* ~/yamls/
-
Run the command:
$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t smo -i ~/yamls --vm-version-source this-rvtconfig
Verify that the configuration has uploaded successfully
-
Verify that the output after the command has completed running includes the following sentence:
Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>
-
Exit the SIMPL VM by running:
$ exit
-
Use SSH as the primary user (
sentinel
) to access each of the SMOs. -
From the home directory, run the command:
$ report-initconf status
until the following is displayed in the output:
status=vm_converged
If after 15 minutes, the status of the VMs is not converged, contact Metaswitch technical support. |
Test the rollback
-
Perform a test SMS to force a registration.
If the test SMS does not succeed, contact Metaswitch technical support. |
Exit the maintenance window
Take the deployment out of maintenance window mode.
-
Use SSH to access the SIMPL VM.
-
Run the command:
$ cd <rvtconfig-path> $ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>
-
verify the command output includes the following:
Maintenance window has been terminated. The VMs will resume running scheduled tasks as per their configured schedules.
RVT service centralization and continuity configuration
This section describes how to set up the service centralization and continuity (SCC) services.
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:
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.
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
andparallel
use theps-only
behavior -
cs-ps
uses thecs-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
andPath
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.
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 acounter
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
, orTLDN
. -
❏ The source for generating potential PS routes; one of:
IMS_PUBLIC_IDENTITY
,SIP_INSTANCE
, orPATH_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
, orMSISDN_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
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
Ensure that HLR integration has been configured. |
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
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
Prevent T-CSI 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-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
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 SIPDiversion
header, or -
false
to indicate that the limit has been reached using the number ofDiversion
headers present.
-
-
Set
cs-domain-diversion-limit
to the maximum number of times you want to indicate that call forwarding was allowed (note that no matter what this setting is, T-ADS will still indicate that the limit has been reached).
Related section: Interaction with call forwarding
Allow call forwarding services in the CS network
In the tads
section, remove or comment out the entire suppress-cs-domain-call-diversion
section.
# suppress-cs-domain-call-diversion:
# use-diversion-counter-parameter: true
# cs-domain-diversion-limit: 1
Related section: Interaction with call forwarding
Setting up PS routing behaviour
I want to…
Route the PS attempt to the subscriber’s IMS public identity
In the tads
section, set tads-identity-for-terminating-device
:
tads-identity-for-terminating-device: IMS_PUBLIC_IDENTITY
Related section: PS routing
Route PS attempts to the SIP instance of the terminating device(s)
In the tads
section, set tads-identity-for-terminating-device
:
tads-identity-for-terminating-device: SIP_INSTANCE
Related section: PS routing
Route PS attempts to the SIP instance path of the terminating device(s)
In the tads
section, set tads-identity-for-terminating-device
:
tads-identity-for-terminating-device: PATH_FROM_SIP_INSTANCE
Related section: PS routing
Check that a subscriber has support for Voice Over PS before attempting to route over the PS network
Ensure that HSS integration has been configured. |
In the tads
section, ensure that the voice-over-ps-support
section is present and not commented out.
voice-over-ps-support:
request-user-identity-type: IMPU
Set which subscriber identity to use when querying the HSS for the voice over PS support information. See request-user-identity-type
for the list of options.
Related section: Route validation and voice over PS support
Skip the check that the subscriber has voice over PS support before attempting to route the call over the PS network
In the tads
section, remove or comment out the entire voice-over-ps-support
section.
# voice-over-ps-support:
# request-user-identity-type: IMPU
Related section: Route validation and voice over PS support
Setting up route selection behavior
I want to…
Change the SIP response code used to end the call if no valid route to the called party can be found
In this example the call will be ended with a 410 Gone
response.
In the tads
section, set end-session-error-code
:
end-session-error-code: 410
End all companion device connection attempts if any one of them returns a 486 Busy response
In the tads
, on-parallel-routing
section, set release-all-legs-on-busy
:
release-all-legs-on-busy: true
Related section: Deciding on a route in parallel routing mode
Change the maximum time to wait to get a final response from any parallel connection attempt
This example sets the maximum wait time to 15 seconds.
In the tads
, on-parallel-routing
section, set parallel-timer-max-wait-milliseconds
to the desired value in milliseconds:
parallel-timer-max-wait-milliseconds: 15000
Related section: Deciding on a route in parallel routing mode
Try the next available route if a PS attempt results in a particular SIP response status code or codes
A 488 response will always cause the next available route to be attempted, and does not need to be included in this field. |
This example lists 408
, 480
, and 481
as the codes that should trigger the next routing attempt.
In the tads
, on-sequential-routing
section, set ps-fallback-response-codes
with the list of desired response codes:
ps-fallback-response-codes: [ 408, 480, 481 ]
Related section: Deciding on a route in sequential routing modes
Change the maximum time to wait for a response before trying the next route
This setting is only relevant when using a sequential routing mode and is subject to the provisional response condition described in Deciding on a route in sequential routing modes. |
In the tads
, on-sequential-routing
section, set tads-timer-max-wait-milliseconds
to the value in milliseconds:
tads-timer-max-wait-milliseconds: 5000
Access transfer
What it does
Access transfer is a Rhino VoLTE TAS SCC service that is responsible for managing the handover of a call from a packet switched (PS) network to a circuit switched (CS) network when a subscriber moves out of PS network coverage. It works by replacing the existing access leg (that is, the SIP leg between the Rhino VoLTE TAS and the served user) with a new one.
Access transfer is initiated on receipt of a new initial INVITE request that has a Request-URI which aligns with either the configured ATU-STI or STN-SR. Initially this request is not directly associated with the call it applies to, and initially may not even be processed by the same Rhino VoLTE TAS node that is handling the original call. Information in the new INVITE request is used to correlate it with the original call so that it can be injected into that call, where it is used to establish the new access leg.
Supported cases
The Rhino VoLTE TAS supports Single Radio Voice Call Continuity (SRVCC) for PS to CS transfer of sessions in the following cases:
-
a single active session with media anchored in the Access Transfer Gateway (eSRVCC)
-
a single active session with media not anchored in the Access Transfer Gateway (standard SRVCC)
-
a single alerting session (aSRVCC)
-
a single originating session in the pre-alerting state (bSRVCC).
If a device initiates access transfer while it has multiple sessions in progress (for example, if the subscriber has someone on hold while talking on another call), only the most recently active session will be transferred. All other sessions are treated as superfluous and are ended as part of the transfer procedure.
Enabling access transfer
Access transfer is not enabled through configuration. Instead, it is enabled per-call if both of the following requirements are met:
-
The served subscriber’s registration data indicates that their device has
UE-SRVCC-Capability
. -
The served subscriber has an assigned C-MSISDN in the HSS.
There are additional requirements for alerting and pre-alerting access transfer. These take the form of media feature tags in the SIP Contact
header from the subscriber. For the calling subscriber this head will be checked on the initial INVITE request, for the called subscriber the first SIP 18x
response will be checked. To enable alerting access transfer there must be a +g.3gpp.srvcc-alerting
tag, and for pre-alerting access transfer there must be a +g.3gpp.ps2cs-srvcc-orig-pre-alerting
tag. Note that pre-alerting access transfer is only applicable to the calling subscriber.
Access Transfer Control Function
Access Transfer Control Function (ATCF) is a signalling anchor that is used for eSRVCC procedures. It is responsible for initiating access transfer procedures in the Rhino VoLTE TAS by sending a INVITE request using the ATU-STI as the Request-URI
.
To determine where to send access transfer requests, the ATCF must know the ATU-STI to use for a given subscriber. The Rhino VoLTE TAS is responsible for notifying the ATCF of the ATU-STI, which it does by sending it in a SIP MESSAGE request when the subscriber registers with the network. The maximum time that the Rhino VoLTE TAS should wait for a response to the MESSAGE request can be configured in the atcf-update-timeout-milliseconds
field.
STN-SR and ATU-STI
The STN-SR (Session Transfer Number for SRVCC) and ATU-STI (Access Transfer Update - Session Transfer Identifier) serve the same purpose of identifying that an incoming request is for access transfer. The main difference between the two is that they are used to trigger different versions of the access transfer procedure.
The STN-SR is used for access transfer as defined in the Rel-8 3GPP specifications, where signalling is not anchored in the ATCF, therefore the Rhino VoLTE TAS receives the transfer request directly from the MSC (Mobile Switching Center, part of the CS core network). It takes the form of a number prefix on the Request-URI
of the incoming access transfer request. The only requirement for picking an STN-SR is that it must cause messages to be delivered to the Rhino VoLTE TAS. When a subscriber registers with the network, the Rhino VoLTE TAS will update their STN-SR in the HSS to match what is configured here.
The ATU-STI is used for access transfer, as defined in the Rel-10 3GPP specifications, where signalling is anchored in the ATCF, therefore the transfer request comes from the ATCF. It is a fixed URI that is used as the Request-URI
on access transfer requests. As the Rhino VoLTE TAS tells the ATCF what ATU-STI to use for a subscriber, the only requirement for its value is that it resolves to the Rhino VoLTE TAS.
Configuration
The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to access transfer in the sentinel-volte/scc/service-continuity
section.
What you need
-
❏ The STN-SR that will trigger Rel-8 access transfer.
-
❏ Optionally, a custom timeout period to wait for a response from the ATCF when updating the ATU-STI for a subscriber.
Setting up access transfer
I want to…
Set the STN-SR for triggering Rel-8 access transfer
In the service-continuity
section, set stn-sr
with the desired number prefix:
stn-sr: "123456"
Related section: STN-SR and ATU-STI
Change how long to wait for the ATCF to respond to a request to update a subscriber’s ATU-STI
In the service-continuity
section, set atcf-update-timeout-milliseconds
with the desired time period, in milliseconds:
atcf-update-timeout-milliseconds: 5000
Related section: Access Transfer Control Function
Reorigination
What it does
Reorigination enables CS calls to be processed in the SCC-AS. SS7 triggers received by the Rhino VoLTE TAS are forwarded to a number within a pre-defined range, which causes the call to be rerouted into the IMS. The SCC-AS then acts as a B2BUA between the I-CSCF and the subscriber’s assigned S-CSCF.
Routing through the I-CSCF
The SCC-AS will add a CSCF address to the route
header of the outgoing INVITE
message. This address can be either the calling party’s S-CSCF address retrieved from the HSS, or it can be the I-CSCF address configured in i-cscf-uri
.
Anti-fraud measures
To guard against fraud, the P-Asserted-Identity
from the incoming INVITE
can be compared to the normalized calling party number from the InitialDP. If they do not match, the request is rejected with a 403 response.
The P-Visited-Network-Information header
The SCC-AS will add a P-Visited-Network-Information
header to the outgoing INVITE
. It is recommended that this is set according to IR.65, section 6.2.1, that is, that the format for this is epc.ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org
if the version followed is 12 or less, or ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org
if a later version is used. The values of <MCC>
and <MNC>
are extracted from the triggering SS7 message.
The IP Multimedia Routing Number pool
The number used as the interchange between the SS7 and IP networks (the IMRN) must belong to a pre-allocated, reserved range of values. These numbers must be reserved to prevent overlap with numbers in use by subscribers. The pre-allocated range must be configured within the Rhino VoLTE TAS.
The pool of values does not need to be overly large, as values will only be reserved for the time between the receipt of the SS7 trigger and the processing of the INVITE
. As an approximation, with normal error rates and a 20 ms interval between IMRN reservation (on the SS7 end) and IMRN return-to-pool, a range of 1000 values will accommodate 50,000 calls per second. Adjust the pool sizings to meet network requirements accordingly.
The simple-imrn-pool
defines the digit string, with the cdma-imrn-formation
and gsm-imrn-formation
sections defining the protocol-specific digit formatting details.
Bypass reorigination for unregistered subscribers
If a subscriber is not registered in the IMS network, reorigination from SS7 to IMS can be skipped to avoid unnecessary processing. This bypass can be enabled for all unregistered subscribers, or for only non-roaming subscribers (to support terminating charging of roaming subscribers through the IMS).
Configuration
The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to reorigination in the sentinel-volte/scc/service-centralisation
section.
What you need
-
❏ The expected format of the
P-Visited-Network-Information
header. -
❏ The range of numbers available to be used as the IMRN.
-
❏ The expected format of the IMRN.
Setting up reorigination
I want to…
Use the configured I-CSCF address and prevent the HSS from being queried
To include the configured I-CSCF address in the route
header of the outgoing INVITE
, in the service-centralisation
section, set use-direct-icscf-routing
:
use-direct-icscf-routing: true
Related section: Routing through the I-CSCF
Set the format of the PVNI header to the later standard
To set the P-Visited-Network-Information
header template to the later format, in the service-centralisation
section, set generated-pvni-template
:
generated-pvni-template: "ims.mnc<MNC>.mcc<MCC>.3gppnetwork.org"
Related section: The P-Visited-Network-Information header
Reject messages sent to an IMRN where the P-Asserted-Identity does not match the recorded calling party digits
To enable comparing the P-Asserted-Identity
header to the normalized calling party number, in the service-centralisation
section, set police-originating-requests
:
police-originating-requests: true
Related section: Anti-fraud measures
Set a 1000 element IMRN range
To create a 1000 element range with 10-digit numbers from 5550000000 to 5550000999, in the service-centralisation
section, set the values in simple-imrn-pool
as follows:
simple-imrn-pool:
minimum-correlation-id: 5550000000
maximum-correlation-id: 5550000999
number-of-digits-in-correlation-id: 10
Related section: The IP Multimedia Routing Number pool
Configure the CDMA responses sent in error conditions
In CDMA networks, the responses sent in error conditions are configured in the scc-cdma-actions
section.
scc-cdma-actions:
action-on-unsupported-trigger: accessDeniedReason_terminationDenied
action-on-failed-to-allocate-routing-number: accessDeniedReason_busy
default-failure-action: accessDeniedReason_serviceDenied
To configure the error response:
-
when an invalid SS7 trigger is received, set the
action-on-unsupported-trigger
-
when an internal error occurred and the Rhino VoLTE TAS could not generate an IMRN, set the
action-on-failed-to-allocate-routing-number
-
on other errors, set the
default-failure-action
.
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
routing-to-internal-network-number-allowed
astrue
. -
set
nature
asNATIONAL
-
set
numbering-plan
asISDN
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:
-
imrn-type of digits
asDIALED_OR_CALLED_PARTY_NUMBER
-
imrn-nature of number
asINTERNATIONAL
-
imrn-numbering plan
asTELEPHONY
.
Bypass terminating reorigination for unregistered subscribers on GSM networks
In GSM networks, the terminating reorigination trigger can be bypassed for subscribers that are not registered in the IMS.
To enable this, in the scc-gsm-service-centralisation
section, set bypass-terminating-forwarding-if-served-user-not-ims-registered
:
bypass-terminating-forwarding-if-served-user-not-ims-registered: true
Bypass terminating reorigination for unregistered, non-roaming subscribers on GSM networks
In GSM networks, the terminating reorigination bypass can be enabled for all unregistered subscribers, or for only non-roaming subscribers.
To bypass reorigination for unregistered subscribers while still reoriginating roaming traffic, in the scc-gsm-service-centralisation
section, set bypass-terminating-forwarding-if-served-user-not-ims-registered
and always-term-reoriginate-if-served-user-is-roaming
:
This will result in only unregistered, non-roaming subscribers bypassing reorigination. Registered subscribers and roaming subscribers will still reoriginate to the IMS.
bypass-terminating-forwarding-if-served-user-not-ims-registered: true
always-term-reoriginate-if-served-user-is-roaming: true
Bypass reorigination for unregistered subscribers on CDMA networks
In CDMA networks, to bypass reorigination for subscribers that are not registered in the IMS, in the scc-cdma-service-centralisation
section, set bypass-forwarding-if-served-user-not-ims-registered
:
bypass-forwarding-if-served-user-not-ims-registered: true
RVT MMTel configuration
This section describes how to configure MultiMedia Telephony (MMTel) services.
- Announcements
- Announcements on call failure
- PSAP callback
- Dial plan enforcement (DPE)
- MMTel privacy settings
- Conference (CONF)
- Call barring
- Communication Waiting (CW)
- Communication Hold (HOLD)
- Communications Diversion (CDIV)
- Voicemail forwarding
- Companion device
- Vertical service codes (VSC)
- International Call Management
- Location based dialing (LBD)
- Explicit Communication Transfer (ECT)
- Flexible Alerting (FA)
- Session transfer to own device
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.
Configuration
The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to announcements in the sentinel-volte/mmtel/announcement
section.
What you need
-
❏ The SIP: or Tel: URI of the media server (MRF) that plays the announcements.
-
❏ Details of the announcements available on that media server:
-
❏ their URI
-
❏ their mime type
-
❏ which locales are available for each announcement.
-
-
❏ Details of how those announcements will be used:
-
❏ Whether to repeat the announcement:
-
❏ and if so, the maximum number of times to repeat
-
❏ and the delay between repetitions.
-
-
❏ Whether or not the announcement can be interrupt by user actions.
-
❏ Whether or not the media stream should be forced to be one way between the MRF and the user during the announcement.
-
❏ Whether to suspend charging while the announcement is playing.
-
❏ Whether to end the call if the announcement cannot be played.
-
Setting up the MRF connection
I want to…
Specify the address of the MRF to use for announcements
In the mmtel
, announcement
section, set announcements-media-server-uri
.
announcements-media-server-uri: sip:annc-audio@mrf-announcements:5260;lr;transport=tcp
Change the timeout when signaling the MRF
The default timeout is 1000 ms.
To set a new value, in the mmtel
, announcement
section, ensure that the announcements-no-response-timeout-milliseconds
parameter is present and not commented out. Set the desired value, in milliseconds.
announcements-no-response-timeout-milliseconds: 1500
Setting up each announcement
I want to…
Repeat an announcement indefinitely until interrupted by user actions
For the desired announcement in the mmtel
, announcement
section, announcements
list:
- id: 20
description: "MMTel - Outgoing Call Barring"
announcement-url: "file://mmtel_ocb.3gp"
duration-milliseconds: 13000
repeat: -1
delay-milliseconds: 1000
mimetype: "audio/3gpp"
interruptable: true
end-session-on-failure: false
enforce-one-way-media: false
suspend-charging: false
-
Set the
repeat
value to-1
, which will send arepeat=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
totrue
.
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.
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
-
Ensure that
error-code-announcements
list is present and not commented out. -
Add a new announcement. Set the values to the following:
-
error-code
to the SIP response code to play the announcement for. -
announcement-id
to theid
of the announcement to play. -
end-call-with-487-response
tofalse
to end the call with the 404 response.
-
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
-
Ensure that
default-error-code-announcement
is present and not commented out. -
Set
announcement-id
to theid
of the announcement to play. -
Set
end-call-with-487-response
to:-
false
to end the call with the original response, or -
true
to force all other error codes to replaced with a487
response.
-
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
-
Ensure that
error-code-announcements
list is present and not commented out. -
Add a new announcement. Set the values to the following:
-
error-code
to488
. -
announcement-id
to theid
of the announcement to play. -
end-call-with-487-response
totrue
to end the call with a487
response.
-
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
-
Ensure that
default-error-code-announcement
exists and plays the desired announcement, as above. -
Ensure that
error-code-announcements
list exists and is not commented out. -
Add an entry for the
error-code
. -
Remove or comment out its
announcement-id
. -
Add
disable-announcement
, with the value set totrue
.
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.
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 the087
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.
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.
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.
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.
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.
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 |
|
N/A |
Temporary Mode Default Action |
N/A |
For when temporary mode is active:
|
What is restricted by OIR on a subscriber’s outgoing requests |
||
Presentation Restriction |
|
|
User Policy |
|
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 thefrom
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.
Display name | Action |
---|---|
Set Dialled Caller ID Restriction Type |
Used to override the OIR service’s There are 3 valid values: * * * |
For more information, see Vertical service codes.
Setting up OIR
I want to…
Restrict only network defined user identity information for OIR subscribers
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
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
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 theP-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
orPrivacy
header is removed from the originating user’s request -
if
anonymize-from-header
is set true, thefrom
header is anonymized
Interactions with other services
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.
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 theselector
element or of thevideolayout
element. -
❏ The maximum number of participants in the call.
-
❏ Whether video conferences are allowed.
Setting up conferencing
Ensure that conferencing media server integration has been configured. |
The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to conferencing in the sentinel-volte/mmtel/conferencing
section.
I want to…
Set the URI of the Media Resource Function
In the conferencing
section, set conference-mrf-uri
to the URI:
conference-mrf-uri: sip:mrf@mrfhost.example.com:5060
Route messages to the MRF via the IMS
In the conferencing
section, set route-to-mrf-via-ims
to true
:
route-to-mrf-via-ims: true
Set the MSML schema vendor name
In the conferencing
section, set msml-vendor
to the vendor name:
msml-vendor: Dialogic
Attach the MSML root element as a child of videolayout
In the conferencing
section, set root-on-selector
to false
:
root-on-selector: false
Add a conference PSI alias
In the conferencing
section, add the conference PSI alias to the list of conference-factory-psi-aliases
:
conference-factory-psi-aliases:
- sip:conf-factory@ims.mnc<MNC>.mcc<MCC>.com
Set the maximum number of participants in a conference
In the conferencing
section, set maximum-participants
:
maximum-participants: 4
Allow video-conferencing
In the conferencing
section, set allow-video-conference-calls
to true
:
allow-video-conference-calls: true
Set the default expiry time on conference subscriptions
In the subscription
section, set default-subscription-expiry-seconds
:
default-subcription-expiry-seconds: 1800
Set the minimum allowed subscription time
In the subscription
section, set min-subscription-expiry-seconds
:
min-subscription-expiry-seconds: 10
Notify participants about subscription changes every 10 seconds
In the subscription
section, set polling-interval-seconds
:
polling-interval-seconds: 10
Call barring
What it does
Call barring is a set of MMTel services that conditionally bar calls using a combination of system-wide and per subscriber rules.
-
Incoming Call Barring (ICB) bars incoming calls based on per subscriber rules written using common-policy schema (for example, a subscriber may set up Do Not Disturb, to bar all calls).
-
Anonymous Call Rejection (ACR) bars incoming calls from anonymous callers.
-
-
Outgoing Call Barring (OCB) bars outgoing calls based on per subscriber rules written using common-policy schema.
-
Operator Determined Barring (ODB) is a fixed set of barring conditions, each enabled or not per subscriber.
-
Operator Specific Barring (OSB) is a subset of ODB containing four rules each enabled or not per subscriber, but where the system-wide conditions and actions are configured using common-policy schema. Additionally, the action when these rules trigger may be augmented to retarget the call, with an ability to disable charging, and/or use a rule-specific announcement in this case.
-
Prefix barring uses dialed number rules to either explicitly allow or bar an outgoing call, or to effectively force a match condition for some of the ODB conditions, including the OSB rules.
-
Announcements may be set to be played to the caller when a call is barred.
Interactions with other services
Communications Diversion (CDIV)
Call barring for incoming calls is applied before MMTel CDIV, so any barred incoming call will not be subject to forwarding.
However, an inbound call which is not barred but then forwarded will have outbound barring processing applied to the outbound forwarded call.
Vertical service codes with XCAP data update
Vertical service codes in combination with XCAP data update may change subscriber data, affecting subscriber ICB and OCB rules, and enabling or disabling ODB rules for a subscriber.
ODB rules may prevent changes to subscriber data, both via vertical service codes with XCAP data update, and when using XCAP directly from user equipment.
Configuration
The example for sentinel-volte-gsm-config.yaml and example for sentinel-volte-cdma-config.yaml show example configuration relevant to call barring in the sentinel-volte/mmtel/communication-barring
section.
What you need
-
❏ Whether the system should process or ignore international and international-exHC barring rules based on the reliability of determining that an incoming call is international.
-
❏ The ID of an optional announcement to play when an incoming call is barred due to an anonymous caller.
-
❏ The ID of an optional announcement to play when an incoming call is barred otherwise.
-
❏ The ID of an optional announcement to play when an outgoing call is barred.
-
❏ For up to four operator specific barring rules:
-
❏ The common policy ruleset which defines the conditions and action for the rule.
-
❏ Whether to retarget the call and if so:
-
❏ the URL target
-
❏ the ID of an optional announcement to play
-
❏ whether to disable charging.
-
-
Setting up announcements
Call barring configuration only needs the announcement ID of the announcements that should be played. The details of those announcements should be configured beforehand. For details about how to do this, see Announcements.
Setting up call barring
I want to…
Enable ODB
In the hss-queries-enabled
section, set odb
to true
:
odb: true
Disable ODB
In the hss-queries-enabled
section, set odb
to false
:
odb: false
Setting up incoming call barring
I want to…
Use the same announcement for all incoming barred calls
In the incoming-communication-barring
, announcement
section, set the same announcement ID for both announcements:
announcement:
announcement-id: 21
anonymous-call-rejection-announcement-id: 21
Use a different announcement for barred incoming anonymous calls
In the incoming-communication-barring
, announcement
section, set separate announcement IDs for the two announcements:
announcement:
announcement-id: 21
anonymous-call-rejection-announcement-id: 22
For barred incoming calls, only play an announcement when it is anonymously barred
In the incoming-communication-barring
, announcement
section, remove or comment out the announcement-id
.
announcement:
# announcement-id: 21
anonymous-call-rejection-announcement-id: 22
For barred incoming calls, only play an announcement when it is not anonymously barred
In the incoming-communication-barring
, announcement
section, remove or comment out the anonymous-call-rejection-announcement-id
.
announcement:
announcement-id: 21
# anonymous-call-rejection-announcement-id: 22
Enable evaluation of incoming international barring rules
In the incoming-communication-barring
section, set international-rules-active
to true
.
international-rules-active: true
Setting up outbound call barring
I want to…
Play an announcement for barred outgoing calls
In the outgoing-communication-barring
, announcement
section, set the announcement-id
:
announcement:
announcement-id: 20
Not play an announcement for barred outgoing calls
In the outgoing-communication-barring
section, delete or comment out the whole announcement
section.
# announcement:
# announcement-id: 20
Bar a suspended subscriber from making any calls, redirecting them to a specific number
-
Ensure ODB is enabled. See Enable ODB above.
-
Choose an OSB rule number to use.
(considering what types are spare and the desired priority of this and existing rules)
-
Ensure this OSB rule is disabled for all subscribers.
out of scope of this document
-
Set the OSB rule to:
-
bar all outbound calls
-
retarget any outbound call to the call center
-
optionally set up a specific announcement to play to the subscriber before retargeting the call
-
disable online charging for the call.
-
-
In the
operator-communication-barring
section, for the selected rule, underoperator-barring-rules
, add the following (this example for type1 OSB rule):
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).
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.
-
If it is not already present, add an
announcement
section directly undercommunication-waiting
.
communication-waiting:
announcement:
-
In the
announcement
section, set theannouncement-id
to the ID for the desired 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.
Parameter | Config field | Description |
---|---|---|
AS |
Sets the bandwidth available for application specific data. It is safe to set this to 0. |
|
RS |
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 |
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.
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 ( |
FULL_HOLD |
The media streams to the holding party are put on a two-way hold for the duration of the announcement. |
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.
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
-
If it is not already present, add an
announcement
section in thecommunication-hold
section.
communication-hold: