Commit d3e425f8 authored by Etienne Allovon's avatar Etienne Allovon

Enhance and harmonize upgrade procedures

- Harmonize XiVO PBX and XIVO CC upgrade pages
- Add xivo-dcomp pull step in xivo pbx proc
- Move LTS manual steps from release notes to upgrade proc
parent cb770320
......@@ -26,4 +26,5 @@ System
xivo-dird-phoned <xivo-dird-phoned>
xivo-purge-db <purge_logs>
xivo-service <service>
xivo-upgrade <xivo_upgrade_script>
xivo-sysconfd <xivo-sysconfd>
.. _upgrade:
*********
Upgrading
*********
*******
Upgrade
*******
Upgrading a *XiVO PBX* 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.
server.
.. note:: Downgrade is not supported
Overview
========
To upgrade your *XiVO PBX*, you have to use both ``xivo-dist`` and :ref:`xivo-upgrade <xivo-upgrade_script>` tools:
* ``xivo-dist`` to select the version
* ``xivo-upgrade`` to actually upgrade the XiVO PBX
The upgrade consists of the following steps:
These tools handle the process of upgrading:
* the system (Debian packages)
* and the *XiVO PBX* packages
* switch the version via ``xivo-dist`` utility
* upgrade via the ``xivo-upgrade`` utility: it will upgrade the system (Debian packages) and the *XiVO PBX* packages
.. warning:: The following applies to *XiVO PBX* **>= 2016.03**. For older version, see :ref:`version_specific_upgrade` section.
......@@ -29,39 +23,93 @@ These tools handle the process of upgrading:
Preparing the upgrade
=====================
There are two cases:
#. :ref:`Upgrade to another LTS XiVO PBX version <upgrade_to_lts_version_xpbx>`,
#. :ref:`Upgrade to the latest Bugfix release <upgrade_latest_ltsbugfixrel_xpbx>` of your current installed LTS version.
.. _upgrade_to_lts_version_xpbx:
Upgrade to another LTS version
------------------------------
To prepare the upgrade you should:
#. Switch the sources to the new XiVO PBX **LTS** version with ``xivo-dist``, for example::
#. Switch the sources to the new XiVO PBX **LTS** version with ``xivo-dist``, for example, to switch to Aldebaran LTS version::
xivo-dist xivo-aldebaran
#. **Read carefully the** :ref:`xivosolutions_release` **starting from your current version to the version you target.**
#. Check if you are in a specific setup that requires a :ref:`specific procedure <upgrade_specific_proc>`
#. **Read carefully the** :ref:`xivosolutions_release` starting from your current version to the version you target
#. **Check** the specific instructions and manual steps *from your current LTS to your targetted LTS*: see :ref:`upgrade_lts_manual_steps`
#. **Check also** if you are in a specific setup that requires a :ref:`specific procedure <upgrade_specific_proc>`
to be followed (e.g. :ref:`upgrading-a-cluster`).
#. Finally, you can download the packages beforehand by running ``xivo-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.
#. And then upgrade, see `Upgrading`_
Upgrade
=======
.. _upgrade_latest_ltsbugfixrel_xpbx:
.. note:: About `xivo-upgrade` script see:
Upgrade to latest Bugfix release of an LTS version
--------------------------------------------------
.. toctree::
:maxdepth: 2
After the release of an **LTS** *version* (e.g. *Polaris*) we may backport some bugfixes in this version.
We will then create a **subversion** (e.g. Polaris **.04**) shipping these bugfixes.
These bugfix version does not contain any behavior change.
xivo_upgrade_script
To upgrade to the **latest subversion** of your current installed *version* you need to:
#. **Read carefully the** :ref:`xivosolutions_release` starting from your installed version (e.g. Polaris.00) to the latest bugfix release (e.g. Polaris.04).
#. Verify that the debian sources list corresponds to your *installed LTS* or refix it, for example for Polaris::
xivo-dist xivo-polaris
#. And then upgrade, see `Upgrading`_
Upgrading
=========
.. note:: About `xivo-upgrade` script usage see :ref:`xivo-upgrade_script`
After having prepared your upgrade (see above), you can upgrade:
#. For custom setups, follow the required procedures described below (e.g. :ref:`upgrading-a-cluster`).
#. When ready, launch the upgrade process. **All XiVO PBX services will be stopped during the process**::
xivo-upgrade
#. 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, XiVO Client connections etc.
#. Download the new config-mgt service::
xivo-dcomp pull
#. Upgrade the config-mgt service::
xivo-dcomp up -d
Post Upgrade
============
When finished:
* Check that all services are running::
xivo-service status all
* Check that all the docker services are in the correct version. Compare the output of ``xivo-dcomp version`` with the table in :ref:`xivosolutions_release`
* Check that services are correctly working like SIP registration, ISDN link status,
internal/incoming/outgoing calls, XiVO Client connections etc.
.. _upgrade_lts_manual_steps:
Manual steps for LTS upgrade
============================
.. toctree::
:maxdepth: 1
upgrade_from_five_to_polaris
upgrade_from_polaris_to_aldebaran
.. _upgrade_specific_proc:
......@@ -76,8 +124,6 @@ Specific procedures
migrate_i386_to_amd64
asterisk_latest
xivocc_recording
upgrade_from_five_to_polaris
upgrade_from_polaris_to_aldebaran
.. _version_specific_upgrade:
......
.. _upgrade_cc:
*******
Upgrade
*******
Upgrading a *XiVO CC* is done by executing commands through a terminal on the
server.
.. note:: Downgrade is not supported
Overview
========
The following components will be upgraded :
The upgrade consists of the following steps:
- Docker images
- xivocc-installer package
* switch/verify the version in the debian sources list
* update of the ``xivocc-installer`` package
* update of the Docker images
.. warning:: This upgrade procedure applies only to XiVO CC installed via the ``xivocc-installer`` package.
Preparing the upgrade
=====================
Before upgrading you have to check or change your sources list.
It should be located in the file :file:`/etc/apt/sources.list.d/xivo-dist.list`.
There are three cases:
#. :ref:`Upgrade to an LTS XiVO CC version <upgrade_latest_version_xcc>`,
#. :ref:`Upgrade to the latest subversion <upgrade_latest_subversion_xcc>` of your current installed version.
There are two cases:
.. warning:: Note that it is not possible to downgrade to any version.
#. :ref:`Upgrade to another LTS XiVO CC version <upgrade_to_lts_version_xcc>`,
#. :ref:`Upgrade to the latest Bugfix release <upgrade_latest_ltsbugfixrel_xcc>` of your current installed LTS version.
.. _upgrade_latest_version_xcc:
.. _upgrade_to_lts_version_xcc:
Upgrade to an **LTS** version
-----------------------------
Upgrade to another LTS version
------------------------------
Currently XiVO CC *latest* **LTS** version is Polaris and is the numeric release 2017.11. To upgrade to the latest version the sources list must point towards *debian* URI and *xivo-polaris* suite::
To upgrade to another XiVO Solution **LTS**:
deb http://mirror.xivo.solutions/debian/ xivo-polaris main
#. Switch the debian sources to the targetted **LTS** version (it should be located in the file :file:`/etc/apt/sources.list.d/xivo-dist.list`). For example, to switch to Aldebaran LTS version::
or point towards *archive* URI and *xivo-2017.11-latest* suite::
deb http://mirror.xivo.solutions/debian/ xivo-aldebaran main
deb http://mirror.xivo.solutions/archive/ xivo-2017.11-latest main
#. **Read carefully the** :ref:`xivosolutions_release` starting from your current version to the version you target
#. **Check** the specific instructions and manual steps *from your current LTS to your targetted LTS*: see :ref:`upgrade_lts_manual_steps`
#. **Check also** if you are in a specific setup that requires a :ref:`specific procedure <upgrade_specific_proc_xcc>`
#. And then upgrade, see `Upgrading`_
.. _upgrade_latest_subversion_xcc:
.. _upgrade_latest_ltsbugfixrel_xcc:
Upgrade to latest **subversion**
--------------------------------
Upgrade to latest Bugfix release of an LTS version
--------------------------------------------------
.. important:: For version older than Five (2017.03), see `XiVO Five documentation <https://documentation.xivo.solutions/projects/five>`_
After the release of a *version* (e.g. *Polaris (2017.11)*) we may backport some bugfixes in this version.
We will then create a **subversion** (e.g. Polaris **.04** (2017.11 **.04**)) shipping these bugfixes.
These bugfix version does not contain any behavior change.
After the release of a *version* (e.g. *2017.11*) we may backport some bugfixes in this version.
We will then create a **subversion** (e.g. 2017.11 **.01**) shipping these bugfixes.
To upgrade to the **latest subversion** of your current installed *version* you need to:
#. **Read carefully the** :ref:`xivosolutions_release` starting from your installed version (e.g. Polaris.00) to the latest bugfix release (e.g. Polaris.04).
#. Verify that the debian sources list corresponds to your *installed LTS* (it should be located in the file :file:`/etc/apt/sources.list.d/xivo-dist.list`)
#. Verify that the :file:`/etc/docker/compose/factory.env` file has
#. ``XIVOCC_TAG=VERSION`` (where ``VERSION`` is your current installed *version* - e.g. *2017.11*)
#. and ``XIVOCC_DIST=latest``
#. Then update the images with ``xivocc-dcomp pull`` command,
#. And upgrade the containers with ``xivocc-dcomp up -d`` command.
* ``XIVOCC_TAG=VERSION`` (where ``VERSION`` is your current installed *version* - e.g. *2017.11*)
* and ``XIVOCC_DIST=latest``
#. And then upgrade, see `Upgrading`_
Preparing the upgrade
=====================
To prepare the upgrade you should:
Upgrading
=========
#. Read :ref:`xivosolutions_release` starting from your version to the version you target.
After having prepared your upgrade (see above), you can upgrade:
Upgrade
=======
When you have checked the sources.list you can upgrade with the following commands::
#. When you have checked the sources.list you can upgrade with the following commands::
apt-get update
apt-get install xivocc-installer
The current ``docker-compose.yml`` file will be renamed to ``docker-compose.yml.dpkg-old`` and new template downloaded.
A new ``docker-compose.yml`` file will be rendered from the template using the current xivocc version.
Then you have to:
#. Download the new images::
#. If there is any change, you should accept the new :file:`docker-compose.yml` file. Then compare it with the old :file:`docker-compose.yml.dpkg-old` file and report in the new any specific configuration.
#. Then download the new docker images::
xivocc-dcomp pull
#. And run the new container (**All XiVO CC services will be restarted**)::
#. And run the new containers (**Corresponding XiVO CC services will be restarted**)::
xivocc-dcomp up -d
......@@ -93,71 +93,32 @@ Then you have to:
Post Upgrade
============
Check your upgrade through :ref:`check-list`.
When finished:
Upgrade notes
=============
See :ref:`xivosolutions_release` for version specific informations.
Reporting Upgrade notes
=======================
These notes include upgrade procedures for old versions of the **Pack reporting**, before **XivoCC** starts and before it was packaged with Docker.
In those cases, run the following command to find the installed version of the pack reporting:
.. code-block:: bash
* Check your upgrade through :ref:`check-list`.
* Check that all the services are in the correct version. Compare the output of ``xivocc-dcomp version`` with the table in :ref:`xivosolutions_release`
dpkg -l|grep pack-reporting
From version < 1.6
------------------
Manual steps for LTS upgrade
============================
* data retention time will be lost during upgrade : save it and write it back in */etc/xivo-reporting-db.conf*
* the upgrade is likely to be long if there is a lot of data in *queue_log*. Purge old data out of this table if possible
in order to accelerate the upgrade
* at the end of the upgrade, run *apt-get autoremove* (deletion of xivo-stat, xivo-libdao and xivo-lib-python)
See :ref:`upgrade_lts_manual_steps` in XiVO Upgrade page.
From version < 1.8
------------------
* XiVO in version < 14.08 is not supported anymore
* if it is required, the upgrade of the XiVO must be done before the upgrade of the pack reporting,
and no call must be performed between the two upgrades
.. _upgrade_specific_proc_xcc:
From a version using Debian packaging to a version using Docker
---------------------------------------------------------------
Specific procedures
===================
* **Beware**: this will require a migration of the original PostgreSQL database to the Dockerised one. For this you need to have free disk space :
the amount of free disk space must equal the size of */var/lib/postgresql*. This check must be performed after docker images have been pulled.
* Run the following commands:
.. toctree::
:maxdepth: 2
.. code-block:: bash
xivocc_old_pack_reporting_upgrade
apt-get update
service xivo-db-replication stop
service xivo-full-stats stopsource/releasenotes/index.rst
apt-get install pack-reporting xivo-full-stats xivo-reporting-db xivo-db-replication db-utils
service xivo-db-replication stop
service xivo-full-stats stop
* Install docker, docker-compose and xivocc-installer
* Open `docker-xivocc.yml` and remove sections recording_rsync, config_mgt, recording_server, xuc, xucmgt
* Run `xivocc-dcomp pull`
* CHECK THE FREE DISK SPACE. The next command will migrate the database. This may take several hours.
.. code-block:: bash
sudo -u postgres pg_dump --format c xivo_stats | docker exec -i xivocc_pgxivocc_1 pg_restore -U postgres -d xivo_stats
* Start by `xivocc-dcomp up -d`
From a dockerized version before callbacks
------------------------------------------
Upgrade notes
=============
* Run the following commands:
See :ref:`xivosolutions_release` for version specific informations.
.. code-block:: bash
docker exec -ti compose_pgxivocc_1 psql -U postgres -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"' xivo_stats
docker exec -ti compose_pgxivocc_1 psql -U postgres -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"' xuc_rights
*************************************
Old Pack Reporting Upgrade Procedures
*************************************
These notes include upgrade procedures for old versions of the **Pack reporting**, before **XivoCC** starts and before it was packaged with Docker.
In those cases, run the following command to find the installed version of the pack reporting:
.. code-block:: bash
dpkg -l|grep pack-reporting
From version < 1.6
==================
* data retention time will be lost during upgrade : save it and write it back in */etc/xivo-reporting-db.conf*
* the upgrade is likely to be long if there is a lot of data in *queue_log*. Purge old data out of this table if possible
in order to accelerate the upgrade
* at the end of the upgrade, run *apt-get autoremove* (deletion of xivo-stat, xivo-libdao and xivo-lib-python)
From version < 1.8
==================
* XiVO in version < 14.08 is not supported anymore
* if it is required, the upgrade of the XiVO must be done before the upgrade of the pack reporting,
and no call must be performed between the two upgrades
From a version using Debian packaging to a version using Docker
===============================================================
* **Beware**: this will require a migration of the original PostgreSQL database to the Dockerised one. For this you need to have free disk space :
the amount of free disk space must equal the size of */var/lib/postgresql*. This check must be performed after docker images have been pulled.
* Run the following commands:
.. code-block:: bash
apt-get update
service xivo-db-replication stop
service xivo-full-stats stopsource/releasenotes/index.rst
apt-get install pack-reporting xivo-full-stats xivo-reporting-db xivo-db-replication db-utils
service xivo-db-replication stop
service xivo-full-stats stop
* Install docker, docker-compose and xivocc-installer
* Open `docker-xivocc.yml` and remove sections recording_rsync, config_mgt, recording_server, xuc, xucmgt
* Run `xivocc-dcomp pull`
* CHECK THE FREE DISK SPACE. The next command will migrate the database. This may take several hours.
.. code-block:: bash
sudo -u postgres pg_dump --format c xivo_stats | docker exec -i xivocc_pgxivocc_1 pg_restore -U postgres -d xivo_stats
* Start by `xivocc-dcomp up -d`
From a dockerized version before callbacks
==========================================
* Run the following commands:
.. code-block:: bash
docker exec -ti compose_pgxivocc_1 psql -U postgres -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"' xivo_stats
docker exec -ti compose_pgxivocc_1 psql -U postgres -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"' xuc_rights
......@@ -217,10 +217,10 @@ Behavior Changes
Upgrade
^^^^^^^
.. toctree::
:maxdepth: 2
Follow the usual procedures (**don't forget** the specific steps to upgrade to Aldebaran):
upgrade_from_polaris_to_aldebaran
* :ref:`XiVO PBX upgrade procedure <upgrade>`
* :ref:`XiVO CC upgrade procedure <upgrade_cc>`
Features & bugfixes list
......
****************************
Upgrade Polaris to Aldebaran
****************************
In this section is listed the manual steps to do when migrating from Polaris to Aldebaran.
Before Upgrade
==============
* If docker is installed (on XiVO PBX or XiVO CC), its custom start options may cause the upgrade to fail. Please check that ``/etc/systemd/system/docker.service.d``
directory does not exist or it is empty. Otherwise see documentation on `docker web <https://docs.docker.com/config/daemon/systemd/#custom-docker-daemon-options>`_.
On XiVO PBX
-----------
* XiVO Aldebaran is only available in **64-bit** versions. To migrate XiVO from ``i386`` to ``amd64``, you must follow :ref:`migrate_i386_to_amd64`.
* Configuration files and dialplan subroutine for ACD outgoing calls for call blending
(See `Polaris documentation <https://documentation.xivo.solutions/en/2017.11/administrator/xivocc/system_configuration.html#acd-outgoing-calls-for-call-blending>`_)
was integrated to XiVO.
The configuration **must** be manually removed if it exists::
sed -i '/generate_agent_skills.py/d' /etc/asterisk/queueskills.conf
rm /usr/local/sbin/generate_agent_skills.py
rm /etc/asterisk/extensions_extra.d/xuc_outcall_acd.conf
* If the XiVO was added to XiVO Centralized User Management, the file ``routage.conf`` **must** be updated.
* Download the new `routage.conf <https://gitlab.com/xivo-utils/icdu-packaging/raw/a53e1fe2411ff5ed85dc54e61d135dc578c2a91f/interface-centralisee/xivo_config/routage.conf/>`_ file
* Replace the old file ``/etc/asterisk/extensions_extra.d/routage.conf`` by the new one
* Follow the :ref:`upgrade` page.
On XiVO CC
----------
* Update distribution to xivo-aldebaran in source list::
echo "deb http://mirror.xivo.solutions/debian xivo-aldebaran main" > /etc/apt/sources.list.d/xivo-dist.list
After Upgrade
=============
On XiVO PBX
-----------
* Outgoing call was removed from redirections.
You MUST check the xivo-upgrade log with the following command::
zgrep MIGRATE_OUTCALL_FWD /var/log/xivo-upgrade.log*
Then you MUST edit each object to reconfigure the changed destination.
All Outgoing call redirections can be replaced by an Extension redirection with the appropriate context.
For example an outgoing redirection towards "my_outcall (@to-extern)" to number "0123456789"
can be replaced by an extension redirection to "0123456789" with context "to-extern"
* ConfigMgt service was moved to XiVO PBX. Here's how to migrate the ConfigMgt database:
* On your **XiVO CC** (where the service pgxivocc is run) authorize user root to login with password via ssh,
* Then on your **XiVO CC**, stop the services with ``xivocc-dcomp stop``
* Then, on your **XiVO PBX**, run the migration script and follow the instruction::
xivo-migrate-configmgt-db
* Finally, when migration is complete, relaunch the services on **XiVO CC**::
xivocc-dcomp up -d --remove-orphans
On XiVO CC
----------
* Update new kibana default panels::
xivocc-dcomp stop kibana_volumes
docker rm -v xivocc_kibana_volumes_1
xivocc-dcomp up -d
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment