Upgrading a Wazo is done by executing commands through a terminal on the server. You can connect to the server either through SSH or with a physical console.
To upgrade your Wazo to the latest version, you must use the
wazo-upgrade script. You can
start an upgrade with the command:
- You can’t use wazo-upgrade if you have not run the wizard yet
- Upgrading from a deprecated version is not supported.
- When upgrading Wazo, you must also upgrade all associated Wazo Clients. There is currently no retro-compatibility on older Wazo Client versions. The only exception is Wazo 16.16, which is compatible with Wazo Client 16.13.
This script will update Wazo and restart all services.
There are 2 options you can pass to wazo-upgrade:
-dto only download packages without installing them. This will still upgrade the package containing wazo-upgrade.
-fto force upgrade, without asking for user confirmation
wazo-upgrade uses the following environment variables:
XIVO_CONFD_PORTto set the port used to query the HTTP API of xivo-confd (default is 9486)
- Consult the roadmaps starting from your current version to the current prod version.
- Read all existing Upgrade Notes (see below) starting from your version to the latest version.
- For custom setups, follow the required procedures described below (e.g. HA cluster).
- To download the packages beforehand, run
wazo-upgrade -d. This is not mandatory, but it does not require stopping any service, so it may be useful to reduce the downtime of the server while upgrading.
- When ready, run
wazo-upgradewhich will start the upgrade process. Telephony services will be stopped during the process
- When finished, check that all services are running (the list is displayed at the end of the upgrade).
- Check that services are correctly working like SIP registration, ISDN link status, internal/incoming/outgoing calls, Wazo Client connections etc.
Version-specific upgrade procedures¶
Upgrading from XiVO 16.13 and before¶
When upgrading from XiVO 16.13 or before, you must use the special XiVO to Wazo upgrade
procedure instead of simply running
Upgrading from XiVO 14.01, 14.02, 14.03, 14.04 installed from the ISO¶
In those versions, xivo-upgrade keeps XiVO on the same version. You must do the following, before the normal upgrade:
echo "deb http://mirror.wazo.community/debian/ xivo-five main" > /etc/apt/sources.list.d/xivo-upgrade.list \ && apt-get update \ && apt-get install xivo-fai \ && rm /etc/apt/sources.list.d/xivo-upgrade.list \ && apt-get update
Upgrading from XiVO 13.24 and before¶
When upgrading from XiVO 13.24 or earlier, you must do the following, before the normal upgrade:
Ensure that the file
/etc/apt/sources.listis not configured on
archive.debian.org. Instead, it must be configured with a non-archive mirror, but still on the
squeezedistribution, even if it is not present on this mirror. For example:
deb http://ftp.us.debian.org/debian squeeze main
archive.debian.orgin another file:
cat > /etc/apt/sources.list.d/squeeze-archive.list <<EOF deb http://archive.debian.org/debian/ squeeze main EOF
And after the upgrade:
Upgrading from XiVO 13.03 and before¶
When upgrading from XiVO 13.03 or earlier, you must do the following, before the normal upgrade:
wget http://mirror.wazo.community/xivo_current.key -O - | apt-key add -
Upgrading a cluster¶
Here are the steps for upgrading a cluster, i.e. two Wazo with High Availability (HA):
On the master : deactivate the database replication by commenting the cron in
On the slave, deactivate the xivo-check-master-status script cronjob by commenting the line in
On the slave, start the upgrade:
When the slave has finished, start the upgrade on the master:
When done, launch the database replication manually:
xivo-master:~$ xivo-master-slave-db-replication <slave ip>
Reactivate the cronjobs (see steps 1 and 2)
Upgrading from i386 (32 bits) to amd64 (64 bits)¶
When upgrading Wazo, if you encounter problems related to the system locale, see PostgreSQL localization errors.
If wazo-upgrade fails or aborts in mid-process, the system might end up in a faulty condition. If in doubt, run the following command to check the current state of xivo’s firewall rules:
If, among others, it displays something like the following line (notice the DROP and 5060):
0 0 DROP udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpt:5060
Then your Wazo will not be able to register any SIP phones. In this case, you must delete the DROP rules with the following command:
iptables -D INPUT -p udp --dport 5060 -j DROP
Repeat this command until no more unwanted rules are left.
Consult the 17.14 Roadmap
xivo-authhas been renamed
- If you have developed a
xivo-authauthentication backend the name of the entry point has changed to
wazo_auth.backends. You should make this modification in your plugin’s
setup.pyfile in the
- If your custom development use service discovery to find
xivo-auth, you will have to search for the
wazo-authservice instead of
- If you have developed a
- We released a new version of the CTI client, rebranded as Wazo Client 17.14.1. It is compatible with all previous versions of Wazo (i.e. not before 16.16). See also the compatibility table.
Consult the 17.12 Roadmap
- Wazo has a new database named
mongooseim. The backup-restore procedure has been updated to include this new database.
Consult the 17.11 Roadmap
- wazo-plugind REST API version
0.1has been deprecated and will be removed in Wazo
18.02. See changelog for version 17.12
Consult the 17.09 Roadmap
Codecs can now be customized in the /etc/asterisk/codecs.d/ directory. If you had custom configuration in /etc/asterisk/codecs.conf you will have to create a new file in codecs.d to use your customized configuration. A file named codecs.conf.dpkg-old will be left in /etc/asterisk if this operation is required.
Provd plugins from the addons repository have been merged into the main plugin repository. If you were using the addons repository you can safely switch back to the stable repository. See Alternative plugins repository for more details.
xivo-call-logshas been deprecated in favor of
xivo-servicehas been deprecated in favor of
If you have a custom certificate configured, you will need to add a new symlink for the new daemon wazo-webhookd:
ln -s "/etc/xivo/custom/custom-certificate.yml" "/etc/wazo-webhookd/conf.d/010-custom-certificate.yml"
Consult the 17.08 Roadmap
The call logs has been improved by adding
date_answerinformations. If you want to add these new informations to the old call logs, you need to regenerate them. For example, to regenerate the last month of call logs:
xivo-call-logs delete -d 30 xivo-call-logs generate -d 30
This is only useful if you plan to use the call logs REST API to read calls that have been placed before the upgrade.
If you have setup a custom X.509 certificate for HTTPS (e.g. from Let’s Encrypt), you have to update your config in
/etc/xivo/custom/custom-certificate.yml, according to the updated documentation, namely for the config regarding
Consult the 17.05 Roadmap
python-flask-cors has been updated from 1.10.3 to 3.0.2. Configuration files with custom allow_headers will have to be updated to the new syntax. The following command can be used to see if you have a configuration file which needs to be updated.
for f in $(find /etc/*/conf.d -name '*.yml'); do grep -H allow_headers $f; done
The old config in
rest_api: cors: allow_headers: Content-Type, X-Auth-Token
The new config in
rest_api: cors: allow_headers: ["Content-Type", "X-Auth-Token"]
See also the reference ticket #6617.
Consult the 17.02 Roadmap
- A few more services are now available by default on port TCP/443 (the complete list is documented in the Nginx section). This does not pose any additional security risk by default, but if you have extra strict requirements about security, they can be manually disabled.
Wazo 16.16 is the first public release of the project under the Wazo name. It is also the first release of Wazo under the “phoenix” codename.
Consult the 16.16 Roadmap
- A special procedure is required to upgrade from XiVO to Wazo.
- Asterisk has been upgraded from version 13.11.2 to 14.2.1, which is a major Asterisk upgrade.
- If you are using custom sheets that are stored locally, they must now
be readable by the system user
xivo-ctid. Make sure that this user has read access to the UI file of your custom sheets.
- Switchboard statistics have been removed. The existing statistics data remain in the database for later migration but no more statistics will be collected.
conferencedestination type in incalls REST API has been renamed to
- The phonebook has been migrated from the web interface to xivo-dird. The phonebook contacts
from the web interface have been moved to new dird-phonebooks. For users with many entities
on the same Wazo, this will create one phonebook for each entity. The configuration has been
updated to keep the previous behavior. No manual actions are required for installations with only one entity or
if one phonebook by entity is the desired configuration. If only one phonebook is desired for all entities, some
of the duplicate phonebooks can be deleted from the web interface and their matching configuration
can also be removed.
- The list of phonebooks can be modified in
- The list of phonebooks sources can be modified in:
- The selected phonebooks for reverse lookups can be modified in
- Direct directories can be modified in
Please consult the following detailed upgrade notes for more information:
XiVO 16.13 is the last public release of the project under the name XiVO.
Consult the 16.13 Roadmap
- Previously, a user’s DND was effective only if this user had DND enabled and the DND extension (*25 by default) was also enabled. Said differently, disabling the DND extension meant that no user could effectively be in DND. Starting from XiVO 16.13, a user’s DND is effective regardless of the state of the DND extension. The following features are impacted in the same way: call recording, incoming call filtering, forward on non-answer, forward on busy and unconditional forward.
- If you have manually added nginx configuration files to the
/etc/nginx/locations/httpdirectory, you’ll need to move these files to
/etc/nginx/locations/http-availableand then create symlinks to them in the
/etc/nginx/locations/http-enableddirectory. This also applies to the https directory. See Nginx.
- A regression has been introduced in the switchboard statistics. See issue 6443.
Consult the 16.11 Roadmap
- Fax reception: the “log” backend type has been removed. You should remove references to it in your
/etc/xivo/asterisk/xivo_fax.confif you were using it. Now, every time a fax is processed, a log line is added to
Consult the 16.10 Roadmap
- The config file
/etc/xivo/xivo-confgend.confhas been replaced with
/etc/xivo-confgend/conf.d. Custom modifications to this file are not migrated automatically, so manual intervention is required to migrate custom values to the
conf.ddirectory. The file
/etc/xivo/xivo-confgend/asterisk/contexts.confhas been moved to
/etc/xivo-confgend/templates/contexts.conf, but custom modification are left untouched. See also Configuration Files for more details about configuration files in XiVO.
Consult the 16.09 Roadmap
- The Wazo Client now uses xivo-ctid-ng to do transfers. Those new transfers cannot be cancelled
*0DTMF sequence and there is no interface in the Wazo Client to cancel a transfer for profiles other than the switchboard (bug #6321). This will be addressed in a later version.
- Transfers started from the Wazo Client do not respect the
Dial timeout on transferoption anymore (bug #6322). This feature will be reintroduced in a later version.
Consult the 16.08 Roadmap
CTI Protocol is now in version 2.2
Some security features have been added to the XiVO provisioning server. To benefit from these new features, you’ll need to update your xivo-provd plugins to meet the system requirements.
If you have many phones that are connected to your XiVO through a NAT equipment, you should review the default configuration to make sure that the IP address of your NAT equipment don’t get banned unintentionally by your XiVO.
Newly created groups and queues now ignore call forward requests from members by default. Previously, call forward requests from members were always followed. This only applies to call forward configured directly on the member’s phone: call forward configured via *21 have always been ignored in these cases.
Note that during the upgrade, the previous behaviour is kept for already existing queues and groups.
This behaviour is now configurable per queue/group, via the “Ignore call forward requests from members” option under the “Application” tab. We recommend enabling this option.
Consult the 16.07 Roadmap
Consult the 16.05 Roadmap
deleteallactions of the “lines” web service provided by the web interface have been removed. As a reminder, note that the web services provided by the web interface are deprecated.
Consult the 16.04 Roadmap
- CTI Protocol is now in version 2.1
- The field Rightcall Code from under Services tab will overwrite all password call permissions for the user.
- Faxes stored on FTP servers are now converted to PDF by default. See Using the FTP backend if you want to keep the old behavior of storing faxes as TIFF files.
Consult the 16.03 Roadmap
- The new section in the web interface will only be visible by a non-root administrator after adding the corresponding permissions in the administrator configuration.
- Update the switchboard configuration page for the statistics in Configuration for multiple switchboards.
- The API for associating a line to a device has been replaced. Consult the xivo-confd REST API changelog for further details
- The configuration parameters of xivo_ldap_user plugin of xivo-auth has been changed. See xivo_ldap plugin.
- The user’s email is now a unique constraint. Every duplicate email will be deleted during the migration. (This does not apply to the voicemail’s email)
Consult the 16.02 Roadmap
- The experimental xivo_ldap_voicemail plugin of xivo-auth has been removed. Use the new xivo_ldap plugin.
- Bus messages in the xivo exchange are now sent with the content-type application/json. Some libraries already do the message conversion based the content-type. Kombu users will receive a python dictionnary instead of a string containing json when a message is received.
- xivo-ctid encryption is automatically switched on for every XiVO server and Wazo Client >= 16.02. If you really don’t want encryption, you must disable it manually on the server after the upgrade. In that case, Wazo Clients will ask whether to accept the connection the first time.
Consult the 16.01 Roadmap
- The page has been removed. Consequently, every Web Services Access has now all access rights on the web services provided by the web interface. These web services are deprecated and will be removed soon.
- During the upgrade, if no CA certificates were trusted at the system level, all the CA
certificates from the ca-certificates package will be added. This is done to resolve an issue with
installations from the ISO and PXE. In the (rare) case you manually configured the ca-certificates
package to trust no CA certificates at all, you’ll need to manually reconfigure it via
dpkg-reconfigure ca-certificatesafter the upgrade.
- xivo-ctid uses xivo-auth to authenticate users. See Authentication.
- the service_discovery section of the xivo-ctid configuration has changed. If you have set up Contact and Presence Sharing, you should update your xivo-ctid configuration.
- the CTI Protocol is now versioned and a message will be displayed if the server and a client have incompatible protocol versions.