The Sipwise C5 version mr8.3.1 has the following important changes:
Some important technical points for those interested:
Please find the complete changelog in our release notes on our WEB site.
The Sipwise C5 software upgrade procedure to mr8.3.1 will perform several fundamental tasks:
Sipwise C5 CARRIER is a PRO-style system that has "A" and "B" sets of nodes with specific roles. The number of nodes can differ between installations and must be clarified before the upgrade at the planning stage.
The software upgrade is usually performed by Sipwise engineers according to the following steps:
| warning | |
The only allowed software upgrade path is the one described above. All the other theoretically possible upgrade scenarios can lead to unpredictable results. |
| warning | |
On CARRIER nodes "A" and "B" MUST be used as described in this document. It is NOT allowed to swap them unless proxy replication (of MySQL on port 3308) is configured on the db01b node. |
Confirm the following information:
It is recommended to execute the preparatory steps in this chapter a few days before the actual software upgrade. They do not cause a service downtime, so it is safe to execute them during peak hours.
This should be web01a on CARRIER and sp1 on PRO.
| tip | |
Use the static server IP address so you can switch between the nodes. |
Run the terminal multiplexer under the sipwise user (to reuse the Sipwise .screenrc settings that are convenient for working in multiple windows):
screen -S my_screen_name_for_ngcp_upgrade
Become root inside your screen session:
sudo -s
Check the overall system status:
ngcp-status --all
Make sure that the cluster health status is OK: Check the nodes in parallel, using the clish command:
| info | |
Software must be identical on all nodes (before and after the upgrade!) |
| info | |
to exit from ngcp-clish press Ctrl+Z (or type exit): |
# ngcp-clish Entering 'clish-enable' view (press Ctrl+Z to exit)... # exit #
For the below steps, investigate and make sure you understand why the custom modifications were introduced and if they are still required after the software upgrade. If the custom modifications are not required anymore, remove them (e.g. if a bug was fixed in the target release and the existing patch becomes irrelevant).
Create tickets to Sipwise developers to make relevant custom modifications part of the product in future releases. This allows you to get rid of the customtt files one day.
| warning | |
If you directly change the working configuration (e.g. add custom templates or change the existing ones) for some reason, then the system must be thoroughly tested after these changes have been applied. Continue with the software upgrade preparation only if the results of the tests are acceptable. |
Find the local changes to the template files:
ngcp-customtt-diff-helper
The script will also ask you if you would like to download the templates for your target release. To download the new templates separately, execute:
ngcp-customtt-diff-helper -d
In the tmp folder provided by the script, you can review the patchtt files or merge the current customtt with the new tt2 templates, creating the new customtt.tt2 files. Once you do this, archive the new patchtt/customtt files to reapply your custom modifications after the software upgrade:
ngcp-customtt-diff-helper -t
Find all available script options with the "-h" parameter.
Check if there are any *.tt2.dpkg-dist files among the templates. They usually appear when tt2 files are modified directly instead of creating customtt/patchtt files. If you find any *.tt2.dpkg-dist files, treat the corresponding tt2 files as if they were customtt.tt2 and introduce the changes from the existing tt2 files into the new templates (create associated customtt.tt2 or patchtt.tt2) before the software upgrade.
find /etc/ngcp-config -name \*.tt2.dpkg-dist
Note that in the end all *.tt2.dpkg-dist files must be removed before the software upgrade as they prevent the upgrade script from updating the tt2 files.
Check and remove dpkg files left from previous software upgrades.
Make sure that the list is empty before you continue:
find /etc/ngcp-config -name \*.tt2.dpkg\*
Log into all the servers.
Open separate windows for all the servers inside your "screen" session.
(Press Ctrl+a + c to open a new window, Ctrl+a + a or Ctrl+a + [0-9] to
change the window. Ctrl+a + " shows the list of all your windows.
Use Ctrl+a + A to change the window names to corresponding hosts).
Changes made directly in tt2 templates will be lost after the software upgrade. Only custom changes made in customtt.tt2 or added by patchtt.tt2 files will be kept. Hence, check the system for locally modified tt2 files on all nodes:
ngcp-status --integrity
Check the configuration framework status on all nodes. All checks must show the "OK" result and there must be no actions required:
ngcpcfg status
On a CARRIER, check the replication on both central DB servers and on ports 3306 and 3308 of all the proxy servers. Ensure that all the proxy nodes replicate the read-only DB (127.0.0.1:3308) from the db01a node. Otherwise, discuss a special plan to address your particular configuration.
On a PRO, check the replication on both nodes.
The result must always show:
Slave_IO_Running: Yes Slave_SQL_Running: Yes Seconds_Behind_Master: 0
Test the cluster failover to see if everything works fine as well on "B" nodes (on a CARRIER) or the second node (on a PRO). On all the standby nodes execute:
ngcp-make-active
Create two test subscribers or use the credentials for existing ones. Register subscribers with the platform and perform a test call to ensure that call routing and media flow are working fine.
Run "apt-get update" on all nodes and ensure that you do not have any warnings and errors in the output.
| warning | |
If the installation uses locally specified mirrors, then the mirrors must be switched to the Sipwise APT repositories (at least for the software upgrade). Otherwise, the public Debian mirrors may not provide packages for old Releases anymore or at least provide outdated ones! |
Ensure that both management nodes have access to deb.sipwise.com by executing the following commands on a management node:
ngcp-approx-cache-helper --check --node sp1 ngcp-approx-cache-helper --check --node sp2
The checks must show only 200 OK results. If you see cannot connect!, Received 404 or any other error, check these possible causes:
The Sipwise C5 — starting from mr6.5.1 release — enforce software licensing restrictions in form of a regular comparison of the licensed services and capacities against the actual usage patterns of the platform. In case some functionalities are enabled but not licensed, an error in syslog will be reported and the impacted services will be automatically deactivated.
Before proceeding with the upgrade, please take some time to check that all the modules not licensed are actually disabled in config.yml file. To verify if they are enabled execute the following commands:
ngcpcfg get sems.prepaid.enable ngcpcfg get sems.prepaid.inew.enable ngcpcfg get pbx.enable ngcpcfg get pushd.enable ngcpcfg get intercept.enable ngcpcfg get voisniff.admin_panel ngcpcfg get voisniff.daemon.li_x1x2x3.enable ngcpcfg get voisniff.daemon.start
If the output of one of the commands is yes but the module is not licensed, you have to deactivate it. For example, in case of pre-paid billing module execute:
ngcpcfg set /etc/ngcp-config/config.yml sems.prepaid.enable=no ngcpcfg apply 'Disable prepaid module' ngcpcfg push all
| warning | |
Please, pay particular attention to pre-paid billing module because it is enabled by default. |
| info | |
Sipwise C5 can be upgraded to mr8.3.1 from previous release or previous build only. The script ngcp-upgrade will find all the possible destination releases for the upgrade and makes it possible to choose the proper one. |
| info | |
If there is an error during the upgrade, the ngcp-upgrade script will
request you to solve it. Once you’ve fixed the problem, just execute
|
The upgrade script will ask you to confirm that you want to start. Read the given information carefully, and if you agree, proceed with y.
The upgrade process will take several minutes, depending on your network connection and server performance. After everything has been updated successfully, it will finally ask you to reboot your system. Confirm to let the system reboot (it will boot with an updated kernel).
The following options in ngcp-upgrade can be specially useful in some
instances of upgrade:
--step-by-step: confirm before proceeding to next step. With this option
the upgrade operation is performed confirming every step before execution,
with the possibility to instruct to continue without confirming further steps
until the end (if confirmation is only needed for some steps at the
beginning).
--pause-before-step STEP_NAME: pause execution before step, given by the
name of the script (e.g. "backup_mysql_db"). This option can be useful in
several scenarios, for example:
--step-by-step), or just continue without stop until the end
--skip-db-backup: This will speed-up the process in cases where it’s
deemed unnecessary, and this is very likely in the upgrade of nodes other than
the first.
Sipwise C5 introduces Maintenance Mode with its mr5.4.1 release. The maintenance mode of Sipwise C5 will disable some background services (for instance: ngcp-mediator) during the software upgrade. It thus prevents the system from getting into an inconsistent state while the upgrade is being performed. You can activate maintenance mode by applying a simple configuration change as described later.
ngcpcfg pull
ngcpcfg set /etc/ngcp-config/config.yml "general.maintenance=yes"
ngcpcfg apply 'Enabling maintenance mode before the upgrade to mr8.3.1' ngcpcfg push all
| warning | |
Customers with far-sighted software upgrade policies usually have pre-production installations to test the services in their environment before upgrading the production platform. In this case, the approx cache should be updated on both platforms simultaneously to synchronize the package versions between them, hence consider carefully before executing this step. |
To download the latest packages metadata into the approx cache, execute the following command on the standby management node. This action ensures that all nodes within the platform have identical packages after the software upgrade:
ngcp-approx-cache-helper --update --skip-all-repos --extra-ngcp-release mr8.3.1
Log in to all nodes and execute the checks from Section 13.4, “Preparing the software upgrade” again. This will ensure that nothing was broken since the preparation steps were finished. Also, execute ngcpcfg show and ngcpcfg status to check the latest configuration changes.
Perform the BFT test.
To upgrade Sipwise C5 CARRIER to mr8.3.1 release, execute the following commands on the standby management "A" node:
| info | |
Sometimes the DB and MGMT roles are assigned to the same host. This is OK. |
| warning | |
Do NOT execute the software upgrade on web01a and db01a in parallel! |
Run the following command node to install the package responsible for upgrading Sipwise C5 to a newer release:
ngcp-prepare-upgrade mr8.3.1
| info | |
Don’t worry, ngcp-upgrade-carrier does not exist, ngcp-upgrade-pro is used in Carrier too. |
| warning | |
Do not use "ngcpcfg apply/build" after executing the steps from the above section, otherwise the changes will be overwritten and you will have to redo these steps. The same applies to similar sections below. |
Run the upgrade script on the standby node as root:
ngcp-upgrade
Merge/add the custom configuration templates if needed.
Apply the changes to configuration templates:
ngcpcfg apply 'apply customtt/patchtt for new the release mrX.X on xxx01a'
Send the new templates to the shared storage and the other nodes
ngcpcfg push --nobuild --noapply all
| warning | |
Do NOT execute ngcpcfg push --shared-only at this stage, as it will affect further upgrades due to noticed outdated local ngcpcfg storage. If you did so, run ngcpcfg push --nobuild --noapply all once again to pull ngcpcfg changes on all the nodes from glusterfs. |
| info | |
If the DB and MGMT roles are assigned to the same host, then skip this step as you have already upgraded the standby MGMT node "A" above. |
Run the following commands to upgrade the standby DB node "A" (select the same release version as above and follow the on-screen recommendations):
ngcp-prepare-upgrade mr8.3.1 ngcp-upgrade
| info | |
It is important to upgrade db01a node before upgrading any proxy nodes.
Otherwise, the "local" MySQL (127.0.0.1:3308) on proxy nodes may become out of
sync in case the new release has |
Run the below commands selecting the same release version and follow the on-screen recommendations:
ngcp-prepare-upgrade mr8.3.1 ngcp-upgrade
The following options in ngcp-upgrade can be useful for this phase of
upgrades, because it is very likely that the backup was already performed:
--skip-db-backup: This will speed-up the process in cases where it’s
deemed unnecessary.
See a more detailed description of the options in: ngcp-upgrade options
| warning | |
Ensure that all standby nodes "A" are:
* upgraded to the new release (check /etc/ngcp_version or use |
On all "A" nodes run:
ngcp-make-active
Ensure that the "A" nodes became active, by executing the 'ngcp-status' and 'ngcp-clish' commands described above.
Ensure that ALL "B" nodes are standby now!
Run the following commands selecting the same release version and following the on-screen recommendations:
ngcp-prepare-upgrade mr8.3.1 ngcp-upgrade
| info | |
You can upgrade all standby "B" nodes simultaneously (including the ones with the mgmt and db roles). |
The following options in ngcp-upgrade can be useful for this phase of
upgrades:
--step-by-step: confirm before proceeding to next step.
--pause-before-step STEP_NAME: pause execution before step, given by the
name of the script (e.g. "backup_mysql_db").
See a more detailed description of the options in: ngcp-upgrade options
Make sure you are prepared to spend about two hours upgrading the system. Note that a short service downtime is possible during the services switchover to the upgraded node.
Start with the software upgrade on the standby sp1 node. Then, switch the services over to the upgraded node and upgrade the other (now standby) sp2 node, as described in the steps below.
Execute the upgrade script on the standby node as root:
ngcp-prepare-upgrade mr8.3.1 ngcp-upgrade
The following options in ngcp-upgrade can be useful for this phase of
upgrades:
--step-by-step: confirm before proceeding to next step.
--pause-before-step STEP_NAME: pause execution before step, given by the
name of the script (e.g. "backup_mysql_db").
See a more detailed description of the options in: ngcp-upgrade options
Introduce the custom changes to configuration templates if needed (by adding corresponding patchtt/customtt files). Apply the changes to configuration templates and send them to the shared storage and the other node:
ngcpcfg apply 'Added custom changes when the first node was upgraded' ngcpcfg push --nobuild --noapply
Execute on the current standby node as root:
ngcp-make-active
Go to the new standby node. Run the upgrade script as root:
ngcp-prepare-upgrade mr8.3.1 ngcp-upgrade
The following options in ngcp-upgrade can be useful for this phase of
upgrades, because it is very likely that the backup was already performed in the
upgrade of the first node:
--skip-db-backup: This will speed-up the process in cases where it’s
deemed unnecessary.
See a more detailed description of the options in: ngcp-upgrade options
In order to disable the maintenance mode, do the following:
ngcpcfg pull
ngcpcfg set /etc/ngcp-config/config.yml "general.maintenance=no"
ngcpcfg apply 'Disable the maintenance mode after the upgrade to mr8.3.1' ngcpcfg push all
When everything has finished successfully, check that replication is running.
Check ngcp-status --all.
Finally, do a basic functionality test.
Check the web interface, register two test subscribers and perform a test call
between them to ensure call routing works.
| info | |
You can find a backup of some important configuration files of your existing installation under /ngcp-data/backup/ngcp-mr8.3.1-* (where * is a place holder for a timestamp) in case you need to roll back something at any time. A log file of the upgrade procedure is available at /ngcp-data/backup/ngcp-mr8.3.1-*/upgrade.log. |
If your current release is already the latest or you prefer to be on the LTS release, we still suggest applying the latest hotfixes and critical bug fixes.
Execute all steps as described in Section 13.4, “Preparing the software upgrade”. They include the system checks, customtt/patchtt preparation and others. It is important to execute all the steps from the above chapter.
On a CARRIER it is suggested to promote B-nodes to active and start the update with A-nodes.
The main goal of the following command is to download the new packages into the approx cache. So all the nodes in the cluster will get identical packages.
ngcp-approx-cache-helper --auto --node localhost
Merge/add the custom configuration templates if needed.
Apply the changes to configuration templates:
ngcpcfg apply 'apply customtt/patchtt after installing the latest packages'
Send the new templates to the shared storage and the other nodes.
ngcpcfg push --nobuild --noapply all
Execute on the standby nodes as root:
ngcp-make-active
Check in a minute that the nodes became active:
ngcp-check-active