The default schema uses the first-party REGISTER callID field as a part of the primary key. RFC 3261 Section 10.2 states that User Equipment (UE) should use the same callID for the duration of the time it is registered. As the specification allows UE to use different CALLID values for the same registration, this requires proper handling.

As the callID is a part of the primary key, one row is used per unique callID, which may result in multiple rows representing the same logical registration. In cases where a significant proportion of UE on the network do not reuse their callID significantly more disk space is required to hold registration records. This contributes to the disk space for registration records being unpredictable under some circumstances.

The alternate schema uses the IMS private identity (hereafter deviceID) in place of callID in the schema. Per 3gpp 24.229 specification this must be set on all REGISTER attempts. As the deviceID does not change from registration attempt to registration attempt, the size of the database is more predictable.

See Data Schema for details of the Registrar schemas.

The following sections provide instructions for switching to the alternate schema on the MMT node. The required tables already exist on the TSN. You will change MMT configuration to use the alternate tables.

Impacts

During the change of the schema, the system may be affected as follows:

  1. There will be an increase in the number of HSS queries. This is because the third-party registrations serve as a cache, and in their absence, devices can only be verified through queries to the HSS. After the procedure is complete, the number of HSS queries should gradually return to the pre-maintenance window level.

    Note The speed at which the number of HSS queries returns to normal depends on the registration validity period. It can be very quick or fairly slow. It is anticipated to be very quick on average.

  2. When you run the TRUNCATE command, disk usage will not drop immediately. Disk usage will only drop after the nodetool clearsnapshot command is run. This is because the TRUNCATE command moves the data to a snapshot instead of deleting. The snapshot is only removed when the nodetool clearsnapshot command is run.

Note If you encounter any impacts that are not listed, contact Metaswitch technical support.

Pre-maintenance window steps for changing the Cassandra schema

Before entering the maintenance window you need to take some steps to get prepared. Performing these beforehand ensures that changing the Cassandra schema is a smooth exercise. Some steps can be done well in advance. Other steps need to bedone immediately before entering the maintenance window, as they are a final check to ensure everything is ready for the change.

Pre-maintenance window steps that can be done in advance

Verify the deployed MMT version

Make sure that the MMT VMs have already been upgraded to at least the maintenance version of RVT 4.1-1-1.0.0. The configuration changes that are being made will only work if the MMT is at least this version.

Create file with commands to run

There are commands that will need to be run in preparation for and during the Cassandra schema change. These commands requires specific arguments that need to be prepared beforehand. Creating a file of commands ready to be copy/pasted and run beforehand ensures smooth running of the steps. Placeholder values are of the form <…​>. <a|b> means a choice of either a or b. For example, mmt-<gsm|cdma> means mmt-gsm or mmt-cdma.

The file of commands can be stored anywhere that is convenient.

Many of the commands are rvtconfig commands. Further information can be found in the rvtconfig reference.

Determine the following arguments:

  1. tsn-mgmt-address - The management IP address of at least one TSN node. The TSN management IP addresses can be found in the TSN section of the SDF. If multiple addresses are used, they should be formatted as -c <address1> <address2>…​.

  2. deployment-id - This can be found in the SDF under the key deployment-id.

  3. site-id - The site-id of the site you are changing config for. This can be found in the SDF as site-id.

  4. group-id - Either RVT-mmt-gsm.<site-id> or RVT-mmt-cdma.<site-id> depending on whether the MMTs are of the GSM or CDMA variant. If you are unsure, this can be determined from the rvtconfig-path below.

  5. sdf-path - The path to the SDF file on your SIMPL VM.

  6. rvtconfig-path - The path to the rvtconfig on your SIMPL VM. This is expected to be something like: /home/admin/.local/share/csar/mmt-gsm/<version>/resources

If Cassandra authentication is enabled, then two additional arguments will be required for every rvtconfig command.

  1. cds-username - Username to authenticate with Cassandra. You can find it in the SDF under cassandra-username.

  2. cds-password-secret-name - Password identifier to authenticate with Cassandra. You can find it in the SDF under cassandra-password-id.

They are added in the format --cds-username <cds-username> --cds-password-secret-name <cds-password-secret-name> as the last two arguments to every rvtconfig command.

Create a text file containing all the subsequent commands with substitutions completed.

Take a backup of the current configuration

In case you need to roll back later, prepare a copy of the current configuration. Otherwise, you may have to recreate your configuration files manually.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

    $ cd <rvtconfig-path>
