12. Software Upgrade

12.1. Release Notes

The sip:provider CE version mr5.4.2 has several important changes comparing to the previous release:

[PRO/Carrier] Implement new Apple push protocol for iOS SIP:Phone application [TT#14952]
Introduce maintenance mode for ngcp-upgrade [TT#16751]
Switch from the YAML and YAML::Tiny Perl modules to the modern YAML::XS [TT#17650]
Implement new network.yml dynamic validator program. [TT#14817]
[Carrier] Introduce node status at network.yml to be able to add more nodes to the cluster without affecting a running system [TT#16316]
The ngcp-snmp-agent daemon now exposes OIDs and emits traps for peer host status. [TT#16530, TT#17602]
The ngcp-witnessd daemon now collects extended Kamailio statistics. [TT#2399]
The ngcp-sercmd program has gained a new memdbg command. [TT#16548]
The ngcp-check_active has been renamed to ngcp-check-active, and has gained a new -v option. [TT#16850]
New ngcp-type, ngcp-make-active and ngcp-make-standby scripts. [TT#16850]
The ngcpcfg program gained new set and del commands. [TT#16903]
added option kamailio.lb.remove_isup_body_from_replies [TT#17453]
kamailio: control debug per module via config.yml [TT#17200]
[PRO/Carrier] added huntgroup display-name support for PBX hunt indicator [TT#14840]

Please find the complete changelog in our release notes on our WEB site.

12.2. Upgrade from previous versions to mr5.4.2

The sip:provider CE system upgrade to mr5.4.2 will be performed in a couple of tasks:

Verify APT source lists
Upgrade NGCP software packages
Upgrade NGCP configuration templates
Upgrade NGCP DB schema
Upgrade the base system within Debian (v8) to the latest package versions

12.2.1. Set the proper software repositories

warning
warning	Ensure you are using Sipwise APT repositories. Public Debian mirrors may not provide packages for old Debian releases anymore. Also they can be outdated. Consider to use Sipwise repositories for the time of 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}->mr5.4.2
deb https://debian.sipwise.com/debian/ jessie main contrib non-free
#deb-src https://debian.sipwise.com/debian/ jessie main contrib non-free
#
deb https://debian.sipwise.com/debian-security/ jessie-security main contrib non-free
#deb-src https://debian.sipwise.com/debian-security/ jessie-security main contrib non-free
#
deb https://debian.sipwise.com/debian/ jessie-updates main contrib non-free
#deb-src https://debian.sipwise.com/debian/ jessie-updates 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}->mr5.4.2
deb https://deb.sipwise.com/spce/${NGCP_CURRENT_VERSION}/ jessie main
#deb-src https://deb.sipwise.com/spce/${NGCP_CURRENT_VERSION}/ jessie main
EOF

Run "apt-get update" and ensure you have no warnings/errors here.

12.2.2. Preparing for maintenance mode

Sipwise NGCP introduces Maintenance Mode with its mr5.4.1 release. The maintenance mode of NGCP will disable some background services (for instance: 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.

important
important	For sip:provider CE systems running NGCP release earlier than mr5.4.1: As upgrading from an earlier release to mr5.4.1 or later will result in a system being aware and making use of the maintenance mode, it is necessary to prepare the NGCP for it before the software upgrade.

Enable maintenance mode:

Edit /etc/ngcp-config/config.yml file:
- For systems running NGCP release earlier than mr5.4.1: insert a new line: "maintenance: yes" in general section of the configuration file
- For systems running NGCP release mr5.4.1 or later: set the general.maintenance parameter to yes

general:
  maintenance: yes

Disabling background services. These tasks are for systems currently running NGCP release earlier than mr5.4.1. The maintenance mode of NGCP is not available in your system yet, before the software upgrade. Therefore it is necessary to manually disable the following background services to avoid potential inconsistency in system state:

Mediator
Rate-o-mat
CDR Exporter

To do:

Stop mediator and rate-o-mat services:

service mediator stop
service ngcp-rate-o-mat stop

Prevent background services from (re)starting. You need to change configuration in /etc/ngcp-config/config.yml file: set the enable parameter to "no" as shown below:
```
mediator:
  enabled: no
...
rateomat:
  enable: no
```

In order to disable CDR exporter process you need to add a new custom template file because there is no such file by default:

config="/etc/cron.d/ngcp-cdr-exporter"
customtt="/etc/ngcp-config/templates/etc/cron.d/ngcp-cdr-exporter.customtt.tt2"
[ -f "${customtt}" ] || cp "${config}" "${customtt}"
vim "${customtt}"

Comment out the single line in the file:

# 25,55 * * * *   root    . /etc/default/ngcp-roles; if ...

Please don’t forget to reverse the manual changes after the upgrade, as described in Enabling background services section of the handbook!

For all NGCP systems, regardless of their version:

Apply configuration changes, execute command:

ngcpcfg apply 'Enable maintenance mode before the upgrade to mr5.4.2'

12.2.3. Switch to new repositories

For upgrading the sip:provider CE to release mr5.4.2, execute the following commands:

NGCP_CURRENT_VERSION=$(cat /etc/ngcp_version)
sed -i "s/$NGCP_CURRENT_VERSION/mr5.4.2/" /etc/apt/sources.list.d/sipwise.list
apt-get update
apt-get install ngcp-upgrade-ce

12.2.4. Upgrade the sip:provider CE

Run the upgrade script as root like this:

ngcp-upgrade

info
info	sip:provider CE can be upgraded to mr5.4.2 from previous release or previous build only. The script ngcp-upgrade will find all the possible destination releases for the upgrade and allow to choose the proper one.

info
info	If there is an error during upgrade, the ngcp-upgrade script will request you to solve it. Once you’ve fixed the problem just re-execute `ngcp-upgrade` again and it will continue from the previous step.

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.

12.3. Post-upgrade tasks

12.3.1. Disabling maintenance mode

In order to disable maintenance mode do the following:

Edit /etc/ngcp-config/config.yml file:

general:
  maintenance: no

Enabling background services. If you upgraded from NGCP release earlier than mr5.4.1 you have to manually reverse the changes you applied before the upgrade. (Disabling background services)

Enable background services to start. You need to change configuration in /etc/ngcp-config/config.yml file: set the enable parameter to "yes" as shown below:
```
mediator:
  enabled: yes
...
rateomat:
  enable: yes
```

In order to enable CDR exporter process you need to remove customtt file and edit cron config file:

rm /etc/ngcp-config/templates/etc/cron.d/ngcp-cdr-exporter.customtt.tt2
vim /etc/cron.d/ngcp-cdr-exporter

Remove comment at the beginning of the single line of file:

25,55 * * * *   root    . /etc/default/ngcp-roles; if ...

For all NGCP systems, regardless of their previous version:

Execute command:

ngcpcfg apply 'Disable maintenance mode after the upgrade to mr5.4.2'

12.3.2. Post-upgrade checks

When all finishes successfully check that replication is running. Check ngcp-status. Finally, do a basic functionality test. Check web interface, register two test subscribers and perform a test call between them to ensure call routing works.

info
info	You can find a backup of some important configuration files of your existing installation under /var/backup/ngcp-mr5.4.2-* (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 /var/backup/ngcp-mr5.4.2-/upgrade.log*.