The Sipwise C5 version mr7.5.12 has the following important changes:
Please find the complete changelog in our release notes on our WEB site.
The Sipwise C5 software upgrade procedure to mr7.5.12 will perform several fundamental tasks:
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.
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
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).
| 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.
| warning | |
Starting from version mr7.0.1 a new kamailio module called "pv_headers" has been introduced. This new module enables storing all headers in XAVP to freely modify them in the kamailio logic and only apply them once when it’s time for the packet to be routed outside. The main goal of the module is to offload the intermediate header processing into the XAVP dynamic container as well as provide with high-level methods and pseudovariables to simplify SIP message header modifications. The module is enabled by default in kamailio proxy and all the templates have been updated to use this new logic. Before proceeding with the upgrade it is essential that the customtt/patchtt you have in place are updated to this new format. At appendix you can find additional information on the module. |
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\*
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
Run "apt-get update" 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! |
| warning | |
Upgrade to mr7.5 is allowed with kamailio.location in Redis DB only! It is necessary for the proper migration of location records from datetime to bigint/epoch. |
Starting from mr6.2.1, location, acc and dialogs data are stored in RedisDB allowing better system performances. Before proceed with the upgrade, check if location data are already migrated to RedisDB:
ngcpcfg values "kamailio.proxy.redis.usrloc"
If the answer is yes, then skip this sub-chapter and proceed with the next one. On the contrary, an answer equals to no means that the migration process has not been completed. This happens because, to be more flexible and to reduce the downtime of the system, only acc and dialogs data have been moved automatically to RedisDB. Migration of location data is a step that should be done manually and it was probably skipped during previous upgrades.
To proceed with the migration and complete the process, execute the following commands during out of business hours.
ngcpcfg set /etc/ngcp-config/config.yml "kamailio.proxy.redis.usrloc=yes"
ngcpcfg apply 'Enable location data storage on RedisDB'
| important | |
Execute the following 3 steps one after another with as short as possible delay between them. |
ngcp-location-migrate
ngcp-location-sync
ngcp-service kamailio-proxy restart ngcp-service ngcp-panel restart ngcp-service ngcp-mediator restart
ngcp-location-migrate -c
| info | |
The document describes upgrade from all mr7.4.* and mr6.5.* LTS releases. |
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 set /etc/ngcp-config/config.yml "general.maintenance=yes"
ngcpcfg apply 'Enabling maintenance mode before the upgrade to mr7.5.12'
| warning | |
Ensure you are using the Sipwise APT repositories. Public Debian mirrors may not provide packages for old Debian releases anymore. Also, they might be outdated. Consider using Sipwise repositories for the time of the upgrade. |
Execute the following commands as root:
echo "# Please visit /etc/apt/sources.list.d/ instead." > /etc/apt/sources.list
mkdir -p /etc/apt/sources.list.d
for file in /etc/apt/sources.list.d/*.list ; do mv "${file}" "${file}.DISABLED" ; done
NGCP_CURRENT_VERSION=$(cat /etc/ngcp_version)
cat > /etc/apt/sources.list.d/debian.list << EOF
# Debian repositories, deployed via upgrade ${NGCP_CURRENT_VERSION}->mr7.5.12
deb https://debian.sipwise.com/debian/ stretch main contrib non-free
#deb-src https://debian.sipwise.com/debian/ stretch main contrib non-free
#
deb https://debian.sipwise.com/debian-security/ stretch-security main contrib non-free
#deb-src https://debian.sipwise.com/debian-security/ stretch-security main contrib non-free
#
deb https://debian.sipwise.com/debian/ stretch-updates main contrib non-free
#deb-src https://debian.sipwise.com/debian/ stretch-updates main contrib non-free
deb https://debian.sipwise.com/debian-debug/ stretch-debug main contrib non-free
#deb-src https://debian.sipwise.com/debian-debug/ stretch-debug main contrib non-free
EOF
NGCP_CURRENT_VERSION=$(cat /etc/ngcp_version)
cat > /etc/apt/sources.list.d/sipwise.list << EOF
# NGCP_MANAGED_FILE
# Sipwise repository, deployed via upgrade ${NGCP_CURRENT_VERSION}->mr7.5.12
deb https://deb.sipwise.com/spce/${NGCP_CURRENT_VERSION}/ stretch main
#deb-src https://deb.sipwise.com/spce/${NGCP_CURRENT_VERSION}/ stretch main
EOF| warning | |
Do not use "ngcpcfg apply/build" after executing the steps from the above block, as otherwise the changes will be overwritten and you will have to redo these steps. Run "apt-get update" and ensure you have no warnings/errors here. |
To upgrade Sipwise C5 to release mr7.5.12, execute the following commands:
NGCP_CURRENT_VERSION=$(cat /etc/ngcp_version)
sed -i "s/${NGCP_CURRENT_VERSION}/mr7.5.12/" /etc/apt/sources.list.d/sipwise.list
sed -i "s/stretch/buster/g" /etc/apt/sources.list.d/sipwise.list /etc/apt/sources.list.d/debian.list
apt-get update
apt-get install ngcp-upgrade-ceRun the upgrade script as root like this:
ngcp-upgrade
| info | |
Sipwise C5 can be upgraded to mr7.5.12 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).
Once up again, double-check your config file /etc/ngcp-config/config.yml (sections will be rearranged now and will contain more parameters) and your domain/subscriber/peer configuration and test the setup.
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.
In order to disable the maintenance mode, do the following:
ngcpcfg set /etc/ngcp-config/config.yml "general.maintenance=no"
ngcpcfg apply 'Disable the maintenance mode after the upgrade to mr7.5.12'
When everything has finished successfully, check that replication is running.
Check ngcp-status.
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-mr7.5.12-* (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-mr7.5.12-*/upgrade.log. |
If your current release is already the latest or you prefer to be on the LTS release, we still suggest appling the latest hotfixes and critical bug fixes.
Execute all steps as described in Section 14.3, “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.
Merge/add the custom configuration templates if needed.
Apply the changes to configuration templates:
ngcpcfg apply 'apply customtt/patchtt after installing the latest packages'
Execute the final checks as described in the Post-upgrade checks section.