$ rvtconfig dump-config -c <tsn-mgmt-address> -d <deployment-id> --group-id <group-id> --vm-version-source this-rvtconfig --output-dir ~/yamls-rollback
    Note --output-dir is the output directory for the rvtconfig dump-config command. Any easily accessible directory can be chosen and the command will create the directory if it does not exist. The recommendation is to maintain ~/yamls-rollback, as this value is referenced in the rollback procedure. In the event that a different folder is used, substitute that value for ~/yamls-rollback in the rollback procedure.

Create the new configuration file

The new configuration needs to be written for upload. The configuration points to change are located in the mmt-<gsm|cdma>-overrides.yaml file in ~/yamls. Create the file if it does not exist.

MMT configuration change

Caution Contact Metaswitch technical support for assistance with writing the new configuration.
Warning Yaml uses semantic whitespace. The resulting file must be valid yaml that rvtconfig can accept.

If mmt-<gsm|cdma>-overrides.yaml does not exist, create it with the following content:

rhino-config:rhino-configuration:
  namespaces:
  - name: ''
    profile-tables:
    - name: RegistrarConfigurationTable
      profiles:
        - name: 'Metaswitch::::'
          present: true
          attributes:
            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

If mmt-<gsm|cdma>-overrides.yaml exists and does not contain the string RegistrarConfigurationTable, insert the following contents immediately below the line profile-tables::

    - name: RegistrarConfigurationTable
      profiles:
        - name: 'Metaswitch::::'
          present: true
          attributes:
            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

If mmt-<gsm|cdma>-overrides.yaml exists and contains the string RegistrarConfigurationTable, insert the following into the attributes key of RegistrarConfigurationTable:

            - name: usePrivateIdAsRegistrarDataPrimaryKey
              content: 'true'

Pre-maintenance window steps to be done immediately prior to entering the maintenance window

Caution Before performing these steps, ensure that you have:

  1. A file with all the commands that need to be run for changing the Cassandra schema. The commands will have all the required arguments substituted.

  2. Two sets of .yaml configuration files - the new configuration (~/yamls), the current config (~/yamls-rollback).

  3. Verified that the deployment consists of the right version of the VMs.

Compare live configuration on MMTs with configuration on SIMPL

  1. Use SSH to access the SIMPL VM.

  2. Verify that the directory /tmp/checkdiff does not exist. If the directory does exist, remove it.

  3. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig compare-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls-rollback --output-dir /tmp/checkdiff --vm-version-source this-rvtconfig
Caution --output-dir is the output directory for the rvtconfig compare-config command. The command will create the directory if it does not exist and will return an error if the directory does exist.

  1. Verify that the command completes with:

No differences found in yaml files.
Uploading this configuration will have no effect unless secrets, certificates or licenses have changed, or --reload-resource-adaptors is specified.

If the output returned does not include "No differences found in yaml files.", contact Metaswitch technical support.

Perform health checks on MMTs in the deployment

The deployment needs to be in a healthy state. To verify that the deployment is healthy, run the following tests.

Run validation tests with CSAR validate

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ csar validate --vnf mmt-<gsm|cdma> --sdf <sdf-path>

  1. Verify that the command completes with:

All tests passed for CSAR 'mmt-<gsm|cdma>/<version-number>'!

Enter the maintenance window

If all the healthchecks above pass, start a maintenance window and then run through the steps for changing the Cassandra schema. To enter a maintenance window:

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig enter-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

Procedure

This section describes the steps for changing the primary key for MMT nodes. These steps are expected to take 30 minutes to complete.

Note Before beginning these steps, ensure that the placeholder values in commands listed here have been substituted with the required values. Placeholder values are of the form <…​>.

Truncate the registrations and assocuris tables on Cassandra

The existing registrations and assocuris tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.

  1. Use SSH to access the TSN as the primary user (sentinel).

  2. Start the Cassandra CLI by running the command:

$ cqlsh

  1. Truncate the tables by running the command:

TRUNCATE opencloud_thirdparty_reg.REGISTRATIONDATA;
TRUNCATE opencloud_thirdparty_reg.ASSOCURIS;

  1. Verify that there are no messages printed to the console after running the TRUNCATE command.

  2. Exit the Cassandra CLI by running:

$ exit
Note If the TRUNCATE command fails, run the next command (nodetool clearsnapshot), before attempting to run the TRUNCATE command and the nodetool command again.

Clear snapshots on all TSN nodes

  1. SSH as the primary user (sentinel) into each of the TSNs sequentially and run the command:

$ nodetool clearsnapshot opencloud_thirdparty_reg --all

Verify that the truncation has been successful

  1. Run the command:

$ df -h

  1. Verify that for the following two rows in the output, the <use>% values are less than 50%:

Filesystem                             Size    Used      Avail  Use% Mounted on
[...]
/dev/sda3                             <size>  <used>   <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size>  <used>   <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
Caution If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support.

  1. Exit the TSN by running:

$ exit

Upload the configuration

The new configuration written during the pre-maintenance window steps, is required to change the schema that is in use.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls --vm-version-source this-rvtconfig

Verify that the configuration has uploaded successfully

  1. Verify that the output after the command has completed running includes the following sentence:

Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>

  1. Exit the SIMPL VM by running:

$ exit

  1. Use SSH as the primary user (sentinel) to access each of the MMTs.

  2. From the home directory, run the command:

$ report-initconf status

until the following is displayed in the output:

status=vm_converged
Note If after 15 minutes, the status of the VMs is not converged, proceed to Rollback.

Test the new tables

  1. Perform a test call to force a registration.

Note If the test call does not succeed, proceed to Rollback.

Exit the maintenance window

Take the deployment out of maintenance window mode.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

  1. verify the command output includes the following:

Maintenance window has been terminated.
The VMs will resume running scheduled tasks as per their configured schedules.

Rollback

This section describes the steps for rolling back the change of primary key for MMT nodes. These steps are expected to take 30 minutes to complete.

Truncate the registrations_v2 and assocuris_v2 tables on Cassandra

The existing registrations_v2 and assocuris_v2 tables take up some space on disk. Truncate these tables to ensure free disk space is over 50%. Truncation must be run on one TSN node.

  1. Use SSH to access the TSN as the primary user (sentinel).

  2. Start the Cassandra CLI by running the command:

$ cqlsh

  1. Truncate the tables by running the command:

    TRUNCATE opencloud_thirdparty_reg.REGISTRATIONDATA_V2;
TRUNCATE opencloud_thirdparty_reg.ASSOCURIS_V2;

  2. Verify that there are no messages printed to the console after running the TRUNCATE command.

  3. Exit the Cassandra CLI by running:

$ exit
Note If the TRUNCATE command fails, run the next command (nodetool clearsnapshot), before attempting to run the TRUNCATE command and the nodetool command again.

Clear snapshots on all TSN nodes

  1. SSH as the primary user (sentinel) into each of the TSNs sequentially and run the command:

$ nodetool clearsnapshot opencloud_thirdparty_reg --all

Verify that the truncation has been successful

  1. Run the command:

$ df -h

  1. Verify that for the following two rows in the output, the <use>% values are less than 50%:

Filesystem                             Size    Used      Avail  Use% Mounted on
[...]
/dev/sda3                             <size>  <used>   <avail> `<use>%` /
[...]
/home/sentinel/cassandra-ramdisk/data <size>  <used>   <avail> `<use>%` /home/sentinel/cassandra-ramdisk/data
Caution If the disk usage is over 50%, do not proceed with the rest of the steps and contact Metaswitch technical support.

  1. Exit the TSN by running:

$ exit

Upload the config

The backup config, which was taken during the pre-maintenance window steps, is required to change the schema that is in use.

  1. Use SSH to access the SIMPL VM.

  2. Copy the backup over ~/yamls:

    cp -f ~/yamls-rollback/* ~/yamls/

  3. Run the command:

$ cd <rvtconfig-path>
$ ./rvtconfig upload-config -c <tsn-mgmt-address> -t mmt-<gsm|cdma> -i ~/yamls --vm-version-source this-rvtconfig

Verify that the configuration has uploaded successfully

  1. Verify that the output after the command has completed running includes the following sentence:

Wrote config for version <version>, deployment ID <deployment-id>, and group ID <group-id>

  1. Exit the SIMPL VM by running:

$ exit

  1. Use SSH as the primary user (sentinel) to access each of the MMTs.

  2. From the home directory, run the command:

$ report-initconf status

until the following is displayed in the output:

status=vm_converged
Note If after 15 minutes, the status of the VMs is not converged, contact Metaswitch technical support.

Test the rollback

  1. Perform a test call to force a registration.

Note If the test call does not succeed, contact Metaswitch technical support.

Exit the maintenance window

Take the deployment out of maintenance window mode.

  1. Use SSH to access the SIMPL VM.

  2. Run the command:

    $ cd <rvtconfig-path>
$ ./rvtconfig leave-maintenance-window -c <tsn-mgmt-address> -d <deployment-id> -S <site-id>

  3. verify the command output includes the following:

Maintenance window has been terminated.
The VMs will resume running scheduled tasks as per their configured schedules.
Previous page Next page
Rhino VoLTE TAS Version 4.1